Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

Creating Configuration Items Programmatically

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:

  1. Create a server description.

  2. Create an associated client configuration.

Creating a Server Description

A server description is an instance of OAuth2.ServerDefinitionOpens in a new tab. To create a server definition:

  1. Switch to the %SYS namespace.

  2. If the authorization server supports discovery, call the Discover() method of %SYS.OAuth2.RegistrationOpens in a new tab. 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.ServerDefinitionOpens in a new tab,

  3. Then save the returned instance of OAuth2.ServerDefinitionOpens in a new tab.

Or, if the authorization server does not support discovery:

  1. Switch to the %SYS namespace.

  2. Create an instance of OAuth2.ServerDefinitionOpens in a new tab.

  3. 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:

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

  4. Save the instance.

Creating a Client Configuration

A client configuration is an instance of OAuth2.ClientOpens in a new tab. To create a client configuration:

  1. Switch to the %SYS namespace.

  2. Create an instance of OAuth2.ClientOpens in a new tab.

  3. 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.htmlOpens in a new tab.

    • 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.EndpointOpens in a new tab is a serial class with the properties UseSSL, Host, Port, and Prefix.

    • SSLConfiguration

    • ServerDefinition, which must be an instance of OAuth2.ServerDefinitionOpens in a new tab 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).”

  4. If the authorization server supports dynamic client registration, call the RegisterClient() method of %SYS.OAuth2.RegistrationOpens in a new tab. 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.ClientOpens in a new tab.

Creating the Server Configuration Items Programmatically

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

  1. 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.

  2. Create the associated client descriptions.

Creating the Authorization Server Configuration

An authorization server configuration is an instance of OAuth2.Server.ConfigurationOpens in a new tab. To create an authorization server configuration:

  1. Switch to the %SYS namespace.

  2. Create an instance of OAuth2.Server.ConfigurationOpens in a new tab

  3. 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.EndpointOpens in a new tab. The class OAuth2.EndpointOpens in a new tab 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.htmlOpens in a new tab.

    • 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.JWTOpens in a new tab.

    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).”

  4. 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.ClientOpens in a new tab. To create a client description:

  1. Switch to the %SYS namespace.

  2. Create an instance of OAuth2.Server.ClientOpens in a new tab.

  3. 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.htmlOpens in a new tab.

    • 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.

  4. Save the instance.

    The system generates values for the ClientId and ClientSecret properties.

Next sectionImplementing DirectLogin()
Previous sectionUsing Caché as an OAuth 2.0 Authorization Server
FeedbackOpens in a new tab