Step-by-step integration
DID.app integrates with your websites, APIs and apps via the OpenID Connect protocol.
Authenticating End Users takes two steps.
- Redirect a user to DID.app with an authentication request from your application.
- Fetch the user information from the authentication response.
Create Authentication Request
Redirect the End User to the authorization url: https://auth.did.app/oidc/authorize. Provide the details of the authentication request as query parameters.
-
client_id
(Required) Provided by DID.app and specific to your application. -
redirect_uri
(Required) An endpoint on your application that handles the authentication response. -
response_mode
How the code will be sent to the redirect endpoint. Recommended value for applications with a server isform_post
, data will be sent as the body of aPOST
request with content typeapplication/x-www-form-urlencoded
. -
prompt
A value ofcreate
will display the “create an account” UI, any other value will show the “Sign in” UI. -
state
An arbitrary value used to maintain state between the request and the callback, this value will be returned unmodified in the response.
Example
Using a form to create an authentication request.
<form action="https://auth.did.app/oidc/authorize" method="get">
<input name="client_id" value="[CLIENT_ID]" type="hidden" />
<input name="redirect_uri" value="[REDIRECT_URI]" type="hidden" />
<input name="response_mode" value="form_post" type="hidden" />
<button type="submit">Sign in</button>
</form>
Handle Authentication Response
Parse the authentication response, it will contain the following parameters:
-
code
(Success Responses) A single use code that can be exchanged for user information. -
error
(Failure Responses) A string value error code, returned if unable to authenticate user or user cancels authentication. -
state
(All Responses) The state value sent with the authentication request.
Fetch user information associated with the code.
Send a POST
request to the token endpoint. https://auth.did.app/oidc/token.
Provide the code and your applications details as form parameters.
-
client_id
(Required) Provided by DID.app and specific to your application. -
client_secret
(Required) Provided by DID.app and specific to your application. -
code
(Required) Extracted from authentication response
curl https://auth.did.app/oidc/token \
-d 'client_id=[CLIENT_ID]' \
-d 'client_secret=[CLIENT_SECRET]' \
-d 'code=[CODE]' \
The response body will contain your user information.
{
"userinfo": {
"sub": "00000000-0000-0000-0000-000000000000",
"email": "user@example",
"email_verified": true
},
"id_token": "COMPACT JWT",
"access_token": "COMPACT JWT"
}
The sub
is the identifier of a user within your application.
It is intended to be used as the primary identifier of your user and does not change.
You should not rely on a users email being constant over time.
Final steps
At this point authentication is complete. It is up to your service to handle things from here.
For most applications this will involve starting a session for authenticated user. How this is done will depend on the platform, or framework that you are using. We have specific integration guides that cover this step for the following technologies.
Can’t find your preferred platform in our docs? There may already be OpenID Connect library for your platform: A list of certified implementations is maintained at https://openid.net/developers/certified/.
Visit our Roadmap to request an integration guide for a new platform.