Google is committed to advancing racial equity for Black communities. See how.

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

For considerations for using a custom domain with a SAML identity provider, see Use a custom domain with the SAML provider.

The following sections describe how to customize your domain based on whether you are using Apigee Edge or Apigee hybrid.

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

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

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

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 80, using the custom domain name you specify.

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

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.
    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 or the selected custom domain may already be in use.
      • 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.
  6. Click Enable.
    You can enable your custom domain even if the custom domain or DNS configuration is invalid.

Step 4: Configure your DNS

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.

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.

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

Customize your domain name (Apigee hybrid)

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

  1. Register your domain name
  2. Create a Compute VM instance
  3. Create a Cloud DNS entry
  4. Install and configure the NGINX web server on your VM instance
  5. Create an SSL certificate (optional)
  6. Update the default rule configuration
  7. Update the NGINX configuration
  8. Enable the custom domain on your portal

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

NOTES:

  • Do not use the string "apigee" in your custom domain name.
  • Consider redirecting to other similar domain name alternatives.

Step 2: Create a Compute VM instance

To create a Compute VM instance, follow the steps described in Creating and starting a VM instance. Ensure that you configure the following fields as described below:

Description
Field
Name Enter a meaningful name for your Compute VM instance.
Boot Disk Select Google Drawfork Debian GNU/Linux 9 (the default).
Firewall Select Allow HTTP traffic and Allow HTTPS traffic to support both types of network traffic.
External IP address Configure the external IP address. For more information, see Reserving a static external IP address.
  1. Expand the Management, security, disks, networking, sole tenancy section.
  2. Click Networking.
  3. Under Network interfaces, click on the default network interface to edit it.
  4. In the External IP drop-down, select Create IP address.
  5. Enter a name for the IP address that is meaningful to you.
  6. Click Create.
    An IP address is created and reserved.
  7. Take note of the IP address. You will need to provide the value in the next step.

Step 3: Create a Cloud DNS entry

To create a Cloud DNS zone, follow the steps described in Managing Zones. Ensure that you configure the following fields as described below:

Field Description
Zone type Select Public.
Zone name Enter a meaningful name for the zone. For example: mycompany-zone
DNS name Enter the suffix for the zone using a domain name that you own. For example: mycompany.com

After you create a zone, on the Zone details page, click Add record set and follow the steps described in Managing Records. Ensure that you configure the following fields as described below:

Field Description
DNS Name Specify the prefix for your DNS name. The suffix that you defined for the Cloud DNS zone is also displayed, but is not editable. For example: developers.mycompany.com
Resource Record Type Select A (the default).
TTL Set to desired value or leave set to 5 (default).
TTL Unit Set to desired value or leave set to minutes (default).
IPv4 Address Enter the external IP address that you configured when creating the Compute VM instance.

Step 4: Install and configure the NGINX web server on your VM instance

To install the NGINX web server on your VM instance:

  1. Connect to your VM instance using SSH, as described in Connecting to instances.
  2. Install the NGINX web server:

    sudo apt-get install nginx 

    Enter Y to confirm the install when prompted.

  3. Confirm that NGINX has been installed:

    curl localhost

    The Welcome to nginx! HTML page contents are returned.

  4. Confirm the external IP address that you configured when creating the Compute VM instance is accessible:

    curl _external-ip-address

    The Welcome to nginx! HTML page contents are returned.

If the connection to the external IP address fails:

  • Ensure that the Firewall configuration for your VM instance is set to both Allow HTTP traffic and Allow HTTPS traffic. See Step 2: Create a Compute VM instance.
  • You may need to configure a firewall rule, as described in Configuring Firewall Rules, and add it to your VM instance, as described in Adding tags. Ensure that you configure the following fields as described below:

    Field Description
    Name Enter a meaningful name, such as http-to-portal
    Network Select default (default)
    Direction Select Ingress (default)
    Action on match Select Allow (default)
    Targets Select Specified target tags (default)
    Target tags Enter a meaningful tag name, such as http-to-portal
    Source filter Select IP ranges
    Source IP ranges Enter 0.0.0.0/0
    Protocols and ports Select Specified protocols and ports
    Select tcp for the protocol and enter 80,443 for the ports

