Obtaining a vanity hostname

If you want a branded experience when users interact with identity-related flows with your organization, you can obtain a vanity hostname for your IBM® Security Verify tenant. You can customize the login, registration, profile management experiences, and more.

Before you begin

To configure a vanity hostname, you and IBM must complete several configuration steps. To start the process, you must complete the IBM Vanity Hostname Certificate Provisioning Form that is provided by the IBM project office.

Also ensure the following items.

  • Understand the Vanity hostname syntax and options and select the best one for your organization based on your organization certificate practices.
  • Understand the prerequisites.
  • Contact your IBM® representative to purchase a tenant and a vanity hostname.
  • Ensure that you can properly engage your organization’s DNS/website admins for domain validation.
  • The customer must own the domain of the vanity hostname. If the vanity hostname is sso.acme.com, your organization must own the domain acme.com.
  • The vanity hostname must be unique and not exist already. It applies to the tenant and must be used for IBM Security Verify only.

About this task

A vanity hostname is a custom hostname for your IBM Security Verify tenant. A default tenant hostname mentions IBM. With a vanity hostname, a customer can customize the hostname such that IBM is not displayed in the URL. For example, your Verify tenant hostname might be acme.verify.ibm.com, but you might like users to instead see a vanity hostname of login.acme.com.

Vanity hostname syntax
When your organization first receives an IBM Security Verify tenant, the tenant URL follows the following syntax. <tenant identifier>.<domain> Where
  • <tenant identifier> is the tenant identifier provided. An example can be <acme>.
  • <domain> defaults to <verify.ibm.com>, but can be customized for a vanity hostname.
  • The full hostname in this example is acme.verify.ibm.com, which is the URL that users see when they log in along with other identity interactions that are enabled by IBM Security Verify.
Each vanity hostname requires a certificate to allow the SSL negotiation between the user and Verify.
  • A “trusted” certificate authority must sign the certificates. They must not be self-signed.
  • The following section describes the provisioning of the certificate for a vanity hostname.
  • After the certificate is provisioned, IBM performs extra steps to fully provision a vanity hostname. Those extra steps take approximately five working days to complete.
Certificate configuration options
Each certificate must have a "Common Name" (CN). It can also have "Subject Alternative Names" (SANs). The certificate covers all hostnames that are listed either as CN or SAN.
Note: Wildcards for example, *.so.acme.com are not supported for either CN or SAN.
If you provide only a “Common Name” when you complete the certificate form, a specific certificate is needed for each vanity hostname.
If three Verify tenants need a vanity hostname and only “Common Name” is supplied, the organization pays for each vanity hostname because each vanity hostname has its own certificate. In this example, three vanity hostnames need to be purchased.
CN = sso.acme.com

CN = sso-qa.acme.com

CN = sso-dev.acme.com
Note: When a user authenticates with Verify through one of those vanity hostnames such as sso.acme.com, the user sees only the vanity hostname that is being used. The user does not see sso-qa.acme.com and sso-dev.acme.com that are also valid vanity hostnames. Potential attackers cannot easily discover all the vanity hostnames. They can see only the one that they’re using.

If “SAN Names” are provided in addition to “Common Name” when completing the certificate form, each SAN name is provisioned on the same certificate as the “Common Name”.

If three Verify tenants need a vanity hostname where “Common Name” is supplied along with 2 SAN Names, the organization pays for only one vanity hostname. In this example, one vanity hostname needs to be purchased.
CN = sso.acme.com
  SAN = sso-qa.acme.com
  SAN = sso-dev.acme.com
Note: When a user authenticates with Verify through one of those vanity hostnames such as sso.acme.com, the user can also see the other vanity hostnames that are covered by the certificate. In this case, sso-qa.acme.com and sso-dev.acme.com. Unfortunately potential attackers can use this information. It makes it easier for them to discover all the valid vanity hostnames.
If you want to move from “SAN” to "CN", you must restart the process and align to the "CN" pricing structure.
Certificate provisioning options
After a vanity hostname option is selected, organizations must select either "IBM provisioned” or “3rd party certificate” to validate or provision the certificate.
IBM provisioned
IBM can order certificates on behalf of the organization. IBM uses DigiCert as certificate provider and DigiCert signs the certificates.

The certificate validation type is OV (Organization Validation) and the client must go through the DigiCert validation process for the certificate. As a certificate authority, Digicert must independently validate that the relevant owner of the requested domain approved the certificate. This DigiCert validation process is independent and is outside of IBM Security Verify interactions.

The process includes validation of the company’s address and validation of the domain administrator. The interaction with DigiCert is directly between DigiCert and the customer.

If you select the IBM option, the process is as follows.
  1. Notify your domain administrator who is listed in whois.com that DigiCert is going to issue a Domain Validation request.
  2. Return the validation to DigiCert promptly.
  3. DigiCert then attempts to communicate with the administrative contact that was provided in the IBM Vanity Hostname Certificate Provisioning Form by using a validated phone number that belongs to your organization. The validation is done on a live phone call.
    Note: Depending on the ability of DigiCert to find the right contacts in the organization, multiple attempts might be needed.
Third-party certificate
With a third-party certificate, organizations can use the certificate authority of their choice after IBM generates a certificate signing request (CSR).
The following steps show the process flow.
  1. IBM Generates the CSR.
  2. IBM sends this CSR to your organization.
  3. Your organization sends this CSR to your own CA. Your organization can choose the validation type that you want.
  4. Your CA returns the signed certificate to your organization.
  5. Your organization sends the certificate (leaf certificate + trust chain: Intermediate and root certificate) to IBM

Procedure

  1. Download and complete the IBM Security Verify Certificate Provisioning Form.
    Ensure that you complete all mandatory fields.
  2. Create a support ticket
    Go to How to Open a Case and open a case with the subject “Vanity host name request for customer name” and attach the vanity host form to the ticket.
  3. Create a CNAME DNS record that points your vanity hostname to its related IBM Security Verify tenant.
    Only your organization can create the CNAME DNS record. For example, sso.clienthostname.com CNAME <tenant>.verify.ibm.com.
  4. After the CNAME DNS is configured correctly, inform IBM by using the previously created support ticket.
    The vanity hostname is not yet usable. IBM must still complete more processes.
  5. IBM completes the remaining configuration.
    When this step is done, IBM notifies your organization and the vanity hostname is ready to use.