Overview of OAuth 2.0 and OpenID Connect
This chapter provides a brief overview of OAuth 2.0 authorization framework and OpenID Connect. The next chapter introduces InterSystems IRIS® data platform support for OAuth 2.0 and OpenID Connect.
The OAuth 2.0 authorization framework enables a third-party application (generally known as a client) to obtain limited access to an HTTP service (a resource). The access is limited; the client can obtain only specific information or can use only specific services. An authorization server either orchestrates an approval interaction or directly gives access. OpenID Connect extends this framework and adds authentication to it.
The OAuth 2.0 framework defines four roles:
Resource owner — Usually a user.
Resource server — A server that hosts protected data and/or services.
Authorization server — A server that is responsible for issuing access tokens, with which the client can access the resource server. This server can be the same application as the authorization server but can also be a different application.
An access token contains information about the identity of the user or client, as well as metadata such an expiration date, expected issuer name, expected audience, scope, and so on.
The general purpose of an access token is to enable a client to access specific data or services available via HTTP at a resource server. In the overall flow, the client application requests an access token from the authorization server. After receiving this token, the client uses the access token within HTTP requests to the resource server. The resource server returns the requested information only when it receives requests that contain a valid access token.
An access token can also be revoked, if the authorization server supports this.
Forms of Access Tokens
InterSystems IRIS supports two forms of access tokens:
JSON Web Tokens (JWTs). A JWT is a JSON object. A JWT can be digitally signed, encrypted, or both.
Note that one kind of JWT is an ID token; this is specific to OpenID Connect.
A JWT can be signed, encrypted, or both.
Opaque access tokens (also known as reference tokens). This form of access token is just the identifier of a token that is stored elsewhere, specifically on the authorization server. The identifier is a long, random string, intended to be very difficult to guess.
An access token contains a set of claims that communicate the identity of the user or client, or that communicate metadata such the token’s expiration date, expected issuer name, expected audience, scope, and so on. The OpenID Connect Core specification defines a standard set of claims, and other claims may be used as well.
JWTs and JWKSs
As noted above, a JWT can be signed, encrypted, or both. In most cases, the participants in the OAuth 2.0 framework use pairs of JWKSs (JSON web key sets) for this purpose. In any pair of JWKSs, one JWKS is private and contains all the needed private keys (per algorithm) as well as the client secret for use as a symmetric key; this JWKS is never shared. The other JWKS contains the corresponding public keys and is publicly available.
Each participant has a private JWKS and provides other participants with the corresponding public JWKS. The owner of a private JWKS uses that JWKS for signing outbound JWTs and decrypting inbound JWTs. The other parties use the corresponding public JWKS to encrypt outbound JWTs and verify signatures of inbound JWTs, as shown in the following figure:
Grant Types and Flows
In the OAuth 2.0 framework, a grant type specifies how the authorization server should process the request for authorization. The client specifies the grant type within the initial request to the authorization server. The OAuth 2.0 specification describes four grant types, as well as an extensibility mechanism for defining additional types. In general, each grant type corresponds to a different overall flow.
The four grant types are as follows:
Authorization code — This grant type can be used only with a client application that has a corresponding server. In this grant type, the authorization server displays a login page with which the user provides a username and password; these are never shared with the client. If the username and password correspond to a valid user (and if other elements of the request are in order), the authorization server first issues an authorization code, which it returns to the client. The client then uses the authorization code to obtain an access token.
The request for the authorization code is visible in the browser, as is the response. The request for the access token, however, is a server-to-server interaction, as is that response. Thus the access token is never visible in the browser.
Proof Key for Code Exchange (PKCE) is an extension to the authorization code flow that prevents a malicious actor from obtaining an access token with an intercepted authorization code. With PKCE, the client’s request for an authorization code includes an additional secret value. The authorization server saves this secret when it issues the authorization code. The client’s subsequent request to exchange the authorization code for an access token must include the original secret; someone who had intercepted the authorization code would not know this secret, thereby preventing them from obtaining an access token.
Resource owner password credentials — In this grant type, the client prompts the user for a username and password and then uses those credentials to obtain an access token from the authorization server. This grant type is suitable only with trusted applications.
Client credentials grant type — In this grant type, there is no user context, and the client application is unattended. The client uses its client ID and client secret to obtain an access token from the authorization server.
RFC 7523 describes an additional grant type, JWT authorization. This grant type uses of a JSON Web Token (JWT) Bearer Token to request an OAuth 2.0 access token and to authenticate the client; InterSystems IRIS supports this grant type in addition to the four in the OAuth 2.0 specification.
Note that in the OAuth 2.0 framework, in general, all HTTP requests are protected by SSL/TLS.
In addition, when a client sends a request to the authorization server, that request must be authenticated. The OAuth 2.0 specification describes the ways in which a client can authenticate the request.
The authorization server allows the client to specify the scope of the access request using the scope request parameter. In turn, the authorization server uses the scope response parameter to inform the client of the scope of the access token issued.
OpenID Connect is an extension to the OAuth 2.0 authorization process. To request authentication, the client includes the openid scope value in the request to the authorization server. The authorization server returns information about the authentication in a JWT called an ID token. An ID token contains a specific set of claims, listed in the OpenID Connect Core specification.
Endpoints in an Authorization Server
An authorization server provides some or all of the following URLs or endpoints, which can process requests of varying kinds:
|Authorization endpoint||Returns an authorization code (applies only to authorization code grant type)|
|Token endpoint||Returns an access token|
|Userinfo endpoint||Returns a JSON object that contains claims about the authenticated user (applies only to OpenID Connect)|
|Token introspection endpoint||Returns a JSON object that contains claims determined by examining an access token|
|Token revocation endpoint||Revokes a token|