Edit

Share via

Issuer service communication examples

  • Article

The Microsoft Entra Verified ID service can issue verifiable credentials by retrieving claims from an ID token generated by your organization's OpenID compliant identity provider. This article instructs you on how to set up your identity provider so Authenticator can communicate with it and retrieve the correct ID Token to pass to the issuing service.

To issue a Verifiable Credential, Authenticator is instructed through downloading the contract to gather input from the user and send that information to the issuing service. If you need to use an ID Token, you have to set up your identity provider to allow Authenticator to sign in a user using the OpenID Connect protocol. The claims in the resulting ID token are used to populate the contents of your verifiable credential. Authenticator authenticates the user using the OpenID Connect authorization code flow. Your OpenID provider must support the following OpenID Connect features:

Feature Description
Grant type Must support the authorization code grant type.
Token format Must produce unencrypted compact JWTs.
Signature algorithm Must produce JWTs signed using RS 256.
Configuration document Must support OpenID Connect configuration document and jwks_uri.
Client registration Must support public client registration using a redirect_uri value of vcclient://openid/.
PKCE Recommended for security reasons, but not required.

Examples of the HTTP requests sent to your identity provider are included below. Your identity provider must accept and respond to these requests in accordance with the OpenID Connect authentication standard.

Client registration

To receive a verifiable credential, your users need to sign into your IDP from the Microsoft Authenticator app.

To enable this exchange, register an application with your identity provider. If you are using Microsoft Entra ID, you can find the instructions here. Use the following values when registering.

Setting Value
Application name <Issuer Name> Verifiable Credential Service
Redirect URI vcclient://openid/

After you register an application with your identity provider, record its client ID. You will use it in the section that follows. You also need to write down the URL to the well-known endpoint for the OIDC compatible identity provider. The Issuing Service uses this endpoint to download the public keys needed to validate the ID token once that it’s sent by Authenticator.

The configured redirect URI is used by Authenticator so it knows when the sign-in is completed and it can retrieve the ID token.

Authorization request

The authorization request sent to your identity provider uses the following format.

GET /authorize?client_id=<client-id>&redirect_uri=vcclient%3A%2F%2Fopenid%2F&response_mode=query&response_type=code&scope=openid&state=12345&nonce=12345 HTTP/1.1
Host: www.contoso.com
Connection: Keep-Alive
Parameter Value
client_id The client ID obtained during the application registration process.
redirect_uri Must use vcclient://openid/.
response_mode Must support query.
response_type Must support code.
scope Must support openid.
state Must be returned to the client according to the OpenID Connect standard.
nonce Must be returned as a claim in the ID token according to the OpenID Connect standard.

When it receives an authorization request, your identity provider should authenticate the user and take any steps necessary to complete sign-in, such as multi-factor authentication.

You may customize the sign-in process to meet your needs. You could ask users to provide additional information, accept terms of service, pay for their credential, and more. Once all steps complete, respond to the authorization request by redirecting to the redirect URI as shown below.

vcclient://openid/?code=nbafhjbh1ub1yhbj1h4jr1&state=12345
Parameter Value
code The authorization code returned by your identity provider.
state Must be returned to the client according to the OpenID Connect standard.

Token request

The token request sent to your identity provider will have the following form.

POST /token HTTP/1.1
Host: www.contoso.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 291

client_id=<client-id>&redirect_uri=vcclient%3A%2F%2Fopenid%2F&grant_type=authorization_code&code=nbafhjbh1ub1yhbj1h4jr1&scope=openid
Parameter Value
client_id The client ID obtained during the application registration process.
redirect_uri Must use vcclient://openid/.
scope Must support openid.
grant_type Must support authorization_code.
code The authorization code returned by your identity provider.

Upon receiving the token request, your identity provider should respond with an ID token.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
    yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
    NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
    fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
    AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
    Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
    NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
    QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
    K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
    XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
}

The ID token must use the JWT compact serialization format, and must not be encrypted. The ID token should contain the following claims.

Claim Value
kid The key identifier of the key used to sign the ID token, corresponding to an entry in the OpenID provider's jwks_uri.
aud The client ID obtained during the application registration process.
iss Must be the issuer value in your OpenID Connect configuration document.
exp Must contain the expiry time of the ID token.
iat Must contain the time at which the ID token was issued.
nonce The value included in the authorization request.
Additional claims The ID token should contain any additional claims whose values will be included in the Verifiable Credential that will be issued. This section is where you should include any attributes about the user, such as their name.

Next steps