Sign in using Zoho (OIDC)

Although OAuth is primarily used for authorization, it can also be used to sign-in users for a custom application.

The steps involved in the sign-in process are as follows:

Register your application with Zoho.
Send authorization request to Zoho.
Get an ID token from Zoho.
Obtain the user's details from the ID token.
Authenticate users.

This authentication flow is based on the OpenID connect specification. Zoho’s OIDC metadata (or discovery document) can be retrieved through the following URL. You can select the required data center.

Metadata URL for

▼

https://accounts.zoho.com/.well-known/openid-configuration

This endpoint contains details about Zoho’s OIDC configuration including supported endpoints, scopes, claims, public keys, and such.

1. Register your application with Zoho

Register your application with the Zoho API console. You will obtain a client ID and a client secret. These credentials will be used to communicate with Zoho.

2. Send authorization request to Zoho

When the user tries signing in to your app using Zoho (typically via a 'Sign in using Zoho' option), this request needs to be sent to Zoho to obtain the authorization code. The request must include the parameter scope=email.

Endpoint

CopiedGET         {accounts-server-url}/oauth/v2/auth

Note: The accounts-server-url is specific to the location (i.e., datacenter) where your app is registered.

Query parameters

Parameter	Description
client_id	required The unique ID of your application. Obtained from the Zoho API console when you register your application.
response_type	required Must be passed with the constant value code.
redirect_uri	required The URI endpoint that Zoho will redirect the web browser back to, with the authorization code after authorizing the client. The redirect_uri has to be the same URI that is provided when registering the client in the API console. Should start with http:// or https://. For example: https://www.zylker.com/oauthredirect
scope	required The value can be email, profile, or openid. email returns the email address of the user and its verified status. profile returns the profile information of the user. openid returns the unique identifier of the user.

Request example

Copiedhttps://accounts.zoho.com/oauth/v2/auth
?response_type=code
&client_id=1000.GMB0YULZHJK411284S8I5GZ4CHUEX0
&scope=email
&redirect_uri=https://www.zylker.com/oauthredirect

Response parameters

After Zoho authenticates the user, a consent page will be shown to the them, and all the permissions your app is requesting will be displayed there. Once the user provides consent, the authorization code will be sent to the redirect_uri of the application.

Parameter	Description
code	The authorization code that can be exchanged for an id_token by making a request (step 3) to Zoho Accounts server. The lifetime of the authorization code is two minutes and can be used only once.
location	Indicates the data center (DC) location of the user (i.e., where their account is stored). If the user's DC is different from that of your app, then you will need to enable multi DC support and make the ID token request to the user's DC. For example, if the location mentioned in the response is in, then the ID token request URL should be https://accounts.zoho.in/oauth/v2/token.

Response example

Copiedhttps://www.zylker.com/oauthredirect
?code=1000.a1110799eac53c491fee9efef8246535.df7da86ff64daa66413e2899e9b7fad7
&location=in
&accounts-server=https://accounts.zoho.in

3. Get ID token from Zoho

After receiving the authorization code, this request needs to be sent to Zoho to obtain the ID token. The ID token will contain the details of the user.

Endpoint

CopiedPOST         {accounts-server-url}/oauth/v2/token

Note: The accounts-server-url is specific to the location (i.e., datacenter) where the user is present. Mentioned as location in the response of the authorization request.

Query parameters

Parameter	Description
client_id	required The unique ID of your application. Obtained from the Zoho API console when you register your application.
client_secret	required The unique secret of your application that is know only to your application and Zoho. Obtained from the Zoho API console when you register your application.
grant_type	required Indicates the way the application gets the id_token from the authorization server. In this case, it is by providing an authorization code and the value must be authorization_code.
code	required The authorization code received through the authorization code request (step 2).
redirect_uri	optional The URI endpoint that Zoho will redirect the web browser back to with the id_token, after authorizing the client and the authorization code. The redirect_uri has to be the same URI which is provided when making the authorization code request. Should start with http:// or https://. For example: https://www.zylker.com/oauthredirect

Request example

Copiedhttps://accounts.zoho.com/oauth/v2/token
?client_id=1000.GMB0YULZHJK411248S8I5GZ4CHUEX0
&client_secret=122c324d3496d5d777ceeebc129470715fbb856b7
&grant_type=authorization_code
&redirect_uri=https://www.zylker.com/oauthredirect
&code=1000.86a03ca5dbfccb7445b1889b8215efb0.cad9e1ae4989a1196fe05aa729fcb4e1e

Response parameters

