DocsICP FilingConsole
官方文档
首页

OAuth 2.0 identity authentication

更新时间：
复制 MD 格式
产品详情
我的收藏
Note

This feature is available only in the AI Premium Edition. For details about version differences, see Version Introduction.

What is OAuth 2.0

OAuth 2.0 is an open authorization protocol. It allows third-party applications to securely access a user's resources, such as data or services, with the user's consent, without requiring the user to share their account credentials.

In other words, Alibaba Cloud Mail can use OAuth 2.0 to delegate the authentication process to your enterprise. This delegation is secure because your enterprise account credentials are not transmitted to or stored on mail servers.

How OAuth 2.0 authentication works

To enable users to sign in to their mailboxes with your enterprise IdP, the Alibaba Cloud Mail server and your enterprise IdP must exchange information according to the OAuth 2.0 protocol.

The OAuth 2.0 standard protocol supports multiple grant types. This integration requires the authorization code grant.

Both servers must implement the OAuth 2.0 authorization code grant, with the mail server acting as the OAuth 2.0 client and the enterprise IdP as the OAuth 2.0 server.

How to implement OAuth 2.0

To implement the OAuth 2.0 authorization code grant, refer to the following standard protocol documents:

  1. The OAuth 2.0 Authorization Framework (RFC 6749)

  2. Proof Key for Code Exchange by OAuth Public Clients (RFC 7636)

Additionally, for parts of the protocol that are not strictly defined, you must adhere to the following requirements:

  1. Implement the OAuth 2.0 Authorization endpoint, which is the URL of your enterprise IdP's sign-in page.

    1. The endpoint must support the response_type=code request parameter for the authorization code grant.

  2. Implement the OAuth 2.0 Token endpoint.

    1. The endpoint must support the grant_type=authorization_code request parameter to exchange an authorization code for an access token.

    2. The endpoint must support the grant_type=refresh_token request parameter to exchange a refresh token for a new access token.

    3. The endpoint must support passing the client_id and client_secret parameters in a POST request body to authenticate the client.

  3. Implement a UserInfo endpoint. This is not explicitly defined in the OAuth 2.0 specification.

    1. The endpoint must support exchanging an access token for the current user's email address.

    2. We recommend implementing this as a GET request that passes the access token in the Authorization request header.

  4. Implement an EndSession endpoint. This is not explicitly defined in the OAuth 2.0 specification.

    1. This endpoint is used to sign the user out of the browser session. It ensures that signing out of the mailbox also signs the user out of their enterprise IdP session.

  5. PKCE

    1. If you support PKCE, the code_challenge encoding method must support S256.

OAuth 2.0 sign-in flow

image

Final result

After configuration, users can sign in through the enterprise IdP in two ways:

Method 1: Go to your enterprise's custom mailbox sign-in URL. The user is automatically redirected to the enterprise IdP's sign-in page.

image.png

Method 2: Go to your enterprise's custom mailbox sign-in URL and click the icon for your OAuth 2.0 IdP under More sign-in options.

image.png

Configuration steps

Step 1: Create an OAuth 2.0 client in your IdP

If your enterprise uses a self-built IdP, contact the responsible team to create an OAuth 2.0 client for Alibaba Cloud Mail.

If your enterprise uses a third-party Identity as a Service (IDaaS) product, follow the product's documentation to create an OAuth 2.0 client. Use the following key settings:

  1. Grant types (grant_type for the Token endpoint): authorization_code, refresh_token

  2. Response type (response_type for the Authorization endpoint): code

  3. Token endpoint authentication method: client_secret_post

  4. Authorization code expiration: At least 600 seconds (recommended).

  5. Access token expiration: 14 days or 1,209,600 seconds (recommended).

  6. Refresh token expiration: 28 days or 2,592,000 seconds (recommended).

  7. Callback URL: See the configuration page, as shown in the following figure.

image

Note

If multiple callback URLs are provided (separated by commas), you must add each one as a separate entry in your IdP's configuration.

Step 2: Configure the OAuth 2.0 client in the console

  1. In the domain admin console, go to Enterprise Customization > Identity Source Management and click Start Configuration to go to the Select Authentication Protocol page.

image

  1. Click the OAuth2.0 identity source button to go to the OAuth2.0 Configuration page.

image

  1. On the OAuth2.0 Configuration page, verify that you meet the prerequisites.

image

Note

If you use Microsoft for OAuth authentication, for the Client Secret field, provide the secret's Value, not its ID, from your Microsoft application settings.

image

Prerequisite

Description

Mandatory

Add a custom sign-in URL.

Path: Enterprise Customization > UI Customization > Customize Mailbox Logon URL > Add Domain

A custom mailbox sign-in URL is required to correctly route users to the enterprise IdP.

Complete the CNAME configuration for the custom sign-in URL.

Path: Enterprise Customization > UI Customization > Customize Mailbox Logon URL > CNAME Settings

This ensures that the custom mailbox sign-in URL works correctly.

Complete the ICP filing for the custom sign-in URL.

