OIDC Authentication flow in Zoho Directory

OIDC Authentication flow in Zoho Directory

Overview

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 authorization framework. It enables applications to verify a user's identity through an external Identity Provider (IdP).
In an OIDC-based authentication flow, the Identity Provider is responsible for authenticating users and issuing tokens. Zoho Directory uses the configured OIDC endpoints and credentials to communicate with the external IdP, authenticate users, validate the returned tokens, and retrieve user information when required.

Configuration

Zoho Directory acts as the Service Provider (SP) and the external identity provider (IdP) acts as the OpenID Connect Provider responsible for authenticating users.
  1. To configure OIDC authentication in Zoho Directory, the admin has to register Zoho Directory as a client application in the IdP and enter the IdP's details in Zoho Directory.
  2. The OIDC configuration in Zoho Directory requires the following information from the IdP:
    1. Client ID: Identifies Zoho Directory to the IdP in every request.
    2. Client Secret: To authenticate Zoho Directory when exchanging authorization code for tokens.
    3. Issuer URL: Issuer URL obtained from your IdP to automatically retrieve the authorization URL and access token URL.
    4. Authorization URL: Users are redirected to this URL to authenticate and grant access.
    5. Access token URL: URL used to exchange the authorization code for tokens.
    6. Scopes: Specify the ZD information requested during authentication. The default scopes are openid, email, and profile.
    7. (optional)User Information URL: To retrieve additional user information from your IdP.
  3. In return, Zoho Directory provides a Redirect URI, which must be configured in the IdP. This is where the users are redirected after signing in.

Flow

The OIDC flow happens between the Browser, Zoho Directory, and the Identity Provider. Two values travel through the browser during sign-in: state, created by Zoho Directory, and code, created by the IdP.
  1. state: A random, encrypted value added to the request that is sent to the IdP. Zoho keeps a copy tied to the user's browser through a secure cookie. The IdP returns it unchanged. Zoho checks if the state matches the copy for that browser, which blocks a forged or replayed response.
  2. code: A short-lived, one-time value that the IdP issues, returned in the Redirect URI.
The browser carries only redirects and the one-time code; the token request and response go directly between Zoho Directory and the IdP.

1. User attempts to sign in

When a user tries to sign in to an application that is integrated with Zoho Directory, Zoho Directory identifies that OIDC authentication is configured for the user.

2. User is redirected to the Identity Provider

Zoho Directory redirects the browser to the IdP for authentication. The authorization request includes the Client ID, Redirect URI, requested Scopes, response_type=code, and a state value.

3. User is authenticated

The IdP authenticates the user with the configured authentication methods, such as username and password, MFA, or passwordless authentication. The user's credentials are verified by the IdP. Zoho Directory is not involved in the authentication process.

4. Authorization code is returned

After successful authentication, the IdP redirects the browser to the Zoho Directory's Redirect URI with a one-time code and the same state. Zoho Directory checks if the state matches the value stored for that browser. A mismatch, or an error from the IdP, stops the sign-in.

5. Zoho Directory requests tokens from the Identity Provider

After receiving the code, Zoho Directory's server securely sends it to the IdP's token endpoint over an HTTPS POST request with grant_type=authorization_code. Zoho Directory authenticates the request using the Client ID and Client secret. The IdP then returns the ID Token and Access Token to Zoho Directory.
  1. ID Token: Contains information about the authenticated user.
  2. Access Token: It is used to access protected resources/APIs, including retrieving additional user information when required.

6. Token validation

Before signing the user in, Zoho Directory verifies the ID Token received from the IdP. Zoho Directory performs the following checks on the ID Token:
  1. Signing algorithm and signature: The token's alg must use a supported signing algorithm. Unsigned tokens (alg: none) are rejected.
    1. If alg is RS256, Zoho Directory verifies the signature with the IdP's public key obtained from the jwks_uri in its discovery document.
    2. If alg is HS256, Zoho Directory verifies the signature with the client credentials.
  2. Expiry: The exp claim must be present and indicate a time in the future.
  3. Issued-at and not-before timestamps: The iat and nbf claims must not be in the future.
If any check fails, the sign-in is rejected.

7. User mapping

After successfully validating the token, Zoho Directory identifies the corresponding user account and maps the user attributes received from the IdP to the directory user. Zoho Directory matches the IdP user to a directory user by the sub claim (The user's unique, permanent ID at the IdP, inside the ID Token). 
  1. Linked user: If this IdP user (sub) has signed in before, Zoho Directory uses the linked account.
  2. First sign-in: If the user is signing in for the first time, Zoho Directory looks up a user with the email from the ID Token, and links that user to this IdP.
  3. No matching user: If no user matches the email from the ID token, a new user with the name and email from the token will be created using Just-In-Time(JIT) provision. If JIT provision is not enabled, the sign-in will be rejected.
  4. Policy check: The user must belong to the organization, and their sign-in policy must include this IdP.

8. Access is granted

After the user is identified and mapped, Zoho Directory checks the user's sign-in policy.
If MFA is required, the user must complete it before a session is created. Zoho Directory then creates its own sign-in session in the browser. The ID Token and Access Token are discarded after sign-in and are not stored.

9. Sign-out Flow

Signing out of Zoho Directory ends only the Zoho session. The user's session at the IdP is managed separately and is not ended by Zoho sign-out. The user’s session at the IdP stays active. To sign out fully, the user must also sign out of the IdP.