Akamai Authentication: API Security & Credential Setup

Authentication overview

Akamai provides authentication mechanisms designed to secure access to its management APIs, configuration portals, and edge services. These mechanisms ensure that only authorized entities can interact with Akamai's global network, manage configurations, or retrieve data. The primary method for API interaction is a custom scheme known as EdgeGrid, which combines API keys with request signing, along with support for OAuth 2.0 for integrations requiring delegated authorization.

Authentication to Akamai's developer APIs primarily involves signing requests with credentials generated within the Akamai Control Center. This approach secures communication and verifies the identity of the calling application or user. For web content and user access to applications protected by Akamai, various authentication and authorization solutions are available through products like Akamai App & API Protector and Enterprise Application Access, which can integrate with identity providers using standards such as SAML, OpenID Connect, and OAuth 2.0. The focus here is on authenticating programmatic access to Akamai's management plane.

Supported authentication methods

Akamai offers several methods for authenticating access to its platform and APIs, catering to different integration needs and security requirements:

• EdgeGrid Authentication: This is the recommended method for programmatic access to Akamai APIs. It's a custom HMAC-SHA256 based signing scheme that incorporates API keys, client tokens, and access tokens. Every API request is cryptographically signed, preventing tampering and unauthorized access. Akamai provides detailed EdgeGrid authentication documentation for its APIs.
• OAuth 2.0: For scenarios requiring delegated authorization, such as third-party applications accessing Akamai resources on behalf of a user, Akamai supports OAuth 2.0. This allows applications to obtain limited access to user accounts without exposing user credentials. The standard OAuth 2.0 authorization framework is widely adopted for API security.
• API Client Tokens: These are combinations of client tokens, client secrets, and access tokens generated within the Akamai Control Center. They are used in conjunction with EdgeGrid to sign API requests.
• Service User Keys: For some older or specialized integrations, Akamai may use service user keys, which are typically username/password pairs or API keys directly assigned to service accounts. These are generally being phased out in favor of EdgeGrid for API access due to its enhanced security properties.

The following table summarizes Akamai's primary authentication methods for API access:

Getting your credentials

To obtain credentials for Akamai API access, you typically follow these steps within the Akamai Control Center:

1. Log In to Akamai Control Center: Access the Akamai Control Center with your user account.
2. Navigate to API Credentials: Go to Manage > Identity & Access > API Clients.
3. Create a New API Client: Click on "New API Client" to begin the creation process.
4. Configure Client Details:
   • Provide a descriptive Name for your API client, such as "My Application Integration."
   • Assign appropriate Permissions (scopes) to the client. This is crucial for adhering to the principle of least privilege, ensuring the client can only access the necessary APIs and resources. For example, if your application only needs to manage CDN configurations, you would grant permissions related to the "Content Delivery Network" API.
   • Specify Callback URLs if you are configuring an OAuth 2.0 client for delegated access.
   • Set an expiration date for the credentials to enforce periodic key rotation.
5. Generate Credentials: Once configured, the Control Center will generate the necessary credentials, which typically include:
   • Client Token: A unique identifier for your API client.
   • Client Secret: A secret key used in conjunction with the client token for request signing.
   • Access Token: An additional token that, along with the client token and secret, forms the complete set of credentials for EdgeGrid authentication.
6. Securely Store Credentials: It is critical to store these credentials securely. Do not embed them directly into source code or commit them to version control systems. Use environment variables, secret management services, or secure configuration files. Akamai provides SDKs and libraries to simplify the process of using these credentials with EdgeGrid.

For some services, you may need to register an application within an identity provider integrated with Akamai, such as an enterprise IAM system, to obtain client IDs and secrets for OAuth 2.0 flows. Refer to the specific Akamai product documentation for those scenarios.

Authenticated request example

Using Akamai's Python SDK, an authenticated API request using EdgeGrid typically involves configuring a client with your credentials and then making calls. This example demonstrates how to make a basic authenticated request using the akamai-edgegrid Python library. This library handles the complex signing process automatically.

import requests
from akamai.edgegrid import EdgeGridAuth, EdgeRc

# Configure EdgeRc client from a file (recommended for production)
# Alternatively, credentials can be passed directly as a dictionary
# edgerc = EdgeRc(path='~/.edgerc', section='default')
# or
edgerc = {
    'host': 'akab-your-client-token-xxxx.luna.akamaiapis.net', # Your Akamai API host
    'client_token': 'akab-client-token-xxxx',
    'client_secret': 'client-secret-xxxx',
    'access_token': 'akab-access-token-xxxx'
}

# Replace with the actual host and API endpoint relevant to your Akamai configuration
BASE_URL = f"https://{edgerc['host']}"
API_PATH = '/config-dns/v2/zones'

try:
    # Initialize the EdgeGridAuth object
    session = requests.Session()
    session.auth = EdgeGridAuth(
        client_token=edgerc['client_token'],
        client_secret=edgerc['client_secret'],
        access_token=edgerc['access_token']
    )

    # Make an authenticated GET request
    response = session.get(f"{BASE_URL}{API_PATH}")
    response.raise_for_status() # Raise an exception for HTTP errors

    print("Request successful!")
    print("Status Code:", response.status_code)
    print("Response Body:", response.json())

except requests.exceptions.HTTPError as e:
    print(f"HTTP error occurred: {e}")
    print(f"Response body: {e.response.text}")
except Exception as e:
    print(f"An error occurred: {e}")

This example assumes you have the akamai-edgegrid library installed (pip install akamai-edgegrid). The EdgeGridAuth object automatically signs the request with the provided credentials, adding the necessary Authorization header before sending it. The host in the edgerc dictionary typically includes a unique API client token prefix generated when you create your credentials.

Security best practices

Adhering to security best practices is essential when managing Akamai API credentials and implementing authentication:

• Least Privilege: Grant API clients only the minimum necessary permissions (scopes) to perform their intended functions. Regularly review and adjust these permissions as required. Akamai's API security documentation emphasizes this principle.
• Secure Credential Storage: Never hardcode API keys, secrets, or tokens directly into your application's source code. Use environment variables, dedicated secret management services (e.g., AWS Secrets Manager, HashiCorp Vault, Azure Key Vault), or secure configuration files that are not committed to version control.
• Credential Rotation: Implement a regular schedule for rotating API client tokens and secrets. Akamai allows you to set expiration dates for credentials, which helps enforce this practice. Timely rotation mitigates the risk associated with compromised credentials.
• Auditing and Logging: Enable and monitor audit logs for API access and credential management activities within the Akamai Control Center. This allows you to detect and respond to suspicious access patterns or unauthorized attempts. Comprehensive logging is a fundamental component of identity management best practices.
• IP Whitelisting: If possible, restrict API access to specific IP address ranges from which your applications are expected to originate. While not always feasible for dynamic environments, it adds an extra layer of security.
• Error Handling: Implement robust error handling in your applications to gracefully manage authentication failures without exposing sensitive information. Avoid returning verbose error messages that could aid attackers.
• SDK Usage: Utilize Akamai's official SDKs (Python, Go, Java, Node.js) when interacting with the APIs. These SDKs are designed to handle the complexities of EdgeGrid signing securely and efficiently.
• Separate Environments: Use distinct sets of API credentials for development, staging, and production environments. This prevents a compromise in a non-production environment from affecting your live systems.