Criando uma Função de Autorizador

Para criar uma função de autorizador que aceite um token de acesso multi-argumento definido pelo usuário:

1. Grave um código na função de autorizador que aceite JSON no seguinte formato como entrada do serviço API Gateway:

   
   {
     "type": "USER_DEFINED",
     "data": {
       "<argument-n>": "<context-variable-value>",
       "<argument-n>": "<context-variable-value>",
       "<argument-n>": "<context-variable-value>"
     }
   }

   em que:

   • "type": "USER_DEFINED" indica que os argumentos e valores que estão sendo passados para a função de autorizador são definidos na especificação de implantação de API.
   • "<argument-n>" é um nome de argumento, correspondente a um nome de argumento definido pelo usuário especificado na seção parameters da especificação de implantação de API. Por exemplo, "state", "xapikey"
   • "<context-variable-value>" é o valor da variável de contexto especificada na seção parameters da especificação de implantação de API. Por exemplo, o valor da variável de contexto do parâmetro de consulta request.query[state], o valor da variável de contexto do parâmetro de cabeçalho request.headers[X-Api-Key]. Observe que ao transmitir vários valores para a função de autorizador de cabeçalhos de solicitação e parâmetros de consulta, "<context-variable-value>" é passado para a função de autorizador como um array. Observe também que, se o valor de uma variável de contexto não estiver presente na solicitação original ao gateway de API, a variável de contexto não será passada para a função de autorizador.

   Por exemplo, talvez você queira que a função de autorizador aceite os valores da variável de contexto do parâmetro de consulta request.query[state] e da variável de contexto do parâmetro de cabeçalho request.headers[X-Api-Key] como entrada do Gateway de API. Portanto, por exemplo, se os valores da variável de contexto do parâmetro de consulta request.query[state] e da variável de contexto do parâmetro de cabeçalho request.headers[X-Api-Key] forem california e abc123def456fhi789 respectivamente, a função de autorizador deverá aceitar a seguinte entrada JSON:

   
   {
     "type": "USER_DEFINED",
     "data": {
       "state": "california",
       "xapikey": "abc123def456fhi789"
     }
   }

   Observe que, se o cabeçalho X-API-Key não estiver presente na solicitação original para o gateway de API, a variável de contexto xapikey não será transmitida à função de autorizador (em vez de ser transmitida com um valor nulo).

2. Grave um código na função de autorizador que retorne o seguinte JSON para o Gateway de API como uma resposta HTTP 200 quando o token de acesso multiargumento definido pelo usuário tiver sido verificado com sucesso com um provedor de identidades, e o provedor de identidades tiver determinado que o token é válido:

   {
     "active": true,
     "scope": ["<scopes>"],
     "expiresAt": "<date-time>",
     "context": {
       "<key>": "<value>", ... 
     }
   }

   em que:

   • "active": true indica que o provedor de identidades determinou que o token de acesso especificado originalmente para a função de autorizador é válido. Observe que esse campo booliano é opcional, mas assume false como padrão se não estiver incluído na resposta JSON.
   • "scope": ["<scopes>"] é, opcionalmente, os escopos de acesso obtidos pela função de autorizador do provedor de identidades. Observe que ["<scopes>"] pode ser um array JSON de strings delimitadas por vírgulas, como ["list:hello", "read:hello", "create:hello"], ou uma string separada por espaço, como "list:hello read:hello create:hello". Observe que esse campo será obrigatório se a propriedade type da política de solicitação de autorização estiver definida como ANY_OF.
   • "expiresAt": "<date-time>" é opcionalmente uma string de data e horário no formato ISO-8601 indicando quando expirará o token de acesso especificado originalmente para a função de autorizador. Esse valor é usado ao determinar o tempo de armazenamento em cache dos resultados após chamar a função de autorizador. Você pode armazenar os resultados em cache por um mínimo de 60 segundos e um máximo de 1 hora. Observe que, se esse campo não for incluído na resposta JSON ou se "<date-time>" for inválido, os resultados serão armazenados em cache por 60 segundos.
   • "context": {"<key>": "<value>", ... } é uma lista delimitada por vírgulas opcional dos pares de chave/valor no formato JSON a ser retornada ao serviço API Gateway. A função de autorizador pode retornar qualquer par chave-valor para uso pela implantação de API (por exemplo, o nome de usuário ou endereço de e-mail do usuário final). Para obter mais informações sobre como usar o valor no par de chave/valor retornado por uma função de autorizador como variável de contexto em uma definição de backend HTTP, consulte Adicionando Variáveis de Contexto a Políticas e Definições de Backend HTTP.

   Por exemplo:

   {
     "active": true,
     "scope": ["list:hello", "read:hello", "create:hello", "update:hello", "delete:hello", "someScope"],
     "expiresAt": "2019-05-30T10:15:30+01:00",
     "context": {
       "email": "john.doe@example.com"
     }
   }

   Quando a função de autorizador retorna uma resposta HTTP 200 e active: true no corpo JSON da resposta, o Gateway de API retorna uma resposta HTTP 200 para o cliente de API.

