# OAuth 2.0 Overview

OAuth 2.0 is an industry standard authorization framework. Here's a definition of the OAuth 2.0 framework from the IETF specification:

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

Essentially, OAuth 2.0 provides a way for apps to gain limited access to a user's protected resources without the need for the user to divulge their login credentials to the app. In the context of Cornerstone, these protected resources could be any data exposed through our public APIs including employee's transcript data, job applications or performance reviews.

# Generic Flow

The diagram below illustrates the general flow for OAuth 2.0 transactions. If you are unfamiliar with the terms used in this diagram, review the description following this diagram to gain a better understanding of the OAuth 2.0 flow.

OAuth 2.0 flow

  • Application (Client): The client is the application that is attempting to get access to the user's account. It needs to get permission from the user before it can do so.
  • Resource Server: The resource server is the API server used to access the user's information.
  • Authorization Server: The authorization server is responsible for validating authorization grants and issuing access tokens that give the application (client) access to the user's data on the resource server. Depending on the size of the implementation, the authorization server and the resource server could be the same component.
  • User (Resource Owner): The resource owner is the end user who is giving access to some portion of their account.
  • Authorization Grant: The authorization grant gives the application (client) permission to retrieve an access token on behalf of the end user. OAuth 2.0 defines four grant types. See Grant Types below for more details.
  • Access Token: An access token is a string of characters that serves as a credential used to access the protected resource.
  • Protected Resource: A protected resource is any data owned by the resource owner that is accessed by the application (client) through the API.

# Grant Types

Before an external application can call Cornerstone's APIs, they must acquire a token from Cornerstone. The OAuth 2.0 framework describes a number of grant flows ("methods") for acquiring an access token. Each grant flow has a distinct use case.

  • Authorization Code: In the authorization code flow, the application must first receive an authorization code from the resource server before the authorization server issues an access token. In this flow, the application never sees the user's credentials for the resource server. This grant type is typically used when the application resides on a server rather than on the client.
  • Implicit: The implicit flow is a simplified version of the authorization code. It is typically used when the application resides on the client or any environment where the application cannot securely store the authorization code. In this flow, the authorization server returns an access token directly when the user is authenticated instead of issuing an authorization code first.
  • Resource Owner Credentials: In the resource owner credentials flow, the application acquires and sends the user's username and password to the authorization server. Once the username/password is validated by the authorization server, it issues an access token. This flow is recommended only for highly trusted applications.
  • Client Credentials: The client credentials flow is used for server-to-server integrations where the end user is not involved in the authentication process. Essentially, the application is acting on its own behalf, i.e., the application is also the resource owner. In this flow, an application presents its client ID and secret to the authorization server to receive an access token.

Currently, Cornerstone only supports the Client Credentials grant flow.

# Access Token

An access token is a long string of characters that serves as a credential used to access the protected resource. Tokens are included in the headers that are sent in the request to the resource server. The resource server understands that the access token is being used in lieu of credentials like a username/password. Access tokens can be revoked if needed. Additionally, access tokens have expiry periods. If a token has expired, the application will need to request a new access token from the authorization server.

# Scopes

OAuth 2.0 provides the concept of 'scopes'. Using scopes, an authorization server can provision an access token with limited access to protected resources. For example, an application may have access only to specific Cornerstone APIs, may be able to perform POST operations, or may only be granted read-only access that limits the application to GET operations.