Authentication types

In the API Manager, you can use API keys to authenticate your APIs and applications. The API Manager generates the API keys and enable you to add API key-based authentication to your APIs.

Validation using API keys is a type of security you can enforce while creating an API. Applications use the API key and the API Manager checks to see if the API key is in an approved state for a resource.

The API Manager uses three API authentication types:

1. apiKey
2. basicAuth
3. OAuth2

OAuth2

In any traditional client-server application when the client requests for a protected resource or web page, the server authenticates the client. The client passes the credentials to the server and the authentication happens. Based on the authentication result, the client gets access to the protected resource. This approach works fine in a controlled environment where an organization/entity manages both the client and server applications.

Today’s organizations adopt an open and collaborative platform architecture in which the data is shared through an API mechanism. The API mechanism allows any developer (internal or customers) to quickly interact with the service without the intervention of the service owner. This framework enables users to build mashups, mobile and desktop client applications, and other third-party services.

The services often require access to sensitive data of an API which in turn requires authentication or access control. One common method of authentication is the user name and password authentication. However, providing password to a third-party application has many disadvantages. Entering a password in a third-party application requires a user’s trust. Also, from a usability perspective, it is not possible to revoke an application until the password has changed. In the same way, the application fails to work reliably if the password has changed.

OAuth2 combats the risks mentioned above, that are associated with the password anti-pattern. OAuth2 is a standard for delegating authorization to an application on behalf of the user without providing the password. Instead of the user password, an application receives an access token with limited lifetime access. Depending on the type of application, obtaining an access token varies. These access tokens are called grant types. To know more about OAuth 2.0, refer to IETF OAuth 2.0 specification.

OAuth2: Terms and actors

Resource owner

An entity capable of granting access to a protected API. A resource owner can be an end user.  The resource owner delegates authorization to the third-party client or application. Through this delegation, the application can access the API on behalf of resource owner.

Resource Server

The server hosting the APIs. The resource server accepts and responds to protected API requests using access tokens. The API Manager acts as resource server that validates access tokens and performs access-control on a protected API.

Client

An application that makes protected resource requests on behalf of the resource owner and the owner’s authorization.  The term "client" does not imply to any particular implementation characteristics (for example, if the application executes on a server, a desktop, or other devices). The API Manager application is an OAuth2 client.

Authorization Server

The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization. The API Manager acts as an authorization server as well.

Access Token

Access tokens are credentials to access protected APIs.  An access token is a string representing an authorization issued to the client.  The string is opaque to the client.  Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server. The API Manager currently supports Bearer Access tokens which are opaque tokens.

Refresh Token

Refresh tokens are credentials used to obtain access tokens. The authorization server issues the refresh tokens to the client. The client obtains refresh tokens when the current token becomes invalid or expires.

Authorization Code

An opaque code obtained through authorization code grant flow can be redeemed to get a limited life time access token and a refresh token. Once code is redeemed, it is no longer valid and cannot be used to get access tokens.

Scope

A scope is a permission associated with a protected resource. If the publisher protects any resource using OAuth2, specifying a scope along with it requires the access token to have this scope associated with it.

Client ID

Every application with OAuth2 authorization has a unique identifier.

Client Secret

The Client Secret gets the access token in Client credentials flow and authorization code flow.

The API Manager provides complete OAuth2 support including authentication provider, role-based authorization framework for scopes, and login web pages along with token management component. The API Manager acts as authorization server and resource server. The authentication provider supports integration with LDAP, database, and federated authentication using SAML. 

OAuth2 endpoints

The API Manager OAuth2 provider provides the following endpoints which are used to obtain and manage access tokens:

Authorization Endpoint

http(s)://servername:serverport/oauth2/auth: The endpoint where the end user logs in and provides the consent to provision the authorization grant to the application.

Token Endpoint

http(s)://servername:serverport/oauth2/token: The endpoint that the client uses to obtain an access token by presenting its authorization grant or refresh token.

Redirect Endpoint

After the user interacts with the authorization endpoint, a user is redirected back to the application. The redirect (or callback) URL is specified in the application created in the API Manager. Currently, the API Manager does not support multiple redirect URL’s registration in the application.

Token Info Endpoint

http(s)://servername:serverport/oauth2/tokeninfo: The tokeninfo endpoint provides information about the access token. The response of the endpoint includes information like create time, expiry, Application Id (client_id) of the logged in user, and scopes.

The token info endpoint receives the access token in two ways:

1.       Using query parameter access_token

2.       Using the authorization header

Example of a simple HTTP GET request with query parameter access _token:

