Using OAuth 2.0 and OpenID Connect with InterSystems IRIS
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 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:
Usually a user.
A server that hosts protected data and/or services.
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.
The client, resource server, and authorization server are known to each other, by prior arrangement. An authorization server has a registry of clients, which specifies the client servers and resource servers that can communicate with it. When it registers a client, an authorization server generates a client ID
and a client secret
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.
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.
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:
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:
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.
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.
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:
||Returns an authorization code (applies only to authorization code grant type)
||Returns an access token
||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
The InterSystems Developer Community provides the following articles on OAuth 2.0 and OpenID Connect: