DocsICP FilingConsole
Documentation
Home Page Alibaba Mail Postmaster Feature Customization Identity source management Identity Authentication Integration – OIDC

Identity Authentication Integration – OIDC

Updated at:
Copy as MD
Product
My Favorites

Note

This feature is supported only in the Premium Edition. For differences between editions, see Edition Overview.

What is OIDC?

OIDC (OpenID Connect) is an identity authentication protocol built on OAuth 2.0. It extends OAuth 2.0 by defining parts that OAuth 2.0 leaves unspecified. The authorization flows of both protocols are largely the same, with the following key differences:

  1. The OIDC authorization flow returns an ID token in addition to other tokens.

  2. OIDC defines specifications for parts not covered in OAuth 2.0, such as scope, service discovery, and user information fields.

Understanding OIDC-based Identity Authentication Integration

To enable users to log on to their mailbox using enterprise identity provider (IdP) credentials, the mailbox server and the enterprise IdP server must exchange information according to a shared agreement. This agreement is the OIDC standard protocol.

The OIDC standard supports multiple patterns. This document refers specifically to the Authorization Code Grant pattern.

Both the mailbox server and the enterprise IdP server must implement the OIDC standard protocol—the former as the OIDC client and the latter as the OIDC server.

How OIDC Works

For details on implementing the OIDC Authorization Code Grant pattern, refer to the following standard protocol documents:

  1. OIDC Core Specification

  2. OIDC Discovery Specification

  3. OIDC End-Session Standard Protocol

  4. JWK Specification

  5. PKCE Specification

  6. OAuth 2.0 Specification

Additionally, for parts of the protocol defined loosely, strictly follow the instructions in this document under “Configuration Steps” → “Step 2: Configure the OIDC Client in the Mailbox Admin Console” → “On the ‘OIDC Configuration’ page, verify that all prerequisites are met.”

Login Flowchart for OIDC-based Identity Authentication Integration

image.svg

Final Result

After configuration, you can choose from three modes:

Mode 1: Mixed Mode

Go to your company’s custom mailbox login URL and click the icon for the corresponding OIDC IdP under “More Login Options.”

Use this mode for initial testing after configuring OIDC to avoid disrupting regular user logins.

image.png

Mode 2: OIDC Preferred

When users visit your company’s custom mailbox login URL, they are automatically redirected to the enterprise IdP login page.

image.png

Note that in this mode, users can still log on using their mailbox credentials if they access the official Alibaba Mail pages, bypassing your enterprise OIDC IdP authentication.

Official Alibaba Mail URLs:

image.png

Mode 3: OIDC Only

This mode enhances Mode 2. Enabling it has the following effects:

  1. Users cannot log on using mailbox credentials on official Alibaba Mail pages. They will be prompted to go to the company-specified login page for enterprise OIDC IdP authentication.

image.png

  1. Standard protocols (IMAP, POP, SMTP) no longer support mailbox credential authentication.

    1. Regular users who use clients such as Outlook or Foxmail must go to the web version of the mailbox to create a third-party client security password and use that password to log on.

    2. System mailboxes used for automated email sending (typically implemented via code using standard protocols) must also go to the web version of the mailbox to create a third-party client security password, use that password for authentication, and update their code accordingly.

Important

Enable with caution! Because this mode affects standard protocols, ensure all existing mailboxes that depend on these protocols have already switched to third-party client-specific passwords before enabling it.

image.png

Configuration Steps

Step 1: Create an OIDC Client for the Mailbox in Your Enterprise IdP

If your enterprise runs a self-hosted IdP, contact your internal team to create an OIDC client for the mailbox.

If your enterprise uses a third-party IDaaS product, follow that product’s documentation to create an OIDC client.

