Try WSO2 Cloud for Free
Sign in

All docs This doc
Skip to end of metadata
Go to start of metadata

In WSO2 Identity Cloud, the default URL for your User Portal takes the format https:/<tenant>. For example, if your tenant name is 'foo', the default URL of your User Portal is https:/

You can use a customized URL that is more representative of your company or personal branding instead of using the default URL.

In this tutorial, you learn how to generate SSL certificates and DNS records to configure a custom URL for WSO2 Identity Cloud.

Let's begin. 

Create SSL certificates and DNS records

  1. Install a SSL key generation tool (OpenSSL is used in this tutorial).
  2. 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 private.key.

    openssl genrsa -out private.key 2048

    Note that the key file is generated in your folder location as 'private.key'.

  3. 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.

    openssl req -new -key private.key -sha256 -nodes -out request.csr -subj "/C=US/ST=California/L=Mountain View/O=WSO2/OU=IT/"

    Note that the certificate-signing-request file is generated in your folder location as 'request.csr'

  4. 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, 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 cat utility (available in Unix and Unix-based operating systems) to concatenate them to a single chain file (chain.crt). For example:

    cat COMODORSADomainValidationSecureServerCA.crt COMODORSAAddTrustCA.crt AddTrustExternalCARoot.crt > chain.crt

    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.crt file should have content in the following order: 

    (Your Intermediate certificate: COMODORSADomainValidationSecureServerCA.crt)
    -----END CERTIFICATE----- 
    (Your Intermediate certificate: COMODORSAAddTrustCA.crt)
    -----END CERTIFICATE-----
    (Your Root certificate: AddTrustExternalCARoot.crt)
    -----END CERTIFICATE-----
  5. 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:

 Expand to see the listed steps
  • 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 is developers'.

  • Set the CNAME destination to the Identity Cloud's custom DNS endpoint, which is

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 PortalFollow the steps below to customize the URL of your User Portal:

  1. Log in to the Identity Cloud as the tenant admin.
  2. Click the Setting icon at the top, right hand corner and select Custom URL (under Manage your cloud) from the options that appear.

  3. Select the Identity Cloud tab and click Modify to change the existing domain.

  4. 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.

  5. 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:

    SSL certificateThis 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

    • Not expired

    • Issued directly or by a wild card entry for a provided custom URL. For example:

      • In the direct method, if the CNAME is, the issued SSL file must contain

      • In the wildcard method, if the CNAME is, the issued SSL file should be *

    SSL Key FileThis 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 FileThis 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

  • No labels