To configure the NGINX server to map to your custom domain:

  1. Create a file named /etc/nginx/conf.d/hostname.conf using your favorite editor. For example:

    sudo nano /etc/nginx/conf.d/developers.conf

  2. Enter the following contents, replacing your-custom-domain-name with your domain name, such as developers.mycompany.com:

    server {
        listen        80;
        server_name   your-custom-domain-name;
        server_tokens off;
    #default rule location / { proxy_pass http://localhost; } }

  3. Reload the NGINX web server:

    sudo nginx -s reload

  4. Confirm the domain name is accessible:

    curl your-custom-domain-name

    Confirm that the "Welcome to NGINX" HTML page is returned.

Step 5: Create an SSL certificate (optional)

Note: This step is optional.

To create an SSL certificate:

  1. Install Let's Encrypt:

    sudo apt-get install certbot python-certbot-nginx

    Enter Y to confirm the install when prompted.

  2. Create an SSL certificate and install it into NGINX for your domain:

    sudo certbot --nginx

    Respond to the prompts as indicated below:

    Prompt Response
    Enter your email address your-email-address
    Read and agree to the terms of service A
    Consent to or decline sharing your email address with the Electronic Frontier Foundation Y or N
    Enter the numbers corresponding to the domains names for which you'd like to activate HTTPS (separated by commas) 1
    Choose whether or not to redirect HTTP traffic to HTTPs 2 (Redirect)

    A certificate and chain are created. In addition, the /etc/nginx/conf.d/hostname.conf file is updated with information about the SSL certificate. You'll see comments similar to the following on relevant lines in the file: # managed by Certbot

  3. Confirm the domain name is accessible over HTTPS:

    curl https://your-domain-name

Step 6: Update the default rule configuration

Edit the /etc/nginx/conf.d/hostname.conf file to replace the #default rule with the content shown below.

Replace the three variables at the top of the content below with values that are relevant to your custom domain and portal, as follows:

Variable Description
$my_custom_domain Your custom domain, such as: developers.mycompany.com
$my_portal Default domain name for your integrated portal, such as: orgname-portalname.apigee.io
$my_idp Navigate to the live portal, click Sign in, and copy the domain name from the resulting URL. For example: wtupohzhfghzszv-ppgfvtqop14v7gii.accounts.apigee.io

Note: Do not include https:// or /login in the variable definition.

# set the variable values
    set $my_custom_domain your-custom-domain-name;
    set $my_portal your-portal-domain-name;
    set $my_idp portal-sign-in-domain-name;

    #portal IDP rule
    location ~ ^/accounts/(.*)$ {
        proxy_pass https://$my_idp/$1$is_args$args;
        proxy_set_header x-apigee-cname $my_custom_domain;
        proxy_redirect  https://$my_idp https://$my_custom_domain/accounts;
    }

    #default rule
    location / {
        proxy_pass https://$my_portal;
        add_header Set-Cookie "portalDefaultDomain=${my_portal};Domain=${my_custom_domain};Path=/;Max-Age=100000";
    }

Step 7: Update the NGINX configuration

Edit the /etc/nginx/nginx.conf file to add a resolver which allows NGINX to lookup DNS entries. Set the resolver to 8.8.8.8, which is the Google Public DNS IP address, as the first line in the http configuration. For example:

...
http {
   resolver 8.8.8.8;
...

Step 8: Enable the custom domain on your portal

To enable the custom domain on 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. Enter your custom domain name.
  5. Click Enable.

Test that when you access the custom domain in a browser you are directed to your integrated portal.

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.