How InterSystems IRIS Supports OAuth 2.0 and OpenID Connect
This chapter introduces InterSystems IRIS® data platform support for OAuth 2.0 and OpenID Connect.
With InterSystems IRIS support for OAuth 2.0 and OpenID connect, you can do any or all of the following:
Use an InterSystems IRIS web application as a client
Use an InterSystems IRIS web application as a resource server
Use an InterSystems IRIS instance as an authorization server
For example, you can use an InterSystems IRIS web application as a client of an authorization server that uses third-party technology. Or you can use third-party clients with an authorization server that is built on InterSystems IRIS. The resource server or resource servers could be implemented in InterSystems IRIS or in a different technology.
In all cases, the authorization server is the most complex element and is generally created first. You create clients later. When you create a client, it is generally necessary to understand the capabilities and requirements of the authorization server, such as the scopes it supports.
InterSystems IRIS Support for OAuth 2.0 and OpenID Connect
The InterSystems IRIS support for OAuth 2.0 and OpenID Connect consists of the following elements:
Configuration pages in the Management Portal.
If you configure a client (or a resource server), use the options at System Administration > Security > OAuth 2.0 > Client Configuration.
If you configure an authorization server, use the options at System Administration > Security > OAuth 2.0 > Server Configuration.
Classes in the %SYS.OAuth2 package. These classes are the client API. If you define an InterSystems IRIS web application as an OAuth 2.0 client, your client uses methods in these classes.
Classes in the %OAuth2 package. If you use an InterSystems IRIS instance as an OAuth 2.0 authorization server, you customize the server by subclassing one or more of the classes in the package %OAuth2.Server. Other classes in %OAuth2 provide utility methods for your code to call.
Classes in the OAuth2 package (in the IRISSYS database). These include persistent classes for internal use by InterSystems IRIS, and you can ignore most of them. However, if you want to create configuration items programmatically, you would use a subset of the classes in this package.
The following subsections provide an overview of the configuration items.
Configuration Items on a Client
Within an InterSystems IRIS instance that is acting as an OAuth 2.0 client, it is necessary to define two connected configuration items for a given client application: a server description (which describes the authorization server) and a client configuration (which configures the client). A given instance can have any number of server descriptions. Each server description has multiple client configurations, as shown in the following figure, which also indicates some of the information stored in these configuration items:
This architecture intended to simplify configuration, because it enables you to define multiple client configurations that use the same authorization server without needing to repeat the details of the authorization server.
You can create these items via the Management Portal, as described in the chapter “Using an InterSystems IRIS Web Application as an OAuth 2.0 Client. ”Or you can create them programmatically, as described in the appendix “Creating Configuration Items Programmatically.”
Configuration Items on the Server
Within an InterSystems IRIS instance that is acting as an OAuth 2.0 authorization server, it is necessary to define a server configuration (which configures the authorization server) and a number of client descriptions. The following figure indicates some of the information stored in these configuration items.
A given InterSystems IRIS instance can have at most one server configuration and can have many client descriptions. One client description is necessary for each client application. A client description is also necessary for each resource server that uses any endpoints of the authorization server. If a resource server does not use any endpoints of the authorization server, there is no need to create a client description for it.
You can create these items via the Management Portal, as described in the chapter “Using InterSystems IRIS as an OAuth 2.0 Authorization Server.” Or you can create them programmatically, as described in the appendix “Creating Configuration Items Programmatically.”
Standards Supported in InterSystems IRIS
This section lists the standards that InterSystems IRIS supports for OAuth 2.0 and Open ID Connect:
The OAuth 2.0 Authorization Framework (RFC 6749) — See https://tools.ietf.org/html/rfc6749
The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750) — See https://tools.ietf.org/html/rfc6750
OAuth 2.0 Token Revocation (RFC 7009) — See https://tools.ietf.org/html/rfc7009
JSON Web Token (JWT) (RFC 7519) — See https://tools.ietf.org/html/rfc7519
OAuth 2.0 Token Introspection (RFC 7662) — See https://tools.ietf.org/html/rfc7662
OpenID Connect Core 1.0 — See http://openid.net/specs/openid-connect-core-1_0.html
OAuth 2.0 Form Post Response Mode — See http://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html
JSON Web Key (JWK) (RFC 7517) — See https://tools.ietf.org/html/rfc7517
OpenID Connect Discovery 1.0 — See https://openid.net/specs/openid-connect-discovery-1_0.html
OpenID Connect Dynamic Client Registration — See http://openid.net/specs/openid-connect-registration-1_0-19.html
JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC 7523) — See https://tools.ietf.org/html/rfc7523