Created

15 March 2016

Requirements    
Prerequisite knowledge
Required products
Sample files
This article does not require you to be an expert in API Manager. A  general understanding of how applications are made using API’s and
little knowledge about CF 2016 API Manager.
Adobe ColdFusion Enterprise Edition (2016 release) (Download trial)
DB userstore
(302 KB)

 
Introduction

Whenever there is a request to the ColdFusion (2016 release) API Manager gateway/runtime, the runtime resolves whether an API exists in the API Manager server. Once the runtime resolves the API, the runtime authenticates the request and decides whether or not to allow the request.
 
Once the security requirements are met, the credentials used in the request are used to identify the application consuming this API. The API Manager runtime also performs the rate limiting and throttling based on the subscribed SLA Plan.
 
The API Manager supports several popular authentication and authorization methods to protect an API. This article provides an overview about these methods and lets you pick up the right method for your API.
 
API Manager allows choosing an authentication method at API sub-resource granular level and also allows to configure multiple auth types for an API. Also, an API Publisher can make a particular API resource public by setting the authentication method as none. CF API Manager currently supports the following authentication types to protect an API published.
 
API Key and BASIC Authentication
 
In this part, we shall cover the first two authentication methods-API Key-based and Basic Authentication schemes.
 

 
API Key

API Key-based authentication type is the simplest form of protecting an API. The API Key is an opaque secret shared between the application and the API Manager. When you register an application in the API Manager, an API Key is generated. All APIs under this application protected using API Key authentication can be consumed by passing the API Key got from the registered application.
 
As an application developer, you can embed this API Key inside the client application. As you embed the API key inside the application, do not consume the API from a mobile/JavaScript application because it exposes your API Key. When the API Manager receives the request for an API Key-protected resource,  the API key is extracted from the request to identify the application and its subscription to this API. If the subscription to this API is valid and approved, the request goes through rate limiter. If the rate limiting/throttling is successful, the request is forwarded to the target API to fetch the response.
 
Consuming the API
You can pass the API Key to the API Manager in a request in either of the following ways:
 
  • Header
  • Query Parameter
  • Form Parameter
When consuming an API protected using API Key, the API runtime checks for the API Key in the header. If the key is not found, then the runtime checks in the query params. If the key is not found again, the runtime checks in the form (or post) parameter.
 
The publisher/subscriber can use the Try-out feature of the API Manager to test the API right away and see the API Key as part of the request. It is recommended to use HTTPS when passing these credentials in the API request.
 
