Authenticate APIs

In order for a request to execute correctly, an API must be authenticated on the CA API Gateway. Four authentication methods are available:
apidp35-cr5
In order for a request to execute correctly, an API must be authenticated on the CA 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 CA API Gateway Administrator must install and configure the CA OAuth Toolkit (OTK) on the CA API Gateway and then integrate the OTK with the API Portal. For more information, see CA API Gateway OAuth Toolkit.
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. See "Add New Applications" for instructions on how to create a new application and generate an API key.
  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. 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. See "The API Explorer" for details.
  2. Click 
    Authentication
    .
  3. Choose 
    OAuth 1.0 
    from the 
    Service Authentication 
    menu.
  4. Complete the fields described in the following table.
  5. 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 CA 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 CA 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 (CA 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.
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. See "The API Explorer" for details.
  2. Click 
    Authentication
    .
  3. Choose 
    OAuth 2.0 
    from the 
    Service Authentication 
    menu.
  4. Complete the fields described in the following table.
  5. 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.