Authorization

Identity and Access in Akamai Cloud is used to manage identities within an account and manage operations that those identities may perform. By authenticating identities and authorizing them to access specific services and entities, Identity and Access ensures that the right identities access the right entities. Identity and Access uses the role-based access control (RBAC) model to authorize operations on entities. To learn more, see Identity and Access in Akamai Cloud.

To find out what permission or role is needed to run a specific Linode API operation, check the Permissions and scopes section for the operation.

• If the operation requires a specific permission, you need to check the Available roles list or run the List available roles operation and look for the role that contains the specific permission and fits the required access the most. Then, assign this role to your user or ask your account administrator to assign this role to you.
• If the operation requires a specific role to run it but no permission, it means that Identity and Access is not natively-enabled for this service yet. To learn more about this case, see Identity and Access for non-natively enabled services.
• For operations that have neither permission nor role specified, continue using grant-based access control.

Authentication

Some of this API's operations are publicly accessible and don't require authentication. However, all operations that affect your account require either a personal access token or OAuth authentication, when using third-party applications.

Personal access tokens

The easiest way to access the API is with a personal access token generated from ​Akamai​'s Cloud Manager portal. This token should only allow the level of access needed by the application.

Create a personal access token

Revoke a personal access token

If you want to decommission a token or think it may have been compromised, you can revoke it. Once revoked, any application using the token will no longer be authorized to access your account through the Linode API.

Personal access token authentication

📘

The scopes listed in the OAuth model also apply to this security model.

OAuth

If you're designing an application that can authenticate with an arbitrary user, use the OAuth 2.0 workflows we offer here.

👍

If you only need to access the Linode API for personal use, create a personal access token.

Before you begin

To implement OAuth in your application, first you need to create an OAuth client. You can do this with the Linode API. Consider these points when creating this client:

• The response from the Create an OAuth client operation gives you a client_id and the client secret. Store these values for use in the future.

• Clients can be public or private, and are private by default. You can choose to make the client public during creation.

  • The private client. Use this with applications that can securely store the client secret. For example, an application running on a secured server that only the developer has access to would use a private OAuth client. This is also called a confidential client in some OAuth documentation.

  • The public client. Use this in applications that can't guarantee security of the client secret. For example, this could be a native app running on a user's computer that can't keep the client secret safe, as a user could potentially inspect the source of the application. So, native apps or apps that run in a user's browser should use a public OAuth client.

• The redirect_uri is displayed as the Callback URL in Cloud Manager.

For a detailed example of an OAuth 2.0 implementation, see How to Create an OAuth App with the Linode Python API Library.

OAuth authentication

The OAuth authentication workflow is a series of exchanges between your third-party app and ​Akamai​ cloud services. The user is authenticated before an application can start making API calls on the user's behalf.

📘

The OAuth 2.0 Authorization Framework (RFC 6749)

Our OAuth authorization follows the methodology explained in RFC 6749, with these considerations:

• Looking at the diagram in section 1.2 of RFC 6749, login.linode.com serves as the Resource Owner and the Authorization Server. We refer to this as the login server throughout this section. The Resource Server is api.linode.com, which we refer to as the API server here.

• The OAuth spec refers to the private and public workflows we call out here as the authorization code flow and implicit flow, respectively.

The private workflow

1. The user visits the application's website and is directed to login with ​Akamai​ cloud computing services.

2. Your application then redirects the user to our login server with the client application's client_id and requested OAuth scope, which needs to appear in the URL of the login page. See the "OAuth scopes" listing in OAuth reference for details.

3. The user logs into the login server with their username and password.

4. The login server redirects the user to the specified redirect URL with a temporary authorization code (exchange code) in the URL.

5. The application issues a POST request to the login server with the exchange code, client_id, and the client application's client_secret:

   • Make an HTTP POST request as application/x-www-form-urlencoded or as multipart/form-data to:

     https://login.linode.com/oauth/token

   • Include the following parameters in the POST body:

     PARAMETER	DESCRIPTION
     client_id	Your app's client ID.
     client_secret	Your app's client secret.
     code	The exchange code you just received from the redirect.

