Creating Configuration Items Programmatically

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:

   • 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 the appendix “Certificates and JWTs (JSON Web Tokens).”

4. Save the instance.

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.

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.

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.