The example below provides a step by step procedure that shows how to protect a publicly available pet store API using API Key authentication method.
 
  1. Log in to the API Manager publisher portal. (http://hostname:port/portal).
  2. Navigate to Create API -> Import REST API From Swagger.
  3. Provide the Swagger URL http://petstore.swagger.io/v2/swagger.json and click Import. You can see the complete API definition along with the resource definitions.
  4. Provide the API Name and Context as petstore. Navigate to Security -> Authentication and choose apiKey as the authentication type. Click Apply to All Resources. Doing so sets API Key as the authentication method to all the API resources. You can however override this authentication type at sub-resource level as well.
  5. Select the SLA plans GOLD and SILVER. Click Apply to all resources to set the SLA plans available to all the resources. At the sub-resource level, you can also de-select the SLA plan which makes it as unavailable in that particular SLA plan.
  6. Click Publish to publish the API and makes it ready for use.
Once the API is published, subscribers/consumers can search for this API, read the API, and try it out using Try-out feature. The subscriber can also subscribe to the API and consume it from the developer application.
 
  1. Log in to the API Manager portal as Subscriber. If you have both publisher and subscriber roles, switch to subscriber role in the portal.
  2. Navigate to My Applications and register the developer application by providing a name and description. An API Key gets generated for this application.
  3. Browse for this API in the API Catalog and select the API. Click Subscribe.  Choose the new application, the SLA plan, click Subscribe.
API Manager Portal
Now the developer can embed the API Key in the application and send the following request to get a Pet by its ID. Here is a sample request and response:
 
GET /Petstore/1.0.0/pet/10 HTTP/1.1
 
Host: apimanager.com
 
api_key: 7838634dd2b04b4c9754fff6bb330230
 
As the key is valid, the request goes through rate limiter for rate limiting and throttling check. When the request is forwarded to the backend API, the API Key provided in the request is stripped off. Here is the response:
 
{ "id": 10, "category": {"id": 0, "name": "string"}, "name": "doggie", "photoUrls": [ "string"], "tags": [{"id": 0, "name": "dog0225"}], "status": "available" }
 
API Key Regeneration
When API Key is regenerated, the old API Key of the application is no longer valid and the developer can embed the new API Key in the application to consume the API.
 
Prologue to Basic & OAuth 2.0
 
Basic Authentication and OAuth 2.0 involves authenticating and authorizing the request where the end user of the developer application needs to present the username and password. The OAuth 2.0 browser-based redirection flows also support authenticating the end users through federation using SAML 2.0.
 
A user store is a place where you define connection details to the data store where all the user accounts, groups/roles, and membership information is stored. Currently API Manager supports LDAP and database as the user data stores. The API Manager connects to these data stores to authenticate the users, search, read the user accounts, and groups and user-group membership. A group or role defines a set of permissions or provides a logical separation between users.
 
A sample example of how to create a simple Generic LDAPv3 user store & DB user store is specified in the examples zip provided with this article. Follow the instructions and configure the user store which you can use it in the next sections. Even though OAuth 2.0 is not an authentication protocol, the API Manager provides an authentication layer over the authorization framework of OAuth 2.0.
 
A scope is a mechanism that allows developer applications to tell the API Manager server what permissions are needed on the protected APIs. You can associate scopes with group or role memberships. The developer application must register the list of scopes required for the application. When making a request to the API which is protected using Scope checks whether the application has registered this scope. If yes, the API Manager checks are there any roles associated with the scope. If roles are associated, user/group membership is checked whether the user is having that roles/groups then the access will be granted. If rate limiting and throttling is successful then the response will be given to the developer application from the target API. When roles are specified on the scopes user should be part of all the roles/groups mentioned. OAuth2 spec talks about the scope but we have extended this concept of scope to basic authentication as well.
 

 
Basic Authentication

Basic authentication is the simplest form of authenticating a user via user name and password. The API Manager allows protecting an API using the Basic authentication scheme. The publisher needs to configure the user store against which the credentials needs to be authenticated. If the API resource is protected with a Scope and configured with roles, then role authorization also happens during the consumption of the API.
 
To consume an API with Basic authentication, you must be a part of the roles/groups defined in the scope. If you want to use Basic authentication, consume your Web API over a Secure Socket Layer (SSL) because you need to pass user name & password in every call to the protected API.
 
The example below provides a step by step procedure that shows how to authenticate and authorize the publicly available pet store API using Basic authentication scheme. The example also uses LDAP Directory as the backend user store through the API Manager gateway. 
 
  1. Login to API Manager publisher portal. (http://hostname:port/portal)
  2. Navigate to Create API -> Import REST API From Swagger
  3. Provide the Swagger URL http://petstore.swagger.io/v2/swagger.json in the popup & click Import. It auto populates the UI with complete API Definition along with the resource definitions.
  4. Provide the API Name and Context as petstore. Navigate to Security -> Authentication and choose basicAuth as the authentication type. Click Apply to all resources. Doing so sets Basic Auth as the authentication method to all the resources. You can also one can override this authentication type at the sub-resource level as well.
  5. Select Enterprise Directory as the user store against which the credentials need to be authenticated.
Authentication Configuration
  1. Create two scopes, pet_write and pet_read. Only users with Pet Reader role can read the pets. Users with role Pet Writer can write and delete the pets. 
pet_read
pet_write
  1. Assign pet_read to all the resources for all the GET operations of pet resource. Assign pet_write to all the resources of pet other than GET.
pet_read
  1. Select SLA Pans GOLD and SILVER. Click Apply to all resources to set SLA Plan for all the resources. At a sub-resource granular level, you can also de-select the SLA plan that makes it as unavailable in that particular SLA plan.
  2. Click Publish to publish the API and makes it ready for use.
Now the API is published, subscribers/consumers can search for this API, read the API and can subscribe it to consume from the Developer application.
 
  1. Log in to the API Manager portal as Subscriber. If you have both publisher and subscriber roles, switch to subscriber role in the portal.
  2. Navigate to My Applications. Register the developer application and provide a name and description. A unique identifier for the application clientid gets generated for this application.
  3. Browse for this API in the API catalog and select the API. Click Subscribe.  Select the created Application, choose the SLA Plan, and select both the scopes Petstore_pet_read and Petstore_pet_write. Click Subscribe.
API Access
Passing the credentials in API Runtime request:
 
With HTTP Basic Authentication, your 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 cGF1bDpQYXNzd29yZEAxMjM=
 
But simply passing user name/password credentials does not identify which application is consuming the API. So the application unique identifier (client ID) must be embededed in the developer application and must be sent in each request. The client ID can be sent either using header or query or post parameter named clientid.
 
A user named paul with role per writer consumes the API that adds a new pet to the store.
 
PUT /PetStore/v1.0.0/pet HTTP/1.1 Host: localhost:9100 Authorization: Basic dm9yZGVsOnZvcmRlbA== clientid: 3ffb313f16856a4d6b1feecd2e50b950 Accept: application/json Content-type: application/json { "id": 100, "category": { "id": 1, "name": "dogs" }, "name": "German Shepard", "photoUrls": [ "string" ], "tags": [ { "id": 10, "name": "dogs" } ], "status": "available" }
The following checks happen once the API Manager receives the request for the Basic Auth Protected API.
 
  1. The API Manager looks for the Application unique identifier (or client ID)  in the request.
  2. Once the API Manager finds the client ID, the API Manager checks if the client ID is valid for the API and is approved. If there is no client ID or the request is invalid, the request fails and it sends status code 400 (Bad request) in the response.
  3. The API Manager checks for any scope associated with a current API operation. If the scope exists, the API Manager registers the scope. If yes, the scope is registered while subscribing to the API. The current API is protected using scope pet_write. If a scope is not registered, the request fails and sends unauthorized 401 response.
  4. The API Manager extracts the authorization header from the request and authenticates against the configured userstore. If authentication is not successful or the credentials are invalid, an unauthorized response is sent in the response.

 
Where to go from here

This article provides an overview of the authentication and authorization processes available in API Manager. Please check Part 2 of this article to know more about the additional authorization frameworks in API Manager.