Ámbito

Por IETF RFC 6749, el valor del parámetro de ámbito se expresa como una lista de series delimitadas por espacios y sensibles a las mayúsculas y minúsculas.

En IBM® API Connect, los ámbitos no tienen ningún significado inherente. En su lugar, los ámbitos se definen en el proveedor OAuth para que una aplicación pueda solicitar una señal de acceso que sea válida para uno o varios de los ámbitos. En la API protegida, los ámbitos están listados como requisitos para que una señal de acceso se considere válida. Todos los ámbitos listados por la definición de seguridad para la API deben ser otorgados por la señal de acceso.
Nota:
  • Un proveedor OAuth debe tener al menos un ámbito.
  • No se otorgará una señal OAuth a menos que se configure un ámbito predeterminado en el proveedor, o que se incluyan uno o más ámbitos predefinidos en la solicitud de concesión.
  • Si no se define ningún ámbito predeterminado y la solicitud no contiene un ámbito, se devuelve un error de ámbito no válido para la solicitud.

Proveedor de OAuth

Para proporcionar un soporte más refinado para el manejo del alcance de OAuth, permite que la extensión de registro de usuario Authentication URL mod ifique el valor del alcance.

Cuando define un proveedor OAuth, las extensiones Comprobación de ámbito avanzada proporcionan la flexibilidad para comprobar y alterar temporalmente los ámbitos permitidos. Las extensiones opcionales son Comprobación de ámbito de aplicación y Comprobación de ámbito de propietario.

El ámbito que finalmente recibe la aplicación viene determinado por las interacciones que se describen en los tres párrafos siguientes. El proceso de ámbito sigue la secuencia de los elementos 1, 2 y 3 de la lista siguiente, ofreciendo tres oportunidades para alterar temporalmente el valor de ámbito. La figura 1 ofrece una visión general del proceso.

  1. Después de que la aplicación se autentique correctamente, y si se ha configurado proveedor nativo OAuth > Comprobación de ámbito avanzada > Comprobación de ámbito de aplicación , API Connect realiza una llamada para permitir una verificación adicional y utiliza el contenido de x-selected-scope para alterar temporalmente el valor de ámbito solicitado inicialmente por la aplicación. Cuando la comprobación del ámbito de aplicación está habilitada, el encabezado de respuesta x-selected-scope de HTTP debe estar presente o la llamada fallará.
  2. Si el proveedor nativo de OAuth > Seguridad de usuario > Autenticación está configurado para autenticar a los usuarios de la aplicación mediante un Registro de autenticación ( URL ), entonces API Connect realiza una llamada, como se documenta en Registro de usuario de Autenticación ( URL ). Cuando el código de respuesta esHTTP 200, y la cabecera de respuesta x-selected-scope está presente, el valor que se ha configurado en x-selected-scope se utiliza como el nuevo valor de ámbito, alterando temporalmente lo que la aplicación ya ha solicitado y lo que se ha proporcionado en la comprobación de ámbito de aplicación descrita en el párrafo 1. En la cabecera de respuesta, x-selected-scope es un elemento opcional.
  3. Una vez que el usuario se autentica correctamente, y si Proveedor nativo de OAuth > Verificación de alcance avanzada > Verificación de alcance del propietario está habilitado y configurado con una URL válida, API Connect hace un llamado para permitir el contenido de x-selected-scope para refinar el valor del alcance. Cuando la comprobación del ámbito del propietario está habilitada, el encabezado de respuesta x-selected-scope de HTTP debe estar presente o la llamada fallará.
    Figura 1. Visión general del ámbito avanzado de OAuth
    Visión general del ámbito avanzado de OAuth.

El permiso de ámbito final otorgado por la señal de acceso es el resultado del flujo descrito en los elementos 1, 2 y 3. La Figura 2 muestra una vista más detallada del flujo de transacciones con ejemplos que muestran cuándo x-selected-scope proporciona un nuevo valor de ámbito.

Figura 2. Detalle de ámbito avanzado de OAuth
Detalle de ámbito avanzado de OAuth.

Imposición de API de consumidor

