OpenID Connect Interface Version 1

This version of the OpenID Connect (OIDC) interface provides two sets of endpoints: one set that supports request payloads via Pushed Authorisation Request (PAR) and one that supports non-PAR requests. It is available in all versions of Cenda.

PAR endpoints can be used for both Issuance and Verification flows.

Non-PAR endpoints can only be used for Verification flows.

Note

Condatis recommend that if you are using Version 1 of the OIDC interface that you upgrade to Version 2 to ensure fuller compliance with the OIDC standards. It is intended that Version 1 will be deprecated in due course.

PAR Authorisation

The endpoints that Cenda supports to provide PAR support are:

  • GET OpenID Configuration request (PAR specific)
  • POST Pushed Authorisation Request
  • GET Authorise (PAR specific)
  • POST 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 /oidc/.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/oidc/par",
  "authorization_endpoint": "https://loctest.ccg.condatis.com/oidc/authorize",
  "token_endpoint": "https://loctest.ccg.condatis.com/oidc/token",
  "jwks_uri": "https://loctest.ccg.condatis.com/oidc/.well-known/openid-configuration/jwks",
  "response_modes_supported": [
    "query"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "response_types_supported": [
    "code"
  ],
  "require_pushed_authorization_requests": true,
  "issuer": "https://loctest.ccg.condatis.com/oidc",
  "grant_types_supported": [
    "authorization_code"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post"
  ]
}

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 Definition

Parameter Description
scope Defines the VC definition to be used for issuance or verification.
id_token_hint JWT that contains the data to be used in the issued VC as specified at ID 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 be code. 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 be query. 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.

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 NOT 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 iss claim must be present and must match the issuer client_id.
  • The aud claim must be present and must match the issuer URL of Cenda, as returned in the OpenID Configuration response.
  • The exp claim must be present and indicate that the token has not expired at the time of making the request.
  • If present, the nbf claim 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 before

{
  "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/oidc"
}.[Signature]

Example PAR Request

POST /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 By PAR

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 Description
client_id The client_id as defined in Cenda for the issuer. This must match the client_id used when calling the PAR endpoint.
request_uri The request_uri received in the response when calling the PAR endpoint.

Example Authorise Request

GET /oidc/authorize
    ?client_id=a8f48dc5-060a-4db3-b012-ad86ddfe692f
    &request_uri=urn:ietf:params:oauth:request_uri:77b92f25-38a1-4787-b229-9cb9a7aa0d5a

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

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 is authorization_code
client_id The client_id as defined in Cenda for the issuer. This must match the client_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 the redirect_uri used when calling the PAR endpoint.

Example Token Request

POST /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 authorisation_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

Non-PAR Request

The endpoints that Cenda supports to provide non-PAR Authorisation are:

  • GET OpenID Configuration request (non-PAR specific)
  • GET Authorise (non-PAR specific)
  • POST Token

Root 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 Root OpenID Configuration request

GET /.well-known/openid-configuration

Example OpenID Configuration response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "authorization_endpoint": "https://loctest.ccg.condatis.com/oidc/authorizev1",
  "token_endpoint": "https://loctest.ccg.condatis.com/oidc/token",
  "jwks_uri": "https://loctest.ccg.condatis.com/.well-known/openid-configuration/jwks",
  "response_modes_supported": [
    "query"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "response_types_supported": [
    "code"
  ],
  "issuer": "https://loctest.ccg.condatis.com/oidc",
  "grant_types_supported": [
    "authorization_code"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post"
  ],
  "subject_types_supported": [
    "public"
  ],
  "request_parameter_supported": false
}

Authorise by Non-PAR

The OIDC authorise endpoint for performing authorisation request using query string parameters.

Authorise Request Definition

Parameter Condition Description
client_id Required client_id as defined in Cenda for the verifier.
response_type Required Must be code . Only authorisation code flow is allowed.
redirect_uri Required 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 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 be query. Only query string response mode is supported.
scope Required defines the VC definition to be verified as defined below.
state Recommended 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.
code_challenge_method Required 'S256' or 'plain'
code_challenge Required Code challenge is generated from code verifier - SHA hash if method is 'S256', or same as code verifier if method is 'plain'
context_id Onfido only The ContextId needed to continue an Onfido journey

Example Authorise Request

GET /oidc/authorizev1?
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=...

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.

Authorise Response

After verifying Cenda will redirect a browser to the specified redirect_uri with the authorisation code which must be passed to the token endpoint to retrieve the token.

Authorise Response Definition

Parameter Description
code The code needed to call the token endpoint to receive the token.
state If a state parameter is included in the request, the same value will appear in 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://{redirecturi}/signin-oidc?
code=SplxlOBeZQQYbYS6WxSbIA
&state=af0ifjsldkj

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
ClientId Not provided 400 invalid_request
RedirectUri Registered in client 400 invalid_request
Scope Registered redirected invalid_scope
ResponseType Not provided redirected invalid_request
ResponseType Not "code" redirected unsupported_response_type
ResponseMode Not "query" redirected invalid_request

Token Request

The OIDC Token endpoint.

Token Request Definition

Parameter Description
grant_type Supported grant type is authorization_code.
client_id client_id as defined in Cenda for the issuer.
client_secret client_secret as defined in Cenda for the issuer.
code Code returned from the authorise call.
code_verifier The original code_verifier string of which the SHA-256 hash has been used as the code_challenge value in the authorise request.
redirect_uri The redirect URI defined in Cenda for the issuer.

Example Token Request

POST /oidc/token
Content-type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=11111111-1111-1111-1111-111111111111
&client_secret={{ClientSecret}}
&code={{code}}
&code_verifier={{codeVerifier}}
&redirect_uri=https://oidcappdevrelyingparty.azurewebsites.net/signin-oidc

Token Response

After verifying, Cenda will return a JWT token containing the attributes verified.

If an error occurs an authentication error as per OIDC spec will be returned.

Token Response Definition

Parameter Description
id_token The ID token containing the attributes of the VC requested.
scope The scope used in the initial authorise 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
Cache-Control: no-store
Pragma: no-cache
{
    "id_token": "eyJhbGciOiJIUzI1Ni......",
    "state": "CfDJ8MMeKOZ1un5........"
}

id_token body
{
    "nbf": 1599482515,
    "exp": 1600087315,
    "iss": "https://localhost",
    "aud": "a489fc44-3cc0-4a78-92f6-e413cd853eae"
    {claim} = ""
}

Error Response

Error Response Definition

Parameter Description
error When an error is encountered an invalid_request error will be returned to the caller

Example Error Response

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache

  {
   "error": "invalid_request"
  }

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