API Authorization – OAuth2

The industry has largely aligned on the use of OAuth2 and/or OpenID Connect as the solution for providing authentication and authorization for developer API access. The OAuth2 RFC 6749 specification accommodates various different API access scenarios ranging from simple server to server integration to the increasingly common use case of a user of a particular service granting authorized access to all or a subset of their data to a 3rd party application.

Overview

OAuth 2.0 is a simple and secure authorization framework. It allows applications to acquire an access token for authorized API access via various workflows supported within the OAuth2 specification. Once an application has an access token, it can access the various APIs serviced by the server platform either to configure the platform itself or act on behalf of a related user. At a very high level, authorization with OAuth2 can be accomplished in the following steps.

• Decide on the use case for API Access – administrative configuration of the server platform or managing the hosted data on behalf of a user.
• Create API Client definition on the server that matches the above use case
• Request an Access Token using the Client ID details from the API client definition created in the previous step.
• Make authorized API calls to the server APIs by including the Bearer <access_token> in the HTTP Authorization header.

OAuth Basics

The best way to understand the different use cases for OAuth2 is to start with the various roles that make up a possible OAuth2 transaction.

Resource Owner

The resource owner is the person or application that owns the data that is to be shared. For example, a user on Facebook or Twitter could be a resource owner and the resource they own is their data on these social platforms. Typically, the resource owner is thought of as a person but it could also be an application. The OAuth 2.0 specification supports different workflows for each of these use cases.

Within the context of ClearPass, the resource owner can be thought of as the Sponsor or ClearPass operator that is acting upon the data stored within the ClearPass platform.

Resource Server

The resource server is the server hosting the resources. For example, a platform such as Facebook or Twitter would be considered a resource server. It is essentially the server hosting the protected content that will be accessed via the APIs.

Relating this back to the ClearPass API use cases, the resource server is the ClearPass server or cluster of servers depending on the deployment type. All nodes within the ClearPass cluster can service read-only API calls, and any unsafe API operations (POST, PUT, DELETE) will be internally proxied to the ClearPass publisher for database synchronization.

Client Application

The client application is the application requesting access to the protected resources stored on the resource server.

This will be the application that is being developed to leverage the APIs and data hosted by the ClearPass platform. This App could take many forms, from a native mobile App through to a server side script that is run on a periodic basis.

Authorization Server

The authorization server authorizes the client application to access the resources of the resource owner. The authorization server and the resource server can be deployed as part of the same server, but the OAuth 2.0 specification does not dictate whether they should be collocated or separated.
In the case of the ClearPass platform and in the interests of simplicity it is fair to assume the resource server and authorization server are co-located on the same server.

OAuth2 Client

Before any OAuth transactions can be processed, the first step is to register a new application definition. When registering a new app with the ClearPass Authorization Server, basic information such as application name and the OAuth2 grant type are specified.
From the ClearPass Guest administration interface, a new OAuth2 API client can be created by browsing to the Administration > API Services > API Clients web page. Click on the Create API client button in the top right corner and the following form can be completed to suit the requirements of the current API integration.

A more detailed discussion of the various options when configuring an OAuth2 client is included in ClearPass Configuration chapter later.

The result of registering an OAuth2 app is a client id and client secret. These will need to be retained and shared with the app developer to enable them to successfully authorize the API access and make subsequent API calls.

Client ID and Secret

After registering your app, you will receive a client ID and a client secret. The client ID is considered public information, and is used to build login URLs, or included in JavaScript source code on a page. The client secret must be kept confidential. If a deployed app cannot keep the secret confidential, such as JavaScript or native apps, then the secret is not to be used.

Authorization Grant Types

OAuth 2 provides several "grant types" for different use cases. The grant types defined are:

• Authorization Code for apps running on a web server
• Implicit for browser-based or mobile apps
• Password for logging in with a username and password
• Client credentials for application access

Note: ClearPass 6.6 supports only the password and client credentials grant types. ClearPass 6.8 and later support OAuth2 tokens. A description of how the Authorization and the Implicit Flow grant types differ from those currently supported by ClearPass have been included in Appendix B for completeness.

Resource Owner Password

OAuth 2 also provides a password grant type, which can be used to exchange a username and password for an access token directly. This is often compared with HTTP basic authentication as the same credentials are being exchanged but has the same security benefits of the other OAuth2 grant types in expiring access token and the ability to refresh the access token without the need to cache or resubmit the user credentials.
Since this requires the application to natively collect the user's credentials, this grant type should only be used for apps with a direct relationship (first party) with the authorization server. A real world example could be the official mobile app for a social networking site versus allowing 3rd party developers to leverage APIs to develop their own mobile experience for the social platform (they should be leveraging the Implicit flow).

1. User enters credentials directly into the app’s native user interface

• App should not cache user credentials under any circumstances

2. The App submits the user credentials to the Authorization Server.

• Includes grant_type=password, user, password, client_id, client_secret
• client_secret is not required if the OAuth2 app is defined as a public client

3. Resource Server returns an access token for use in subsequent API calls

• Includes access_token, expiry time, token_type=bearer, refresh_token

4. The app includes the access token in the HTTP Authorization header

• Includes Bearer <access_token>

5. Resource Server returns an authenticated API payload

Client Credentials

The simplest grant type offered by OAuth2 doesn’t include a 3rd party user at all and is essentially intended for server-to- server integrations for updating the application server configuration. In this case, applications need a way to get an access token for their own use and do this outside the context of any specific user. OAuth2 provides the Client Credentials grant type for this purpose.

Given the simplicity of this grant type, many developers may leverage its basic workflow to recover an access token so they can get and up running quickly with the APIs. That being said, client credentials should never be used in production where a non-trusted 3rd party developer has access to the client secret.

The following diagram shows the transaction flow of the client credentials grant type.

1. The first party app submits an access token request to the Authorization Server

• Includes grant_type=client_credentials, client_id, client_secret

2. Resource Server returns access token for use in subsequent API calls

• Includes access_token, expiry time, token_type=bearer

3. The app includes the access token in the HTTP Authorization header

• Includes Bearer <access_token>

4. Resource Server returns authenticated API payload