SSO for Web Applications with a Back End

It’s recommended to use the OIDC-based Authorization Code Grant if you’re using a web based application with its own back end server for user session management. In the Authorization Code Grant flow, the front end initializes the flow, and leverages back-channel communication between your back end server and Digital Identity Management. This flow is the most secure option because no tokens, or your RP client ID and secret, are exposed to the outside world. Once a user authenticates with their Digital Identity Management ID, Digital Identity Management issues a one-time Authorization Code to the RP. The RP uses the code in a secure back-channel request to obtain the access token, refresh token, or ID token from Digital Identity Management.

Flow Diagram

The diagram below represents the communication between the key actors using the Authorization Code Grant flow:

Interaction Steps

The interaction steps between each actor in the Authorization Code Grant flow are as a follows:

The user’s browser visits the web application to access the secured service.
Your web app UI checks with its back end to determined whether the user is already considered as signed in. For example, the user’s browser has a cookie or a session ID from a previous login.
Your back end determines that the user is not signed in.
Your back end generates and stores a nonce ASCII string. This is used to validate the OIDC response, and must not be guessable by an outside attacker.
Your back end returns a response to the UI that indicates the browser should redirect to the OIDC Authorization endpoint with parameters appropriate to the application RP.
Your UI generates a secure state ASCII string, and stores it in a browser cookie. This will be used to mitigate against Cross-Site Request Forgery (CSRF/XSRF) attacks.
Your app UI redirects the browser to Digital Identity Management’s /oidc/authorize endpoint with the following HTTP GET query string parameters:

Parameter	Description	Sample Value
`scope`	Space-separated list of OAuth 2.0/OIDC scopes to request.	`openid profile email offline_access`
`response_type`	Defines the desired response type. Use the value `code` to select Authorization Code Grant Flow.	`code`
`client_id`	ID of the relying party. This ID must be registered with the issuer.	`MyApplication-WebUI`
`redirect_uri`	Location where the browser should be redirected once the OIDC interaction is complete whether successful or not.The location must have been configured for the relying party.	`https://myapplication/oidc_complete`
`state`	ASCII `state` value to help mitigate against CSRF/XSRF. As a best practice, we recommend your app to embed the value in a cookie for later checks.	`AASN12jkasdn21nasDASD9230j2`
`nonce`	ASCII `nonce` value to help mitigate against replay attacks.The back end will verify that the generated ID token contains this nonce value.	`DSJF#sdnSF9@#(sdmklsfmkad`
`prompt`	Optional parameter. Can be one of the following values:
`none`	If the user is not already signed in to Digital Identity Management, do not prompt them to sign in. Instead, immediately redirect back to the RP with an error code.This can be useful if the application has a special onboard flow separate from Digital Identity Management, or if the application should only be accessed by end users who have already signed in to Digital Identity Management.	`none`
`login`	Even if the user is already signed in to Digital Identity Management, treat them as unauthenticated, and require that they sign in again.This can be useful if the application in question is considered high-security or sensitive.	`login`
`max_age`	Optional parameter. When this parameter value is specified and if the last time the user entered their Digital Identity Management credentials exceeds this value in seconds, then they will be prompted to re-authenticate to Digital Identity Management.This is similar to specifying `prompt=login`, but with a time sensitivity.

The user’s browser loads the oidc/authorize URL as per the HTTP 302 response from step 7. Digital Identity Management inspects the browser’s cookies to determine if the user is already authenticated. The next step depends on whether the user is already authenticated in Digital Identity Management.
(Conditional) If the request is not valid, or if the user is already authenticated and re-authentication is not being forced, then Digital Identity Management immediately responds with an HTTP 302 Temporary Redirect to the redirect_uri with certain HTTP Query parameters. Skip steps 10 through 12 and go to step 13 directly.

(Conditional) If the user is not authenticated, then Digital Identity Management redirects them to the configured IdP Portal (that is, the central sign-in page for all of your registered RPs).

Identity Provider (IdP) App
Your tenancy on the Digital Identity Management platform includes a default, out-of-the-box Identity app, also known as the sign-up/sign-in page. You can implement and leverage this UI for onboarding and authenticating your end users, or you may create and use your own Identity app using Digital Identity Management REST API and Processes.

