API reference

Autorisatie

De Identity Federation-dienst van Cleverbase gebruikt OAuth 2.0 voor autorisatie.

GET /oauth2/authorize

• RFC 6749
• OpenID Connect

Omschrijving

Start de OAuth 2.0-autorisatieserver met een Authorization Code flow, zoals beschreven in sectie 1.3.1 van RFC 6749.
De autorisatie komt terug als authorization code, die de client vervolgens MOET gebruiken om met de methode oauth2/token een access token (en id_token) op te halen.

Input parameters

Antwoord

Foutgevallen

De kolom hieronder bevat de tekst die de gebruiker te zien krijgt, en die blijft daarom onvertaald staan zoals hij is.

Voorbeelden

• Verzoek met alleen de service-scope

  Minimaal verzoek voor alleen inloggen:

  GET /oauth2/authorize?
  response_type=code&
  client_id=<OAuth2_client_id>&
  redirect_uri=<OAuth2_redirect_uri>&
  scope=openid&
  lang=en-US&
  state=12345678&
  nonce=54321

• Verzoek met uitgebreide scopes

  Met de IDF-scopes "openid email com.cleverbase.personal_info com.cleverbase.id_number":

  GET /oauth2/authorize?
  response_type=code&
  client_id=<OAuth2_client_id>&
  redirect_uri=<OAuth2_redirect_uri>&
  scope=openid email com.cleverbase.personal_info com.cleverbase.id_number&
  lang=en-US&
  state=12345678&
  nonce=54321

• Antwoord met alleen de service-scope

  HTTP/1.1 302 Found
  Location: <OAuth2_redirect_uri>?
  code=FhkXf9P269L8g&
  state=12345678

• Foutantwoord

  HTTP/1.1 302 Found
  Location: <OAuth2_redirect_uri>?error=invalid_request&
  error_description=Invalid%20Authorization%20Code

POST /oauth2/token

• RFC 6749
• OpenID Connect

Omschrijving

Haal bij de autorisatieserver een OAuth 2.0 bearer access token en een ID token op, door de authorization code mee te sturen die de server na een geslaagde authenticatie teruggaf, samen met de gebruikte scope en het client-id en client secret die de clientapplicatie heeft.

Input parameters

Input headers

Antwoord

Voorbeelden

• Voorbeeldverzoek

  POST /oauth2/token HTTP/1.1
  Authorization: Basic K3dfKT59SUD8gWghq1ghjuZ
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code&
  code=<RESULT_FROM_/oauth2/authorize>&
  client_id=<OAuth2_client_id>&
  client_secret=<OAuth2_client_secret>&
  redirect_uri=<OAuth2_redirect_uri>

• Voorbeeldantwoord

  Voorbeeld wanneer het oorspronkelijke verzoek aan oauth2/authorize alleen "openid" bevatte:

  {
    "access_token": "f0EigERuAYruavv2fwRc4ZJKn1x1Uef8ymarsCqKfJw...",
    "expires_in": 3600,
    "id_token": "<ID_TOKEN_JWT_CONTENT>",
    "scope": "openid",
    "token_type": "bearer"
  }

  Voorbeeld wanneer dat verzoek de scopes "openid email com.cleverbase.personal_info com.cleverbase.id_number" bevatte:

  {
    "access_token": "rxdF-27ehy4LFSUsh32gVDfN9QpdwqDu-3ZtbVsx5J8...",
    "expires_in": 3600,
    "id_token": "<ID_TOKEN_JWT_CONTENT>",
    "scope": "openid email com.cleverbase.personal_info com.cleverbase.id_number",
    "token_type": "bearer"
  }

Het ID token valideren

Clients MOETEN het ID token in het tokenantwoord valideren volgens OIDC hfst. 3.1.3.7.

Ontbrekende claims

Als een claim wel is opgevraagd maar niet gedeeld kan worden, valt het veld weg uit het id_token en uit het antwoord van userinfo, conform OpenID Connect Specification 3.3.3.6. Clients MOETEN er dus rekening mee houden dat niet alle opgevraagde claims in het id_token en het antwoord van userinfo aanwezig zijn.

Gebruikersinformatie

Het UserInfo-endpoint is een OAuth 2.0 Protected Resource die claims teruggeeft over de geauthenticeerde eindgebruiker. Om die claims op te halen doet de client een verzoek aan het UserInfo-endpoint met een access token dat via OpenID Connect-authenticatie is verkregen. De claims komen terug als JSON-object met naam-waardeparen.

Let op: wordt dit endpoint voor IDF gebruikt, dan zijn de optionele scopes nodig. Anders komt alleen een pairwise pseudonieme identifier voor de natuurlijke persoon terug. Zie scopes en claims voor de details.

Meer informatie: OpenID Connect.

GET /userinfo

Input headers

Antwoord

Voorbeeldverzoek

GET /userinfo HTTP/1.1
Authorization: Bearer 4/CKN69L8gdSYp5_pwH3XlFQZ3ndFhkXf9P2_TiHRG-bA
Content-Type: application/json

Voorbeeldantwoord

Voorbeeld wanneer het oorspronkelijke verzoek aan oauth2/authorize alleen de scope "openid" bevatte (dus alleen inloggen):

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "aud": [
        <client_id>
    ],
    "auth_time": 1650458268,
    "iat": 1650458274,
    "iss": "https://esign.acc.cleverbase.com/",
    "rat": 1650458253,
    "sub": "bf70e2da-feff-4c6b-86c2-47eda199ab30"
}

Voorbeeld wanneer dat verzoek de scopes "openid email com.cleverbase.personal_info com.cleverbase.id_number" bevatte:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "aud": [
        <client_id>
    ],
    "auth_time": 1650459478,
    "birthdate": "1990-12-22",
    "com.cleverbase.birthplace": "Rome",
    "com.cleverbase.document.type": "NLD_PASSPORT",
    "com.cleverbase.id_number": "XWN75IM16",
    "com.cleverbase.last_name": "De Bruijn",
    "com.cleverbase.nationality": "NLD",
    "email": "demo.acc.190422.102459@cleverbase.com",
    "email_verified": true,
    "given_name": "Willeke Liselotte",
    "iat": 1650459485,
    "iss": "https://esign.acc.cleverbase.com/",
    "rat": 1650459462,
    "sub": "bf70e2da-feff-4c6b-86c2-47eda199ab30"
}