OAuth Resource Server Demo

InterSystems IRIS Demo: Creating an OAuth Resource Server

The following demo shows how to configure InterSystems IRIS as a simple OAuth resource server and how to protect a web application with it. Broadly, this involves:

1. Creating an SSL/TLS configuration.

2. Creating a server definition for your authorization server, like Keycloak.

3. Creating the resource server in InterSystems IRIS.

4. Associating a resource server with the web application.

Creating an SSL/TLS Configuration

This example creates a client SSL/TLS configuration (Security.SSLConfigsOpens in a new tab) for securing traffic between the InterSystems IRIS resource server (client) and your authorization server (server). It assumes the following:

• Your authorization server has a server certificate.

• You have a CA certificate(s) that issued the server's certificate. This example uses a single certificate /certs/ca.crt.

For more details about creating SSL/TLS configurations in general and determining the required certificates, see Create SSL/TLS Configurations.

1. Go to Security Administration > Security > SSL/TLS Configurations > Create New Configuration.

2. Set the following fields:

   • Configuration Name — tls-oauth

   • Enabled — Selected

   • Type — Client

   • Server certificate verification — Require, whether the client (the resource server) should verify the certificate of the server (the authorization server).

   • File containing trusted Certificate Authority certificate(s) — /certs/ca.crt, the CA certificate(s) that the client trusts to verify the identity of the server.

Creating a Server Definition

A server definition (OAuth2.ServerDefinitionOpens in a new tab) is a logical grouping of connection information used by the resource server to contact the authorization server and to register OAuth clients.

This example creates a server definition for a Keycloak authorization server hosted on localhost:8443:

1. Go to System Administration > Security > OAuth 2.0 > Client > Create Server Description.

2. Set the following fields:

   • Issuer endpoint — https://localhost:8443/realms/iris, the issuer (iss) endpoint. The exact URL will vary between authorization servers; the one used in this demo is Keycloak.

   • SSL/TLS Configuration — tls-oauth, the name of the SSL/TLS configuration that your resource server should use to verify the authorization server.

   • Registration access token — The access token clients should use when they first authenticate and register with the authorization server. This token is generated and provided by your authorization server when you configure it; copy and paste that value into this field.

   • Select Save.

3. Select Discover and Save. InterSystems IRIS contacts the authorization server and fills out the rest of the fields, including information for other endpoints.

Creating a Resource Server

When a client wants to access some resource protected by a resource server (OAuth2.ResourceServerOpens in a new tab), the client authenticates with a mutually trusted authorization server and presents the resource server with a token. After verifying with the authorization server that the token is valid, the resource server uses the contents of the token to determine the InterSystems IRIS user and the roles they should have.

To create a resource server:

1. Go to System Administration > Security > OAuth 2.0 > Resource Server > Create Resource Server.

2. Set the following fields. For more details on these fields, see Server-type Configuration:

   • Name — my-resource-server, the name of the resource server.

   • Enabled — Selected.

   • Server Definition — https://localhost:8443/realms/iris, the server definition (identified by its issuer endpoint) for the authorization server.

   • Audiences — iris-resource-server, the required aud claim. This indicates that this resource server will only validate a user if their token's aud field contains iris-resource-server.

   • Access Token Validation — JWT, how the resource server should validate the token. This setting should align with however you configured your authorization server; this example authorization server issues JSON Web Tokens (JWT). If you configure it to issue opaque tokens, select Call Introspection.

   • Authenticator — The class used by the resource server to interpret and use the claims in the token to assign the client a username and roles. This example uses the default %OAuth2.ResourceServer.SimpleAuthenticator, which indicates that the InterSystems IRIS username is specified by the subject (sub) claim and the roles are specified by the scope (scope) claim.

     The optional prefix lets you filter for values that have the specified prefix. For example, if scope consists of iris:myrole email and your prefix is iris:, the resource server resolves these claims to the InterSystems IRIS role myrole.

3. Select Save.

Creating a Resource Server Mapping

A resource server mapping (OAuth2.ResourceServer.MappingOpens in a new tab) associates a resource server with the resource it's supposed to protect.

1. Go to System Administration > Security > Authentication/Web Session Options and select Allow OAuth2 authentication. This enables OAuth as an authentication method.

2. Go to System Administration > Security > Applications > Web Applications and select your web application.

3. In the web application's Security Settings, select OAuth2.

4. Go to System Administration > Security > OAuth 2.0 > Resource Server.

5. In the Mapping tab, select New, filling out the following fields:

   • Service — %Service_WebGateway, the service type for web applications.

   • Key — A pattern (or exact string) that matches the name of the web application. To match multiple names, you can use an asterisk (*) as a wildcard.

   • Resource Server — my-resource-server, the resource server that should protect the web application.

6. Select Save.