Using OpenID Connect to integrate vith Criipto Verify

Criipto Verify is integrated through the authentcation API which follows the OpenID Connect and OAuth2 specifications.

The following describes the two flows and introduces the parameters to configure the authentication and subsequent user information retrieval.

The full specification of Criipto Verify OAuth2 and OpenID Connect options will be provided in the coming API reference.

Authenticate the User

To begin the login flow, you will need to authenticate the user at the identity source indicated in your request.

To authenticate the user, your app must send the user to the OAuth2 authorization endpoint with the appropriate set of parameters.

You can find the URL for the OAuth2 authorization endpoint in the OpenID Connect Discovery Document exposed on your Criipto Verify Domain:

GET https://YOUR_SUBDOMAIN.criipto.id/.well-known/openid-configuration

The response from this endpoint is a JSON document, with an authorization_endpoint property. The corresponding property value is the URL of the OAuth2 authorization endpoint.

Example authentication URL

The following initiates the authentication through an OAuth2 authorization request:

GET https://YOUR_SUBDOMAIN.criipto.id/oauth2/authorize?
    response_type=code|id_token&
    client_id=CLIENT_ID&
    redirect_uri=YOUR_RETURN_URL&
    acr_values=CHOSEN_IDENTITY_SERVICE&
    scope=openid&
    state=YOUR_STATE

Note that providing response_type=code specifies that you want the back-channel authorization code flow, where as specifying response_type=id_token indicates that you want the implicit flow. In the implicit flow you receive the issued token in a query parameter on the return URL.

If you want to receive the id_token in another way you must specify the response_mode parameter, see below.

Parameters

Parameter name Description
response_type Denotes the kind of credential that Criipto will return (code or id_token). If you are integrating a traditional server based web application - back-channel flow - use code. Use id_token for single page applications using a front-channel flow
client_id Your application’s Client ID. You can find this value in the Criipto Verify UI in the settings for actual application
redirect_uri The URL to which Criipto will redirect the browser after authentication has been completed. The authorization code and the id_token will be available in the code and id_token URL parameter for the back-channel flow and on a URL query parameter for the front-channel flow. This URL must be pre-registered as a valid callback URL in your application settings.

Warning: Per the OAuth 2.0 Specification, Criipto removes everything after the hash and does not honor any fragments.
scope Specifies the scopes for which you want to request authorization, which dictate which claims (or user attributes) you want returned. These must be separated by a space. To get an ID Token in the response, you need to specify a scope of at least openid.
acr_values Identifies which e-ID identity service you want to use. You can only specify one value, and it must identify the exact type of identity service, as some countries have both e.g. a mobile and web based service. Possible values are listed here.
response_mode (optional) Specifies how you want your result delivered via the redirect_uri: Use query to return the code/id_token as a query parameter, fragment to have it delivered on a URL fragment, and finally form_post to have it posted back to your redirect_uri.

Default values are query for response_type=code and query for response_type=id_token.
state (optional but recommended) An opaque arbitrary alphanumeric string your app adds to the initial request that Criipto includes when redirecting back to your application.
login_hint (optional) Some e-ID types will prompt users for input such as phone number or SSN. To avoid this you may pass these data in the login_hint as described here.

As an example, your HTML snippet for your authorization URL when adding login to your app might look like:

<a href="https://acme-corp.criipto.id/oauth2/authorize?
  response_type=id_token&
  client_id=urn:debug:jwt.io&
  acr_values=urn:grn:authn:no:bankid&
  redirect_uri=https://jwt.io&
  scope=openid&
  state=etats">
  Sign in with Norwegian BankID
</a>

You can try the above URL right now if you have a test user for Norwegian BankID.

For more about how to handle the implicit flow, see below.

Response for code flow

For the code flow, when you used response_type=code, you will receive an HTTP 302 response which redirects your browser to your specified redirect_uri with the authorization code included at the end of the URL:

HTTP/1.1 302 Found
Location: YOUR_RETURN_URL?code=AUTHORIZATION_CODE&state=YOUR_STATE

Note that depending your your response_type you may also receive an id_token as a query parameter instead of the authorization code.

Exchange the code for a token

For the code flow you will need to exchange the returned code for an actual token. This is done by posting the authorization code received from the previous step to the token endpoint.

Note that you must use a HTML-form-style HTTP POST here, and preferably send the credentials in the Authorization HTTP header. You must also x-www-form-urlencode the values of the CLIENT_ID and CLIENT_SECRET, respectively, before constructing the Authorization header in Basic format.

HTTP POST https://YOUR_SUBDOMAIN.criipto.id/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <BASE64(xWwwFormUrlEncode(CLIENT_ID):xWwwFormUrlEncode(CLIENT_SECRET))>

grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_RETURN_URL

Note We do also support receiving the client credentials in the payload, but this usage is discouraged by the OAuth2 specification, and we strongly recommend that you send the credentials in the Authorization: Basic ... HTTP header value as described above.

The client id and secret are retrieved from the Criipto Verify management UI and the redirect_uri must be exactly the same you used in the authorization request in the previous step.

Response for implicit flow

In the implicit flow, when you asked for response_type=id_token, the token is returned directly to the application on a URL query parameter. If you are building a Single-Page Application, you can specify response_mode=fragment to get the id_token returned on the # part of the URL. This will ensure that the id_token is only available to the client, typically your Javascript in the browser.

Validate the response

You can now proceed with validating the returned JWT and access the contained end-user information. The validation step is required - if you do not validate the signature, you cannot trust the contained end-user information. We strongly recommend that you find a battle-hardened library for you specific platfrom to do this heavy lifting. The sample applications you can find here all adhere to this recommendation. If we do not have a sample for your particular technology stack, you can find an extensive list of libraries on jwt.io (scroll down to the Libraries for Token Signing/Verification section).