Configure your Identity Provider

Overview

The OpenID4VCI and OIDC Bridge issuance workflows augment your existing identity management infrastructure. You can leverage an existing Identity Provider (IdP) to authenticate users and retrieve information required to generate verifiable credentials and make them available to an end-user's digital wallet.

If you are unfamiliar with OpenID Connect, the identity protocol underpinning the OpenID provisioning capability, there are many excellent guides available online such as this guide from Google, or this guide from Mozilla.

Prerequisites

You can use any OpenID Provider as long as it supports the following capabilities specified by OpenID Connect Core and OpenID Connect Discovery:

• Must publish the OpenID Provider configuration at /.well-known/openid-configuration

• Must support Authorization Code flow

• Must support the state parameter

These are required to allow the OpenID4VCI issuance workflow to engage with your IdP and accept an ID Token containing the end-users claims.

Identity Provider configuration

Perform the following steps to ensure your IdP is properly configured and ready to be used to issue verifiable credentials:

Step 1: Create your Identity Provider

If you don't have an existing IdP, we offer a number of tutorials on how to set up an IdP with the following providers (remember you can use any IdP provider as long as it meets the outlined requirements):

• Auth0

• Azure AD B2C

• Okta

Step 2: Update the OpenID configuration file

Browse to https://<your-host-domain>/.well-known/openid-configuration (it should be publicly available) and verify the following values exist (other options may validly sit alongside):

1{
2    "authorization_endpoint": "https://your-auth-endpoint/auth",
3    "token_endpoint": "https://your-token-endpoint/token",
4    "jwks_uri": "https://your-jwks-endpoint/jwks",
5    "response_types_supported": [
6        "code"
7    ],
8    "grant_types_supported": [
9        "authorization_code"
10    ],
11    "token_endpoint_auth_methods_supported": [
12        "client_secret_basic"
13    ],
14}

Step 3: Setup an application client on your Identity Provider

Setup an application client on your IdP:

• Make note of your client_id and client_secret.

• Use an example callback URL (also known as redirect_uri) e.g. https://example.com/callback. We will update it after you create an authentication provider configuration.

Step 4: Run a manual test to request an ID token

1. In a new browser window, make a request of the following structure:

1https://auth0-tenant.au.auth0.com/authorize
2?scope=openid%20profile
3&response_type=code
4&client_id=<your_client_id>
5&state=xqw2Lcafhx0NIoX0
6&nonce=kjfhuo34hPxksklj
7&prompt=login
8&redirect_uri=https://example.com/callback

• Use the authorization endpoint defined in your IdP /.well-known/openid-configuration file. This example uses an Auth0 IdP.

• response_type: Use code to indicate the expected response type.

• client_id: Use the client_id for the client application you created on your IdP.

• state: Use any random string.

• nonce: Use any random string.

• prompt: Use login to prompt your IdP to display the login screen.

• redirect_uri: Use the example URI you used for the client application you created on your IdP.

2. Authenticate with the IdP using a user that you have set up on it.

Example Auth0 login page

3. The redirect will terminate, but you can still retrieve the code from the query parameter:

1https://example.com/callback?code=oLxCRk2oPgfR8QU3&state=xqw2Lcafhx0NIoX0https://example.com/callback?code=oLxCRk2oPgfR8QU3&state=xqw2Lcafhx0NIoX0

4. Construct a request of the following structure to the /token endpoint of your IdP tenant:

1curl --request POST \
2  --url https://auth0-tenant.au.auth0.com/oauth/token \
3  --header 'Content-Type: application/json' \
4  --header 'Authorization: Basic dkowU0NLY2hyNFhqQzB4SE5FOERrSDZQbWxnMmxrQ046UU53ZmE0WWk0SW05enkxdV8xNW43U3pXS3QtOUc1Y2RIMHIxYk9OUnBVUGZOLVVJUmFhWHZfOTB6OFY2LU9qSA==' \
5  --data-raw '{
6    "grant_type": "authorization_code",
7    "code": "oLxCRk2oPgfR8QU3",
8    "redirect_uri" : "https://example.com/callback"
9}'