http(s)://example.com/oauth2/tokeninfo?access_token=3ffb313f16856a4d6b1feecd2e50b950

(or) using the authorization header:

GET example.com/oauth2/token HTTP/1.1

Host: example.com

Authorization: Bearer 3ffb313f16856a4d6b1feecd2e50b950

Token Revocation Endpoint

http(s)://servername:serverport/oauth2/revoke: The endpoint that can be used to revoke any access token or refresh token. Once revoked, the access token or refresh token becomes invalid.

OAuth2 Self Service

http(s)://servername:serverport/oauth2/self/<Logon Identifier>: If the OAuth2 server authentication provider is a user store (LDAP or database), an end user can view the list of approved applications along with the approved scopes. The end user can also revoke any application access. Configure the login identifier in the user store to set up this portal.

Application Registration

To obtain access tokens or authorization codes, register the application with the API Manager. The API Manager authorization server identifies the application. Registering an application with the API manager provides the following pair of keys:

• client Id: Client Id is a public identifier
• client secret: Client secret is a secret identifier

Register the callback URL (or redirect URL) of the application with the API Manager so that the deployed application can access the token. To use any of OAuth2 grant types, the API Manager subscribes to at least one API that is protected using OAuth2.

Grant types

A grant is a method of acquiring an access token that accesses an OAuth2- protected API. OAuth2 provides different grant types for different scenarios based on the type of application (server, browser, or mobile).

Client credentials grant type

Among the four grant types of OAuth 2.0, client credentials is the simplest grant type. This grant type can be used in cases where an application that is confidential (means ability to store client credentials safely) consumes the API.

Prerequisites

Register an application with the API Manager. The application subscribes to at least one API that is protected using OAuth2.

Access Token Request

In this flow/grant type, the following request is made to the token endpoint with the following details. The HTTPs request is made using HTTP POST with the content-type “application/x-www-form-urlencoded”.

http(s)://servername:serverport/oauth2/token

The sample below is an HTTP request to request an access token with scopes:

POST example.com/oauth2/token HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=625bc9f6-3bf6-4b6d-94ba-e97cf07a22de&client_secret=625bc123-3bf6-4b6d-94ba-e97cf07a22de&scope=sample_read%20sample_write

Both client Id and client secret can also be sent using the authorization header. The sample HTTP request requests an access token by passing the client credentials in authorization header along with scopes.

Authorization: Basic Base64 (clientId:clientSecret)

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=sample_read%20sample_write

Access Token Response

If the request for the access token is successful, the response is sent in JSON Format. The JSON includes the following keys.

The following example shows a JSON response:

{

  "access_token": "7ee85874dde4c7235b6c3afc82e3fb",

  "token_type": "bearer",

  "expires_in": 1200,

  "scope": " sample_read sample_write"

}

To retrieve this information any time, the client application can pass the requested access token to the token info endpoint. As this flow involves direct client authentication, the endpoint response does not include any user info.

Access Token Revocation

Every access token has an expiry time. The access token becomes invalid and revoked automatically when the token reaches its expiry time. When the token expires, applications request for a new token and is granted one. Client credentials flow/grant type does not grant any refresh token. If the access token has to be revoked before its expiry time, pass the access token to the revocation endpoint. When revoking the access token using client credentials, the flow requires passing the client credentials in the token revocation request for a second time.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample HTTP request shows how to revoke the Access token issued using client credentials flow.

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token&client_id=625bc9f6-3bf6-4b6d-94ba-e97cf07a22de&client_secret=625bc123-3bf6-4b6d-94ba-e97cf07a22de

Client Secret Regeneration

You can generate the Client Secret by logging into the portal to prevent any unauthorized access to the Client Secret.

Once the Client Secret is regenerated, the older Client Secret becomes invalid. Use the new Client Secret to request for new access tokens.

Security Considerations

The security of OAuth2 depends on the secure transmission of OAuth2 access tokens and client credentials. Therefore, access all the OAuth2 endpoints on HTTPS (SSL/TLS) transport for production environments.

You can choose Mandate HTTPS in the Security Configuration page in the API Manager administrator to prevent all OAuth2 endpoints from accepting any request over HTTP.  Keep the client secret confidential and store it in a secure database.

Keep the application private, otherwise the credentials can be captured by decompiling/analyzing the source code of the application. Use this flow on server-side application where secure storage can be guaranteed.

How is Client Credential grant different from API Keys security?

In case of client credentials, you use the access token is used to call the API. On the other hand, in API Key security, you can use the API key to validate the API. You get an extra layer of security control where you can revoke the access token easily without modifying the client application. 

Implicit/token grant type (two-legged OAuth2)

