1.5 OAuth 2.0, OpenID Connect and SAML

1.5.1 OAuth 2.0

OAuth 2.0 is a Token-based authorisation framework and is defined and implemented using Grant Flow type patterns. These define the different types of interaction a client application can perform to gain an “access token” and thus access to the protected resource.

There are four grant flows types supported by the OAuth 2.0:

  1. Authorisation Code
  2. Implicit
  3. Resource Owner Password Credentials
  4. Client Credentials

1.5.2 Grant Types

The following table explains which grant flow type to use for which situation:

Description

Recommendations

Authorisation Code

Use for Internal Users or where the Customer is the Resource Owner, your agency controls the Resource Server, but the Authorisation server is not owned by the agency or is elsewhere within the organisation.

  • The Authorisation Server provides the Authorisation Code (grant) to the client application once the Resource Owner has approved the request
  • The client application then uses this to request the access token
  • The Authorisation Server validates the client application using the Client ID and Client Secret. The client application has to store these credentials securely
  • The client application authenticates to the Authorisation Server via its TLS certificate and call-back URL

Useful if the API requires a customer of a client application to authorise access to a protected resource provided by the API.

Recommended

The most secure OAuth flow.

Use for public facing APIs for Customer Authorisation pattern.

Use for Internal Use Only pattern.

Use the state attribute to link request and response.

Implicit

Used when the client application resides on a device (e.g. smart phone) and cannot secure the credentials.

Only the “Access token” is transmitted from the Authorisation Server to the client.

Not Recommended

The least secure grant type.

If used it should ONLY be for information that is public and ONLY for GETs.

Resource Owner Password Credentials

The Resource Owner’s username and password are used once as the Authorisation grant to obtain an Access Token. The credentials are then discarded.

 

Not Recommended

Use for Customer Authorisation pattern if Authorisation Code grant flow can’t be used.

Use for Internal Use Only pattern to secure Internal APIs that use Active Directory Groups / Kerberos for authorisation and authentication if Authorisation Code grant flow is not available.

Client Credentials

The client application is able to obtain access to the protected resource on its own behalf.

 

 

Recommended

Use:

-       For the Authorise Consuming Application pattern from device to API

-       Also use for Server to Server (B2B), using signed tokens

-       when the Customer using the client application is also the Resource Owner

Table 4 - OAuth 2.0 Grant types

This table compiles the different grant types and provides recommendations for agencies implementing an API Security Framework. Recommendations are based on maximising the level of security for the APIs being exposed.

OAuth 2 introduced different grants types to provide organisations with the flexibility to support a variety of client application models. These models are not device driven i.e. there is no specific device (e.g. mobile) mapping to grant type; it is the level of risk an agency is prepared to support that needs to be defined.

For the application developer, the difference is in the infrastructure they need to provide e.g. the “Authorisation Code” model requires a managed server on which the client application runs.

The “Authorisation Code” is the most frequently used model and as it is regarded as the most secure model it is covered in more depth later in this document. The Implicit grant is the least secure and to quote from the OAuth RFC:

“Implicit grants improve the responsiveness and efficiency of some clients (such as a client implemented as an in-browser application), since it reduces the number of round trips required to obtain an access token.  However, this convenience should be weighed against the security implications of using implicit grants”

These OAuth 2.0 Grant flow types replace the two-legged and three-legged patterns used in OAuth 1.0.

1.5.3 Basic OAuth Implementation Patterns

There are three primary implementation patterns:

  1. Client Credential Grant Flow
  2. Authorisation Code Grant Flow
  3. Distributed Resource and Authorisation Servers (UMA model – see section 1.5.9)

Illustration of OAuth 2 Implementation Models 

Figure 18: OAuth 2 Implementation Models

As can be seen above, in most models the Resource Server resides with the Authorisation Server. But OAuth 2.0 also supports a distributed model, if needed, where the Resource Server and Authorisation Server are separate.

By adding an Authentication Server component into the API Security Framework, a number of additional implementation models can be considered. The models above have separate Authorisation servers e.g. external Identity Service Providers, Google, RealMe etc. or internal Authorisation services.

These Authentication Services could be housed on the same system as the Authorisation and Resource Server, and can, as would be expected, simplify the Security architecture.