6. The login server responds to the client application with new OAuth tokens. The access_token is set to expire in two hours. Store these values from the response:

   • "access_token": "abc123def456hij789klm"
   • "refresh_token": "012nop345qrs678tuv901"

7. Make authenticated HTTP requests to the API for the next two hours by including the access_token in this header with each request:

   Authorization: Bearer abc123def456hij789klm

8. After the access_token has expired, the application issues a POST request to the login server to request a new one using the the refresh_token:

   • Make an HTTP POST request as application/x-www-form-urlencoded or as multipart/form-data to:

     https://login.linode.com/oauth/token

   • Include the following parameters in the POST body:

     PARAMETER	DESCRIPTION
     grant_type	Set this to the refresh_token when refreshing access.
     client_id	Your app's client ID.
     client_secret	Your app's client secret.
     refresh_token	The refresh_token received from the previous response.

A response body is returned with a new access_token with a two-hour TTL, as well as a new refresh_token that can be used to repeat the process.

The public workflow

1. The user visits the application's website and is directed to login with ​Akamai​ cloud services.

2. Your application then redirects the user to our login server with the client application's client_id and requested OAuth scope, which needs to appear in the URL of the login page. See the "scopes" listing in OAuth reference for details.

3. The user logs into the login server with their username and password.

4. The login server redirects the user back to your application with an OAuth access_token embedded in the redirect URL's hash. This is temporary and expires in two hours. No refresh_token is issued. So, once the access_token expires, you need to issue a new one. To do this, the user needs to log in again.

OAuth reference

• Authorization URL. https://login.linode.com/oauth/authorize
• Token URL. https://login.linode.com/oauth/token
• OAuth scopes. A scope specifies the level of access the client is requesting. It refers to the information or functionality that the application can access, and whether read-only or write access is allowed. These are the scopes supported with the Linode API:

Authenticate Monitor API operations

The Akamai Cloud Pulse monitoring application offers the Get an entity's metrics operation that you can use to see metric information for a specific ​Akamai​ Cloud Manager service. To use this operation, you need to generate a JWE-format token for inclusion in the call.

For use with Object Storage

1. Run the List supported services operation and store the service_type for Object Storage.

2. Determine how the token will be applied to your Object Storage buckets:

   • Apply to specific buckets on your account. Run the List Object Storage buckets operation and store the hostname values for the target buckets.

   • Apply to all buckets on your account. Skip to the next step.

3. Run the Create a token for a service type operation, using the stored service_type in the call's URL. Build the body parameters, based on how the token is to be applied to your buckets:

   • Apply to specific buckets on your account. Include your stored hostname values as the entity_ids array:

     {
       "entity_ids": [
         "primary-bucket-1.us-east-12.linodeobjects.com",
         "secondary-bucket-1.us-east.linodeobjects.com"
       ]
     }

   • Apply to all buckets on your account. Set the request as an empty object:

     {}

4. Store the token from the response.

5. Run the Get an entity's metric operation, passing the stored token as a Bearer authorization header. Below is an example using cURL:

   curl --request POST \
        --url https://monitor-api.linode.com/v1/monitor/services/dbaas/metrics \
        --header 'accept: application/json' \
        --header "authorization: Bearer abc123" \
        --header 'content-type: application/json' \
        --data '
   {
     "aggregate_function": "min"
   }

For use with all other services

1. Run the List supported services operation and store the service_type for the applicable service.

2. Run the appropriate List operation for your service and store the id for the target object. For example, if you're looking for metrics data for a Managed Database, run the List Managed Databases operation and store the id for the target database.

3. Run the Create a token for a service type operation, using the stored service_type in the call's URL and the object's id as the entity_id in the request body. Store the token from the response.

4. Run the Get an entity's metric operation, passing the stored token as a Bearer authorization header. Below is an example using cURL:

   curl --request POST \
        --url https://monitor-api.linode.com/v1/monitor/services/dbaas/metrics \
        --header 'accept: application/json' \
        --header "authorization: Bearer abc123" \
        --header 'content-type: application/json' \
        --data '
   {
     "aggregate_function": "min"
   }