Documentación de Oracle Cloud Infrastructure

Creación de una función de autorizador

Descubra cómo crear funciones de autorizador de argumentos únicos y de varios argumentos para utilizarlas con API Gateway.

En función de la funcionalidad que necesite, puede escribir:

  • (Recomendado) Función de autorizador de varios argumentos que acepta un token de acceso de varios argumentos definido por el usuario que comprende uno o más elementos de una solicitud (consulte Creación de una función de autorizador de varios argumentos (recomendado)). Tenga en cuenta que las funciones de autorizador de varios argumentos pueden aceptar tokens de acceso único incluidos en una cabecera de solicitud o un parámetro de consulta.
  • Una función de autorizador de argumentos que acepta un token de acceso de un argumento que comprende un valor único contenido en una cabecera de solicitud o un parámetro de consulta (consulte Creación de una función de autorizador de un argumento).

Creación de una función de responsable de autorización de varios argumentos (recomendada)

Para crear una función de autorizador que acepte un token de acceso de varios argumentos definido por el usuario:

  1. Escriba código en la función de autorizador que acepte JSON con el siguiente formato como entrada de API Gateway:

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

    donde:

    • "type": "USER_DEFINED" indica que los argumentos y valores que se transfieren a la función de autorizador se definen en la especificación de despliegue de API.
    • "<argument-n>" es un nombre de argumento que corresponde a un nombre de argumento definido por el usuario especificado en la sección parameters de la especificación de despliegue de API. Por ejemplo, "state", "xapikey"
    • "<context-variable-value>" es el valor de la variable de contexto especificada en la sección parameters de la especificación de despliegue de API. Por ejemplo, el valor de la variable de contexto del parámetro de consulta request.query[state], el valor de la variable de contexto del parámetro de cabecera request.headers[X-Api-Key]. Tenga en cuenta que al transferir varios valores a la función de autorizador desde cabeceras de solicitud y parámetros de consulta, "<context-variable-value>" se transfiere a la función de autorizador como matriz. Tenga en cuenta también que si el valor de una variable de contexto no está presente en la solicitud original al gateway de API, la variable de contexto no se transfiere a la función de autorizador.

    Por ejemplo, puede que desee que la función de autorizador acepte los valores de la variable de contexto del parámetro de consulta request.query[state] y la variable de contexto del parámetro de cabecera request.headers[X-Api-Key] como entrada de API Gateway. Por ejemplo, si los valores de la variable de contexto del parámetro de consulta request.query[state] y de la variable de contexto del parámetro de cabecera request.headers[X-Api-Key] son california y abc123def456fhi789 respectivamente, la función de autorizador debe aceptar la siguiente entrada JSON:

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

    Tenga en cuenta que si la cabecera X-API-Key no está presente en la solicitud original al gateway de API, la variable de contexto xapikey no se transfiere a la función de autorizador en absoluto (en lugar de transferirse con un valor nulo).

  2. Escriba código en la función de autorizador que devuelve el siguiente JSON al gateway de API como respuesta HTTP 200 cuando el token de acceso de varios argumentos definido por el usuario se haya verificado correctamente con un proveedor de identidad y el proveedor de identidad haya determinado que el token es válido:

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

    donde:

    • "active": true indica que el proveedor de identidad ha determinado que el token de acceso transferido originalmente a la función de autorizador es válido. Tenga en cuenta que este campo booleano es opcional, pero el valor por defecto es false si no se incluye en la respuesta de JSON.
    • "scope": ["<scopes>"] es opcionalmente el ámbito de acceso que la función de autorizador ha obtenido del proveedor de identidad. Tenga en cuenta que ["<scopes>"] puede ser una matriz de JSON de cadenas delimitadas por comas, como ["list:hello", "read:hello", "create:hello"], o una cadena separada por espacios, como "list:hello read:hello create:hello". Tenga en cuenta que este campo es necesario si la propiedad type de la política de solicitud de autorización está definida en ANY_OF.
    • "expiresAt": "<date-time>" es opcionalmente una cadena fecha-hora en formato ISO-8601 que indica cuándo caducará el token de acceso que se transfirió originalmente a la función de autorizador. Este valor se utiliza al determinar cuánto tiempo se almacenarán en la caché los resultados después de llamar a la función de autorizador. Puede almacenar en caché los resultados durante un mínimo de 60 segundos y un máximo de 1 hora. Tenga en cuenta que si este campo no se incluye en la respuesta de JSON o si "<date-time>" no es válido, los resultados se almacenan en caché durante 60 segundos.
    • "context": {"<key>": "<value>", ... } es una lista opcional delimitada por comas de pares clave-valor en formato JSON que se devolverá al gateway de API. La función de autorizador puede devolver cualquier par clave-valor para que lo utilice el despliegue de API (por ejemplo, el nombre de usuario o la dirección de correo electrónico del usuario final). Para obtener más información sobre el uso del valor en el par clave-valor devuelto por una función de autorizador como una variable de contexto en una definición de backend HTTP, consulte Agregación de variables de contexto a políticas y definiciones de backend HTTP.

    Por ejemplo:

    {
  "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"
  }
}

    Cuando la función de autorizador devuelve una respuesta HTTP 200 y active: true en el cuerpo JSON de la respuesta, API Gateway devuelve una respuesta HTTP 200 al cliente de API.

  3. Escriba código en la función de autorizador que devuelve el siguiente JSON al gateway de API como respuesta HTTP 200 cuando el token de acceso de varios argumentos definido por el usuario se haya verificado correctamente con un proveedor de identidad, pero el proveedor de identidad haya determinado que el token no es válido:

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

    donde:

    • "active": false indica que el proveedor de identidad ha determinado que el token de acceso transferido originalmente a la función de autorizador no es válido. Tenga en cuenta que este campo es opcional, pero se define por defecto en false si no está presente en la respuesta de JSON.
    • "wwwAuthenticate": "<directive>" es opcionalmente el valor de la cabecera WWW-Authenticate que la función de autorizador devolverá si el token de acceso no es válido, lo que indica el tipo de autenticación necesaria (como básica o de portador). Por ejemplo, "wwwAuthenticate": "Bearer realm=\"example.com\"". Para obtener más información, consulte RFC 2617 HTTP Authentication: Basic and Digest Access Authentication.

    Por ejemplo:

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

    Opcionalmente, puede incluir una sección validationFailurePolicy en la especificación de despliegue de API para modificar el código de respuesta, el mensaje de respuesta y las cabeceras de respuesta que se devuelven al cliente de API. Si no incluye una sección validationFailurePolicy, API Gateway devuelve la cabecera WWW-Authenticate como respuesta al cliente de API, junto con un código de estado 401. Consulte Notas sobre las políticas de fallos de validación y el manejo de respuestas de autenticación con fallos de funciones de autorizador de varios argumentos.

  4. Escriba código en la función de autorizador que devuelva una respuesta HTTP 5xx si el token no se ha podido verificar con el proveedor de identidad (por lo que no se sabe si el token es válido o no válido), o en caso de error en la función de autorizador o en OCI Functions.

    Cuando la función de autorizador devuelve una respuesta HTTP 5xx, API Gateway devuelve una respuesta HTTP 502 al cliente de API. Se ignora cualquier JSON en el cuerpo de la respuesta.