Path: Enterprise Customization > UI Customization > Customize Mailbox Logon URL > ICP Filing Settings

This ensures that the custom mailbox sign-in URL can be legally operated in the Chinese mainland.

Recommended

Set the custom sign-in URL as the default link.

Path: Enterprise Customization > UI Customization > Customize Mailbox Logon URL > Set as Functional Mail Link

In some scenarios, you may need to direct employees to use the enterprise's custom sign-in URL to access their mailboxes.

Add an SSL certificate for the custom sign-in URL.

Path: Enterprise Customization > Domain Management > SSL Certificate Management > Upload Certificate

This allows the custom sign-in URL to be accessed over HTTPS for better security.

Enforce HTTPS.

Path: Enterprise Customization > Domain Management > SSL Certificate Management > Enforce HTTPS

This ensures that all connections to the custom sign-in URL use HTTPS by default, improving security.

Force all users to enable security passwords, or disallow all users from using third-party clients.

Path: Security Management > Account Security Policy > Force Enable Security Password / Allow Third-party Clients

If you plan to enable the "Only allow logon via this identity source" option, you must force enable security passwords to ensure that standard protocols (SMTP, IMAP, POP) continue to work.

Highly recommended: Most account security issues originate from using standard protocols. Enabling security passwords or disabling third-party clients can eliminate these risks and prevent account compromise or financial loss.

Note: After security passwords are enabled, users can no longer authenticate with their regular mailbox password over standard protocols. Each user must create a unique security password for this purpose. Plan this transition carefully to minimize disruption, especially for system mail accounts.

  1. On the OAuth2.0 Configuration page, configure the fields.

Note: When you first configure and test this integration, keep the Set as Default Logon Method option disabled to ensure employees can still sign in to their mailboxes.

Parameter

Description

Basic configuration

Display name

This name appears on the button on the user sign-in page.

Application logo

This logo appears on the sign-in page as the entry point for signing in with OAuth 2.0.

Client ID

The client ID provided by your enterprise IdP.

Client secret

The client secret provided by your enterprise IdP.

Scope

The scope defined for the OAuth 2.0 Authorization endpoint. You can leave this blank if it is not supported.

Authorization URL

The URL of your enterprise IdP's Authorization endpoint, which serves as the sign-in page.

Token URL

The URL of the Token endpoint, used to exchange authorization codes and refresh tokens for access tokens.

UserInfo endpoint HTTP request

The UserInfo endpoint exchanges a token for user information. This field specifies the HTTP request for calling the endpoint.

${access_token} is a placeholder for the access token value. You can change the placeholder name as needed.

Use HTTP for UserInfo endpoint

If this option is disabled, an HTTPS connection is used.

JsonPath for email in UserInfo response

The JsonPath expression to extract the email field from the UserInfo endpoint's response. It extracts the current user's email address during sign-in. You can use an online JsonPath tool to validate the expression.

EndSession endpoint HTTP request

The EndSession endpoint is a browser-side sign-out endpoint that clears the user's sign-in session with the enterprise IdP. This field specifies the HTTP request for calling the endpoint.

${redirect_uri} is a placeholder for the callback URL value. You can change the placeholder name as needed.

Use HTTP for EndSession endpoint

If this option is disabled, an HTTPS connection is used.

Callback URL

You must add all of these URLs to your enterprise IdP's configuration.

Mailbox sign-in URL

The URL for signing in to the mailbox through the IdP. This should be your enterprise's custom mailbox sign-in URL.

Sign-in configuration

Enable identity source

You must enable this switch to validate and use this identity source for sign-in.

After you enable it, an OAuth 2.0 sign-in button for this identity source is added to the sign-in page.

Set as Default Logon Method

After you enable this switch, users who access the enterprise's custom mailbox sign-in URL are automatically redirected to the enterprise IdP sign-in page.

Important: Before enabling this option, verify that you can sign in successfully using this identity source to avoid locking out employees.

Only allow logon via this identity source

We recommend enabling this switch for new enterprises. For established enterprises with many active mail accounts, enable this with caution.

When enabled, employees can only authenticate using this identity source, as other methods like using mailbox credentials will be disabled. For example:

  1. Users cannot sign in with mailbox credentials at the official Alibaba Cloud Mail sign-in URL.

  2. Standard protocols and third-party clients (such as Outlook or Foxmail) cannot authenticate with mailbox credentials. Users must enable security passwords and use a security password to authenticate.

Important: Ensure that you have enabled the Force Enable Security Password policy (Security Management > Account Security Policy > Force Enable Security Password). Otherwise, standard protocols and third-party clients will not work.

  1. After you configure the settings, click Save.

Step 3: Verify the integration

After you save the configuration, a confirmation message appears. Verify that you can successfully sign in to your mailbox through your enterprise IdP.

In a browser, copy the address and open it in an incognito mode window. Click the OAuth 2.0 icon to redirect to your enterprise IdP to sign in.

image

image.png

Previous：Identity Authentication Integration – OIDCNext：Personalization