OpenID Connect Interface Version 2
This version of the OpenID Connect (OIDC) interface provides a consolidated set of endpoints that supports request payloads via Pushed Authorisation Request (PAR) and non-PAR requests for both issuance and verification flows.
It is available in Cenda from V5.0.0 upwards.
Note
Condatis recommend that Version 2 of the OIDC interface is adopted by Relying Party applications as it is intended that Version 1 will be deprecated in due course.
OIDC Endpoints
The endpoints supported are:
GET OpenID Configuration requestPOST Pushed Authorisation RequestGET AuthorisePOST Token
OpenID Provider Configuration
The OpenID Provider Configuration endpoint returns a JSON document containing the other endpoint URIs and the configuration required to request and validate tokens from Cenda.
Example OpenID Configuration request
GET /v2.0/.well-known/openid-configuration
Example OpenID Configuration response
HTTP/1.1 200 OK
Content-Type: application/json
{
"pushed_authorization_request_endpoint": "https://loctest.ccg.condatis.com/v2.0/oidc/par",
"authorization_endpoint": "https://loctest.ccg.condatis.com/v2.0/oidc/authorize",
"token_endpoint": "https://loctest.ccg.condatis.com/v2.0/oidc/token",
"jwks_uri": "https://loctest.ccg.condatis.com/v2.0/.well-known/openid-configuration/jwks",
"response_modes_supported": [
"query"
],
"id_token_signing_alg_values_supported": [
"RS256"
],
"response_types_supported": [
"code"
],
"require_pushed_authorization_requests": false,
"issuer": "https://loctest.ccg.condatis.com",
"grant_types_supported": [
"authorization_code"
],
"token_endpoint_auth_methods_supported": [
"client_secret_post"
],
"subject_types_supported": [
"public"
],
"request_parameter_supported": false
}
Pushed Authorisation Request (PAR)
When using PAR to issue or verify credentials the OIDC PAR endpoint must be called before calling the authorise endpoint. All the details for the issuance or verification are included in the request that is made to the PAR endpoint.
PAR Payload Request Definition
| Parameter | Description |
|---|---|
| scope | Defines the VC definition to be used for issuance or verification. The 'External' scope can be used to identify in the request that an External Client flow is required. |
| id_token_hint | JWT that contains the data to be used in the issued VC as specified atID Token Hint |
| client_id | The client_id as defined in Cenda for the issuer |
| client_secret | The client secret associated with the client_id in Cenda. |
| response_type | Must becode. Only authorisation code flow is supported. |
| redirect_uri | The redirect URI of your app, where authentication responses can be sent and received by your app. It must exactly match one of the redirect URIs registered in Cenda for the issuer. |
| nonce | A value included in the request, generated by the app, that will be included in the resulting id_token value as a claim. The app can verify this value to mitigate token replay attacks. The value typically is a randomized, unique string that can be used to identify the origin of the request. |
| response_mode | Must bequery if provided. Only query string response mode is supported. |
| state | A value included in the request that also will be returned in the token response. It can be a string of any content you want. A randomly generated unique value typically is used to prevent cross-site request forgery attacks. The state also is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view the user was on. The state is also used within the External Client flows and included within clients webhook calls so these webhooks can be assoicated with the original request and thus is required for these flows. |
| code_challenge_method | Defines the method for Proof of Key Code Exchange when the client is configured for PKCE support. It must be "plain" or "S256". |
| code_challenge | Defines the code challenge for PKCE validation when the client is configured for PKCE support. |
Scope
For issuance flows the scope must have the format issue.[CredentialType], where [CredentialType] is one of the configured credential types in Cenda. Exactly one issue-scope must be present in the request. It MUST contain the 'openid' scope.
For verification flows the scope must have the format [CredentialType], where [CredentialType] is one of the configured credential types in Cenda. Multiple [CredentialType] can be present in the request. It MUST contain the 'openid' scope.
For Yoti identity verification flow the scope must be VerifiedIdentity and MUST contain the 'openid' scope.
For Onfido identity verification flow the scope must be VerifiedIdentity_Onfido and MUST contain the 'openid' scope.
ID Token Hint
The id_token_hint should only be provided for issuance flows.
The id_token_hint provided in the PAR payload should contain the attributes to be issued in the credential. Each custom claim is mapped into credential attribute when issuing the credential.
The token must be created following these rules:
- The
issclaim must be present and must match the issuerclient_id. - The
audclaim must be present and must match the issuer URL of Cenda, as returned in the OpenID Configuration response. - The
expclaim must be present and indicate that the token has not expired at the time of making the request. - If present, the
nbfclaim must indicate that the token can be used at the time of making the request. - The token must be signed with the signing key that is registered with Cenda for this issuer.
Example id_token_hint:
{
"alg": "HS256",
"typ": "JWT"
}.{
"FirstName": "First",
"Surname": "Last",
"EmailAddress": "first.last@example.com",
"MobileNumber": "555-123456",
"Company": "Condatis",
"nbf": 1631263420,
"exp": 1646901820,
"iat": 1631263420,
"iss": "a8f48dc5-060a-4db3-b012-ad86ddfe692f",
"aud": "https://loctest.ccg.condatis.com"
}.[Signature]
ID Token Hint with PIN Code
Issuance can be protected with a PIN Code, which the issuer will include in the ID Token Hint and provide to the credential recipient using an appropriate secure medium.
In order to use PIN Code protection for issuance the 'pinCodeLength' must be configured in the associated issuance Credential Template.
The following rules apply for PIN Code issuance, and result in failure of the PAR request, or the authorise request for non-PAR flows:
- The
id_token_hintcan only include PinCode claim only when pinCodeLength is defined in the Credential Template. - The PinCode provided must be numeric.
- The length of the PinCode provided in the ID Token Hint must equal the pinCodeLength.
This is an example id_token_hint that includes a PinCode when the pinCodeLength is set to 4:
{
"alg": "HS256",
"typ": "JWT"
}.{
"FirstName": "First",
"Surname": "Last",
"EmailAddress": "first.last@example.com",
"MobileNumber": "555-123456",
"Company": "Condatis",
"PinCode": "1122",
"nbf": 1631263420,
"exp": 1646901820,
"iat": 1631263420,
"iss": "a8f48dc5-060a-4db3-b012-ad86ddfe692f",
"aud": "https://loctest.ccg.condatis.com"
}.[Signature]
Example Pushed Authorisation Request
POST /v2.0/oidc/par
Content-type: application/x-www-form-urlencoded
client_id=a8f48dc5-060a-4db3-b012-ad86ddfe692f
&client_secret=ca87bdc7e8834610a5426e2308080e8c1c251fbf768a4480a864f03d03fb0cbf
&response_type=code
&response_mode=query
&redirect_uri=https://jwt.ms
&scope=issue.EmployeeCredential
&nonce=91cfc3f8-05b8-40ff-b349-105da54ea59c
&state=f334765a-b511-48bd-919b-e54541293fef
&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJGaXJzdE5hbWUiOiJGaXJz...
PAR Response
PAR Response Definition
| Parameter | Description |
|---|---|
| request_uri | The request uri to be used when calling the authorise endpoint. |
| expires_in | The expiry time of the PAR request in seconds. After this time the request will be deleted and a new PAR request must be made. |
Example PAR Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"request_uri": "urn:ietf:params:oauth:request_uri:77b92f25-38a1-4787-b229-9cb9a7aa0d5a",
"expires_in": 60
}
PAR Error Responses
If an error is encountered during the PAR request validation an error response will be provided as per the table below.
| Parameter | Validation | Status Code | Error |
|---|---|---|---|
| ClientId | Client registered | 400 | unauthorised_client |
| ClientSecret | Client authentication | 400 | unauthorised_client |
| RedirectUri | Registered on client | 400 | invalid_request |
| Scope | Provided and registered | 400 | invalid_scope |
| ResponseType | Set to "code" | 400 | unsupported_response_type |
| ResponseMode | Set to "query" | 400 | invalid_request |
| IdTokenHint | Valid token hint | 400 | invalid_request |
Authorise Request
The OIDC authorise endpoint is accessed by a user agent to display a prompt to the user. Once the authorisation is complete, the user agent will be redirected to the redirect_uri specified in the original request.
Authorise Request Definition
The URI used by the user agent when making a request to the authorise endpoint must include the following query string parameters.
| Parameter | Condition | Description |
|---|---|---|
| client_id | Required | client_id as defined in Cenda for the issuer or verifier client. If the request is authorisation by PAR this must match theclient_id used when calling the PAR endpoint. |
| request_uri | PAR only | The request_uri received in the response when calling the PAR endpoint. |
| response_type | Required for non-PAR | Must becode . Only authorisation code flow is allowed. |
| redirect_uri | Required for non-PAR | The redirect URI of your app, where authentication responses can be sent and received by your app. It must exactly match one of the redirect URIs you registered in the portal. |
| nonce | Required for non-PAR | A value included in the request, generated by the app, that will be included in the resulting id_token value as a claim. The app can verify this value to mitigate token replay attacks. The value typically is a randomised, unique string that can be used to identify the origin of the request. |
| response_mode for non-PAR | Optional for non-PAR | Must bequery if provided. Only query string response mode is supported. |
| scope | Required for non-PAR | defines the VC definition as defined below. The 'External' scope can be used to identify in the request that an External Client flow is required. |
| state | Recommended for non-PAR | A value included in the request that also will be returned in the token response. It can be a string of any content you want. A randomly generated unique value typically is used to prevent cross-site request forgery attacks. The state also is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view the user was on. The state is also used within the External Client flows and included within clients webhook calls so these webhooks can be assoicated with the original request and thus is required for these flows. |
| code_challenge_method | Required for non-PAR | 'S256' or 'plain' |
| code_challenge | Required for non-PAR | Code challenge is generated from code verifier - SHA hash if the method is 'S256', or same as code verifier if the method is 'plain' |
| context_id | Onfido for non-PAR and External client flows for both PAR and Non-PAR | The ContextId needed to continue an Onfido journey or to retrieve the final token in an External flow once its recieved from the 'ContinuationContext' in the client's webhook call. |
Example Authorise Request (PAR)
GET /v2.0/oidc/authorize
?client_id=a8f48dc5-060a-4db3-b012-ad86ddfe692f
&request_uri=urn:ietf:params:oauth:request_uri:77b92f25-38a1-4787-b229-9cb9a7aa0d5a
Example Authorise Request (non-PAR)
GET /v2.0/oidc/authorize?
client_id=0e16e809-5f6e-4d74-b054-8491fdfbdcc6
&redirect_uri=https://{redirecturi}/signin-oidc
&response_type=code
&scope=openid Scope1
&code_challenge=gObHCtOmFwJytgmX2waFeMLiL7Wnz0BPG26T8PtbnDM
&code_challenge_method=S256
&response_mode=query
&nonce=637539811036888192.......
&state=CfDJ8MMeKOZ1un5........
&context_id=...
Authorise Response
After successfully issuing the credential, Cenda will redirect a browser to the specified redirect_uri with the authorisation code.
Authorise Response Definition
The URI the user agent will be redirected to will include the following query string parameters.
| Parameter | Description |
|---|---|
| code | The authorisation code that can be exchanged for an id_token using the token endpoint. |
| state | If a state parameter is included in the request, the same value will be included in the redirect location of the response. The app should verify that the state values in the request and response are identical. |
Example Authorise Response
HTTP/1.1 302 Found
Location: https://jwt.ms/
?code=2FA79872A5797A92DBB259E0856276828A2374664D05CBCB1A0B434BF06C79174E1A5
&state=f334765a-b511-48bd-919b-e54541293fef
Authorise Error Responses
If an error is encountered during the Authorise request processing an error response will be provided as per the table below. If the provided redirect URI has been validated then Cenda will redirect to the the URI provided with the error provided as a query string parameter. If the provided redirect URI has not been validated then Cenda will provide the response indicated with the error provided in the response body.
| Parameter | Validation | Error Response | Error Type |
|---|---|---|---|
| client_id | Not in PAR request and registered | 400 | invalid_request |
| request_uri | PAR request valid | 400 | invalid_request |
| RedirectUri | Registered in PAR request and client | 400 | invalid_request |
| Scope | Registered in PAR request and client | redirected | invalid_scope |
| IdTokenHint | Valid token hint | redirected | invalid_request |
| TokenHint Claims | Match credential template | redirected | invalid_scope |
| TokenHint Image | Images are valid | redirected | invalid_request |
| code_challenge_method | PKCE method not supported when PKCE required | redirected | invalid_request |
| code_challenge | code challenge not provided when PKCE required | redirected | invalid_request |
Token Request
The OIDC Token endpoint can be used to exchange the authorisation code for an id_token.
Token Request Definition
| Parameter | Description |
|---|---|
| grant_type | Supported grant type isauthorization_code |
| client_id | The client_id as defined in Cenda for the issuer. This must match theclient_id used when calling the PAR endpoint. |
| client_secret | The client_secret as defined in Cenda for the issuer |
| code | The authorisation code returned from the authorise call |
| redirect_uri | The redirect URI defined in Cenda for the issuer. This must match theredirect_uri used when calling the PAR endpoint. |
| code_verifier | The code verifier for Proof of Key Code Exchange validation when PKCE required on the client. |
Example Token Request
POST /v2.0/oidc/token
Content-type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=a8f48dc5-060a-4db3-b012-ad86ddfe692f
&client_secret=ca87bdc7e8834610a5426e2308080e8c1c251fbf768a4480a864f03d03fb0cbf
&code=2FA79872A5797A92DBB259E0856276828A2374664D05CBCB1A0B434BF06C79174E1A5
&redirect_uri=https://jwt.ms
Token Response
The response from a token endpoint includes an id_token with claims that match the attributes of the issued credential.
Definition
| Parameter | Description |
|---|---|
| id_token | The ID token containing the issued credential attributes. |
| scope | The scope used in the initial PAR request |
| access_token | A JWT token that is the same as the id_token |
| token_type | The token type will always be 'Bearer' |
| expires_in | The time to expiry of the token in seconds. |
Example Token Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id_token": "eyJhbGciOiJS...",
"scope": "issue.EmployeeCredential",
"access_token": "eyJhbGciOiJS...",
"token_type": "Bearer",
"expires_in": "60"
}
An example id_token contents:
{
"alg": "RS256",
"typ": "JWT",
"kid": "59BA95564A924BA093FBE5473B520F52"
}.{
"FirstName": "First",
"Surname": "Last",
"EmailAddress": "first.last@example.com",
"MobileNumber": "555-123456",
"Company": "Condatis",
"SerialNumber": "ad157828-3827-4c12-b4c4-aca24bd63226",
"ExpiresAt": "2022-09-15T16:25:40.7141508Z",
"nbf": 1631723149,
"exp": 1631726749,
"iat": 1631723149,
"iss": "https://loctest.ccg.condatis.com/oidc",
"aud": "a8f48dc5-060a-4db3-b012-ad86ddfe692f"
}.[Signature]
Token Error Responses
If an error is encountered during the Token request processing an error response will be provided as per the table below.
| Parameter | Validation | Status Code | Error |
|---|---|---|---|
| GrantType | Equals authorization_code | 400 | unsupported_grant_type |
| Code | Provided | 400 | invalid_request |
| Code | Invalid code | 400 | invalid_grant |
| ClientId | Matches code request content | 400 | invalid_client |
| ClientId | Client authentication | 400 | unauthorised_client |
| ClientSecret | Client authentication | 400 | unauthorised_client |
| RedirectUri | Matches code request content | 400 | invalid_grant |
| Code Challenge | PKCE code challenge fails | 400 | invalid_grant |