Parameter	Description
id_token	A JWT that contains the details of the user who is to be authenticated.
access_token	An authorized key that can be used by your application to access the protected resource (mentioned in the scope) on behalf of the user. Validity: 1 hour.
token_type	Indicates the type of access token that is generated and how it must be passed when making API requests to access protected resources. The token type that is used in Zoho OAuth implementation is Bearer.
expires_in	Indicates the time (in seconds) after which the access token expires. The lifetime of an access token is 1 hour (3600 seconds).

Response example

Copied{
"access_token":"1000.2deaf8d0c268e3c85daa2a013a843b10.703adef2bb337b 8ca36cfc5d7b83cf24",
"id_token":"eyJrZXlfaWQiOiI3NDM5ODNiNDU0NTUyODNlNTQ1Nm2RkNDQxNjBhYSIsInR5cCI6IkpXUyIsImFsZyI6IlJTMjU2In0=.eyJhdF9oYXNoIjoiUlFkWVN3X0t4MzNoa2FoNVI3Q2kzQSIsInN1YiI6IjczMzE4MDE5Mi45NDI2Njk1MjIiLCJhdWQiOiIxMDAwLlI1MFFPRkFNV0FSN0pEU0FTVEU2WDdDTzA2Ukg5SyIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJhenAiOiIxMDAwLlI1MFFPRkFNV0FSN0pEU0FTVEU2WDdDTzA2Ukg5SyIsImlzcyI6ImFjY291bnRzLnpvaG8uY29tIiwiZXhwIjoxNjA4MTQwNzY2LCJpYXQiOjE2MDgxMzc4ODYsImVtYWlsIjoib2F1dGh0ZXN0YWNjbnRAZ21haWwuY29tIn0=.OmuBheTwE2ijpvF4AHZnkDrt5pwOj8jKw0X8ATZ4k8noHHMJHP5B7m1N/DEBxCX2BzBdWChGJZVNtxKT8MIEoKubz95XsCn9Z7Lto6PvFtFSp2iHaKi22exwexcRNBCcEDNVOuUq6mWyp/AsTx2QqYy+55cQHHlrBZA4hltaNoUN3nognIonnzjmBzTjRt6oxi2IcbWgT4tgJUO+cKrhWbyPRmM2nJwXTe2VelXICQsnIZQAi6DMzC4UOniOSAeFI8Qfwk8so9b6kdi66DgH7s18dmh/dKumiMbk73S0ZTfdOvULfmtlZJn4LX ujD0oBSvl3Ai6+Q7GkX5g==",
"api_domain":"https://api.zoho.com",
"token_type":"Bearer",
"expires_in":3600
}

4. Obtain user's email address from ID token

In the response of the ID token request (step 3), the id_token of the user will be present. The id_token is a JWT and contains the details of the user. The user details returned depends on the requested scope.

As it is a JWT, it will have three sections: Header, Payload, and Signature (each section separated by a period). Your application will need to decrypt it using the Base64 decryption algorithm. The payload part of the id_token will contain the following claims including the user's details. Not all of the following claims will be present, as the user details claims depend on the requested scope (email, profile, openid).

Parameter	Description
at_hash	Access token hash. It is used to validate that the access token granted is indeed associated with this ID token.
sub	Subject. A unique identifier for the user who is being authenticated. This identifier will always be unique to this user and never reassigned.
aud	Audience. The entity this id_token is intended for, which is your application. The value will be the client_id of your application.
email_verified	Indicates whether the email address of the user is verified or not.
azp	Authorized party. The entity to which the id_token is issued, which is your application. The value will be the client_id of your application.
iss	Issuer. Identifier for the entity that issued this token. Will always be accounts.zoho.com (the ccTLD may vary).
exp	Expiry. The time on or after which the id_token must not be accepted by your application. Represented in the Unix time format.
iat	Issued at. The time at which the id_token was issued. Represented in the Unix time format.
email	The email address of the user who is being authenticated. If the user has multiple email addresses associated with their account, their primary email address will be returned.
picture	The profile picture of the user.
first_name	The first name of the user.
name	The display name of the user.
last_name	The last name of the user.
gender	The gender of the user.

Refer to this specification to learn more about these claims.

Example of a decrypted token payload

Copied{
"at_hash": "RQdYSw_Kx33hkah5R7Ci3A",
"sub": "733180192.942669522",
"aud": "1000.R50Q*****06RH9K",
"email_verified": true,
"azp": "1000.R50Q*****6RH9K",
"iss": "accounts.zoho.com",
"exp": 1608140766,
"iat": 1608137886,
"email": "johndoe@zylker.com"
}

5. Authenticate the user

Check if your requirements for authentication are met from the decrypted id_token. Next, query your database to check if the user is already present. If yes, then initiate a session for the user in your app. If the user is not present, then redirect them to your app's sign-up page.