API Authentication

Red Hat 3Scale 2.saas

For Use with Red Hat 3Scale 2.saas

Red Hat Customer Content Services

Abstract

This guide documents methods for api authentication with Red Hat 3Scale 2.saas.

Chapter 1. Authentication Patterns

By the time you complete this tutorial you’ll know how to set the authentication pattern on your API and the effect this has on applications communicating with your API.

Depending on your API you may need to use different authentication patterns to issue credentials for access to your API. These can range from API keys to openAuth tokens and custom configurations. This tutorial covers how to select between the standard Authentication Patterns Available.

1.1. Authentication Patterns

3scale supports the following authentication patterns out of the box:

  • Standard API Keys: single randomized strings or hashes acting as an identifier and a secret token.
  • Application Identifier and Key pairs: immutable identifier and mutable secret key strings.
  • OAuth 2.0: OAuth 2.0 client id, client secret and access token combinations.

1.2. Extensions

3scale also offers commercially reasonable support for coupling issues credentials with IP address filtering or referrer domain filtering – see the extra section at the end of this tutorial.

1.3. Step 1: Select the Authentication mode for your service.

Once in your Administration Dashboard, navigate to the API tab and select the service you wish to work on (there may be only one service named API in which case select this). Click on the Integration Link.

Select Authentication Mode Step 1

Note that each service you operate could use a different authentication pattern, but only one pattern can be used per service.

It is not recommended you change the authentication pattern once credentials have already been registered since behavior may be unpredictable. To change authentication patterns we recommend creating a new service and migrating customers.

1.4. Step 2: Select the Auth Mode you want to use

Scroll down to the Authentication section an choose the required Authentication mode.

Select Authmode Step 2

1.5. Step 3: Ensure your API accepts the right types of Credentials

Depending on the credential type chosen, you will likely need to accept different parameters in your API calls (key fields, IDs etc.). The names of these parameters need not be the same as those used internally at 3scale, your 3scale authentication will function correctly just as long as the correct parameter names are used in calls to the 3scale backend.

1.6. Step 4: Create an application to test credentials

In order to test the credential sets are working you can create a new application to issue credentials to use the API. Navigate to the Accounts area of your dashboard, click on the account you wish to use and click the new application button.

Filling out the form and clicking save will create a new application with credentials to use the API. You can now use these credentials to make calls to your API and records will be checked against 3scale list of registered applications.

1.7. Standard Authentication Patterns

3scale supports the following authentication patterns out of the box.

1.7.1. API Key

The simplest form of credentials supported is the single API model. Here each application with permissions on the API has a single (unique) long character string something like this:

    API-key = 853a76f7c8d5f4a1ee8bf10a4e0d1f13

By default the name of the key parameter is user_key. You can use this same label or choose another such as API-key in which case you simply need to map the value over before you make the authorization calls to 3scale. The string acts as both an identifier and a secret token for use of the API. It is recommended such patterns are only used either in environments with low security requirements or with SSL security on API calls. The operations which can be carried out on the token and application are:

  • Application Suspend: this suspends the applications access to the API and in effect all calls to the API with the relevant key will be suspended
  • Application Resume: undoes the effect of an application suspend action
  • Key Regenerate: this action generates a new random string key for the application and associates it with the application. Immediately after this action is taken calls with the previous token will cease to be accepted.

The latter action can be triggered from the API Administration dashboard and (if permitted) from the API Developers User console.

1.7.2. App_ID and App_Key Pair

Whereas the API Key Pattern combines the identity of the application and the secret usage token in one token, this pattern separates the two. Each application using the API issues an immutable initial identifier known as the Application ID (App ID). The App ID is constant and may or may not be secret. In addition each application may have 1-n Application Keys (App_Keys). Each Key is associated directly with the App_ID and should be treated as secret.

    app_id = 80a4e03 app_key = a1ee8bf10a4e0d1f13853a76f7c8d5f4

In the default setting, developers are able to create up to 5 keys per application. This allow a developer to create a new key, add it to their code redeploy their application and then disable old keys – causing no application downtime as an API Key Regeneration would.

Note that statistics and rate limits are always kept at the application ID level of granularity and not per API Key. If a developer wishes to track two sets of statistics, they should create two applications rather than two keys.

It is also possible to change mode in the system and allow applications to be created without applications keys present. In this case the 3scale system will authenticate access based on the App ID only (and no key checks are made). This mode is useful for (for example) widget type scenarios or where rate limits are applied to users rather than applications. Note that in most cases you will want your API to enforce there to be at least one application key per application present (this setting can be found on the Settings menu item under usage rules).

1.7.3. openAuth Support

openAuth is a set of specifications which enable a variety of different authentication patterns for APIs. The two major versions released so far (v1 and v2) are significantly different and version 2 includes a number of different supported authentication flows.

1.7.4. More Information

If you have authentication needs which are not covered by this how to, let us know by email at support@3scale.net for information on what else we support.

In addition, 3scale supports coupling credentials with authorized IP ranges per key or referrer domains per key to restrict where specific API credentials can be used. You can enable this additional filtering by navigating to the API Tab and accessing the Settings screen on the API.

Chapter 2. OAuth 2.0

OAuth 2.0 framework provides different authorization grant types that are specifically tailored for different scenarios and application types. It enables a 3rd party application to obtain limited access to a resource, either on behalf of a resource owner or its own behalf.

At 3scale we support the following OAuth 2.0 flows for:

  • Client Credentials
  • Resource Owner Password
  • Client-Side Web Applications (AKA Implicit)
  • Server-Side Web Application (AKA Authorization Code)

These flows typically (though not always) have a number of players involved:

  • Resource Server (provider/API)
  • Client (buyer/developer/application)
  • Resource Owner (end user)
  • Auth Server (NGINX + 3scale cloud Service and/or API Provider’s own Auth Server)

