All Products
Search
Document Center

Identity as a Service:Set custom domains

Last Updated:Mar 31, 2026

Use a custom domain name for your IDaaS EIAM logon page and user portal instead of the system-generated initialization domain name (for example, xxxx.aliyunidaas.com). This keeps your brand consistent across the sign-in experience and lets you enforce access policies—such as restricting logons to specific IP address ranges—through your domain proxy service.

Key concepts

TermDescription
Initialization domain nameThe domain name generated when you create an IDaaS EIAM instance, for example, xxxx.aliyunidaas.com.
Custom domain nameA domain name you own and add to your IDaaS EIAM instance, for example, xxxx.example.com.
Default domain nameThe domain name the instance uses by default. Must be either the initialization domain name or a custom domain name. When automatic redirection is enabled, accessing the initialization domain name redirects to the default domain name.

Potential impacts

Custom domain names affect the following features. Review and adjust their configurations before or after you set up a custom domain name to avoid disrupting your users.

Affected featureConstraint
Logon page and application portalThe logon and portal addresses include a domain name.
DingTalk identity provider — QR code logon and Workbench SSOThe DingTalk callback domain is always the initialization domain name. Do not change it.
SSO to IDaaS application portal or applicationsThe application home page address includes a domain name.
WeCom identity provider — QR code logonThe domain users access (user portal or direct application URL) must match the WeCom authorization callback domain.
WeCom — Webpage authorization logon and data synchronizationThe domain users access must match the WeCom trusted domain.
OIDC and custom applications — Authorization and logout endpointsSingle custom domain: Set it as the default domain name and enable automatic redirection. Without redirection, users may need to log on again during SSO. Multiple custom domains: Each must match the user's logon page domain.
SAML applications — IdP metadata address and SSO URLSame rule as OIDC applications.
WebAuthnWebAuthn only works on the domain where the authenticator was registered. If a user registers on domain A, they cannot use that authenticator on domain B and must register a new one.

Prerequisites

Before you begin, ensure that you have:

  • A dedicated subdomain for IDaaS EIAM (a top-level domain or second-level domain is recommended), for example, login.example.com

  • Permission to manage DNS records for that domain (required to add a CNAME record that verifies ownership)

  • Permission to configure a domain proxy service with an HTTPS certificate

  • A trial or Enterprise IDaaS EIAM instance. Try an instance if you do not have one, or upgrade your existing instance to the Enterprise tier

  • (Chinese mainland instances only) An ICP filing number for the domain

Choose a proxy option

Setting up a custom domain requires two steps: domain configuration in the IDaaS EIAM console, followed by proxy configuration with your chosen proxy service. The proxy service forwards requests from your custom domain to the initialization domain.

Choose the proxy option that fits your infrastructure:

OptionBest for
Alibaba Cloud DCDNTeams that want managed CDN acceleration and simplified certificate handling
Self-managed NginxTeams that already operate their own infrastructure or need full control over the proxy

Add a custom domain name — Domain configuration

Go to Branding > Custom Domain Name > Add Custom Domain Name.

image.png
Important

Custom domain names affect logon, single sign-on (SSO), and data synchronization. Review Potential impacts before proceeding.

Step 1: Enter the domain name

Enter your custom domain name, for example, login.example.com. The domain name:

  • Must be globally unique across all IDaaS EIAM instances

  • Can contain lowercase letters, digits, hyphens (-), and periods (.)

  • Must not include a path or query parameters

  • Has a maximum length of 128 characters

image.png
Important

If an attacker launches a Cross-Site Scripting (XSS) attack on your IDaaS EIAM instance, it could enable a Cross-Site Request Forgery (CSRF) attack on other subdomains under the same parent domain. To reduce this risk, block Cross-Origin Resource Sharing (CORS) requests from the custom domain, or use a dedicated top-level domain.

Step 2: Add a DNS record

Add the DNS record shown on the page to your DNS provider (for example, Alibaba Cloud DNS). This verifies ownership of the domain. For the same instance and domain name, the record type, name, and value are fixed.

