Scope

OAuth-provider

Om de ondersteuning voor de verwerking van OAuth-scopes verder te verfijnen, zorgt API Connect ervoor dat de extensie Een gebruikersregister met verificatie-URL de mogelijkheid krijgt om de waarde van de scope te wijzigen.

Als u een OAuth-provider definieert, bieden extensies van het type Geavanceerde scopecontrole de flexibiliteit om toegestane scopes te controleren en te overschrijven ("override"). De optionele extensies zijn Controle van toepassingsscope en Controle op eigenaarsscope.

Welke scope er uiteindelijk door de toepassing wordt ontvangen, wordt bepaald door de interacties die in de volgende drie alinea's worden beschreven. Bij de verwerking van scopes wordt de volgorde van de alinea's 1, 2 en 3 aangehouden, zodat er dus drie kansen zijn voor "override" van de waarde van de scope. Figuur 1 geeft een overzicht van het proces.

1. Als de toepassing kan worden geverifieerd en als Native OAuth-provider > Geavanceerde scopecontrole > Controle van toepassingsscope geconfigureerd is, doet API Connect een aanroep om extra verificatie mogelijk te maken. Vervolgens wordt de inhoud van x-selected-scope gebruikt voor de "override" van de scopewaarde die oorspronkelijk door de toepassing was aangevraagd. Als Controle van toepassingsscope ingeschakeld is, moet de HTTP-responsheader x-selected-scope aanwezig zijn, anders mislukt de aanroep.

2. Als Native OAuth-provider > Gebruikersbeveiliging > Verificatie zó geconfigureerd is dat toepassingsgebruikers worden geverifieerd met behulp van een verificatie-URL, doet API Connect een aanroep zoals gedocumenteerd in Een gebruikersregister met verificatie-URL. Als de responscode HTTP 200 is en als de responsheader x-selected-scope aanwezig is, wordt de in x-selected-scope geconfigureerde waarde gebruikt als nieuwe waarde voor de scope. Daarmee wordt niet alleen datgene wat de toepassing al heeft aangevraagd overschreven, maar ook datgene wat is aangeleverd in de controle van de toepassingsscope, zoals beschreven in alinea 1. In de responsheader is x-selected-scope een optioneel element.

3. Als de gebruiker kan worden geverifieerd en als Native OAuth-provider > Geavanceerde scopecontrole > Controle eigenaarsscope ingeschakeld is en geconfigureerd is met een geldige URL, doet API Connect een aanroep waarmee de inhoud van x-selected-scope wordt gebruikt om de waarde van de scope te verfijnen. Als Controle eigenaarsscope ingeschakeld is, moet de HTTP-responsheader x-selected-scope aanwezig zijn, anders mislukt de aanroep.

Figuur 1. Overzicht van geavanceerde OAuth-scope

De uiteindelijke scopemachtiging wordt verleend door het toegangstoken dat het resultaat is van de in de alinea's 1, 2 en 3 beschreven stroom. Figuur 2 geeft een gedetailleerder beeld van de transactiestroom met voorbeelden die aangeven wanneer x-selected-scope een nieuwe scopewaarde aanlevert.

Figuur 2. Details van geavanceerde OAuth-scope

Afdwinging van consument-API

GET /getaccount
HTTP/1.1
Host: server.example.com
X-IBM-Client-Id: 8888-8888-8888
Authorization: Bearer AAEkNjVkOWIyYjgtOWY5ZS00YWQwLWIyYzktZ

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

De beheerder kan nog een extra scopecontrole instellen, namelijk door de eigenschap voor de geavanceerde scopecontrole-URL van de consument-API te configureren. Dit wordt dan x-scopeValidate, zoals te zien is in het volgende voorbeeld van een OpenAPI-bestand.

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'

Nadat het toegangstoken door API Connect is geverifieerd op basis van alle scopevereisten, doet API Connect een HTTP POST-aanvraag bij het eindpunt x-scopeValidate, ongeveer zoals in het volgende voorbeeld. Responscode HTTP 200 van het eindpunt wijst op succes. Elke andere responscode en elke verbindingsfout wordt beschouwd als een machtigingsfout voor het token.

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

     HTTP/1.1 200 OK
     Cache-Control: no-store
     Pragma: no-cache
     X-Custom-For-Assemble-Process: audit

Elke HTTP-responsheader die met "x-" begint, wordt bewaard als de contextvariabele oauth.advanced-consent. Uitgaande van het voorbeeld van een geslaagde respons wordt X-Custom-For-Assemble-Process: audit vervolgens oauth.advanced-consent.x-custom-for-assemble-process, toegankelijk in de assemblagestap.

Desgewenst kunt u extra velden voor validatie gebruiken:

Aanvraagheader

Definieert de expressie waarmee aanvraagheaders (request headers) worden vergeleken. Overeenkomende headers worden opgenomen in de aanvraag die naar het geavanceerde scopevalidatie-eindpunt gaat.

Contextvariabele voor respons

Definieert de expressie waarmee responsheaders worden vergeleken. Overeenkomende headers worden opgeslagen als contextvariabelen, met de notatie oauth.advanced-consent.*.