Key configurations include the following:

  1. Grant types (for the token endpoint’s grant_type parameter): authorization_code, refresh_token

  2. Response type (for the authorization endpoint’s response_type parameter): code

  3. Token endpoint authentication method: client_secret_post

  4. ID token signature algorithm: RS256

  5. Authorization code expiration time: at least 600 seconds

  6. ID token expiration time: 14 days (1,209,600 seconds)

  7. Access token expiration time: 14 days (1,209,600 seconds)

  8. Refresh token expiration time: 28 days (2,592,000 seconds)

  9. (Recommended) Supported scopes: openid, offline_access, email

  10. (Recommended) Supported claims: email

  11. Login callback address: see the configuration page, as shown in the image

image

Step 2: Configure the OIDC Client in Mailbox Domain Management

  1. In the mailbox domain management console, go to Enterprise Customization > Identity Source Management, and click Create to open the Select Authentication Protocol page.

image

  1. Click the OIDC identity source button to open the OIDC Configuration page.

image

  1. On the OIDC Configuration page, verify that all prerequisites are met.

image

Requirement

Description

Required

Add a custom login address

Path: Enterprise Customization > Interface Customization > Custom Mailbox Login Address > Add Domain

Your enterprise’s custom mailbox login address must correctly route and redirect to the corresponding enterprise OIDC IdP.

Complete CNAME configuration for the custom login address

Path: Enterprise Customization > Interface Customization > Custom Mailbox Login Address > CNAME Settings

Ensures the custom login address works properly.

Complete ICP filing for the custom login address

Path: Enterprise Customization > Interface Customization > Custom Mailbox Login Address > ICP Filing Settings

Ensures the custom login address works properly.

Recommended

Set the custom login address as the default link

Path: Enterprise Customization > Interface Customization > Custom Mailbox Login Address > Set as Functional Email Link

In some scenarios, employees need to be reminded to use the enterprise’s custom login address to access their mailbox.

Add an SSL certificate for the custom login address

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

Enables HTTPS access to the custom login address for better security.

Enable forced HTTPS

Path: Enterprise Customization > Domain Management > SSL Certificate Management > Force Enable HTTPS

Makes HTTPS the default for the custom login address to improve security.

Enforce security passwords for all users / Disable third-party client access for all users

Path: Security Management > Account Security Policy > Force Enable Security Password / Allow Third-Party Client Access

If you plan to enable “Allow login only through this identity source” in the OIDC IdP settings, you must enforce security passwords to use standard protocols (SMTP, IMAP, POP) properly.

Strongly recommended! Most mailbox security issues stem from standard protocols. Enforcing security passwords or disabling third-party clients eliminates these risks and prevents account theft or financial loss.

Note: After enabling security passwords, mailbox credentials can no longer authenticate via standard protocols. Each user must create a security password and use it for standard protocol access. Plan your rollout carefully to minimize impact—especially for system mailboxes.

  1. On the OIDC Configuration page, configure the relevant fields.

Note: For initial setup, keep “Set as Default Login Method” disabled during testing to avoid preventing employees from logging on.

Field/Feature

Description

Basic Configuration

Display name

This name appears on the login button for users.

Application logo

This icon appears on the login page as the entry point for OIDC login.

Client ID

The Client ID provided by your enterprise OIDC IdP.

Client Secret

The Client Secret provided by your enterprise OIDC IdP.

Issuer URL

The Issuer URL provided by your enterprise OIDC IdP.

Callback address

Add all these URLs to your enterprise OIDC IdP’s callback address list.

Login Configuration

Enable identity source

You must enable this to test or use this identity source for login.

Once enabled, a new OIDC login button appears on the login page.

Set as default login method

When enabled, visiting your enterprise’s custom mailbox login address automatically redirects to the enterprise IdP login page.

Note: Ensure users can successfully log on using this identity source before enabling it. Otherwise, employees will be unable to access their mailboxes!

Allow login only through this identity source

New enterprises should enable this. Existing enterprises (with many active mailbox accounts) should proceed with caution!

When enabled, employees can authenticate only through this identity source—not via mailbox credentials or other methods. For example:

  1. Users cannot log on using mailbox credentials via official Alibaba Mail URLs.

  2. Standard protocols and third-party clients (Outlook, Foxmail) cannot use mailbox credentials. Users must enable “Third-Party Client Security Password” and authenticate using the generated password.