Illustration of OAuth 2.0 Models (colocation of Authorisation and Authentication 

Figure 19: OAuth 2.0 Models (colocation of Authorisation and Authentication services)

1.5.4 Quick Reference Table

The following table provides a quick reference to identify the most appropriate authentication and authorisation model to use for the patterns defined in 1.3.2 Usage Patterns:

API Usage Patterns

Vendor or Internally Developed API Gateway Capability

API Keys

OAuth 2.0 Grant Types

API Gateway Proprietary

Client Credentials

Resource Owner Password Credentials

Authorisation Code

Implicit

Identify Consuming Application

Y

Recommended

 

 

 

 

Y

Authorise Consuming Application

Y

 

Y

Recommended

 

 

 

Y

 

Customer Authorisation

Y

 

 

Y

Y

Recommended

N

Y

 

System to System (B2B)

Y

Y

Recommended

 

 

 

Y

Internal Use Only

 

 

 

Y

 

Y

Recommended

 

Y

 

Application Developer

 

 

 

 

 

Y

Recommended

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Table 5 - Quick Reference Guide

 

  1. The initial consideration for any API Security Framework should be to use the Authorisation Code Grant Type, but the following provide pointers for agencies when considering their requirements:

    1. It is good practice to use API Keys as the basis of all system-to-system authentication, such as consuming application to API.
    2. For the Authorise Consuming Application usage pattern, the Client Credentials Grant Type is recommended but the API Keys model can be used instead.
    3. For the Customer Authorisation usage pattern
  • the Authorisation Code Grant Type is recommended where the customer is the Resource Owner, the provider (agency) controls the Resource Server, but the Authorisation server is not owned by the provider or is elsewhere within the provider organisation
  • the Resource Owner Password Credentials Grant Type is appropriate where the customer is the Resource Owner, the provider (agency) controls the Resource Server, and the API Gateway is the OAuth 2.0 Authorisation Server
  • Use of solely API Keys for Customer Authorisation is only appropriate as a last resort
  • For the Internal Use Only usage pattern, the Authorisation Code Grant Type is recommended, where practical. Otherwise, it may be appropriate to leverage the provider agency’s existing internal authentication and authorisation providers
  • For the Developer Authentication usage pattern, it is appropriate to leverage (or build) the capabilities of the developer portal (e.g. username and password).

1.5.5 Tokens & Credentials

Access tokens are becoming a standard form of access control without the need for passing credentials. Anyone with an access token (bearer token) is permitted access to the resource being controlled, which makes tokens a target for stealing or copying. Hence it is important to keep the lifetime of tokens as short as realistically possible, depending on the type of resource being exposed and business risk appetite.

The OAuth framework (RFC 6749 and 6750) relies heavily on TLS for the security of the bearer token. The following RFCs (or drafts) offer additional integrity and confidentiality capability that can be applied to the bearer token (access token):

  1. OAuth 2.0 Message Authentication Code (MAC) Tokens
  2. JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC 7523)
  3. Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs) (RFC 7800)

Tokens are produced by, and stored in, the Authentication Server. Each one has a specific task in the OAuth 2.0 framework. There are three types of token and three keys that should be considered in an OAuth 2.0 design:

Description

Recommendation

Access Tokens

Also called bearer tokens. No additional identity checks are carried out once this has been issued.

Used by the client application to access protected resources on the provider, and it can be signed.

It is a random character string that also contains “scope” information to allow additional access polices to be applied e.g. duration of access.

It is granted by the Resource Owner via the Authorisation Grant Token Flow and enforced by Authorisation and Resource Servers.

  • It is Required that the token be protected both in transit (TLS) and in storage (encryption)
  • The “Authorisation Request Header Field” format is Required to only be used to transmit tokens
  • It is Recommended that the life time of this token be set to 60 mins
  • It is Recommended that scopes be used for coarse and fine grained access
  • Form-Encoded Body Parameter is Not Recommended for transmission
  • URI Query Parameter is Not Recommended for transmission

Refresh Token

Used to obtain new Access tokens when the old one expires or is invalid.

 

  • It is Required that the token be protected both in transit (TLS) and in storage (encryption)
  • It is Recommended that the life time of this token be set to 24 hours