In the most conventional use case, the user authenticates with Digital Identity Management’s POST /session/start API. This API invokes Digital Identity Management’s multi-step Authenticate User Process. Alternatively, the user may need to first onboard with the Onboard User with Email or Mobile Process, which is invoked by the POST /proces/start/{processName} API. This and other variations are not included in the flow diagram.
Eventually, whether from a /session/start or other Process API call, and potentially after several more steps (for example, to satisfy multi-factor authentication rules, if enabled), the user is authenticated. The final HTTP response from Digital Identity Management includes a special X-Redirect-Location header with a URL constructed from the redirect_uri parameter provided by the RP in step 7. The IdP then redirects the browser to that location.

The user’s browser loads a URL which Digital Identity Management has constructed from the redirect_uri parameter, to which the following HTTP Query parameters will have been added:

Parameter	Description
`code`	The authorization code, if the OIDC request was successful.
`state`	State value as passed in to the `/oidc/authorize` endpoint. The value must be checked against the `state` value S stored in a cookie. If there is a mismatch, a cross-site request forgery (CSRF/XSRF) must be suspected and the operation must be aborted.
`error`	The error code, if an error occurred. The following codes are possible:
Error Code	Meaning
`invalid_request`	The `/oidc/authorize` request was not valid.
`unauthorized_client`	The RP’s `client_id` that was specified in the `/oidc/authorize` request does not exist.
`unsupported_response_type`	The `response_type` that was specified in the `/oidc/authorize` request is not valid, or not enabled for this RP.
`invalid_scope`	One or more of the `scope` values that was specified in the `/oidc/authorize` request is not enabled for this relying party.
`server_error`	An error occurred on the Digital Identity Management server. Equivalent to an `HTTP 500` error code. The request may be retried.
`temporarily_unavailable`	The Digital Identity Management server is temporarily unavailable to process the request. Equivalent to an `HTTP 503` error code. The request may be retried.
`interaction_required`	The user must interact with Digital Identity Management to proceed, but the `/oidc/authorize` request specified that no such interaction be allowed (that is, `prompt=none`).
`login_required`	The user must authenticate with Digital Identity Management to proceed, but the `/oidc/authorize` request specified that no such interaction be allowed (that is, `prompt=none`).
`invalid_request_uri`	The specified `request_uri` value is not registered for this RP.
`error_description`	An easily understandable and readable description of the error.

Your UI checks the state value in the request against the original state value stored in a browser cookie. If there is a mismatch, a cross-site request forgery (CSRF/XSRF) attack is suspected, and the operation must be aborted with an error.
Your UI passes the received Authorization Code down to your back end.
Your back end makes a call to Digital Identity Management’s POST /oidc/token endpoint with the following parameters to redeem the Authorization Code for actual tokens:

Location	Name	Value
Header	`Authorization`	If the client is provisioned to use HTTP Basic Authentication, then this header field must be present with the value `Basic X`, where `X` is a base-64 encoding of the string `A:B`, where- `A` is the client ID - `B` is the client password In other words, the header must present `Basic` {client ID}`:`{client password}.
Body	`grant_type`	`authorization_code`
Body	`code`	The Authorization Code received from Digital Identity Management in the redirect request (step 13).
Body	`redirect_uri`	The redirect URI as supplied in the initial `/oidc/authorize` request. This value will be used by Digital Identity Management to verify the request against a man-in-the-middle type of attack.

If all parameters are correct and the Authorization Code is valid, Digital Identity Management replies with a JSON payload that contains the requested token(s). The payload is of type application/json, and it consists of a JSON object resembling the following:

