BYU's API Manager authentication is handled using OAuth 2.0. BYU's previous API Key infrastructure will no longer be supported. OAuth 2.0 is a protocol which has become standard in the industry, with implementation libraries available in most languages. Most of the information in this document is taken directly from the specifications found at http://oauth.net/2/, with examples specific to BYU added for clarity.

OAUTH ROLES

OAuth 2.0 defines four roles:

Resource Owner - The user that grants access to an application (client). If he or she desires, the resource owner may specify a particular "scope" of access which the client receives (i.e. read access only).

Client - The application acting in behalf of the resource owner. Clients may be public or private. A public client is an application code executed on uncontrolled servers, such as browsers or mobile apps, whereas a private client is an application code executed on secured servers only.

Resource Server - The server which hosts the resources to which the client is requesting.

Authorization Server - The server responsible for issuing access tokens to the client and obtaining resource owner authorization.

In BYU terms, the Resource Owner is the end-user identified by his or her NetID. The Client is the application which makes API requests on behalf of the end-user. The Authorization Server is the WSO2 Identity Server implemented by OIT. And the Resource Server is a combination of the WSO2 API Manager implemented by OIT, and the server where the application code resides. The API Manager provides identify information to and accepts access tokens on behalf of the application.

 

CLIENT REGISTRATION

Before a client can access any APIs, he or she must register with BYU's (WSO2) API Manager and receive both a Consumer Key (client_id) and a Consumer Secret (client_secret). The registration process requires the client to provide a Callback URL (redirect_uri) that will be used in the various OAuth grant types. The Consumer Key (client_id) is public information and is used by all grant types. The client_secret should be kept secured, as it acts as a password for the client to identify itself to the authorization server. The WSO2 API Manager uses different terms from OAuth to represent the same values. In this document, I will use the standard OAuth terminology.

OAuth

API Manager

client_id Consumer Key
client_secret Consumer Secret
redirect_uri Callback URL

 

TRANSPORT LAYER SECURITY

Transport Layer Security (TLS) is a cryptographic security protocol which prevents third-parties from intercepting messages sent over the internet. When an entity uses TLS, all requests will be HTTPS requests, rather than HTTP requests. Any authorization server or resource server interacting with OAuth 2.0 is required to use TLS, in order to protect sensitive information. TLS implementation is strongly recommended for all clients, as well; however, due to issues with feasibility, client use of TLS is not required.

TOKENS

OAuth 2.0 specifies the following token types:

access_token - An access token is used to obtain access to a protected resource. It is issued by the authorization server and has a limited lifetime.

refresh_token - A refresh token is used to obtain a new access token when the existing access token has expired. The refresh token is issued along with an access token for most grant types and has a long lifetime.

authorization_code - An authorization code is a temporary token issued by the authorization server during the Authorization Code grant type. Along with the Client Credentials, it is used to obtain an access token from the authentication server.

GENERIC PROTOCOL FLOW

The basic flow of an OAuth 2.0 request is as follows:

 

In this flow:

A) The client requests authorization from the resource owner either directly or (preferably) indirectly via the authorization server. Details of this interaction depend on the grant type.

B) The resource owner grants access to the client via an authorization grant.

C) The client requests an access token by passing the authorization grant to the authorization server.

D) The authorization server validates the authorization grant and issues an access token.

E) The client requests protected resources from the resource server by attaching the access token.

F) The resource server validates the access token with the authorization server and returns the protected resources.

BYU PROTOCOL FLOW

In BYU's implementation of the OAuth 2.0 protocol flow, the role of the Resource Server is shared by the WSO2 API Manager and the application server. The basic flow of the BYU implementation is as follows:

 

In this flow:

Steps A - D are the same as in the basic OAuth 2.0 protocol flow. Steps E - J have been altered/added in order to account for the shared responsibility of the WSO2 API Manager and the application manager, in fulfilling the duties of a resource server. The additional steps are as follows:

E) The client sends the request for the protected resource, along with the access token, to the API Manager.

F) The API Manager validates the access token with the authorization server.

G) If the access token is valid, the authorization server returns the identity of the client and resource owner associated with the access token.

H) The API Manager forwards the request for the protected resource, along with the identity of the client and resource owner, to the application server.

  • The application server receives the identity as a JSON Web Token (JWT).
  • If there is a resource owner associated with the request, WSO2 also offers the option of having the API Manager define C Framework protocol headers compatible with the NetId, BYUId, and PersonId of the resource owner.

I) The application server returns the protected resource to the API Manager.

J) The API Manager returns the protected resource to the client.