Implicit/token grant is one of the browser-based redirection flows that is suitable for pure JavaScript (client-side)-centric or mobile applications that cannot store user credentials and does not have any server side component.

A simple example is a pure JavaScript application made using Angular/Ember and calls the API directly from JavaScript via Ajax calls. This grant type/flow requires interaction with the end user.

Prerequisites

Register an application with the API Manager. The application subscribes to at least one API that is protected using OAuth2. Specify the callback URL (or redirection URL)  in the API Manager. After authorization request is completed, you are redirected to this registered URL. The registered application includes the client ID that is required for this flow/grant type.

Requesting an Access Token

The flow begins by the application by redirecting the user to API Manager OAuth2 server authorization endpoint (/oauth2/auth) when the application tries to access an OAuth2 protected API.  The URL for sending the authorization request is shown as below:

http://<APIM_SERVERNAME>:port/oauth2/auth?client_id=<Application Client ID>&response_type=token&scope=<list of scopes delimited by string>&state=<random string>

For example,

http://example.com/oauth2/auth?client_id=9a42a56d5b5546079f2f82a62612dab9&response_type=token&

state=nkj34898sdcsd123&scope=foo_read%20foo_write

Once the API Manager OAuth2 server receives the request, it validates all the parameters. If valid, and the authentication method for application is user-store, you see a login page.  If the authentication method for the application is SAML SSO, you are redirected to the SAML Identity provider for authentication. After the authentication is successful, you are presented with another page where you can provide the authorization/consent.

Here, you can select the list of scopes that are permitted for the application, which in turn is provided to the access token.

Once it is redirected to the callback URL, the application has a script to extract the access token out of the URL fragment. The server does not receive the access token because the URL fragment is not sent over HTTP/S by browsers. The callback URL’s fragment contains the following parameters:

Once the access token is obtained from the grant type, it calls the protected API and gets the response from the API.

To retrieve this information any time, the client application can pass the requested access token to the token info endpoint. The API Manager OAuth2 authorization server does not issue any refresh tokens. Once the issued access token expires, the application goes through the OAuth2 two-legged process again.

The API Manager admin portal controls the timeout for the login credentials. If the authentication times out, provide valid credentials (user name and password) again to log in in case of user store authentication method. In case of SAML SSO IDP, authorization happens again. If the application is already approved, you are directly redirected to the callback URL with the fragment having the access token and other details.

Security Considerations

The security of OAuth2 depends on the secure transmission of user credentials, OAuth2 Access Tokens, and Client Credentials. Therefore accessing all the OAuth2 endpoints on HTTPS (SSL/TLS) transport is recommended for production environments. The API Manager administrator can mandate HTTPS transport only in the Security Configuration page. 

Also, register the HTTPs URL callback with the API Manager because the callback URL receives the access token. The application verifies the state parameter value received in the fragment with the value stored in the initial request. Also, verify that the client id from the URL fragment is same as the client id in the JavaScript application code.

Access Token Revocation

Every access token has an expiry time. Once it reaches the expiry time, the access token becomes invalid and is revoked automatically. Once the access token expires, the application makes a request for the access token again. If the access token has to be revoked before its expiry time, pass the access token to the revocation endpoint.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample HTTP request shows how to revoke the access token:

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token

Authorization code grant type (three-legged OAuth 2)

This grant type is suitable for server applications.  In this flow, the access token is hidden from the end user, and instead issues an authorization code.

Redeem the intermediary authorization code at the token endpoint with client credentials to receive access token and refresh token. This flow also requires application to have a server component where it redeems the authorization code for accessing the token and refreshing the token. Once the code is redeemed, it is no longer valid.

Prerequisites

Register an application with the API Manager and subscribe to at least one API that is protected using OAuth2. Also, specify a callback URL (or redirection URL) with the API Manager application so that after authorization request is completed user is redirected to this registered URL. The registered application includes Client ID and Client Secret, which are required for this flow/grant type.

Requesting an access token

The flow begins by the application server component redirecting the end user to API Manager OAuth2 server authorization endpoint (/oauth2/auth). The URL for sending the authorization request is shown below:

http://<APIM_SERVERNAME>:port/oauth2/auth?client_id=<Application Client ID>&response_type=code&scope=<list of scopes delimited by string>&state=<random string>

An example URL is:

http://example.com/oauth2/auth?client_id=9a42a56d5b5546079f2f82a62612dab9&response_type=code&

state=nkj34898sdcsd123&scope=foo_read%20foo_write

Once the API Manager OAuth2 server receives this request, it validates all the parameters. If the parameters are valid, the user sees a login page where the user is asked to provide the login credentials ( user name and password).  If the authentication method for the application is SAML SSO, the user is redirected to the SAML Identity provider for authentication.

