Authenticate APIs

In order for a request to execute correctly, an API must be authenticated on the API Gateway. Four authentication methods are available:

  • API Key
  • HTTP Basic
  • OAuth 1.0
  • OAuth 2.0

NOTE: Before you can use OAuth authentication, The API Gateway Administrator must install and configure the OAuth Toolkit (OTK) on the API Gateway and then integrate the OTK with the API Portal.

Picture 1. - Authenticate

API Key

To authenticate an API using an API key:

  1. From the API Explorer page, select the API to authenticate. See "The API Explorer" for details.
  2. Click Authentication.
  3. Choose API Key from the Service Authentication menu.
    NOTE:If you selected an application from the API Key menu, steps 4 and 5 below are not necessary, because the API Key Name and Value will be pre-populated in these fields.
  4. Enter the Name of the API Key to add. This field is required.
  5. Enter the Value of the API Key to add. This field is required. The API key must be generated on the API Portal.
  6. Select whether the API Key Type is part of the Query parameter, or part of the request Header.
  7. Click OK to validate your input and add it to the request.

HTTP Basic

To authenticate an API using HTTP Basic:

  1. From the API Explorer page, select the API to authenticate. Click Authentication .
  2. Choose HTTP Basic from the Service Authentication menu.
  3. Enter the Username and Password to authenticate.
  4. Click OK to validate your input and add it to the request.

OAuth 1.0

To authenticate an API using OAuth 1.0:

  1. From the API Explorer page, select the API to authenticate. Click Authentication.
  2. Choose OAuth 1.0 from the Service Authentication menu.
  3. Complete the fields described in the following table. (Table 1.- OAuth 1.0)
  4. Click OK to validate your input and add it to the request.

NOTE: If OAuth 1.0 authentication is used, and an API is mapped with a WADL that includes a POST method with “representation” elements, that POST method element should not contain query parameters or query strings. Similarly, you must not add any query parameters in the Add Parameter dialog box, otherwise the resulting OAuth 1.0 token validation will fail.

Setting

Description

Client Key

Enter the client key assigned by the service provider. If using the OAuth Toolkit, enter the API key, which is generated on the Portal via "Adding New Applications".

Client Secret

Enter the client secret assigned by the service provider. If using the OAuth Toolkit, enter the API secret, which is generated on the Portal via "Adding New Applications".

Request URL

Enter the URL/endpoint to request an unauthorized request token. This URL is required. This URL should be a fully qualified hostname matching the OAuth server (API Gateway) SSL certificate.

Authorization URL

Enter the URL/endpoint to authorize a request token. This URL is optional. When omitted, it will be a one-legged OAuth scheme (that is, the token returned by the Request URL is already authorized).

Access URL

Enter the URL/endpoint to exchange an authorization token for an access token. This URL is required.

Table 1.- OAuth 1.0

OAuth 2.0

It is also possible to use the OAuth 2.0 authentication method. The OAuth 2.0 method defines four base grant types: Authorization Code, Implicit, Resource Owner, Password Credentials, and Client Credentials. With OAuth 2.0, the Grant Type you choose affects the process flow. For the Authorization Code and Implicit grant types, the flow is as follows:

  1. The browser redirects the user to the specified authorize endpoint.
  2. The user authenticates and grants access to the application via the service provider.
  3. After access has been granted or denied, the service provider will redirect the user back to the specified page as defined by the redirect_uri.
  4. The access tokens are retrieved from the URI fragment as attached by the service provider.

The Resource Owner Password Credentials and Client Credentials grant types do not involve any redirection. The Resource Owner Password Credentials grant type allows for an access token to be retrieved directly via username and password. With the Client Credentials grant type, access tokens are requested by providing the Client ID and Client Secret to the Token Endpoint.

NOTE: It is required that all proper OAuth 2.0 registrations are completed at the Service Provider. The redirect_uri MUST be set at the Service Provider to http(s)://cms_ portal/resources/oauthCallback.html. OAuth 2.0 will validate this redirect_uri value. If it does not match, the authorization process will fail.

To authenticate an API using OAuth 2.0:

  1. From the API Explorer page, select the API to authenticate. Click Authentication.
  2. Choose OAuth 2.0 from Service Authentication menu.
  3. Complete the fields described in the following table.(Table 2.- OAuth 2.0)
  4. Click OK to validate your input and add it to the request.

Setting

Description

Grant Type

Choose from one of the following:

  • Authorization Code: This grant type is designed to authorize a client via an intermediary server, where instead of requesting authorization directly from the resource owner, the client directs the resource owner to an authorization server.
  • Implicit: This grant type is designed for clients implemented in the web browser. Note: There are additional security risks associated with this grant type.
  • Resource Owner Password Credentials: This option grants access using the username and password of the resource owner. This grant type does not involve any redirection as it allows for an access token to be retrieved directly by providing a username and password.
  • Client Credentials: This grant type does not involve any redirection. Access tokens are requested by providing the Client ID and Client Secret to the Token Endpoint

Client ID

Enter the ID assigned to the user from the service provider. This may be the same as the API key generated on the Portal via "Adding New Applications".

Client Secret

Enter the client secret assigned by the service provider. This field does not appear when the Implicit Grant Type is selected.

Scope

Enter the "scope" or permission of the access. For example, “scope = read” can mean that access is read only. Refer to the service provider for a list of available scopes and requirements. Depending on the service provider, this may be a required field.

Authorize Endpoint

Enter the URL/endpoint to authorize a request token. This field does not appear if the Resource Owner Password Credentials or the Client Credentials Grant Type is selected.

Token Endpoint

Enter the endpoint from which the client will obtain an access token. This field does not appear when the Implicit Grant Type is selected.

Username

Enter the username to be used to obtain the token. This method should only be used in a high trust environment. The Username field only appears if Resource Owner Password Credentials is selected.

Password

Enter a password to be used to obtain the token. This method should only be used in a high trust environment. The Password field only appears if Resource Owner Password Credentials is selected.

Table 2.- OAuth 2.0