Set Up Custom Domain Names

After obtaining Administrator credentials to Portal, which includes getting the access token, the Administrator can change the default URL a tenant has been given to a custom domain name.
After obtaining Administrator credentials to Portal, which includes getting the access token, the Administrator can change the default URL a tenant has been given to a custom domain name.
This page describes how to:
 
  
 
Set Up a Custom Domain Name
The workflow for setting up your custom domain name is as follows:
 
   
 
Change the Default URL
When you create a Portal tenant, by default, the tenant is provided with a sample domain name for accessing the Portal in the following format: https://tenantID.dev.ca.com.
The Administrator can customize the default domain name by performing these steps:
In the steps, you will need to follow commands where:
  •  
    <PAPI_Portal_TSSG
     
    >
     is the Portal API URL, for example, 
    apim-sgg-
    p
    hoenixproject.dev.ca.com
  •  
    <tenant_id>
     is your default domain name, for example,
    acmeco
    .
  •  
    <customdomain>
     is the custom domain you want to change it to, for example 
    portal.acmeco.com
Create a CNAME DNS entry
Create a CNAME DNS entry that is pointing the custom domain to the original portal hostname. For example, portal.acmeco.com → acmeco.dev.ca.com.
Get the Access Token
The access token is required to generate the CSR, upload the certificate, update the Portal with the Gateway custom domain, and to delete the custom domain.
To get the access token:
  1. Log in to the tenant portal as admin user, for example, 
    acmeco.dev.ca.com
  2. Go to Portal API. The API Explorer opens in a new window. 
  3. In the API drop-down list, select 
    Portal API (tenantid)
    , for example 
    Portal API (acemco)
    .
  4. Get the API Key, Shared Secret, and Token Endpoint. 
  5. Use 
    base64
     to encode 
    API Key:Shared Secret
    .
    echo -n <API KEY>:<Shared Secret> | base64
    The following is an example:
    echo -n e3399b3d4b6a4a2da0b9ff8efa0b6394:4ef66c61578a41de8d28280b18724553 | base64
  6. Fetch the authentication access token by running this command:
    curl '<Token Endpoint>' -H 'Authorization: Basic <value from Step 5>' --data 'grant_type=client_credentials&scope=OOB' --compressed
    The following is an example:
    curl 'https://apim-ssg-phoenixproject.dev.ca.com/auth/oauth/v2/token' -H 'Authorization: Basic ZTMzOTliM2Q0YjZhNGEyZGEwYjlmZjhlZmEwYjYzOTQ6NGVmNjZjNjE1NzhhNDFkZThkMjgyODBiMTg3MjQ1NTM=' --data 'grant_type=client_credentials&scope=OOB' --compressed
    If this step is performed correctly, a json payload is returned.
  7. Get the value for 
    access_token
    .