**oidc/token response - body**
{
  "access_token": "eyJraWQiOiJyc2ExIiwiYWxnIjoiConnectyNTYifQ.eyJzdWIiOiI0ZmE2ZmZlMS05NmMwLTQ3ODAtYjNkYi1kNTMwY2RjN
                  TJhOGIiLCJhenAiOiJzZW5zaWNhbERldmljZUdyYW50LU9JREMtQ2xpZW50IiwiaXNzIjoiaHR0cHM6XC9cL3NlbnNpY2FsLX
                  VsbS1wZHQubTFhbWRvY3MuaW9cL29pZGMiLCJleHAiOjE2MTANzE4NzksImlhdCI6MTYxMDQ2ODI4MCwianRpIjoiMGVhNzhm
                  YTktMTIwMS00YmQzLTlkODYtZGU0ZGM5ZTU0ZDQ5In0.TiSh4oiT2xERbFtkQI09oMOBw4QvOdFt11fE8kh-yVxWISjPHj_V-
                  m9QxYCj_1AKrIHBJW1eZw5qyI4xqlNil0ax7RWEuEYqhBOTNQDSzfquERRLKgA1SsmleiO-ps1fXjo0ODmGTDQuJKKKhvgdPy
                  AIYirr8bBW_GNRsi4LJa8LM6yjC9-q9k79-WKNI3OgLy5T4Y-kObN236g0eXAyaSUZ4Ly1pJmUilRJnkI4KNyzqURz7_0awV6
                  k13J1aQnxUIJ5IQhEp0_3Xtq4l8b-rck0X8zXvjwyr7xUAAB6-lGEb2J7bvZEFcvGbn6ss25l1ceZeLLEFXtp9o3ZinyOYA", 
  "token_type": "Bearer", 
  "expires_in": 3599, 
  "scope": "email openid profile", 
  "id_token": "eyJraWQiOiJyc2ExIiwiYWxnIjoiConnectyNTYifQ.eyJzdWIiOiI0ZmE2ZmZlMS05NmMwLTQ3ODAtYjNkYi1kNTMwY2RjNTJhO
              GIiLCJhdWQiOiJzZW5zaWNhbERldmljZUdyYW50LU9JREMtQ2xpZW50IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImtpZCI6InJzYT
              EiLCJpc3MiOiJodHRwczpcL1wvc2Vuc2ljYWwtdWxtLXBkdC5tMWFtZG9jcy5pb1wvb2lkYyIsIm5hbWUiOiJQcmltYXJ5IFVzZXI
              gRGlzcGxheSBOYW1lIEhlcmUiLCJ1bG1fdXNlcl9pZCI6MTAzLCJleHAiOjE2MTA0Njg4ODAsImlhdCI6MTYxMDQ2ODI4MCwianRp
              IjoiYWMzOTUxY2YtZTlhZC00MjBmLTk3OGYtYmJiOGU2Y2YzZTViIiwiZW1haWwiOiJ0Z29rY2VuMjAyMTAxMTJAbWFpbGluYXRvc
              i5jb20ifQ.Hp0fDfODZ08F25HRYZmzImb-mH7-IsPHNLmWN6L7IfM791z7qDBpVRPT1SIKD875rGG88xBGbD0QgiPqnnUmz3xz0zy
              cokk8pmwzFYGyo2LE0ySeL4K-N2iUv4LUieDCE323KvHxKZV2QsazHivaTKGJ1aCy6dv_90LMf0Mv0_pAD3Zyd8eaM2Plt8zUe-Tt
              YQ-ojxrseD6lw2v1YJJpU8h1jtDKjFGLiMGUwDrV7bcUEsVZEOBZ_y1AbfhahbADnttrmN2Kifw9HeeFkGxVkwfFuswNvBx0F0nvL
              PHkWqbOLdotGlQrn6fhFoW1Ibg_PUWNz3ZCXS5uO6r-cpxTWQ" 
}

The fields of this JSON object are as follows:

Field	Description
`access_token`	The access token, a JSON Web Token (JWT).
`token_type`	Value is always `Bearer`.
`expires_in`	The lifetime in seconds of the access token. After this point, the access token must be refreshed (if possible) to continue treating the user as authenticated.
`scope`	The scopes granted by the access token. This may not always be the scopes requested; some scopes may have been denied.
`id_token`	The ID token, a JSON Web Token (JWT).
`refresh_token`	The refresh token, a JSON Web Token (JWT).

Your back end decodes the ID token, and inspects the payload to make sure the nonce key is present and its value matches the nonce value N from the original request (generated in step 4). If not, a replay attack is suspected and the operation must be aborted with an error.
Your system stores the token(s), preferably on the back end side (for example, in a session state), but also possibly as cookies in the web UI.
Your back end informs the web UI that the user is now considered authenticated or signed in.
As long as the access token remains valid, the user remains authenticated and can take actions. For more details on how to refresh (that is, get replacement) a token, refer to the Refreshing Tokens topic.

Home

Guides

APIs

Flow Diagram

Interaction Steps

​Flow Diagram

​Interaction Steps

Flow Diagram

Interaction Steps