Creating Configuration Items Programmatically

Using OAuth 2.0 and OpenID Connect with Caché

InterSystems: The power behind what matters

Caché Development Guides > Using OAuth 2.0 and OpenID Connect with Caché > Creating Configuration Items Programmatically

Class Reference

Search:

The earlier chapters of this book describe how to use the Management Portal to configure OAuth 2.0 clients, resource servers, and authorization servers. InterSystems also supports creating these configuration items programmatically. The following subsections provide the details for clients (including resource servers) and for the authorization server.

Creating the Client Configuration Items Programmatically

To programmatically create the configuration items for an OAuth 2.0 client or an OAuth 2.0 resource server:

Create a server description.
Create an associated client configuration.

Creating a Server Description

A server description is an instance of OAuth2.ServerDefinition. To create a server definition:

Switch to the %SYS namespace.
If the authorization server supports discovery, call the Discover() method of %SYS.OAuth2.Registration. This method is as follows:
```
ClassMethod Discover(issuerEndpoint As %String, 
                     sslConfiguration As %String, 
                     Output server As OAuth2.ServerDefinition) As %Status
```
Where:
- issuerEndpoint specifies the endpoint URL to be used to identify the authorization server.
- sslConfiguration specifies the alias of the Caché SSL/TLS configuration to use calling the Discover() method.
- server, which is returned as output, is an instance of OAuth2.ServerDefinition,
Then save the returned instance of OAuth2.ServerDefinition.

Or, if the authorization server does not support discovery:

Switch to the %SYS namespace.
Create an instance of OAuth2.ServerDefinition.
Set its properties. In most cases, the names of the properties match the labels shown in the Management Portal (apart from spaces and capitalization). For reference, see “Manually Creating a Server Description.” The properties are as follows:
- IssuerEndpoint
- SSLConfiguration
- InitialAccessToken, which corresponds to the Registration access token field.
- Metadata, which is an instance of OAuth2.Server.Metadata, and which includes many properties. See “OpenID Provider Metadata” in https://openid.net/specs/openid-connect-discovery-1_0.html.
For information on ServerCredentials, see “Using Certificates for an OAuth 2.0 Authorization Server,” in the appendix “Certificates and JWTs (JSON Web Tokens).”
Save the instance.

Creating a Client Configuration

A client configuration is an instance of OAuth2.Client. To create a client configuration:

Switch to the %SYS namespace.
Create an instance of OAuth2.Client.
Set its properties. In most cases, the names of the properties match the labels shown in the Management Portal (apart from spaces and capitalization). For reference, see “Configuring and Dynamically Registering a Client.” The properties are as follows:
- ApplicationName
- ClientId, which you do not need to set manually if you will register the client dynamically.
- ClientSecret, which you do not need to set manually if you will register the client dynamically.
- DefaultScope
- Description
- Enabled
- JWTInterval
- Metadata, which is an instance of OAuth2.Client.Metadata, and which includes many properties. For information, see “Client Metadata” in http://openid.net/specs/openid-connect-registration-1_0-19.html.
- RedirectionEndpoint, which corresponds to the option The client URL to be specified to the authorization server to receive responses. This property is of type %OAuth2.Endpoint. The class OAuth2.Endpoint is a serial class with the properties UseSSL, Host, Port, and Prefix.
- SSLConfiguration
- ServerDefinition, which must be an instance of OAuth2.ServerDefinition that you created previously.
For information on ClientCredentials, see “Using Certificates for an OAuth 2.0 Client,” in the appendix “Certificates and JWTs (JSON Web Tokens).”
If the authorization server supports dynamic client registration, call the RegisterClient() method of %SYS.OAuth2.Registration. This method is as follows:
```
ClassMethod RegisterClient(applicationName As %String) As %Status
```
Where applicationName is the name of the client application.

This method registers the client, retrieves client metadata (including the client ID and client secret), and then updates the instance of OAuth2.Client.

Creating the Server Configuration Items Programmatically

To programmatically create the configuration items for an OAuth 2.0 authorization server:

Create an authorization server configuration.

Note that you cannot define more than one authorization server configuration on any given Caché instance. Also, to create this configuration, you must be logged in as a user who has USE permission on the %Admin_Secure resource.
Create the associated client descriptions.

Creating the Authorization Server Configuration

An authorization server configuration is an instance of OAuth2.Server.Configuration. To create an authorization server configuration:

Switch to the %SYS namespace.
Create an instance of OAuth2.Server.Configuration
Set its properties. In most cases, the names of the properties match the labels shown in the Management Portal (apart from spaces and capitalization). For reference, see “Configuring the Authorization Server.” The properties are as follows:
- AccessTokenInterval
- AllowUnsupportedScope
- AudRequired, which corresponds to the Audience required option
- AuthenticateClass
- AuthorizationCodeInterval
- ClientSecretInterval
- CustomizationNamespace
- CustomizationRoles
- DefaultScope
- Description
- EncryptionAlgorithm
- GenerateTokenClass
- IssuerEndpoint, which corresponds to the Issuer endpoint option, is of type OAuth2.Endpoint. The class OAuth2.Endpoint is a serial class with the properties UseSSL, Host, Port, and Prefix.
- JWKSFromCredentials
- KeyAlgorithm
- Metadata, which is an instance of OAuth2.Server.Metadata, and which includes many properties. See “OpenID Provider Metadata” in https://openid.net/specs/openid-connect-discovery-1_0.html.
- RefreshTokenInterval
- ReturnRefreshToken
- SSLConfiguration
- SessionClass
- SessionInterval, which corresponds to the Session termination interval option
- SigningAlgorithm
- SupportSession, which corresponds to the Support user session option
- SupportedScopes, which corresponds to the table with Scope and Description columns. This property is an array of strings, and thus uses the usual array interface: SetAt(), GetAt(), and so on.
- ValidateUserClass
For allowed values for algorithms for signing, key management, and encryption, the class reference for %OAuth2.JWT.

For information on ServerCredentials and ServerPassword, see “Using Certificates for an OAuth 2.0 Authorization Server,” in the appendix “Certificates and JWTs (JSON Web Tokens).”
Save the instance.

Note that Caché does not support having more than one instance of this class.

Also note that in order to save this instance, you must be logged in as a user who has USE permission on the %Admin_Secure resource.

Creating a Client Description

A client description is an instance of OAuth2.Server.Client. To create a client description:

Switch to the %SYS namespace.
Create an instance of OAuth2.Server.Client.
Set its properties. In most cases, the names of the properties match the labels shown in the Management Portal (apart from spaces and capitalization). For reference, see “Creating a Client Description.” The properties are as follows:
- ClientCredentials
- ClientType
- DefaultScope
- Description
- LaunchURL
- Metadata, which is an instance of OAuth2.Client.Metadata, and which includes many properties. For information, see “Client Metadata” in http://openid.net/specs/openid-connect-registration-1_0-19.html.
- Name
- RedirectURL, which corresponds to the Redirect URLs option. This property is an array of strings, and thus uses the usual array interface: SetAt(), GetAt(), and so on.
Save the instance.

The system generates values for the ClientId and ClientSecret properties.