3. Grave um código na função de autorizador que retorne o seguinte JSON para o Gateway de API como uma resposta HTTP 200 quando o token de acesso multiargumento definido pelo usuário tiver sido verificado com sucesso com um provedor de identidades, mas o provedor de identidades tiver determinado que o token é inválido:

   {
     "active": false,
     "wwwAuthenticate": "<directive>"
   }

   em que:

   • "active": false indica que o provedor de identidades determinou que o token de acesso especificado originalmente para a função de autorizador é inválido. Observe que esse campo é opcional, mas assume false como padrão se não estiver presente na resposta JSON.
   • "wwwAuthenticate": "<directive>" é opcionalmente o valor do cabeçalho WWW-Authenticate a ser retornado pela função de autorizador se o token de acesso for inválido, indicando o tipo de autenticação exigida (como Básica ou Portador). Por exemplo, "wwwAuthenticate": "Bearer realm=\"example.com\"". Para obter mais informações, consulte Autenticação HTTP do RFC 2617: Autenticação de Acesso Básica e de Compilação.

   Por exemplo:

   {
     "active": false,
     "wwwAuthenticate": "Bearer realm=\"example.com\""
   }

   Opcionalmente, você pode incluir uma seção validationFailurePolicy na especificação de implantação de API para modificar o código de resposta, a mensagem de resposta e os cabeçalhos de resposta retornados ao cliente de API. Se você não incluir uma seção validationFailurePolicy, o serviço API Gateway retornará o cabeçalho WWW-Authenticate na resposta ao cliente de API, juntamente com um código de status 401. Consulte Observações sobre Políticas de Falha de Validação e o Tratamento de Respostas de Autenticação com Falha das Funções de Autorizador de Vários Argumentos.

4. Grave o código na função de autorizador que retornará uma resposta HTTP 5xx se o token não puder ser verificado com o provedor de identidades (portanto, não se sabe se o token é válido ou inválido) ou no caso de um erro na função de autorizador ou no OCI Functions.

   Quando a função de autorizador retorna uma resposta HTTP 5xx, o Gateway de API retorna uma resposta HTTP 502 para o cliente de API. Qualquer JSON no corpo da resposta é ignorado.

Para criar uma função de autorizador que aceite um token de acesso de argumento único que inclua um único valor contido em um cabeçalho de solicitação ou parâmetro de consulta:

1. Grave um código na função de autorizador que aceite a seguinte entrada de dados JSON do serviço API Gateway:

   
   {
     "type": "TOKEN",
     "token": "<token-value>"
   }

   em que:

   • "type": "TOKEN" indica que o valor que está sendo especificado para a função de autorizador é um token de autorização.
   • "token": "<token-value>" é o token de autenticação que está sendo especificado para a função de autorizador.

   Por exemplo:

   
   {
     "type": "TOKEN",
     "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1nHyDtTwR3SEJ3z489..."
   }

