Blog

Akamai 101: API-Focussed Property Manager Config

Akamai 101: Setting Up an API-Focused Property Manager Configuration

July 9, 2018 by Jeff Costa

line

TIP: If you encounter any unfamiliar terms related to Akamai network and property management in this blog post, check the Glossary section at the end.

In order to run your API on Akamai, the first thing you need to do is set up your backend Luna Property Manager configuration. In this blog post, I’ll show you exactly how to do that.

To set up your configuration, follow these six steps if you’re completely new to Akamai and if you don’t already have a digital property set up in Property Manager:

 

  1. Tell edge servers how to find your origin server
  2. Establish an SSL certificate in the Certificate Provisioning System
  3. Add permissions to a user role
  4. Create a new property
  5. Configure your property’s hostname settings
  6. Add the Akamai API Gateway behavior to your property
     
Note: If you already have a digital property and your origin hostnames are associated to an edge hostname, jump to step 3 (Add permissions to a user role) and step 6 (Add the Akamai API Gateway behavior to your property).

1. Tell edge servers how to find your origin server

Edge servers retrieve your API content from the origin-server hostname before serving it to API clients. In a property configuration file, you must specify which origin-server hostname the edge servers use. The DNS configuration for a dual-stacked hostname must include both A and AAAA DNS record types, returning both IPv4 and IPv6 addresses. Complete the following task to add a DNS record before using the Akamai edge network:

On your authoritative name server, create DNS records for your origin-server hostname by using the following naming convention: origin-<original origin hostname>

where <original origin hostname> is the hostname of the API that you want to have delivered by the Akamai edge network.

For example, if the original DNS records contain:

For IPv4: my-api.hostname.com. IN A 192.0.2.1 For IPv6: my-api.hostname.com. IN AAAA 2001:0DB8:1234:1234:1234:1234:1234:1234

The added records should contain:

For IPv4: origin-my-api.hostname.com. IN A 192.0.2.1M For IPv6: origin-my-api.hostname.com. IN AAAA 2001:0DB8:1234:1234:1234:1234:1234:1234

2. Establish an SSL certificate in the Certificate Provisioning System

To make your API traffic secure at Akamai, you need to maintain a valid TLS certificate. You can establish a valid TLS certificate in Certificate Provisioning System (CPS) in the Akamai Luna Control Center. CPS provides full life cycle management of TLS certificates for your applications.

Note: This task is not mandatory; it only applies when deploying APIs on a secure network. If you do not plan to make your API traffic secure via TLS, you may skip this task.

  1. Log in to Luna Control Center.
  2. From the Configure menu choose Service Provider Support > Certificate Provisioning System (CPS).
  3. Create a certificate enrollment.

The TLS certificate name must match the name of the application hostname.

Akamai recommends:

  • Using server name indication (SNI) certificates
  • Including a test domain in the subject alternate names of your certificate

For more information about certificate enrollments, see CPS Online Help.

 

3. Add permissions to a user role

To go through the Property Manager setup and configure API features at Akamai, you first need to ensure that your Luna user has appropriate permissions assigned in the Identity and Access Management application in Luna.

Note: If you’re an Akamai admin user, you may skip this task because you should already have all required permissions.

If a user that you want to grant access to does not exist in Luna, you should first create that user in Identity and Access Management. For details on creating users, modifying roles, and other aspects of the Identity and Access Management application, see the Identity and Access Management online help.

  1. Log in to Luna Control Center at http://control.akamai.com by entering your User ID and password.
  2. From the Configure menu, under Organization, select Manage Users & Groups.
  3. On the Identity and Access Management page, select the Roles tab.
  4. From the list of available roles, choose the one you want to add permissions to, and from its corresponding Action menu, select Clone role.

Note: Normally, each role that you may clone already contains some predefined permissions. The Description column explains a role’s level of access and it should help you decide which role to associate with a particular user.

5. In the Clone a role window, do these steps:

  • In the Name field, enter a name for the new role.
  • In the Description field, enter a description of the new role.
  • From the Permissions list, select All Permissions.
  • In the section on the right, select the permissions that you want to assign. Click Save.

The following permissions allow access to Akamai API Gateway and related features. See the description of each Luna permission to learn about the access level it provides.

Edit Access to Property Manager Allows users to create and configure properties in Property Manager.

WAF Admin, WAF Config Allow users to access API Definitions, view and edit endpoint and resource information, and manage API versions. Allow KSD customers to modify API security features.

Akamai API Gateway Administrator Allows users to access and modify delivery features, such as API privacy, JWT validation, CORS, caching, and GZIP compression. Allows the use of the Key and Quota Management application.

Botman Feature, Botman Config For Akamai Bot Manager customers, allow users to access and modify resource purpose settings.

