Usage of state for redirects

Redirect users to specific URI after sign in using State parameter

The redirect_uri parameter is only meant as the fixed OAuth callback endpoint, not for forwarding the user to a dynamic URI in your application after authentication.

For that you must store the application state parameter before you redirect users to authenticate so that you can redirect them to a URL. For example, if a user intends to access a protected page in your application, and that action triggers the request to authenticate, you can store that URL to redirect the user back to their intended page after the authentication finishes.

Use the state parameter to lookup and restore the previous state of your application. Generate and store a nonce locally (cookies/session/localstorage), along with any desired state data (like the redirect URL). Use the nonce as a state in the protocol message. If the returned state matches the stored nonce, accept the OAuth message and fetch the corresponding state data from storage.

Generate the nonce that you will use to protect against CSRF attacks as explained before. Store the nonce locally, using it as the key to store all the other application states like the URL where the user intended to go. For example:

{
   "xyzABC123" : {
      redirectUrl: '/protectedResource',
      expiresOn: [...]
   }
}

Authenticate the user, sending the generated nonce as the state.
As part of the callback processing and response validation, verify that the state returned matches the nonce stored locally. If it does, retrieve the rest of the application state (like the redirectUrl).
Once you complete the callback processing, redirect the user to the URL previously stored.

Again, how you store the nonce and the URL or other information pertinent to the application state depends on your application's type. It can be local storage in single-page or native apps or a cookie in a regular web app.

Alternative method

Generate and store a nonce locally.
Encode any desired state (like the redirect URL) along with the nonce in a protected message (that will need to be encrypted/signed to avoid tampering).
In the response processing, unprotect the message, getting the nonce and other properties stored.
Validate that the included nonce matches what was stored locally and, if so, accept the OAuth message.

Example: Web app hosted on multiple-subdomains

To implement OAuth authentication across multiple subdomains (e.g., company1.example.com, company2.example.com) use a single redirect URI e.g. (https://sso.example.com), and utilize the state parameter to manage subdomain-specific redirection after authentication.

Implementation Steps

User Initiates Login:
- When a user accesses a protected resource on a subdomain (e.g., company1.example.com), initiate the OAuth flow by redirecting them to the authorization endpoint.
- Include a state parameter that encodes the originating subdomain or desired post-authentication path. For example:
```
state=company1.example.com
```
Redirect to Authorization Server:
- Redirect the user to the OAuth authorization server with the following parameters:
  - response_type: code
  - client_id: Your application's client ID
  - redirect_uri: http://sso.example.com
  - state: The encoded subdomain information
Handle Callback at sso.example.com:
- After successful authentication, the authorization server will redirect the user back to http://sso.example.com with the code and state parameters.
- At sso.example.com, validate the state parameter to ensure it matches the expected value and to determine the original subdomain.
Exchange Authorization Code for Access Token:
- At sso.example.com, use the received code to request an access token from the token endpoint.
Redirect User to Original Subdomain:
- After obtaining the access token, redirect the user back to the original subdomain using the information from the state parameter. For example:
```
https://company1.example.com
```

Security

State Parameter Validation:
- Ensure that the state parameter is validated to prevent CSRF attacks. This can involve generating a nonce and storing it in the user's session or a secure cookie.
Encoding State Information:
- If the state parameter contains sensitive information or multiple pieces of data, consider encoding it securely (e.g., using JWT or base64 encoding) and signing it to prevent tampering.
Redirect URI Registration:
- Register only http://sso.example.com as the redirect URI in the Developer Portal. All subdomains will use this URI for the OAuth callback.

By centralizing the OAuth callback handling at sso.example.com and using the state parameter to manage subdomain-specific redirection, you can streamline authentication across multiple subdomains while maintaining security and a seamless user experience.

Example diagram

WebSequenceDiagrams Code

title Using `state` for redirecting to the correct company after SSO
actor "User" as U
participant "company1.example.com" as C
participant "connect.visma.com" as IDP
participant "sso.example.com" as CIDP
U->C:Access login page
C->C:Create an encoded value representing itself\nto be used as the "state" parameter
C->IDP:OpenID Connect request (/connect/authorize)\nusing the generated state value
IDP->U:Display login page
U->IDP:Use credentials or external IDP to login
IDP->CIDP:Redirect/POST session details and access tokens, including the received state
CIDP->CIDP:Decode state and observe it represents company1.example.com
CIDP->C:Forward the OIDC callback from Connect as-is
C->C:Process received session information
C->U:Display landing page for logged in users