Authorisation Code

The Authentication Server sends the Authorisation Code to the Client after being granted consent by the Resource Owner.

Used to authenticate the client.

It is Recommended that the life time of this token be set to 24 hours

API Key

A 40+ random character string used in some scenarios to authenticate the client application to the API.

Required when implementing an authorisation solution that uses API Keys. This is normally presented as an option in the developer API Portal.

Client ID

When registering an OAuth Client application with the API Portal, a Client ID is issued.

Used when interacting with the Resource Server.

Required when implementing an OAuth 2.0 model that supports “Authorisation Code” flow

Client Secret

Also provided when the OAuth Client application is registered. This is used with the Client ID when exchanging an authorisation code for an access token

Required when implementing an OAuth 2.0 model that supports “Authorisation Code” flow

Table 6 - Tokens and Credentials

1.5.6 OAuth Scenario (Authorisation Code Grant Flow)

This is hypothetical scenario to demonstrate a key OAuth pattern using the Authorisation Code grant flow. In this scenario IRD have developed a set of APIs that can be used by professional accounting firms to offer additional services to their customers.

The assumption here is that IRD have an API Gateway, that offers:

  1. API Developer Portal
  2. OAuth Authorisation Server
  3. Resource Server, exposing the APIs that can be called
  4. That IRD are securing an API called “View IRD Return” with an Authorisation Code Grant Type

1.5.6.1 Stage 1 – Develop the Application (3rd Party)

The third party (in this case MyAccountantWebsite.com) develops a client application that will be exposed to their customers when they login to their website. It will allow customers of MyAccountantWebSite to authorise and setup delegated access for the MyAccountantWebSite application to view their IRD returns, but without the customer having to provide their IRD user name and password to MyAccountantWebsite.

The application will use the APIs exposed by IRD, and is developed on an MyAccountantWebsite.com Application (Web) Server that can securely store security credentials.

1.5.6.2 Stage 2 – Register the (Client) Application

The developer needs to register as a user of the IRD API Portal. IRD need to verify that this person is allowed to register as a user. (This process is outside the scope of this document, and will vary depending on the sensitivity of the APIs exposed.)

The authentication of the developer can be via:

  • IRD’s internal client login services
  • An external Identity Service provided (OpenID Connect or SAML based, or Social Network Identity provider)

Once the developer has been approved and has been granted login credentials (username and password) they log onto the IRD API Portal and register their client application; this is carried out over a TLS secured link. The following information is provided:

  • The name of the application (by the Developer)
  • Return URL (by the Developer)
  • Client ID (by IRD) – stored securely
  • Client Secret (by IRD) – stored securely

The developer completes development of the client application on MyAccountantWebsite. The next steps detail how the MyAccountantWebsite customer uses the application.

Note: the values of the Client ID and Secret are represented as simple strings below. In reality these are long, randomly generated strings.

 Illustration of Stage 2 Client Registration

Figure 20: Stage 2 Client Registration

1.5.6.3 Stage 3 –Customer Sets New Service and Authorises Access

The Customer logs into MyAccountantWebsite from their browser and clicks on the IRD button (View IRD) which should allow the user access to information presented by the “View IRD Return” API (see Figure 21: Stage 3 Client Registration below). As there is no current “Access Token” stored for the client application to use, the user is redirected to the IRD Authorisation Server “Authorisation End Point” with the following information:

  1. IRD URL A (Authorisation endpoint URL)
  2. Return URL (where the authorisation code will be sent)
  3. Client ID = ABC (random long string that is used to identify the client application)
  4. Scope = READ (defined by the application as to what the application can do)
  5. State = xyz123 (random long string that is used to mitigate man in the middle attacks)

 Illustration of Stage 3 Client Registration

Figure 21: Stage 3 Client Registration

1.5.6.4  Stage 4 – Authentication and Approval by the Resource Owner

As the client application doesn’t have an access token for this customer, or a session set up with IRD, the customer is redirected to the IRD login page. The customer then logs into IRD and will be presented with a request to accept the scopes (in this case READ) for MyAccountantWebsite access.

 Illustration of Stage 4 Client Registration

Figure 22: Stage 4 Client Registration

1.5.6.5 Stage 5 – Provide an Authentication Code

