OIDC Clients
The CCG supports issuance and verification journeys as OIDC requests. OIDC client(s) must be created for an organisation to use in performing OIDC issuance and verification journeys. The use of clients can vary according to the organisation's needs but one of the following strategies will typically be used:
- A single client for all issuance and verification.
- One client for all issuance journeys and a second client for verification.
- Multiple clients that will group issuance and verification journeys as appropriate.
Add a new client for an organisation
A client is required to allow organisations to perform issuance and verification scenarios via the CCG interfaces.
When creating a client, you will also need to create a client secret and client signing key.
Information required to create a new client
Create client request endpoint
POST /api/client
Create client request headers
Header | Value |
---|---|
Authorization | Bearer access_token |
Create client request URL parameters
There are no URL parameters needed for this call.
Create client request body parameters
Parameter | Type | Required | Description |
---|---|---|---|
organisationId | string | Yes | The unique identifier for your organisation. |
name | string | Yes | The name of your client for ease of identification. |
redirectUris | string | No | The list of redirect URIs supported by your client. |
logoUrl | string | No | The URL where your logo is located. |
faviconUrl | string | No | The URL where your favicon icon is located. |
privacyUrl | string | No | The URL where your organisation's privacy statement is located. |
termsOfUseUrl | string | No | The URL where your organisation's terms of use statement is located |
supportedTemplateIds | string | No | The list of supported credential templates by ID. |
NOTE: The definition of "supportedTemplateIds" states that this field is "Not Required". This is the case for creating a client but to use a client for issuance or verification this must be populated with the appropriate credential template IDs (see Create Credential Templates for details).
Create client request body
POST {{GatewayHubUrl}}/api/client
Authorization: Bearer {{accessToken}}
Content-Type: application/json
{
"organisationId": "{{OrganisationId}}",
"name": "{{ClientName}}",
"redirectUris": ["{{ClientIssuanceRedirectUri}}"],
"logoUrl": "{{ClientLogoUrl}}",
"faviconUrl": "{{ClientFaviconUrl}}",
"privacyUrl": "{{ClientPrivacyUrl}}",
"termsOfUseUrl": "{{ClientTermsOfUseUrl}}",
"supportedTemplateIds": ["{{OrganisationId}}-{{CredentialTemplate}}-IssuanceCredentialTemplate"]
}
The settings {{Name}}, etc will need to be updated as appropriate in the request body, as illustrated in the following example.
{
"organisationId": "bd816d9c-9259-4069-a401-t351gc1b1023",
"name": "Condatis Issuance Client",
"redirectUris": [
"https://jwt.ms"
],
"logoUrl": "https://robohash.org/condatis?set=set4",
"faviconUrl": "https://robohash.org/condatis?set=set4",
"privacyUrl": "https://condatis.com/",
"termsOfUseUrl": "https://condatis.com/",
"supportedTemplateIds": [
"bd816d9c-9259-4069-a401-t351gc1b1023-TestCredential-IssuanceCredentialTemplate"
]
}
Create client request returns
A successful call will return a 201 Created status code and the created client as a JSON file. The call creates a clientId
value which is required to create a client secret and signing key, as well as for performing issuing and verifying actions using the CCG.
{
"Type": "string",
"id": "string",
"Name": "string",
"ClientId": "string",
"OrganisationId": "string",
"ClientSecretHash": "string",
"SigningKey": null,
"RequirePKCE": false,
"RedirectUris": [
"string"
],
"LogoUrl": "string",
"FaviconUrl": "string",
"CssUrl": null,
"PrivacyUrl": "string",
"TermsOfUseUrl": "string",
"SupportedTemplateIds": [
"string"
]
}
An unsuccessful call will return a 400 Bad Request status code and an error message which should highlight the parameter(s) that needs checking.
{
"type": "string",
"title": "string",
"status": 0,
"traceId": "string",
"errors": {
"additionalProp1": [
"string"
],
"additionalProp2": [
"string"
]
}
}
Sample success response (201)
Based on the example body above, the JSON object below shows what a successful response looks like with populated values.
{
"clientId": "7f082e87-387b-432c-907e-9251d38d2abc",
"organisationId": "bd816d9c-9259-4069-a401-t351gc1b1023",
"clientSecretCreated": false,
"signingKey": null,
"name": "Condatis Issuance Client",
"requirePKCE": false,
"redirectUris": [
"https://jwt.ms"
],
"logoUrl": "https://robohash.org/condatis?set=set4",
"faviconUrl": "https://robohash.org/condatis?set=set4",
"privacyUrl": "",
"termsOfUseUrl": "",
"cssUrl": null,
"supportedTemplateIds": [
"bd816d9c-9259-4069-a401-t351gc1b1023-TestCredential-IssuanceCredentialTemplate"
]
}
Sample unsuccessful response (400)
If any values are invalid or missing, an error response will be returned with a message highlighting the area that needs checking.
In this example, the body is missing the value for the required name
property. The error message returned shows that in the errors
property - "Name is required."
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-20a2d1c3e4231476e0afcba362bfc9aa-40dfe501838d3164-00",
"errors": {
"Name": [
"Name is required."
]
}
}
Create a client secret
The client secret provides authentication to your issuing/verifying client. You cannot create requests to the endpoint using you client ID without a valid secret.
Create client secret request endpoint
POST /api/client/{{ClientId}}/secret
Create client secret request headers
Header | Value |
---|---|
Authorization | Bearer Token |
Create client secret request URL parameters
Parameter | Type | Required | Description |
---|---|---|---|
ClientId | string | Yes | The ID of your client. |
The ClientId
is required to know which client the secret will be generated for.
Create client secret request body parameters
There are no body parameters needed for this request.
Create a client signing key
The client signing key is used by client applications to sign JWT tokens when passing data as an id_token_hint
to the gateway to issue credentials.
Create client signing key request endpoint
POST /api/client/{{ClientId}}/signingkey
Create client signing key request headers
Header | Value |
---|---|
Authorization | Bearer Token |
Create client signing key request URL parameters
Parameter | Type | Required | Description |
---|---|---|---|
ClientId | string | Yes | The ID of your client. |
The ClientId
is required to know which client the signing key will be generated for.
Create client signing key request body parameters
There are no body parameters needed for this request.