There are typically 2 actions that need to be done when accessing an OAuth protected API endpoint

  1. Requesting an access token from the Authorization Server
  2. Using the access token to access the API endpoint

Depending on the longevity of the access token, the first step might only need to be done once (for non-expiring tokens.)

How these access token is requested can vary based on the OAuth 2.0 flow and its implementation. We will outline the different flows below and the basic implementation for these at 3scale.

For instructions on how to set these up in NGINX, please visit the OAuth with APIcast section in the API Configuration Page. To set up ActiveDocs with OAuth, please visit ActiveDocs and OAuth section in the API Configuration Page.

2.1. Client Credentials Flow

The Client Credentials flow is the simplest of the flows. It is used to grant authorization in the case where the protected resources are already under the control of the client or when access to the resource has already been previously granted through some other means. The main players involved in the access token request step would therefore be the Client and the Authorization Server.

Once an access\_token is issued, the Client will call the API using this access token instead of their credentials (client\_id and client\_secret.)

2.1.1. Regarding Resource Owner Authentication

For the next few workflows, when there is a Resource Owner/End User involved, there will be an extra player involved in the grant workflows. As the NGINX API Gateway does not hold any user details, it will need to delegate user authentication whilst still generating and managing the access tokens for a Client.

This means that in effect there are 2 Auth Servers: NGINX API Gateway to Authorize and Authenticate the Client and API Authentication Server for the Resource Owner.

2.2. Resource Owner Password Credentials Flow

The Resource Owner flow is the next step up from the client credentials flow in terms of simplicity. It allows the application to exchange the resource owner’s username and password for an access token. As such, the user’s password is accessible to the Client and therefore it should only be used when the Client is highly trusted by the resource owner e.g the Twitter mobile app accessing the Twitter API.

Since 3scale does not hold and/or store the end user credentials, these will need to be checked against another Authorization Server or the Resource Server itself. In this case there are 2 sets of validations performed:

  • Are the Client credentials to request the access token valid?
  • Are the Resource Owner credentials to access the Resource Server valid?

In this case, the Resource Owner and Resource Server are both involved in the access token request as they need to provide (in the case of the RO) and validate (in the case of the RS) the credentials sent to the Client for exchange with the Authorization Server. Additionally, the Resource Server will need to validate the RO credentials are valid and either generate the access token or prompt the Authorization Server to do so.

These are the typical steps involved in this flow:

  1. Resource Owner provides username and password to Client
  2. Client requests access token by calling Authorization Server with Resource Owner’s username and password as well as its own client\_id
  3. Authorization Server (NGINX) calls 3scale cloud Authorization Server to check client\_id is valid
  4. If Client credentials are valid, NGINX requests validation of Resource Owner credentials with the Resource/Auth Server.
  5. If Resource Owner credentials are valid, Authorization Server generates and returns access\_token to NGINX.
  6. NGINX sends access\_token on to Client and to 3scale cloud Authorization Service for storage. This will allow subsequent requests using the access token to be associated with the correct Client without the need to send client\_id and/or client\_secret.

2.3. Client-Side Web Applications / Implicit Grant Flow

The Implicit Grant flow is designed for use by Clients running within a browser. It is a simplified version of the Server-Side Web Applications Flow which is optimized for efficiency of the Client by reducing the number of round trips to the Authorization server to receive an access token. As the Client runs within a browser, the access token may be available to the Resource Owner as well as any other applications that have access to the browser. Therefore this flow should be used when:

  • The browser is strongly trusted and/or there’s little danger that the access token will be exposed to untrusted users/applications
  • The Resource Owner is typically logged in to the Resource Server
  • Access to the required resource is only needed temporarily

These are the typical steps involved in this flow when using NGINX/3scale to manage token storage and generation:

  1. Client requests access\_token by calling API Gateway (NGINX) with credentials (client\_id) and redirect uri.
  2. The API Gateway then calls 3scale Cloud Authorization Server to check credentials are valid.
  3. If credentials are valid and redirect uri matches value stored in 3scale, API Gateway redirects to OAuth login URL hosted on Authorization Server.
  4. If Resource Owner is prompted to log in (if not already done so) and asked to grant access to the Client.
  5. If Resource Owner grants access, Authorization Server calls API Gateway with the access token.
  6. API Gateway forwards on access token to Client redirect url.

2.4. Server-Side Web Applications / Authorization Code Grant Flow

This last grant type is used in the case where the Client is a web application server. It allows for an access\_token for a user to be issued directly to the client, without exposing it to the user’s browser and potentially other parties. Additionally as the Resource Owner is authenticated by an authorization server, her credentials are never exposed to the Client. These two features combined make this the most secure (albeit the most complicated) of all the flows.

These are the typical steps involved in this flow when using NGINX/3scale to manage token storage and generation:

  1. Client requests access\_token by calling API Gateway (NGINX) with credentials (client\_id) and redirect uri.
  2. The API Gateway then calls 3scale Cloud Authorization Server to check credentials are valid.
  3. If credentials are valid and redirect uri matches value stored in 3scale, API Gateway redirects to OAuth login URL hosted on Authorization Server.
  4. Resource Owner is prompted to log in (if not already done so) and asked to grant access to the Client.
  5. If Resource Owner grants access, Authorization Server calls API Gateway to inform access has been granted.
  6. API Gateway generates a temporary authorization code and forwards it on to Client redirect url.
  7. Client calls API Gateway OAuth Token endpoint with credentials and authorization code.
  8. If authorization code is valid, API Gateway generates and returns access token to Client redirect url.

Legal Notice

Copyright © 2017 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.