After the authentication is successful, you are presented with another page where you can provide the authorization/consent. Here you can select the list of scopes that are permitted for the application, which in turn is provided to the access token. Once scopes are selected and approved, you are redirected (to the registered URL) back to the application. You attach a query parameter called code with its value along with the state parameter.

Now the application server component verifies the state parameter value received from the request with the value stored in the session. If state parameter is verified, then extract the code parameter value from the request and use client credentials to redeem this code for an access token.

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=9a42a56d5b5546079f2f82a62612dab9&

client_secret=7ee85874dde4c7235b6c3afc82e3fb

If the given client credentials & the authorization code are valid the response will contain an access token along with a refresh token. Refresh token is used to get a new access token when the current access token is expired/revoked. The JSON response includes the following keys.

A sample JSON response is shown below.

{

"access_token": "95d9c3de53a9c48e629ecb6a288f6c",

"token_type": "bearer",

"expires_in": 1200,

"scope": "foo_read",

"refresh_token": "31cf059933238e866779a43237cd7ec"

}

To retrieve this information any time, the client application can pass the requested access token to the token info endpoint. Once the issued access token expires, the application can use the refresh token to get a new access token.

Refreshing access token

The example below shows how to refresh an access token using refresh token. Pass the client credentials along with the request, either through form parameters or using basic authentication.

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=31cf059933238e866779a43237cd7ec&client_id=3ffb313f16856a4d6b1feecd2e50b950&scope=foo_read

If the refresh token is expired/revoked, the application starts the three-legged dance once again. In case of user store authentication, if the authentication times out, provide valid credentials ( user name and password) again to log in. In case of SAML SSO IDP, authorization happens again. If the application is already approved, you are redirected to the callback URL immediately with the intermediary authorization code and state.

Access/refresh token revocation

Each issued access token has an associated expiry time. Once the expiry time is reached, the access token becomes invalid & revoked automatically. Once the access token expires, the application gets a new access token. If the access token has to be revoked before its expiry time, pass the access token to the revocation endpoint.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample HTTP request revokes the access token:

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form- urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token

The revoke endpoint also supports revoking the refresh token pass the refresh token in token parameter and set token_type_hint parameter value as refresh_token.

Security considerations

The security of OAuth2 depends on the secure transmission of user credentials, OAuth2 access tokens, and client credentials. Therefore, accessing all the OAuth2 endpoints on HTTPS (SSL/TLS) transport is recommended for production environments. The API Manager administrator can mandate HTTPS transport only in the Security Configuration page.  Also, HTTPS URL callback is registered with the API Manager application because the callback URL receives the authorization code. The server application verifies the state parameter value received in the request with the value stored in the session. The server application securely stores the access tokens, refresh tokens, and client credentials in a secure database.

Resource owner/password grant type

This grant type allows the application to have their own login page. The password grant type is used in the cases where you have complete trust on the application. This grant type is suitable for a trusted mobile application or a desktop application. This grant type requires user interaction for requesting the access token.

Prerequisites

Register an application API Manager. It is mandatory that the application subscribes least one API that is protected using OAuth2. The registered application includes Client ID which is required for this flow/grant type. For this grant type to function, it is important that all subscribed APIs of type User store are configured with the same user store.

Requesting an Access Token

The user initiates the flow when accessing the installed application is presented with a login form provided by the application. User enters the login credentials (user name, password) then the application sends an authorization request to the API manager OAuth2 server.

In this flow/grant type, the following request is made to the token endpoint with the following details. The HTTPs request is made using HTTP POST having the content-type “application/x-www-form-urlencoded”.

http(s)://servername:serverport/oauth2/token

POST /oauth2/token HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

grant_type=password&username=maxwell&password=sdcoio2380&client_id= 95d9c3de53a9c48e629ecb6a288f6c&scope=foo_read%20foo_write

The API Manager Server validates the incoming request and checks whether the client id is valid and is allowed to use the password grant type.  Then it checks for the application authentication method is user store or not and authenticates the given user name and password against the user store. If the authentication is successful, the Oauth2 server validates the scopes requested.

If the requested scopes are not empty, each scope is looked at whether granting this scope requires any group/role membership. If user is part of the roles specified in the scope, that scope is approved. An access token with approved scopes along with a refresh token is returned as part of the response. The JSON response includes the following keys.

A sample JSON response is shown below:

{                                                             

"access_token": "95d9c3de53a9c48e629ecb6a288f6c",

"token_type": "bearer",

"expires_in": 2800,

"scope":"foo_read foo_write",                                                 

"refresh_token": "31cf059933238e866779a43237cd7ec"

}