With the customer’s acceptance of the scope, the Authorisation server sends an Authorisation code to the client application (with the same state parameter for the client to validate).

 Illustration of Stage 5 Client Registration

Figure 23: Stage 5 Client Registration

1.5.6.6 Stage 6 –Authorisation Code is Sent to Token Endpoint

To gain access to API resources, the client application sends the Authorisation Code to the Token endpoint (T on the diagram below) on the Authorisation Server, along with the Client ID and Client Secret it received when the client application was registered. This is used for authentication of the client application to the authorisation server. Note: The communication must be over TLS.

 Illustration of Stage 6 Client Registration

Figure 24: Stage 6 Client Registration

1.5.6.7 Stage 7 – The Access Token It Provides

The Authorisation Server provides an Access token back to the client application, along with a refresh token (for later use) and an expiry time for the Access token.

 Illustration of Stage 7 Client Registration

Figure 25: Stage 7 Client Registration

1.5.6.8  Stage 8 – The Client Application uses the Access Token to Access the Resource

The Client Application presents the Access Token to the Resource Server at IRD, which is verified by the Authorisation Server and the requested data is returned from the IRD back end system via the View IRD Return API to the MyAccountantWebsite client application.

 Illustration of  Stage 8 Client Registration

Figure 26: Stage 8 Client Registration

This completes the OAuth scenario, as the client application has retrieved, and can use, the resource data returned from the API.

1.5.7 OpenID Connect and SAML (Security Tokens)

Use of OAuth authentication security token profiles is Recommended when an API requires more secure authentication than offered solely by API keys e.g. when data is a two-way flow between the consuming application and the API.

The two recommended implementation patterns (profiles) are:

  • OpenID Connect (see section 1.5.7.1)
  • SAML (see section 1.5.7.2)

The preferred standard is OpenID Connect. Use SAML only if it is readily available to your developer community or has been implemented for a specific sector e.g. Education.

During the authorisation token exchange process a level of authentication is required. The authentication process is basically limited to what authentication services the authorisation server can support. For example, the Resource Owner authorisation process is normally supported out of the box by the authorisation server, using username and password. The authentication service can be enhanced with authentication security tokens by implementing one of the two OAuth profiles detailed above.

For customers and internal users this can be achieved using a brokered or federated service. Basically Federation in the context of API security provides the ability to re-use user identities in a SSO way by providing a trust relationship between the Identity Service Provider (either providing SAML or Open ID Connect support) and the Authorisation Server. This establishment of trust between the Identity Provider and Authorisation Server is normally established using certificates and mutual authentication. All communication has to be over TLS to provide Confidentiality and Integrity controls.

1.5.7.1 OpenID Connect

OpenID Connect is a lightweight RESTful framework for identity service interaction, to provide authorisation services. It is built on top of the OAuth 2.0 framework and basically provides identity information in the form of an ID token.

It introduces a new Authentication service which will run on its own or on the OAuth Authorisation server and returns an “ID Token” along with the access token, after the API request has been authorised.

The ID Token is a JSON Web Token (JWT) that contains authenticated user information (and attributes) that the authorisation (OAuth 2 Server) / authentication server (OpenID Connect Server) provides to the client application. This token can then be used to enforce finer grained access controls by providing additional attributes that can be used by the authorisation server to apply these policies.

The “new” JWT token has to be signed in order to address confidentiality and integrity requirements. There are also additional parameters defined that have been added to address replay attacks.

In the first OpenID Connect pattern detailed in Figure 27, the Authentication and Authorisation Servers are conceptually hosted on different physical servers (the OpenID Connect server can be internal or external to the organisation). The user connects to the web application and is redirected to the OpenID Connect server for authorisation.

Once authorised, the user is redirected to the Web Application which in turn exchanges the ID Token for an access token.

Note: It is the token flow and exchange that is key to understand in this model. The Web Application could be an Application/ API Server and the interface to the authorisation and authentication server managed by the API Gateway

A trusted link is set up between the OpenID Connect Server and the OAuth Server (Authorisation Server) which also allows additional identity information to be provided in a JWT format via an userInfo end point. This is important as the token exchange can result in the loss of user data that is required to provide fine grained access.