image.png

If you do not have DNS access, ask an authorized user to add the record. You can complete the remaining steps after the record is created.

For instructions on adding DNS records with specific providers:

Step 3: Enter the ICP filing number

For IDaaS EIAM instances in Alibaba Cloud regions in the Chinese mainland, provide an entity or website ICP filing number as required by the Administrative Measures on Internet Information Services. The ICP filing number appears on the instance's logon page.

Step 4: Complete the process

Review the information and click Complete. The custom domain name is saved but not yet active—you must complete the proxy configuration to enable it.

Add a custom domain name — Proxy configuration

The proxy configuration makes your custom domain name functional by forwarding user and application requests to the IDaaS EIAM initialization domain. Keeping the proxy available is your responsibility.

Option 1: Alibaba Cloud DCDN

Step 1: Add a domain name

In the Alibaba Cloud DCDN console, go to the Domain Names page and add a domain name.

image.png

Configure the following fields:

  • Accelerated Domain Name: Your custom domain name.

  • Origin Info:

    • Set Origin Type to Origin Domain Name.

    • Enter the initialization domain name shown on the proxy configuration page (do not include https://).

    • Set Port to 443.

After adding the domain name, copy the CNAME record provided by DCDN and add it to your DNS settings. For instructions, see Configure a CNAME record.

Step 2: Configure an HTTPS certificate

On the Domain Names page, open the domain's details page. On the SSL Certificate tab, configure an HTTPS certificate. For instructions, see Configure an HTTPS certificate.

image.png

Step 3: Enable back-to-origin HOST

On the domain's details page, go to the Origin Fetch tab and enable Origin HOST.

image.png

Set Domain Name Type to Origin Domain Name. The initialization domain name of the IDaaS EIAM instance is automatically selected.

image.png

Step 4: Add back-to-origin HTTP headers

On the Origin Fetch tab, click Custom Request Header and add the IP, Host, Token, and other values provided in the IDaaS EIAM console. These headers help prevent IP address spoofing and improve access security.

image.png

After completing the configuration, use Test Connectivity in the IDaaS EIAM console to run a connectivity check.

image
The test simulates access from the IDaaS EIAM service. If you have applied access policies to the domain (such as IP allowlists), the test result may not reflect what your users experience. Test in a simulated user environment as well.

After a successful test, review the affected features, update any related configurations, and roll out the custom domain to your users. If users should still be able to access the initialization domain name, enable automatic redirection.

Option 2: Nginx

Step 1: Install Nginx

Choose the installation method for your environment.

Install from source code
# Download the installation package
wget http://nginx.org/download/nginx-1.18.0.tar.gz

# Extract
tar -zxvf nginx-1.18.0.tar.gz
cd nginx-1.18.0

# Configure and specify the installation directory
./configure --prefix=/usr/local/nginx

# Compile and install
make && make install

# Verify the installation
cd /usr/local/nginx/sbin
./nginx -t

A successful installation outputs:

nginx: the configuration file /usr/local/nginx//conf/nginx.conf syntax is ok
nginx: configuration file /usr/local/nginx//conf/nginx.conf test is successful
Install on CentOS, AlmaLinux, or RHEL
# Install the EPEL repository (required on some systems)
sudo yum install epel-release -y

# Install Nginx
sudo yum install nginx -y

# Start and enable Nginx
sudo systemctl start nginx
sudo systemctl enable nginx

# Verify the service status
sudo systemctl status nginx
Install on Ubuntu or Debian
# Update the package list
sudo apt update

# Install Nginx
sudo apt install nginx -y

# Start and enable Nginx
sudo systemctl start nginx
sudo systemctl enable nginx

# Verify the service status
sudo systemctl status nginx

Step 2: Configure Nginx

  1. Find the configuration file path.

    nginx -t
  2. Configure the reverse proxy to forward requests from your custom domain (for example, www.example.com) to the IDaaS EIAM initialization domain (for example, *****.aliyunidaas.com). Edit the server block under http in nginx.conf:

    server {
        # Listen on HTTPS and enable SSL
        listen 443 ssl;
    
        # Your custom domain name
        server_name www.example.com;
    
        location / {
            # Forward to the IDaaS EIAM initialization domain
            proxy_pass https://*****.aliyunidaas.com;
        }
    }
  3. Redirect HTTP traffic to HTTPS.

    server {
        listen 80;
        server_name www.example.com;
    
        location / {
            return 301 https://$host$request_uri;
        }
    }
  4. Configure the SSL certificate. Upload your certificate and key files to the Nginx server, then update nginx.conf:

    server {
        listen 443 ssl;
        server_name www.example.com;
    
        # SSL certificate paths
        ssl_certificate      /usr/local/nginx/ssl/www.example.com.crt;
        ssl_certificate_key /usr/local/nginx/ssl/www.example.com.key;
    
        # SSL settings
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;
    }
  5. Add the IDaaS EIAM back-to-origin request headers. Copy the IP, Host, and Token values from the IDaaS EIAM console, then add them to the location block using proxy_set_header. These headers authenticate your proxy with IDaaS EIAM and pass the client's real IP address. Misconfiguring or omitting them can allow IP spoofing.

    location / {
        proxy_pass http://***.aliyunidaas.com;
    
        # Pass the client's real IP address
        proxy_set_header X-IDaas-Client-IP $remote_addr;
    
        # Host value expected by IDaaS EIAM
        proxy_set_header X-IDaas-Host eiam-idaas.idpsso.net;
    
        # Proxy authentication token from the IDaaS EIAM console
        proxy_set_header X-IDaas-Proxy-Token PTC*****************************6j;
    
        # Preserve the original Host header
        proxy_set_header Host $host;
    }

    image

Step 3: Restart Nginx

Restart Nginx after saving the configuration.

Source code installation:
sudo /usr/local/nginx/sbin/nginx -s reload
CentOS, AlmaLinux, or RHEL:
sudo service nginx restart
Ubuntu or Debian:
sudo systemctl restart nginx

Domain status

After the proxy configuration is complete, the availability status in the IDaaS EIAM console indicates that the custom domain name feature is enabled on the instance.

image.png
The availability status in the console only confirms that the custom domain name feature is enabled on the instance. It does not verify that the domain is reachable. Because you may apply access policies to the domain (such as IP allowlists), IDaaS EIAM cannot confirm end-to-end availability. Test the domain directly from a user environment.

Set the default domain name

The default domain name serves two purposes:

  • When Automatic Redirection is enabled, users and applications that access the initialization domain name are redirected to the default domain name.

  • It appears in multiple places in the console, including the user portal address and logon address.

To change the default domain name, click Modify the default domain name in the console.

image.png
Important

If you set a custom domain name as the default and enable automatic redirection, change the default domain name back to the initialization domain name if the custom domain becomes unavailable (for example, if the instance expires). Otherwise, users and applications cannot access the instance.

Enable automatic redirection

When automatic redirection is enabled, any access to the initialization domain name is automatically redirected to the default domain name. Accessing a custom domain name does not trigger a redirect.

If you use a single custom domain name, set it as the default and enable automatic redirection. This lets users access the initialization domain name or the custom domain name interchangeably for SSO without any additional application reconfiguration.

If you use multiple custom domain names or do not enable automatic redirection, update the SSO configuration and other affected features (see Potential impacts) for each custom domain name. Without this, users may be prompted to log on again during SSO, or may be unable to log on using WeCom QR codes.

Delete a custom domain name

Before deleting a custom domain name, check whether it is still in use—for example, in identity provider or application SSO configurations. The Last used time in the deletion confirmation dialog shows when the domain's proxy_token was last seen, which you can also check in the proxy configuration directly.

image.png

After deletion, the domain can no longer be used to access the IDaaS EIAM instance. Remove the related CNAME records and proxy configurations from your DNS provider and proxy service to prevent incorrect traffic forwarding.