In WSO2 Identity Cloud, the default URL for your User Portal takes the format
https:/identity.cloud.wso2.com/user-portal/t/<tenant>. For example, if your tenant name is 'foo', the default URL of your User Portal is
You can use a customized URL that is more representative of your company or personal branding instead of using the default URL.
Create SSL certificates and DNS records
- Install a SSL key generation tool (OpenSSL is used in this tutorial).
Using the command-line, navigate to a location of your choice in the server and execute the following command to generate a private SSL key by the name
Note that the key file is generated in your folder location as '
In the command-line, execute the following command to generate a certificate-signing-request file for your custom URL. Make sure you change the business address in this command to your own.
Note that the certificate-signing-request file is generated in your folder location as '
Go to a certificate vendor of your choice and use the certificate-signing-request file to obtain a certificate for your domain.
Any certificate that is accepted by the browser should work. In this tutorial, https://www.comodo.com/ is used as the certificate authority.
When you are done, you receive an email with the certificate for your domain along with the certificate authority's root and intermediate certificates.
Some certificate authorities provide the root and intermediate files as a single chain file, while others provide multiple files.
If you receive multiple root and intermediate files from your certificate authority, use the
catutility (available in Unix and Unix-based operating systems) to concatenate them to a single chain file (
chain.crt). For example:
Tip: If you are using Microsoft Windows, do the following to concatenate the certificate files:
Open all certificate files except your domain certificate in a text editor such as Notepad.
Create a new blank text file.
Copy the contents of all files in the reverse order and paste them into the new text file. For example, copy intermediate 3, intermediate 2, intermediate 1, and then the root certificate.
- Save the newly created file, i.e., chain.crt.
Note that the
chain.crtfile should have content in the following order:
Reserve a domain name with any domain registrar and create DNS CNAME records that map the domain to your Identity user portal.
Tip: Most domain registrars provide step-by-step instructions in their websites. For your convenience, the general steps are listed below:
- Sign in to the domain registrar’s site.
Navigate to your Domain Name Server (DNS) management page. The location and name of this page vary by the host but can generally be found under the 'Domain Management' or 'Advanced Settings' section.
Find the CNAME settings. Under the 'CNAME value or alias', enter the subdomain that you would like to map each URL to. The subdomain of developers.mytesturl.info is developers'.
Set the CNAME destination to the Identity Cloud's custom DNS endpoint, which is customdns.identity.cloud.wso2.com.
Now, you have the SSL certificates and DNS records that you need to configure a custom URL for the Identity Cloud.
Customizing the User Portal URL
Subscribers enter the User Portal URL into a browser to get to your User Portal. Follow the steps below to customize the URL of your User Portal:
- Log in to the Identity Cloud as the tenant admin.
Click the Setting icon at the top, right hand corner and select Custom URL (under Manage your cloud) from the options that appear.
Select the Identity Cloud tab and click Modify to change the existing domain.
Click Verify to check whether a CNAME record exists for this URL.
If the CNAME verification is successful, a screen is prompted for the SSL certificates.
Upload the files (SSL Certificate, SSL Key File and Chain File) that you created and click Proceed.Click here to see the certificate files requirements
The certificate files must satisfy the following requirements:
File Requirements SSL certificate This is the certificate that you got in step 4 of section 'Create SSL certificates and DNS records'. It must satisfy the following requirements:
In X509 format
Not self signed
Issued directly or by a wild card entry for a provided custom URL. For example:
In the direct method, if the CNAME is identitycloudtest.wso2.com, the issued SSL file must contain identitycloudtest.wso2.com.
In the wildcard method, if the CNAME is identitycloudtest.wso2.com, the issued SSL file should be *.wso2.com.
SSL Key File This is the private key of the certificate that you got in step 2 of section 'Create SSL certificates and DNS records'. It must be encrypted in the RSA format. Chain File This is the public key of the certificate that you got in step 4 of the section 'Create SSL certificates and DNS records'. If the public key is included in the SSL file, extract it to a chain file.
If the files are successfully uploaded, you receive a notification saying "Custom URL mapping is successfully added".
Tip: Wait approximately 10 minutes for the changes to take effect. Adding the configurations and restarting the load balancers can take some time.
You have now successfully changed the user portal domain name to a custom value.
Try it out
Access the User Portal using your new URL. In this example, the new user portal URL is https://www.mytesturl-identity.wso2stagingapps.com.