To retrieve this information any time, the client application can pass the requested access token to the token info endpoint. Once the issued access token expires, the application can use the refresh token to get a new access token.

Refreshing Access Token

The example below shows how to refresh an access token using refresh token.

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=31cf059933238e866779a43237cd7ec&scope=foo_read

If the refresh token is expired/revoked, the application asks you for the credentials. Restart the complete flow again.

Access/refresh token revocation

Each issued access token has an associated expiry time. Once the expiry time is reached, the access token becomes invalid and revoked automatically. Once access token expires, the application gets a new access token. If the access token has to be revoked before its expiry time, pass the access token to the revocation endpoint.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample HTTP request shows how to revoke the Access token

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token

The revoke endpoint also supports revoking the refresh token pass the refresh token in token parameter and set token_type_hint parameter value as refresh_token.

Security Considerations

The security of OAuth2 depends on the secure transmission of user credentials, OAuth2 Access Tokens, and Client Credentials. Therefore accessing all the OAuth2 endpoints on HTTPS (SSL/TLS) transport is recommended for production environments. The client application does not store user credentials anywhere and securely stores them. If it is a desktop application, use a secure database. If it is an Android mobile application, store the access tokens and refresh tokens using SharedPreferences API. If it is iOS, store the tokens in KeyChain.

Calling an OAuth2-protected API

Once an access token is obtained from any of the grant types, it can be used to call the OAuth2-protected API. The authorization header format is:

Authorization: Bearer <OAuth2 Access Token>

Pass the access token in the Authorization Header as shown below.

GET example.com/sampleapi/v1.0/examples HTTP/1.1

Host: example.com

Authorization: Bearer 7ee85874dde4c7235b6c3afc82e3fb

Currently, the API Manager only issues bearer tokens. The API Manager validates the access token. If the token is valid, then the API Manager checks if the access token has the scope to call the protected API.

If both the conditions are true, then the API Manager calls the backend and gets the response and provides it to the client.

API Key authentication

An API Key is an opaque token, which is a simple form of authentication to consume an API.  To acquire an API Key, create an application as a subscriber.

Consuming an API protected using API Key

In a request, you can pass an API Key to the API Manager in a request in one of the following ways:

• Header: The api_key header can be used to pass the API Key to the API runtime.
• Query Parameter: The api_key query parameter can be used to pass the API Key.
• Form Parameter: The api_key form parameter can be used to pass the API Key.

When consuming an API protected using API Key, API runtime checks for the API Key in the header. If the key is not found, then API runtime checks in the query parameters. If the key is not found, then the API runtime checks the form (or post) parameter.

If the extracted API Key is valid, the API Manager checks whether this API Key is approved or not. If the key is approved, the API manager gets the SLA plan for this subscription and then uses it for the rate limiting and throttling.

API Key regeneration

When an API Key is regenerated, the old Key of the application is no longer valid. The application starts using the new key to consume the API Key.

Basic authentication

Basic authentication is the simplest form of authenticating a user by passing the user name and password in the request when consuming an API. The API Manager allows protecting an API using the Basic authentication scheme.

A publisher can configure the user store to be used for the authentication. If the API resource is protected with a scope configured with roles, then the API Manager also authorizes the role. The authorization happens during the consumption of the API call.

Create an application in the API Manager and subscribe to an API protected using basic authentication.

With HTTP basic authentication, the user’s user name and password are concatenated, base64-encoded, and passed in the Authorization HTTP header as follows:

Authorization: BASIC Base64 (username:password)

example: Authorization: Basic dm9yZGVsOnZvcmRlbA==

But simply passing the user name or password does not identify the application consuming the API. Send the application unique identifier (client ID) along with the request.

An example of consuming an API protected using BASIC authentication is as follows:

GET example.com/sampleapi/v1.0/examples HTTP/1.1

Host: example.com

Authorization: Basic dm9yZGVsOnZvcmRlbA==

clientid: 3ffb313f16856a4d6b1feecd2e50b950

Once the API Manager receives a request for an API that is protected using basic authentication, it looks for the application id. If the application id (client id) in the request is valid and approved, then the API Manager authenticates the credentials in the request.

If authentication is successful, then the API Manager checks if the current API requested is protected with appropriate scope and authorized role. If yes, the API Manager retrieves the user roles and checks if the current user has all the required roles to consume this API. Once role authorization is successful, the API Manager gets the SLA plan for this subscription for rate limiting and throttling. If rate limit is also allowed, the request is forwarded to get the response from the application.