API reference

Authorization

Cleverbase’s Identity Federation service uses OAuth 2.0 for authorization.

GET /oauth2/authorize

• RFC 6749
• OpenID Connect

Description

Starts the OAuth 2.0 authorization server using an Authorization Code flow, as described in Section 1.3.1 of RFC 6749.
The authorization is returned in the form of an authorization code, which the client SHALL then use to obtain an access token (and id_token) with the oauth2/token method.

Input Parameters

Response

Error response cases

Examples

• Service Scope Request

  Minimal request for login only:

  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

• Extended Scope Request

  Requesting 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

• Service Scope Response

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

• Error Response

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

POST /oauth2/token

• RFC 6749
• OpenID Connect

Description

Obtain an OAuth 2.0 bearer access token and ID token from the authorization server by passing the authorization code returned by the authorization server after a successful user authentication, along with the used scope, the client ID and client secret in possession of the client application.

Input Parameters

Input Headers

Response

Examples

• Sample Request

  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>

• Sample Response

  Example response when original OAuth/authorize request only contains "openid":

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

  Example response when original OAuth/authorize request contained the following scopes "openid email com.cleverbase.personal_info com.cleverbase.id_number":

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

ID token validation

Clients MUST validate the ID Token in the Token Response in accordance with OIDC ch. 3.1.3.7.

Missing claims

When claims cannot be shared but are requested by the client, the fields will be omited from the id_token and userinfo response in line with OpenID Connect Specification 3.3.3.6. This means that clients SHOULD expect not all requested claims to be present in the id_token and userinfo response.

User information

The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint using an Access Token obtained through OpenID Connect Authentication. These Claims are represented by a JSON object that contains a collection of name and value pairs for the Claims.

Note: when this endpoint is used for IDF then optional scopes are required otherwise only a pairwise pseudonymous identifier for the natural person user is returned. See scopes and claims for details

See for more information: OpenID Connect.

GET /userinfo

Input headers

Response

Sample request

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

Sample response

Example response when the original oauth/authorize request only contained the “openid” scope (login functionality only)

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

Example response when the original oauth/authorize request contained the scopes “openid email com.cleverbase.personal_info com.cleverbase.id_number”:

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