If the OpenID Connect server was external, it would be the API Gateway that would be responsible for the interface and token exchange process.

 Illustration of OpenID Connect - Dist. Authorisation and Authentication Server

Figure 27: OpenID Connect - Distributed Authorisation and Authentication Server

The application has to exchange the ID Token for an Access Token in this pattern. In the second pattern (below) the OpenID Connect server is run on the same server as the OAuth Authorisation server, so the ID Token and the Access Token can be issued at the same time. In both models the OpenID Connect Server can use LDAP for its back end User Store, to provide authorisation for internal users.

Illustration of OpenID Connect and OAuth 

Figure 28: OpenID Connect and OAuth

The one final model is for an external OpenID Connect pattern, where the OpenID Connect server is an external Identity Provider (e.g. AoG service) and the API Gateway is responsible for managing the token exchange, potentially also housing the Authorisation Server.

To address the risk of forged or stolen assertions, it is recommended that all communication is over TLS and tokens are at a minimum signed for authentication.

1.5.7.2 SAML

If an OpenID Connect Service is not available, or there is only a SAML Service available, there is an OAuth authentication model that allows a SAML Identity Provider to replace the OpenID Connect service. This looks identical to Figure 27, but replaces the OpenID Connect server with a SAML provider. Like the OpenID Connect model, the SAML instance could be external or internal. The SAML profile works in a similar way to the OpenID Connect one, but there is one disadvantage with the SAML model in that there are no refresh tokens provided. The setting of “time to live” and session timeouts parameters for access tokens can add additional complexity and design constraints.

Illustration of OAuth with SAML Identity Provider

Figure 28: OpenID Connect and OAuth

The API gateway in this model (as with OpenID Connect) provides a threat protection service but could also act as:

  • Authentication Server
  • Redirect service to SAML Provider

This model uses the SAML 2.0 Bearer Profile for OAuth. See RFC 7522 for details.

 

The next sections will define how additional authorisation can be applied to this principal model to provide coarse and fine grained access controls.

1.5.8 Distributed Model Profiles

The above models work well when authorisation is controlled internally, but there will be situations where authorisation needs to be common across several agencies, as a shared resource.

Below are some emerging OAuth 2.0 Profiles which are applicable to a distributed authorisation model. These distributed authorisation models can also leverage and support both internal and external OpenID Connect or SAML Identity Service Providers.

This section addresses proposed OAuth profiles that should be considered if a distributed model is required by an agency or a group of agencies.

These profiles are currently in draft and have not been fully ratified. This section only provides a high level view of the proposed models. If these models are to be implemented, it is recommended that a full assessment is performed of the current state of these proposed RFCs.

OAuth 2.0 introduced a model where the Resource Server can run on a separate server.  This provides for models that can support multiple instances of the Resource Server or Authorisation Server. There are two RFC models currently defined:

  1. Multiple Resource Servers (UMA – see section 1.5.9)
  2. Multiple Authorisation Servers (Chained Authorisation – see section 1.5.10)

Illustration of Distributed Authorisation Models 

Figure 29: Distributed Authorisation Models

The UMA model is driven by the Kantara initiative and has been productionised by a couple of vendors.

The chained authorisation model is based on the Chain Grant Type for OAuth2 (expired) draft profile and is included here as a foundation for future development. There are currently no vendors providing support for this model, therefore any intention to use this model should be carefully considered.

With the introduction of the distributed Authorisation and Resource Servers model comes a number of technology scenarios which were not covered specifically by the basic OAuth 2.0 RFC.