Generate the CSR
Generate the Certificate Signing Request (CSR) using the following command:
curl -X POST --compressed "https://<PAPI_Portal_TSSG>/<tenant_id>/tools/1.0/customdomain/csr/<customdomain>" -H "accept: application/x-pem-file" -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" -d "{ \"country_name\": \"<Country: US, CA>\", \"state_or_province_name\": \"<State or Province: NY, WA, BC>\", \"locality_name\": \"<Locality: Boulder, Raleigh, Vancouver>\", \"organization_name\": \"<Organization Name: CA Technologies, Inc.>\", \"organizational_unit_name\": \"<Organizational Unit Name: IT Department>\", \"common_name\": \"<Common Name: test.customdomain.com>\", \"additional_domain_names\": [ \"<List of SAN Names>\" ] }"
The command also generates a private key if one does not already exist. Both the CSR and private key are stored in the vault. The following is an example:
curl -X POST --compressed "https://apim-ssg-phoenixproject.dev.ca.com/acmeco/tools/1.0/customdomain/csr/portal.acmeco.com" -H "accept: application/x-pem-file" -H "Authorization: Bearer f778f4fa-896c-4f55-969f-5e6a151ee322" -H "Content-Type: application/json" -d "{ \"country_name\": \"CA\", \"state_or_province_name\": \"British Columbia\", \"locality_name\": \"Vancouver\", \"organization_name\": \"CA Technologies\", \"organizational_unit_name\": \"Phoenix Team\", \"common_name\": \"portal.acmeco.com\" }"
Purchase the Certificate with CSR
Bring the CSR to a Certificate Authority (a domain registrar) to purchase a certificate.
Upload the Certificate
Upload the certificate using the following command:
curl -X POST --compressed "https://<PAPI_Portal_TSSG>/<tenant_id>/tools/1.0/customdomain/pem/<customdomain>" -H "accept: application/json" -H "Authorization: Bearer <access_token>" --data-binary @/path/to/cert
The certificate is validated before saving it to the vault. The following is an example:
curl -X POST --compressed "https://apim-ssg-phoenixproject.dev.ca.com/acmeco/tools/1.0/customdomain/pem/portal.acmeco.com" -H "accept: application/json" -H "Authorization: Bearer f778f4fa-896c-4f55-969f-5e6a151ee322" --data-binary @/path/to/portal.acmeco.crt
Note that it may take up to 48 hours for the change from a default URL to a custom domain name to take place, during which time the new custom domain will not be available for use.
Update Email in Settings
By default, activation links in emails sent (such as registration) use the default URL. To change those links to use your Custom Domain, follow this section.  
To update email in settings:
  1. In API Portal, select 
    Portal API
    .
  2. From the drop-down list, select 
    Portal API
     (tenant name).
  3. Select the 
    Settings
     endpoint, select 
    PUT
  4. In the 
    input
     field, fill in 
    CUSTOM_DOMAIN_NAME
    .
  5. Fill in the 
    body
     field. The following example uses mycustomdomain.com, replace the value with your custom domain.
    { "Uuid": "{{GENERATED_UUID}}", "Name": "CUSTOM_DOMAIN_NAME", "Value": "mycustomdomain.com" }
     The UUID is auto-generated. If you need to see the UUID again, select GET call for CUSTOM_DOMAIN_NAME.
Update CORS Assertion
Add the custom domain to the list of valid portal hostnames:
  1. Log in to Policy Manager of TSSG.
  2. Locate the 
    Portal Service Preface
     policy.
  3. Go to 
    Service
    Policy
     panel. Expand the policy and locate 
    Process CORS Request
     on line 11.
  4. Open 
    Process CORS Request
     assertion, select 
    Add
    .
  5. Enter the new custom domain, select 
    OK
    .
 This change needs to be applied every time you upgrade the Portal integration bundle.
The following steps only need to be done once as the change will persist through updates:
  1. Locate the 
    Portal Custom Messages
     policy and open 
    portal-message-received
    .
  2. Locate the 
    Process CORS Request
     line item and add the custom domain to the CORS hostname list. 
  3. In 
    Portal Custom Messages
     policy, open 
    custom-message-received
    .
  4. Locate the 
    Process CORS Request
     line item. Copy and paste the contents of 
    portal-message-received
     into 
    custom-message-received
    .
Configure SAML SSO
To use Custom Domains with SAML SSO, see the following sections.
 This feature is not compatible with SAML SSO (old).
  optional.png Set up a New SAML SSO for Custom Domain
  1. Log in to the custom domain URL with Portal administrator credentials that are provided by the system (not the SAML SSO credentials).
  2. From the custom domain URL, create a new SAML SSO. For more information about creating a new SAML SSO, see Create a SAML SSO Authentication Scheme.
  3. Open the authentication scheme and go to 
    Provider Configuration
    .
  4. In the Service Provider Configuration section, see the 
    Assertion Consumer Service (ACS) URL
    . The URL is your custom domain name URL.
  5. From 
    Assertion Consumer Service (ACS) URL
    , copy the URL (that contains the custom domain URL) and paste into the application callback URL in an identity provider of your choice.
Update Existing SAML SSO
Update an existing SAML SSO for Custom Domain.
  1. Log in to the custom domain URL with Portal administrator credentials that are provided by the system (not the SAML SSO credentials).
  2. Select the SAML SSO that you want to edit.
  3. Go to custom domain URL and set up the SAML SSO from there. For more information about editing an existing SAML SSO, see Edit SAML SSO Configuration.
  4. In the existing authentication scheme, go to 
    Provider Configuration
    .
  5. In the 
    Service Provider Configuration
     section, update 
    Assertion Consumer Service (ACS) URL
     and 
    Service provider ID
     to your custom domain name URL.
  6. Copy your custom domain name URL from 
    Assertion Consumer Service (ACS) URL
     and paste into the application callback URL in an identity provider of your choice.
Delete a Custom Domain Name
If the custom domain is not needed or no longer in use for any reason, it can be deleted. By deleting the custom domain, you are reverted to the default URL (for example, 
acmeco.dev.ca.com
) unless there is another custom domain.  The Administrator would also remove a custom domain name when the domain expires to prevent the URL from getting more hits. To delete, use the following command:
curl -X DELETE --compressed "https://<PAPI_Portal_TSSG>/<tenant_id>/tools/1.0/customdomain/<customdomain>" -H "accept: application/json" -H "Authorization: Bearer <access_token>"
The following is an example:
curl -X DELETE --compressed "https://apim-ssg-phoenixproject.dev.ca.com/acmeco/tools/1.0/customdomain/portal.acmeco.com" -H "accept: application/json" -H "Authorization: Bearer f778f4fa-896c-4f55-969f-5e6a151ee322"
optional.png  Configure Gateway Custom Domain
After configuring Gateway to use your custom domain, you can update the Portal to use the same custom domain.
Update the Gateway to Use the Custom Domain
  1. Create a DNS entry for the Gateway pointing at the TSSG load balancer. The steps to do this will vary depending on the DNS provider you use.
  2. Generate a CSR in Policy Manager, and then go to a Certificate Authority (a domain registrar) to purchase a certificate. For more information, see "Generate a Certificate Signing Request (CSR)" in Gateway documentation
  3. Import a signed private key. For more information, see "Import a Private Key" in Gateway documentation.
  4. Reconfigure the SSL settings for port 8443 by setting the signed certificate as the 
    Server Private Key
     for port 8443. For more information, see "Manage Listen Ports" and "Listen Port Properties" in Gateway documentation.
  5. Update the 
    cluster.hostname
     to the new host name of the Gateway in 
    Manage Cluster-Wide Properties
     through Policy Manager. For more information, see "Manage Cluster-Wide Properties" in Gateway documentation.
Update Portal with the New Gateway Custom Domain
Before you perform this step, you must have already updated the Gateway to use the custom domain. To update Portal with the new Gateway custom domain, use the following command: 
curl -X POST --compressed 'https://<PAPI_Portal_TSSG>/<tenant_id>/tools/1.0/gateway/portal_gateway_custom_domain' -H "accept: application/json" -H "Authorization: Bearer <access_token>" -d "{ \"old_gateway_hostname\": \"<old gateway hostname>\", \"new_gateway_hostname\":\"<new gateway hostname>\" }"
The following is an example:
curl -X POST --compressed 'https://apim-ssg-phoenixproject.dev.ca.com/acmeco/tools/1.0/gateway/portal_gateway_custom_domain' -H "accept: application/json" -H "Authorization: Bearer c4f2a19a-7023-4294-8032-74c1379bacc3" -d "{ \"old_gateway_hostname\": \"acmeco-ssg.dev.ca.com\", \"new_gateway_hostname\":\"gateway.acmeco.com\" }"