Validación de ámbito estándar
Para acceder a la API /getaccount , la aplicación debe enviar una solicitud GET con una señal de acceso que contenga el ámbito, o los ámbitos, definidos en el proveedor OAuth. Si la solicitud no contiene un ámbito, debe especificar un ámbito predeterminado a utilizar. Si no se define ningún ámbito predeterminado y la solicitud no contiene un ámbito, se devuelve un error de ámbito no válido para la solicitud.
GET /getaccount
HTTP/1.1
Host: server.example.com
X-IBM-Client-Id: 8888-8888-8888
Authorization: Bearer AAEkNjVkOWIyYjgtOWY5ZS00YWQwLWIyYzktZ
El siguiente archivo OpenAPI secure-banking.yaml de la aplicación define el ámbito, o ámbitos, que deben existir en la señal para que se le otorgue acceso a la API /getaccount.
secure-banking.yaml

securityDefinitions:
   scope-only:
    type: oauth2
    description: ''
    flow: implicit
    authorizationUrl: ''
    scopes:
      checking: 'Checking Account'
      saving: 'Saving Account'
      mutual: 'Mutual Fund Account'
security:
  - scope-only:
      - checking
  - scope-only:
      - saving
      - mutual
En los ejemplos, la señal de acceso AAEkNjVkOWIyYjgtOWY5ZS00YWQwLWIyYzktZ puede acceder a la API porque contiene una o una combinación de scope-only definida en secure-banking.yaml como, por ejemplo:
  • checking
  • saving mutual
  • checking saving mutual
Comprobación de ámbito avanzada

Los administradores pueden habilitar una comprobación de alcance adicional configurando la propiedad API del consumidor Advanced Scope Check URL que se convierte en x-scopeValidate como se muestra en el siguiente OpenAPI.

securityDefinitions:
  advanced-scope-only:
    type: oauth2
    description: ''
    flow: implicit
    authorizationUrl: ''
    scopes:
      checking: 'Checking Account'
      saving: 'Saving Account'
      mutual: 'Mutual Fund Account'
    x-scopeValidate:
      url: 'https://advanced-scope-check.bk.com/validate-scope'
      tls-profile: 'ssl-client'

Después de verificar correctamente la señal de acceso con respecto a cualquier requisito de ámbito, realizará una solicitud HTTP POST al punto final x-scopeValidate similar al ejemplo siguiente. Código de respuestaHTTP 200desde el punto final indica un éxito. Cualquier otro código de respuesta, o un error de conexión, se trata como un error de permiso para la señal.

     POST /validate-scope?app-name=..&appid=..&org=..&orgid=..&catalog=..&catalogid=..&transid=.. 
HTTP/1.1
     Host: advanced-scope-check.bk.com
     Content-Type: application/json

   {"context-root" : checking,
    "resource" : accountinfo,
    "method" : GET,
    "api-scope-required" : [jointaccount],
    "access_token" : {"client_id" : "2cd71759-1003-4a1e-becb-0474d73455f3",
                      "not_after" : 174364070,
                      "not_after_text" : "2017-07-11T02:27:50Z",
                      "not_before" : 174360470,
                      "not_before_text" : "2017-07-11T01:27:50Z",
                      "grant_type" : "code",
                      "consented_on" : 1499736470,
                      "consented_on_text" : "2059-07-11T01:27:50Z",
                      "resource_owner" : "cn=spoon,email=spoon@poon.com",
                      "scope" : "jointaccount mutual",
                      "miscinfo" : "[r:gateway]"
                    }
}
A continuación se muestra un ejemplo de respuesta satisfactoria.
     HTTP/1.1 200 OK
     Cache-Control: no-store
     Pragma: no-cache
     X-Custom-For-Assemble-Process: audit

Cualquier encabezado de respuesta de HTTP que comience con «x- » se conserva como la variable de contexto oauth.advanced-consent. Basándose en la respuesta satisfactoria de ejemplo, X-Custom-For-Assemble-Process: audit se convierte enoauth.advanced-consent.x-custom-for-assemble-processy se puede acceder a él en el paso de ensamblaje.

Opciones de validación adicionales

Opcionalmente, puede utilizar campos adicionales para la validación:

Cabecera de solicitud
Define la expresión regular que debe coincidir con las cabeceras request . Las cabeceras coincidentes se incluyen en la solicitud al punto final de validación de ámbito avanzado.
Variable de contexto de respuesta

Define la expresión regular que debe coincidir con las cabeceras response . Las cabeceras coincidentes se guardan como variables de contexto con el formato oauth.advanced-consent.*.