OAuth designs usually rely on these two services (Resource and Authorisation) running on the same server. The following is a list of the limitations and the RFCs that address them.

  1. The OAuth standard Client Registration is a manual process. Both OpenID Connect and UMA reference a dynamic registration process. This is addressed with RFC 7591 (Dynamic Client Registration OAuth 2.0 Profile.
  2. In any OAuth model, the ability to revoke token access is a key component of the design. This becomes even more important when supporting multiple Resource and Authorisation Servers. RFC 7009 (Token Revocation Profile) addresses this requirement.
  3. The process for Resource Servers to query the state of an access token is not defined in the OAuth framework. This is defined in RFC 7662 (Token Introspection Profile).

Each of these is explained in the following sections.

1.5.8.1 Dynamic Client Registration OAuth 2.0 profile (RFC 7591)

Any client application has to be registered to the OAuth Authorisation server before it can gain access to Resource Server resources (e.g. APIs). This registration is normally a manual process performed by the developer. This particular profile offers a way to provide an end point on the Authorisation server so that client registration can be dynamic (e.g. a call can be made to this end point with the required registration information, and the authorisation server will register the client). This obviously speeds up the process of registration and makes it available on-demand.

Another key benefit is that the (dynamic) registration process can also generate different client IDs and client Secrets for each client application installation, which can dramatically mitigate risk related to compromised client IDs or secrets.

1.5.8.2 Token Revocation Profile (RFC 7009)

This profile defines a revocation endpoint on the authorisation server to enable clients (consuming applications) to revoke their own access or refresh tokens. This is essential should a token get into the wrong hands and be used for malicious purposes. Before allowing a client to revoke an access token and/or associated refresh tokens, the authorisation server first validates the client’s credentials.

1.5.8.3 Token Introspection Profile (RFC 7662)

This is a key requirement for a distributed model, as it allows a Resource Server to query an Authorisation Server to determine the state of a token and obtain additional meta data, including client ID, active state, scopes and [resource server] audience details. It can also provide extended attributes e.g. audience information.

1.5.9 User Managed Access (UMA)

UMA was introduced to address the following requirements:

  1. Support for multiple and distributed servers
  2. Delegated Authorisation to a person requesting access to one or more resources
  3. The resource owner providing a pre-defined policy of what can be accessed and by whom (i.e. minimise their interaction in the current OAuth approval process) and provides a central point of control.

 

UMA has been developed by the Kantara Initiative group. In UMA the user defines the relationship and access controls (policy) for all their resources across multiple Resource Servers. A centralised UMA Authorisation Server then keeps track of all Resource Servers associated with a given Resource Owner:

 Illustration of UMA

Figure 30: UMA

The Resource Owner introduces the UMA Authorisation Server to the Resource Servers and vice versa. They establish a token-based trust relationship which the Resource Owner authorises. The Resource Owner also defines the access control policies which grant access to potential consumers. A client application, driven by the Requesting Party who is requesting access to resources owned by the Resource Owner, attempts to access a resource on a Resource Server but will be redirected to the UMA Authorisation Server. The client application has to obtain a client key, client secret and access token from the UMA Authorisation Server before trying to get to the required resource on the Resource Server. The Resource Server will validate the access token and the permitted level of access with the Authorisation Server before allowing the client application to consume its required resources.

UMA uses the following “end points” (a URI that is exposed on the Authorisation Server) to allow certain requests to be made and processed:

  1. Token and Authorisation – defined in OAuth 2.0 framework
  2. Dynamic Client and Introspection – defined in extended RFC (see previous section)
  3. Resource Set Registration, Permission Registration and Request Party – defined in the UMA specification

These are detailed in the UMA architecture.  The UMA Authorisation Server offers two APIs to support these interactions:

  • Protection API – used by Resource Servers for getting authorisation-request tokens and validating access tokens
  • Authorisation API – used by the Client Application to obtain a token for accessing a specific resource

1.5.10 Chained Authorisation

This model has been included for interest purposes only. The objective of this model is to define a process for one protected API resource to talk to another resource API, or chain a request from a client application from one resource server to another. This is done by issuing another token (JWT) based on an established trust between the two Authorisation Servers. This model theoretically could support multiple authorisation server chainings and a Master / Slave model, but at present are not covered by explicit RFCs.

The two draft RFCs relating to this model are listed below, but note that both drafts have now expired:

  1. A Method of Bearer Token Re-delegation and Chaining for OAuth 2
  2. Chain Grant Type for OAuth2

 

The diagram below provides an indication of how the process would work. Note: this includes the use of JSON Web Tokens. This is not a fully defined model and would require additional investigation, review, validation and design before use.

Note: Organisations do implement solutions based on Draft RFCs, but can end up with an architecture that is not ratified by the released RFC. Engagement with the RFC is always recommended if this approach is required to meet a business need.

 Illustration of Chained Authorisation

Figure 31: Chained Authorisation

Page last updated: 18/12/2016