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:
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.
||Denotes the kind of credential that Criipto will return (
||Your application’s Client ID. You can find this value in the Criipto Verify UI in the settings for actual application|
||The URL to which Criipto will redirect the browser after authentication has been completed. The authorization code and the
Warning: Per the OAuth 2.0 Specification, Criipto removes everything after the hash and does not honor any fragments.
||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
||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.|
||(optional) Specifies how you want your result delivered via the
Default values are
||(optional but recommended) An opaque arbitrary alphanumeric string your app adds to the initial request that Criipto includes when redirecting back to your application.|
||(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
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>
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_SECRET, respectively, before constructing the
Authorization header in
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
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).