Customize your domain

When you create a developer portal, by default you are provided with an Apigee sample domain name for accessing your live portal in the following format:

https://orgname-portalname.apigee.io

Where orgname is the organization name and portalname is defined using the portal name converted to all lowercase and with spaces and dashes removed.

Before launching a developer portal, it is recommended that you provide your own custom domain name. For example, a popular alternative is:

https://developers.example.com

To customize your domain name, perform the following steps:

  1. Register your domain name.
  2. Configure TLS.
  3. Add a custom domain name to your portal.
  4. Configure your DNS.

After you add a custom domain, you can edit or disable it. For help with troubleshooting issues, see Troubleshoot your custom domain.

Register your domain name

If you need to register a new domain, there are many popular domain registration sites available, such as Google Domains. Which domain registration site you choose is up to you.

When deciding on your domain name, consider that user-friendly, human-readable URLs are a key component in improving search engine optimization, as described in Implement search engine optimization (SEO).

Configure TLS

To support HTTPS, you need to configure TLS by creating keystores and aliases that contain the necessary digital certificates in the portal environment, as described in the following procedure.

To configure TLS:

  1. Purchase a TLS certificate from a reputable certificate authority, such as Google Trust Services. Which certificate authority you choose is up to you.
  2. Sign in to https://apigee.com/edge.
  3. Select your organization from your user profile menu.
  4. Select Admin > Environment to display the environment configuration.
  5. Select the TLS Keystores tab.
  6. Select portal from the environment drop-down.
    portal environment
  7. Create a keystore and alias, as described in Creating keystores and truststore using the Edge UI.

Add a custom domain name to your portal

When you add a custom domain name to your portal, the system creates the following resources for you (using the same functionality used to apply a custom domain name to an endpoint such as api.example.com):

  • A virtual host, listening on port 80, using the custom domain name you specify.

    Note: The virtual host is created in the portal environment, but you cannot view or modify this virtual host.

  • An API proxy using the custom domain URL with its target endpoint set to the default portal domain.
    The name of the API proxy matches the custom domain name with the periods replaced by underscores.

    Note: The API proxy is deployed to the portal environment. You should not modify or delete the API proxy.

To add a custom domain name to your portal:

  1. Select Publish > Portals and select your portal..
  2. Select Settings in the drop-down menu in the top navigation bar or on the landing page.
  3. Click the Domains tab.
  4. Under Custom Domain, complete the following fields.
    Warning: If you delete a keystore or alias that is associated with a custom domain, you will invalidate the custom domain configuration.
    Field Description
    Keystore Select a keystore from the drop-down list.

    Note: The list is populated using the keystores that you have created in the portal environment.

    If you have not created a keystore, click Create a Keystore and refer to Configuring TLS for more information.

    Alias Select a valid alias from the drop-down list.

    Note: The list is populated using the aliases that you have created for the selected keystore. The list does not include keystores with invalid certificate chains, Apigee domains, or truststores.

    To determine when a certificate will expire:

    • View the icons:
      • cert is valid Certificate expires in more than 30 days.
      • cert expires in 30 days Certificate expires within 30 days.
      • cert is expired Certificate has expired.
    • Position your cursor over an alias to display the remaining number of days that the certificate will be valid.
    Domain Select a domain from the drop-down list. If you have selected a wildcard alias, enter the subdomain.

    Note: The list of domains is populated using the common and alternative names for the top-level certificate in the chain defined by the selected alias.

    After you complete all fields, the Custom Domain status icon will be updated, as follows:
    Status Description
    Valid status Keystore, alias, and custom domain are valid.
    Cert will expire in 30 days Certificate will expire within 30 days.
    Status invalid Keystore, alias, and custom domain are invalid.
    In addition, the DNS configuration is validated and the Configure DNS status icon will be updated, as follows:
    Status Description
    Valid status DNS configuration is valid.
    Status invalid DNS configuration is not valid. You must configure your DNS, as described in Configuring your DNS.
  5. Ensure that Always redirect HTTP to HTTPS is enabled.
    Note: It is recommended that you disable this option only when troubleshooting your TLS configuration, as described in Troubleshooting issues with your TLS configuration.
  6. Click Enable.
    You can enable your custom domain even if the custom domain or DNS configuration is invalid.

Configure your DNS

Note: Apigee cannot configure your DNS for you. If you are not sure of the steps required, contact your domain hosting service for more information.

Next, you need to add a canonical name (CNAME) record to your domain DNS to point to {org_name}-portal.apigee.net.

To confirm the CNAME value:

  1. Select Publish > Portals and select your portal.
  2. Select Settings in the drop-down menu in the top navigation bar or on the landing page.
  3. Click the Domains tab.
  4. View the CNAME value for your organization in the Configure DNS section, as shown in the following figure: Configure DNS

The following provides an example of the CNAME record that you would configure for the custom domain shown above (that is, for the developers.example.com custom domain in the myorg organization):

developers.example.com. CNAME myorg-portal.apigee.net.

Edit a custom domain

To edit a custom domain:

  1. Select Publish > Portals and select your portal.
  2. Select Settings in the drop-down menu in the top navigation bar or on the landing page.
  3. Click the Domains tab.
  4. Edit the custom domain information.
  5. Click Save.

Disable a custom domain

To disable a custom domain name and its associated virtual host and API proxy:

  1. Select Publish > Portals and select your portal.
  2. Select Settings in the drop-down menu in the top navigation bar or on the landing page.
  3. Click the Domains tab.
  4. Click Disable.
  5. Click Disable at the prompt to confirm the operation.

The custom domain is disabled and the fields are cleared.

Troubleshoot your custom domain

The following sections provide suggestions for troubleshooting your custom domain.

Identify issues with your TLS configuration

To determine if there is an issue with your TLS configuration, disable the Always Redirect HTTP to HTTPs setting on the Domains tab, as follows:

  1. Select Publish > Portals and select your portal.
  2. Select Settings in the drop-down menu in the top navigation bar or on the landing page.
  3. Click the Domains tab.
  4. Disable Always redirect HTTP to HTTPS.
  5. Click Save.

Then, try accessing the site via HTTP to confirm whether the issue is specific to HTTPS and related to your TLS configuration. See Configuring TLS for more information.

Verify your domain DNS setup using dig

After your domain DNS is updated to include the CNAME record, it takes time for the changes to propagate to other DNS servers world-wide. You can query your domain DNS server to verify that the CNAME record was set up correctly, even before it's fully propagated to other DNS servers, using dig.

For example, the following dig command queries your domain DNS server. In the command output, the ANSWER SECTION contains the CNAME record entry.

$ dig @your.domain.dns developer.mycompany.com
; <<>> DiG 9.8.3-P1 <<>> @your.domain.dns developer.mycompany.com
; (1 server found)
;; global options:  cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 41356
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0
;; WARNING: recursion requested but not available

;; QUESTION SECTION:
;developer.mycompany.com.       IN  A

;; ANSWER SECTION:
developer.mycompany.com.    29  IN  CNAME   myorg-portal.apigee.net.

;; Query time: 141 msec
;; SERVER: 192.168.1.254#53(192.168.1.254)
;; WHEN: Mon Mar 20 16:41:59 2017
;; MSG SIZE  rcvd: 136