• url: We are using an example from Auth0. Replace with the correct URL for your IdP.

• header:

  • Use Content-Type: application/json.

  • Use your client_id and client_secret to create the Authorization: Basic header encoded with Base64 using a tool similar to base64url.com. The string should be formatted as client_id:client_secret prior to being encoded.

• data-raw:

  • grant_type: Use authorization_code

  • code: Use the value captured from the above redirect. This is time sensitive, you have about 5 mins!

  • redirect_uri: Use the same value as the request.

5. The response should include the id_token.

1{
2    "access_token": "-vtm3ahlh9k_V2uDjnZ5r2MPbKRaHpA1",
3    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlJUVXdOVEpCTXpJNFJUTTNNVGt4TURnNU5EVTJRamRETlRVNVJrWTNNamMyTTBWRU1FVkJPUSJ9.eyJodHRwczovL215dGVuYW50Lm1hdHRyLmdsb2JhbC90cmFpbmluZ0NlcnQiOiJQYXNzZWQgQSsiLCJuaWNrbmFtZSI6Im1lIiwibmFtZSI6Im1lQGVtYWlsLmNvbSIsInBpY3R1cmUiOiJodHRwczovL3MuZ3JhdmF0YXIuY29tL2F2YXRhci84ZjlkYzA0ZTZhYmRjYzlmZWE1M2U4MTk0NWM3Mjk0Yj9zPTQ4MCZyPXBnJmQ9aHR0cHMlM0ElMkYlMkZjZG4uYXV0aDAuY29tJTJGYXZhdGFycyUyRm1lLnBuZyIsInVwZGF0ZWRfYXQiOiIyMDIwLTA0LTMwVDA3OjUxOjA4Ljk0MloiLCJpc3MiOiJodHRwczovL2Rldi1yb2w0d29hby5hdS5hdXRoMC5jb20vIiwic3ViIjoiYXV0aDB8NWU2NmVjZjZlNWNjZjUwY2QwMDNmZjIwIiwiYXVkIjoidkowU0NLY2hyNFhqQzB4SE5FOERrSDZQbWxnMmxrQ04iLCJpYXQiOjE1ODgyMzQwNzEsImV4cCI6MTU4ODI3MDA3MX0.KLrMUoqz5mrvNQQ3K09eFijVg3qkmT17R_zOUvVhtfC8LvUWaBYpszQ7j3x3zCZ1TsS4ATS68kcxLfSbq7A71atYVzwjKvGwGce9IjH7cRKyIO8Z1RAcSCw7ncXBOzT_O20sH3BV_ZgPHEJA2PreKQERKjcKSCHJeRaPyqVbh2v2lSHYCm6e8HdB8v_Zq0looLvxS5afQ8PMn3k36COo13F4zvLuUn9is--B-SRUqUjSX6-KOvULa1HXbQVnO6RUNiijQSbN-ZLA_6TRQC8BKoT3-8v1cLSb49sZOXGSBHkkNHGBhMXeJuw4iD8IjYQWpcXlVRQHuCQwFgSHxdez9w",
4    "scope": "openid profile",
5    "expires_in": 86400,
6    "token_type": "Bearer"
7}

6. Copy the id_token value and paste it into a tool like jwt.io to inspect the payload of the ID token:

1{
2    "https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/educationalCredentialAwarded": "Certificate Name",
3    "updated_at": "2020-04-30T07:51:08.942Z",
4    "iss": "https://dev-rol4woao.au.auth0.com/",
5    "sub": "auth0|5e66ecf6e5ccf50cd003ff20",
6    "aud": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
7    "iat": 1588234071,
8    "exp": 1588270071,
9    "auth_time": 1606723358,
10    "nonce": "kjfhuo34hPxksklj"
11}

• sub: This is the unqiue identifier of the authenticated user in your IdP.

• nonce: The value provided in the original request.

What's next?

You can now proceed to create an authentication provider configuration.