6. On the Identity and Access Management page, select the Users and API Clients tab. 7. In the Client Name column, click the name of the user that you want to assign the cloned role to. 8. In the Edit <username> window, select the Assign roles tab. 9. In the Assign roles tab, click the pencil icon next to the appropriate name. 10. From the list of roles, select the role you assigned the permissions to. 11. Click Save to assign the role with the specified permissions to the selected user.

4. Create a new property

A property is an identifier that indicates which property configuration file and product to use when processing incoming requests. Follow these steps to create a property:

  1. Log in to Luna Control Center by entering your User ID and Password.
  2. From the Configure menu, under Property Manager, select New Property.
  3. On the New Property page, from the Property Type menu, select Property Manager.
  4. In the Product area, select the Akamai product you want to configure traffic for.

The following products may include the Akamai API Gateway module:

  • Ion
  • Dynamic Site Accelerator
  • Kona Site Defender
  • Kona Site Defender plus Ion

You can also attach Akamai API Gateway to end-of-sale (EOS)/legacy products.

5. In the Property Name field, enter a name for your property. 6. Click Create Property.

5. Configure your property's hostname settings

You must associate the property hostnames to the edge hostname in Property Manager after you create your property configuration. On the edge network, edge servers read from property configuration files to determine how to distribute content. The association between your property and edge hostnames allows networks to resolve requests for your API. Follow these steps to configure secure delivery of API data over HTTPS with your hostname:

  1. On the Property Manager Editor page, in Property Version Information, select Secure (Customer Certificate).
  2. In Property Hostnames, click Add.
  3. In the Hostnames step, enter your property hostname, or an appropriate portion of that hostname and click Next.
  4. In the IP Version step:
  • Select IPv4 + IPv6 (for dual stack). Note: The IPv4 + IPv6 (dual stack) is the recommended option for most Akamai API Gateway customers. However, if your system is suited only for IPv4, you may select IPv4 instead.
  • Click Next.

5. On the Certificates Matching All Property Hostnames tab, select an SSL certificate.

  • On the Certificates Matching All Property Hostnames tab, select an SSL certificate.
  • Click Next.

6. In the Edge Hostnames step, click the pencil icon and select the existing edge     hostname that your account representative provided:

  • In the Associate Edge Hostname to Property Hostname window, select Select Existing.
  • From Edge Hostname, select the edge hostname that your account representative provided and click Submit.

General property configuration guidelines

When you create a property, some rules and behaviors that apply to your product are already present in the Property Configuration Settings section. To tailor a property specifically for API delivery, you only need to add a simple behavior and ensure that it’s enabled.Depending on the product you’re adding the Akamai API Gateway module to, you might need to configure other behaviors unrelated to API traffic. The configuration of such behaviors is outside of the scope of this document. You can refer to Property Manager Help for detailed behavior descriptions and configuration guidelines.

If you plan to use your property solely for API-related purposes, you can safely delete all web browser-related behaviors, such as Real User Monitoring (RUM) or Front-End Optimization (FEO). These behaviors do not affect your API traffic in any way.

In the Property Configuration Settings section, you have an option to add a couple of HTTP-method related behaviors, such as Allow POST. Adding these behaviors does not have any impact on the methods your API consumers will be able to use when interacting with your registered APIs. In API the Definitions configuration screen, you associate methods to each resource you define and these settings take precedence over any HTTP method configuration in Property Manager.

Similarly, the Property Manager Editor lets you configure caching settings via behaviors such as Caching, Cache HTTP Error Responses, or Downstream Cacheability. Though at first glance these behaviors may seem relevant to your API traffic configuration, you should  set up caching in the API Definitions application. By doing so, you overwrite any Property Manager settings and allow Akamai API Gateway to control the caching of your registered APIs.

Conversely, the Last Mile Acceleration (Gzip Compression) behavior overwrites the GZIP compression settings that you enable in Akamai API Gateway. Thus, if you don’t want the Property Manager settings to interfere with your configuration in API Definitions, delete the Last Mile Acceleration (Gzip Compression) behavior from your property, and configure it in API Manager.

6. Add the Akamai API Gateway behavior to your property

Follow the steps below to add the Akamai API Gateway behavior to the default rule of a property configured for your product. This action lets you deliver APIs over the Akamai network.

  1. In Luna Control Center, select your group breadcrumb.
  2. On the Property Groups page, select the Property Name link for your property.  
  3. On the Property Details page, in the Manage Versions and Activations section, click the version that you want to edit.  
  4. On the Property Manager Editor page, click Edit New Version.  
  5. In the Property Manager Configuration panel, select Default Rule if not already selected.
  6. In the Behaviors section of the Default Rule, click Add Behavior.
  7. In the Add a Behavior for this Rule window’s search field, enter: Akamai API Gateway
  8. In the left pane, select Akamai API Gateway and click Insert Behavior.
  9. In the bottom-right corner of the page, click Save.

The Akamai API Gateway behavior is now included in your property.

Set up your API configuration for testing

