Creating Configuration Items Programmatically

Creating a Server Description

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

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 InterSystems IRIS 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:

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

   For information on ServerCredentials, see Using Certificates for an OAuth 2.0 Authorization Server, in 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. The user that performs these steps must have the %Admin_OAuth2_Client permission. 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 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 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 Certificates and JWTs (JSON Web Tokens).

4. Save the instance using the OAuth2.Server.Configuration.Save() method. The Save() method should be used instead of the %Save() method because it provides additional functionality like creating a web application.

Note that InterSystems IRIS 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.