Note: Ensure you have enforced security passwords for all users (**Security Management** > **Account Security Policy** > **Force Enable Security Password**). Otherwise, standard protocols and third-party clients (Outlook, Foxmail) will stop working!

  1. After configuration, click Save to complete creation.

  2. If saving fails, check whether the Issuer URL meets the requirements.

image.png

Note: The “recommended” conditions below refer to capabilities your enterprise OIDC IdP must implement—even if the Issuer URL response does not explicitly include them. Otherwise, authentication will fail!

Requirement

Description

Required

Must provide authorization_endpoint

The OIDC authorization endpoint—your enterprise IdP’s login page URL.

Must provide token_endpoint

The OIDC token endpoint, used to exchange an authorization code for tokens or a refresh token for a new access token.

Must provide jwks_uri

The OIDC token endpoint returns an ID token (JWT format). The key to verify this JWT must be available via jwks_uri.

Recommended

Note: The “recommended” conditions below refer to capabilities your enterprise OIDC IdP must implement—even if the Issuer URL response does not explicitly include them. Otherwise, authentication will fail!

Must provide introspection_endpoint

Used to parse access token details, validate the token, and retrieve the user’s email. Implement either introspection_endpoint or userinfo_endpoint.

Must provide userinfo_endpoint

Used to exchange an access token for user details, including the user’s email. Implement either introspection_endpoint or userinfo_endpoint.

Must provide end_session_endpoint

Used for browser logout to ensure that when a user logs out of the mailbox, they are also logged out of the enterprise identity account.

grant_types_supported must include authorization_code and refresh_token

The OIDC token endpoint must accept grant_type values of authorization_code and refresh_token.

response_types_supported must include code

The OIDC authorization endpoint must accept a response_type value of code (Authorization Code Grant).

claims_supported must include the email field

The OIDC token endpoint must return an ID token (JWT format) that includes the email field.

scopes_supported must include openid, email, and offline_access

The OIDC authorization endpoint must accept scope values of openid, email, and offline_access.

id_token_signing_alg_values_supported must include RS256

The OIDC token endpoint must sign ID tokens (JWT format) using the RS256 algorithm.

token_endpoint_auth_methods_supported must include client_secret_post

The OIDC token endpoint must accept client_id and client_secret parameters via POST request for authentication.

introspection_endpoint_auth_methods_supported must include client_secret_post

The OIDC introspection endpoint must accept client_id and client_secret parameters via POST request for authentication.

If PKCE is supported, code_challenge_methods_supported must include S256

If your enterprise OIDC IdP supports PKCE, it must support the S256 code challenge method.

Typically, the Issuer URL response should include at least the following information:

{
    "authorization_endpoint": "https://mail.example.com/oidc/auth",
    "token_endpoint": "https://mail.example.com/oidc/token",
    "jwks_uri": "https://mail.example.com/oidc/.well-known/jwks.json",
    "claims_supported": [
        "email"
    ],
    "code_challenge_methods_supported": [
        "S256"
    ],
    "end_session_endpoint": "https://mail.example.com/oidc/session/end",
    "grant_types_supported": [
        "authorization_code",
        "refresh_token"
    ],
    "response_types_supported": [
        "code"
    ],
    "scopes_supported": [
        "openid",
        "offline_access",
        "email"
    ],
    "token_endpoint_auth_methods_supported": [
        "client_secret_post"
    ],
    "userinfo_endpoint": "https://mail.example.com/oidc/me",
    "introspection_endpoint": "https://mail.example.com/oidc/token/introspection",
    "introspection_endpoint_auth_methods_supported": [
        "client_secret_post"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ]
}

  1. After configuration, click Save to complete creation.

Step 3: Verify Successful Authentication Integration

After saving the configuration, the following message appears. Verify that users can successfully log on to the mailbox through your enterprise OIDC IdP.

Browser: Copy the URL and open it in an incognito window. Click the OIDC icon to redirect to your enterprise IdP for login.

image.png

image.png

Previous：Identity authentication with Active DirectoryNext：OAuth 2.0 identity authentication