Before you go live and start serving traffic through the Akamai production network, we recommend that you activate your property on the Akamai edge staging network and point your browser to an edge server. You can use this staging network of edge servers to send test requests and make sure that your connection with Akamai has been established properly. To get set up, simply complete these two steps:

1. Activate Akamai API Gateway in the staging environment

You can activate a new version of your property with the Akamai API Gateway behavior in the staging environment to verify and test your configuration before going live with it.

  1. In Luna Control Center, select your group breadcrumb.
  2. On the Property Groups page, select the Property Name link for your property.
  3. On the Property Details page, in the Manage Versions and Activations section, click the version of your configuration with the Akamai API Gateway behavior enabled.
  4. On the Property Manager Editor page, on the Activate tab, click Activate v# (version number) on Staging.
  5. Track progress by monitoring the Activate tab.

 

 

2. Point your local computer to staging edge servers to test

To test your property configuration on staging, first modify your local hosts file to direct your computer to request content from an Akamai staging edge server rather than your origin API server. This practice is commonly referred to as spoofing.

  1. In Luna Control Center, select your group breadcrumb.
  2. On the Property Groups page, select the Property Name link for your property.
  3. On the Property Details page, in the Manage Versions and Activations section, click the version that you want to test.
  4. On Property Manager Editor page, in the Property Hostnames section, find your edge hostname.
  5. Look up the IP address of the staging version of that edge hostname using one of the two methods below, and copy it to your local clipboard.
  • On a Windows computer, open a new command prompt and perform an nslookup of the staging hostname: nslookup www.my-api.com.edgekey-staging.net
  • On a Mac computer or Linux/Unix machine, open a new terminal, and perform a dig of the staging hostname: dig www.my-api.com.edgekey-staging.net

Note: the staging version of your edge hostname inserts -staging before the final .net.

6. Open your local hosts file in a text editor.

  • For Windows, go to C:\Windows\System32\drivers\etc\hosts.

The directory above \system32\might vary in your environment.

  • For Mac, go to /private/etc/hosts.
  • For Linux/Unix, go to /etc/hosts.

7. At the end of the hosts file, add an entry for your origin hostname that includes the     IP address of the staging version of the edge hostname (from clipboard) and also your property’s domain. For example: 1.2.3.4www.my-api.com

8. Save and close the hosts file.

Note: To undo the redirection to the edge server, remove the new entry from your hosts file.

9. On Mac OS X 10.6 and later, run the following command to flush your DNS cache: dscacheutil -flushcache

Any requests that you’ll make from this computer will now go to the staging edge servers instead of the production servers.

Activate Akamai API Gateway in the production environment

Once you have completed your testing on staging, you will l go live with your verified Akamai API Gateway configuration by activating your property version in the production environment.

  1. In Luna Control Center, select your group breadcrumb.
  2. On the Property Groups page, select the Property Name link for your property.  
  3. On the Property Details page, in the Manage Versions and Activations section, click the version of your configuration that’s enabled with the Akamai API Gateway behavior.  
  4. On the Property Manager Editor page, click Activate v# on Production.
  5. Track progress by monitoring or refreshing the Activate tab.  
  6. Once your property is active, create the DNS CNAME record (for the digital property on your authoritative name servers) that CNAMEs to the edge hostname.

Congratulations. You’ve now set up an Akamai API configuration and pushed it live. Check out all of Akamai’s administrative APIs to see more of what’s possible.

Glossary

The definitions below can help you follow the instructions in this blog post.

Term Definition
API gateway A single-point software layer between one to many API services and their consumer applications.
Behavior In Property Manager, an element in a rule that specifies a feature to apply to requests. A rule can have many behaviors or only one.
Digital property An identifier that indicates which property file and application to use when processing incoming HTTP requests. Often, the digital property is the full, end-user-facing hostname or fully qualified domain name of your application. For instance, www.example.com might be both your domain name and your digital property name. The term “property” is more general and can include several digital properties (such as www1.example.com, www2.example.com, www3.example.com, etc.). So, if you have multiple hostnames associated with a single domain, those digital properties would be managed under one property in Property Manager.
Edge hostname A customer-specific subdomain on a domain that maps incoming requests to edge servers. Typically, customers specify edge hostnames in Canonical Name (CNAME) records.
Edge server An Akamai-owned server that receives requests and provides an integrated suite of services for content and application delivery, content targeting, edge processing, and business intelligence.
Origin server The server where you keep your content. Akamai retrieves content from the origin server and serves it from edge servers.
Origin server hostname The hostname mapping to the customer’s origin server where Akamai retrieves your content.
Property Manager The application that you use to provision, configure, test, and activate your digital properties.
Rule In Property Manager, an instruction that controls how Akamai applies features to requests. Rules consist of two parts: match criteria and behaviors. If a request fulfills the requirements given in a rule’s match criteria, Akamai applies the features configured in that rule’s behaviors. A configuration typically has multiple rules.

 

Jeff Costa is a senior product manager at Akamai Technologies.

Categories: