You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/publish/portal/custom-domain). info


> [!NOTE]
> **Note:** The integrated portal is available as an Apigee-managed solution for Apigee Edge for Public Cloud customers only. If you are an Apigee Edge for Private Cloud customer, refer to the customer-managed [Drupal portal solution](https://docs.apigee.com/api-platform/publish/drupal/open-source-drupal.md.txt).

<br />

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`

> [!NOTE]
> **Note:** Domain names can be customized for paid accounts only.

For considerations for using a custom domain with a SAML identity provider, see [Use a custom domain with the SAML provider](https://docs.apigee.com/api-platform/publish/portal/portal-identity-provider.md.txt#use_a_custom_domain_with_the_saml_identity_provider).

The following sections describe how to customize your domain.

## Customize your domain name (Apigee Edge)

With Apigee Edge integrated portals, to customize your domain name perform the following steps:

1. [Register your domain name](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#register-edge).
2. [Configure TLS](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#configuring-tls).
3. [Add a custom domain name to your portal](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#add).
4. [Configure your DNS](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#dns).

After you add a custom domain, you can edit or disable it. For help with troubleshooting issues, see [Troubleshoot your custom domain](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#troubleshoot).

> [!NOTE]
> **About the portal environment**
>
> The **portal** environment is available for configuring custom domains. The portal environment can only be [configured on the TLS Keystores tab](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#configuring-tls) on the Environments page to enable self-service TLS configuration. All other configuration in the portal environment happens behind the scenes.

### Step 1: Register your domain name

If you need to register a new domain, there are many popular domain registration sites available, such as [Google Domains](https://domains.google). 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)](https://docs.apigee.com/api-platform/publish/portal/portal-best-practices.md.txt#seo).

> [!NOTE]
> **Notes:**
>
> - Do not use the string "apigee" in your custom domain name.
> - Consider redirecting to other similar domain name alternatives.

### Step 2: 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](https://pki.goog/). 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 \> TLS Keystores** to display the TLS keystores page.
5. Select **portal** from the environment drop-down.

   ![](https://docs.apigee.com/static/api-platform/images/portal-env.png)
6. Create a keystore and alias, as described in [Creating keystores and truststore using the Edge UI](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui.md.txt).

### Step 3: 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 443, using the custom domain name you specify.

  > [!NOTE]
  > **Note:** The virtual host is created in the **portal** environment, but you cannot view or modify this virtual host.

  <br />

- 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. The API proxy is deployed to the portal environment.

  > [!CAUTION]
  > **CAUTION:** Do not modify or delete the API proxy that is associated with a custom domain. Otherwise, you will invalidate the custom domain configuration and receive a `Unable to identify proxy for host` error message when attempting to access the custom domain URL. For information about restoring the API proxy in the event it is modified, see [Troubleshoot: Unable to identify proxy for host](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#troubleshoot-portal-API-proxy).

  <br />

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.  

   > [!CAUTION]
   > **Caution:** If you delete a keystore or alias that is associated with a custom domain, you will invalidate the custom domain configuration and it will no longer be accessible.

   | 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 in step 2. After you select a keystore, the **Alias** field displays. |
   | 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 on the list will expire: - View the icons: - ![cert is valid](https://docs.apigee.com/static/api-platform/images/valid-cert.png) Certificate expires in more than 30 days or the selected custom domain may already be in use. - ![cert expires in 30 days](https://docs.apigee.com/static/api-platform/images/status-caution.png) Certificate expires within 30 days. - ![cert is expired](https://docs.apigee.com/static/api-platform/images/invalid-cert.png) Certificate has expired. - Position your cursor over an alias to display the remaining number of days that the certificate will be valid. After you select an alias, the **Domain** field displays. |
   | 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](https://docs.apigee.com/static/api-platform/images/status-green.png) | Keystore, alias, and custom domain are valid. |
   | ![Cert will expire in 30 days](https://docs.apigee.com/static/api-platform/images/status-yellow.png) | Certificate will expire within 30 days. |
   | ![Status invalid](https://docs.apigee.com/static/api-platform/images/status-red.png) | 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:

   > [!NOTE]
   > **Note:** For wildcard domains, you need to click ![](https://docs.apigee.com/static/api-platform/images/refresh.png) in order to validate the DNS configuration.

   | Status | Description |
   |---|---|
   | ![Valid status](https://docs.apigee.com/static/api-platform/images/status-green.png) | DNS configuration is valid. |
   | ![Status invalid](https://docs.apigee.com/static/api-platform/images/status-red.png) | DNS configuration is not valid. You must configure your DNS, as described in [Configuring your DNS](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#dns). |

5. Click **Enable** (or **Save** if you are editing).   
   You can enable your custom domain even if the custom domain or DNS configuration is invalid.

**Note:** You may encounter one of the following errors:

- If another portal in your organization is using the same custom domain, the following error message is displayed:   
  `The portal portal id is already using the specified custom domain`
- If the following error is displayed when you save the custom domain name, contact [Support](https://docs.apigee.com/api-platform/troubleshoot/support.md.txt) for assistance. They will help set up the portal environment to support customization of your domain name.  
  `Portal environment not found: Please contact support`

### Step 4: Configure your DNS

> [!NOTE]
> **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](https://docs.apigee.com/static/api-platform/images/dns.png)

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

> [!NOTE]
> **Note:** 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. See [Verify your domain DNS setup using dig](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#troubleshoot-dns) to verify your DNS set up. You can also check the validity in the DNS configuration by clicking ![](https://docs.apigee.com/static/api-platform/images/refresh.png) in the Configure DNS section of the **Domains** tab.

### Troubleshoot your custom domain

The following sections provide suggestions for troubleshooting your custom domain.

#### Troubleshoot: 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](ftp://ftp.isc.org/isc/bind9/cur/9.10/doc/arm/man.dig.html).

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

#### Troubleshoot: Unable to identify proxy for host

When you [add a custom domain name to your portal](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#add), an API proxy is generated by default that uses the custom domain URL with its target endpoint set to the default portal domain. If you modify or delete the API proxy that is associated with a custom domain, you will invalidate the custom domain configuration and receive a `Unable to identify proxy for host` error message when attempting to access the custom domain URL. For example:


    {"fault":{"faultstring":"Unable to identify proxy for host: developers.mycompany.com:443 and url: \/","detail":{"errorcode":"messaging.adaptors.http.flow.ApplicationNotFound"}}}

To restore the custom domain configuration in the event that the API proxy has been modified or deleted:

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 **Save** to restore the API proxy.

## Update your certificate

> [!NOTE]
> **Note:** You cannot update an existing keystore to add a new certificate. You must create a new keystore when updating a certificate.

For general information on updating TLS certificates, see
[Update a TLS certificate](https://docs.apigee.com/api-platform/system-administration/update-or-replace-ssl-certificate.md.txt).

1. Follow the steps in [Step 2: Configure TLS](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#configuring-tls).
2. Follow the steps in [Step 3: Add a custom domain name to your portal](https://docs.apigee.com/api-platform/publish/portal/custom-domain.md.txt#add)