Creación de una función de autorizador de un solo argumento

Nota

Oracle recomienda el uso de funciones de autorizador de varios argumentos en lugar de funciones de autorizador de un solo argumento debido a su versatilidad adicional. Las funciones de autorizador de argumentos únicos se proporcionaron en versiones anteriores y siguen siendo compatibles. Sin embargo, dado que las funciones de autorizador de varios argumentos también pueden aceptar tokens de acceso de un solo argumento incluidos en las cabeceras de solicitud y el parámetro de consulta, no hay razón para crear nuevas funciones de autorizador de un solo argumento. Además, se prevé que las funciones de autorizador de argumentos únicos queden en desuso en futuras versiones.

Para crear una función de autorizador que acepte un token de acceso de un solo argumento que comprenda un único valor contenido en una cabecera de solicitud o un parámetro de consulta:

  1. Escriba código en la función de autorizador que acepte la siguiente entrada de JSON de gateway de API:

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

    donde:

    • "type": "TOKEN" indica que el valor que se transfiere a la función de autorizador es un token de autenticación.
    • "token": "<token-value>" es el token de autenticación que se transfiere a la función de autorizador.

    Por ejemplo:

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

  2. Escriba código en la función de autorizador que devuelva el siguiente JSON al gateway de API como respuesta HTTP 200 si el token de acceso se ha verificado correctamente con un proveedor de identidad y el proveedor de identidad ha determinado que el token es válido:

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

    donde:

    • "active": true indica que el proveedor de identidad ha determinado que el token de acceso transferido originalmente a la función de autorizador es válido. Tenga en cuenta que este campo booleano es opcional, pero el valor por defecto es false si no se incluye en la respuesta de JSON.
    • "scope": ["<scopes>"] es opcionalmente el ámbito de acceso que la función de autorizador ha obtenido del proveedor de identidad. Tenga en cuenta que ["<scopes>"] puede ser una matriz de JSON de cadenas delimitadas por comas, como ["list:hello", "read:hello", "create:hello"], o una cadena separada por espacios, como "list:hello read:hello create:hello". Tenga en cuenta que este campo es necesario si la propiedad type de la política de solicitud de autorización está definida en ANY_OF.
    • "expiresAt": "<date-time>" es opcionalmente una cadena fecha-hora en formato ISO-8601 que indica cuándo caducará el token de acceso que se transfirió originalmente a la función de autorizador. Este valor se utiliza al determinar cuánto tiempo se almacenarán en la caché los resultados después de llamar a la función de autorizador. Puede almacenar en caché los resultados durante un mínimo de 60 segundos y un máximo de 1 hora. Tenga en cuenta que si este campo no se incluye en la respuesta de JSON o si "<date-time>" no es válido, los resultados se almacenan en caché durante 60 segundos.
    • "context": {"<key>": "<value>", ... } es una lista opcional delimitada por comas de pares clave-valor en formato JSON que se devolverá al gateway de API. La función de autorizador puede devolver cualquier par clave-valor para que lo utilice el despliegue de API (por ejemplo, el nombre de usuario o la dirección de correo electrónico de un usuario final). Para obtener más información sobre el uso del valor en el par clave-valor devuelto por una función de autorizador como una variable de contexto en una definición de backend HTTP, consulte Agregación de variables de contexto a políticas y definiciones de backend HTTP.

    Por ejemplo:

    {
  "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"
  }
}

    Cuando la función de autorizador devuelve una respuesta HTTP 200 y active: true en el cuerpo JSON de la respuesta, API Gateway devuelve una respuesta HTTP 200 al cliente de API.

    Tenga en cuenta que la respuesta de la función de responsable de autorización de un solo argumento tiene el mismo formato que una respuesta de una función de responsable de autorización de varios argumentos (consulte Creación de una función de responsable de autorización de varios argumentos (recomendada)).

  3. Escriba código en la función de autorizador que devuelva el siguiente JSON al gateway de API como respuesta HTTP 200 si el token de acceso se ha verificado correctamente con un proveedor de identidad, pero el proveedor de identidad ha determinado que el token no es válido:

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

    donde:

    • "active": false indica que el proveedor de identidad ha determinado que el token de acceso transferido originalmente a la función de autorizador no es válido. Tenga en cuenta que este campo es opcional, pero se define por defecto en false si no está presente en la respuesta de JSON.
    • "wwwAuthenticate": "<directive>" es opcionalmente el valor de la cabecera WWW-Authenticate que la función de autorizador devolverá si el token de acceso no es válido, lo que indica el tipo de autenticación necesaria (como básica o de portador). Por ejemplo, "wwwAuthenticate": "Bearer realm=\"example.com\"". Para obtener más información, consulte RFC 2617 HTTP Authentication: Basic and Digest Access Authentication.

    Por ejemplo:

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

    API Gateway devuelve la cabecera WWW-Authenticate junto con un código de estado 401 como respuesta al cliente de API.

    Tenga en cuenta que la respuesta de la función de responsable de autorización de un solo argumento tiene el mismo formato que una respuesta de una función de responsable de autorización de varios argumentos (consulte Creación de una función de responsable de autorización de varios argumentos (recomendada)).

  4. Escriba código en la función de autorizador que devuelva una respuesta HTTP 5xx si el token no se ha podido verificar con el proveedor de identidad (por lo que no se sabe si el token es válido o no válido), o en caso de error en la función de autorizador o en OCI Functions.

    Cuando la función de autorizador devuelve una respuesta HTTP 5xx, API Gateway devuelve una respuesta HTTP 502 al cliente de API. Se ignora cualquier JSON en el cuerpo de la respuesta.

Para ver un tutorial de desarrollador relacionado que contenga una función de autorizador de ejemplo, consulte la sección sobre funciones: validar una clave de API con API Gateway.