2. Grave um código na função de autorizador que retorne o seguinte JSON para o Gateway de API como uma resposta HTTP 200 quando o token de acesso tiver sido verificado com sucesso com um provedor de identidades e o provedor de identidades tiver determinado que o token é válido:

   {
     "active": true,
     "scope": ["<scopes>"],
     "expiresAt": "<date-time>",
     "context": {
       "<key>": "<value>", ... 
     }
   }

   em que:

   • "active": true indica que o provedor de identidades determinou que o token de acesso especificado originalmente para a função de autorizador é válido. Observe que esse campo booliano é opcional, mas assume false como padrão se não estiver incluído na resposta JSON.
   • "scope": ["<scopes>"] é, opcionalmente, os escopos de acesso obtidos pela função de autorizador do provedor de identidades. Observe que ["<scopes>"] pode ser um array JSON de strings delimitadas por vírgulas, como ["list:hello", "read:hello", "create:hello"], ou uma string separada por espaço, como "list:hello read:hello create:hello". Observe que esse campo será obrigatório se a propriedade type da política de solicitação de autorização estiver definida como ANY_OF.
   • "expiresAt": "<date-time>" é opcionalmente uma string de data e horário no formato ISO-8601 indicando quando expirará o token de acesso especificado originalmente para a função de autorizador. Esse valor é usado ao determinar o tempo de armazenamento em cache dos resultados após chamar a função de autorizador. Você pode armazenar os resultados em cache por um mínimo de 60 segundos e um máximo de 1 hora. Observe que, se esse campo não for incluído na resposta JSON ou se "<date-time>" for inválido, os resultados serão armazenados em cache por 60 segundos.
   • "context": {"<key>": "<value>", ... } é uma lista delimitada por vírgulas opcional dos pares de chave/valor no formato JSON a ser retornada ao serviço API Gateway. A função de autorizador pode retornar qualquer par chave-valor para uso pela implantação de API (por exemplo, o nome de usuário ou endereço de e-mail de um usuário final). Para obter mais informações sobre como usar o valor no par de chave/valor retornado por uma função de autorizador como variável de contexto em uma definição de backend HTTP, consulte Adicionando Variáveis de Contexto a Políticas e Definições de Backend HTTP.

   Por exemplo:

   {
     "active": true,
     "scope": ["list:hello", "read:hello", "create:hello", "update:hello", "delete:hello", "someScope"],
     "expiresAt": "2019-05-30T10:15:30+01:00",
     "context": {
       "email": "john.doe@example.com"
     }
   }

   Quando a função de autorizador retorna uma resposta HTTP 200 e active: true no corpo JSON da resposta, o Gateway de API retorna uma resposta HTTP 200 para o cliente de API.

   Observe que a resposta da função de autorizador de um único argumento tem o mesmo formato que uma resposta de uma função de autorizador de vários argumentos (consulte Criando uma Função de Autorizador de Vários Argumentos (Recomendado)).

3. Grave um código na função de autorizador que retorne o seguinte JSON para o Gateway de API como uma resposta HTTP 200 quando o token de acesso tiver sido verificado com sucesso com um provedor de identidades, mas o provedor de identidades tiver determinado que o token é inválido:

   {
     "active": false,
     "wwwAuthenticate": "<directive>"
   }

   em que:

   • "active": false indica que o provedor de identidades determinou que o token de acesso especificado originalmente para a função de autorizador é inválido. Observe que esse campo é opcional, mas assume false como padrão se não estiver presente na resposta JSON.
   • "wwwAuthenticate": "<directive>" é opcionalmente o valor do cabeçalho WWW-Authenticate a ser retornado pela função de autorizador se o token de acesso for inválido, indicando o tipo de autenticação exigida (como Básica ou Portador). Por exemplo, "wwwAuthenticate": "Bearer realm=\"example.com\"". Para obter mais informações, consulte Autenticação HTTP do RFC 2617: Autenticação de Acesso Básica e de Compilação.

   Por exemplo:

   {
     "active": false,
     "wwwAuthenticate": "Bearer realm=\"example.com\""
   }

   O serviço API Gateway retorna o cabeçalho WWW-Authenticate na resposta ao cliente de API, juntamente com um código de status 401.

   Observe que a resposta da função de autorizador de um único argumento tem o mesmo formato que uma resposta de uma função de autorizador de vários argumentos (consulte Criando uma Função de Autorizador de Vários Argumentos (Recomendado)).

4. Grave o código na função de autorizador que retornará uma resposta HTTP 5xx se o token não puder ser verificado com o provedor de identidades (portanto, não se sabe se o token é válido ou inválido) ou no caso de um erro na função de autorizador ou no OCI Functions.

   Quando a função de autorizador retorna uma resposta HTTP 5xx, o Gateway de API retorna uma resposta HTTP 502 para o cliente de API. Qualquer JSON no corpo da resposta é ignorado.

Para obter um Tutorial do Desenvolvedor relacionado que contém um exemplo de função de autorizador, consulte Funções: Validar uma Chave de API com o Serviço API Gateway.