Using Caché as an OAuth 2.0 Authorization Server

Configuring the Authorization Server

In order to perform this task, you must be logged in as a user who has USE permission on the %Admin_Secure resource.

1. In the Management Portal, select System Administration > Security > OAuth 2.0 > Server Configuration.

2. On the General tab, specify the following details:

   • Description — Enter an optional description.

   • Issuer endpoint — Specify the endpoint URL of the authorization server. To specify this URL, enter values for the following options:

     • Host name — Specify the host name or IP address of the authorization server.

     • Port — Specify this if needed to accommodate any changes in the CSP Gateway configuration.

     • Prefix — Specify this if needed to accommodate any changes in the CSP Gateway configuration.

     The resulting issuer endpoint has the following form:

     https://hostname:port/prefix/oauth2
     

     

     If you omit Port, the colon is omitted. Similarly, if you omit Prefix, there is only one slash between hostname:port and oauth2.

   • Audience required — Specify whether the authorization server requires the aud parameter in authorization code and implicit requests. If this check box is clear, aud is not required.

   • Support user session — Specify whether the authorization server supports user sessions. A Caché authorization server can support user sessions (note that these are not CSP sessions). To do this, Caché uses a session maintenance class (Session maintenance class); a default is provided. See “Code Customization Options,” later in this chapter. If this check box is clear, sessions are not supported.

   • Return refresh token — Specify the conditions under which a refresh token is returned along with the access token. Select the option appropriate for your business case.

   • Supported grant types — Specify the grant types that this authorization server allows to be used to create an access token. Select at least one.

   • OpenID provider documentation — Specify URLs provided by the OpenID provider as follows:

     • Service Documentation URL — URL of a web page that provides human-readable information that developers might want or need to know when using the OpenID provider.

     • Policy URL — URL of a web page that describes the OpenID provider’s policy on how a relying party can use the data provided by the provider.

     • Terms of Service URL — URL of a web page that describes the OpenID provider’s terms of service.

   • SSL configuration — Select the SSL configuration you created for use by the authorization server (for example, sslconfig).

3. On the Scopes tab, specify the following details:

   • Table with Scope and Description columns — Specify all scopes supported by this authorization server.

   • Allow unsupported scope — Specify whether the authorization server ignores scope values that it does not support. If this check box is clear, the authorization server returns an error when a request contains an unsupported scope value; in this case the request is not processed. If this check box is selected, the authorization server ignores the scope and processes the request.

   • Default scope — Specify the default for access token scope if scope is not specified in the access token request or in the client configuration.

4. On the Intervals tab, specify the following details:

   • Access token interval — Specify the number of seconds after which an access token issued by this server will expire. The default is 3600 seconds.

   • Authorization code interval — Specify the number of seconds after which an authorization code issued by this server will expire. The default is 60 seconds.

   • Refresh token interval — Specify the number of seconds after which a refresh token issued by this server will expire. The default is 24 hours (86400 seconds).

   • Session termination interval — Specify the number of seconds after which a user session will be automatically terminated. The value 0 means the session will not be automatically terminated. The default is 24 hours (86400 seconds).

   • Client secret expiration interval — Specify the number of seconds after which a client secret issued by this server will expire. The default value (0) means that the client secrets do not expire.

5. For the JWT Settings tab, specify the following details:

   • Create JWT Settings from X509 credentials — Select this option if, for signing and encryption, you want to use the private key associated with a certificate; in this case, also see “Using Certificates for an OAuth 2.0 Authorization Server,” in the appendix “Certificates and JWTs (JSON Web Tokens).”

     Note:

     InterSystems expects that the option Create JWT Settings from X509 credentials will rarely be used, and that instead customers use the default behavior described next.

     If you leave this option clear, the system generates a pair of JWKSs (JSON web key sets). One JWKS is private and contains all the needed private keys (per algorithm) as well as the client secret for use as a symmetric key; this JWKS is never shared. The other JWKS contains the corresponding public keys and is publicly available. Caché also copies the public JWKS to the client, so that the client can encrypt and verify signatures of JWTs from the authorization server.

   • Signing algorithm — Select the algorithm to use when signing JWTs. Or leave this blank if JWTs are not to be signed.

   • Key management algorithm — Select the algorithm to use for key management when encrypting JWTs.

     Do this only if you select a content encryption algorithm.

   • Content encryption algorithm — Select the algorithm to use when encrypting JWTs. Or leave this blank if JWTs are not to be encrypted. If you select an algorithm, you must also select an algorithm for key management.

6. On the Customization tab, specify details as described in “Code Customization Options,” later in this chapter.

7. Select Save.

When you save this configuration, the system creates a web application (/oauth2) for use by the authorization server. Do not modify this web application.

How a Caché Authorization Server Processes Requests

This section describes what a Caché authorization server does when it receives an authorization code request or an implicit request for a token.

1. Calls the BeforeAuthenticate() method of the class specified via the Authenticate class option. The purpose of this method is to make any modifications to the request before user identification starts.

   In the default class, this method is a stub.

2. Next, if the grant type is authorization code or implicit grant, Caché does the following:

   1. Calls the DisplayLogin() of the class specified via the Authenticate class option. (But also see the appendix “Implementing DirectLogin().”)

      In the default class, DisplayLogin() displays a simple HTML login page.

   2. If the username is not null, calls the ValidateUser() method of the class specified via the Validate user class option. The purpose of this method is to validate the user and (by modifying the properties array) to prepare any claims to be returned by the token, Userinfo, and token introspection endpoints.

      In the default class, this method is only a sample and is very unlikely to be suitable for production use.

   3. If the user is validated, calls the DisplayPermissions() method of the class specified via the Authenticate class option. The purpose of this method is to display a page to the user that lists the requested permissions.

      In the default class, this method displays a simple HTML page with the permissions.

   Or if the grant type is password credentials, Caché just calls the ValidateUser() method of the class specified via the Validate user class option.

   Or if the grant type is client credentials, Caché just calls the ValidateClient() method of the class specified via the Validate user class option.

3. If the user accepts the permissions, calls the AfterAuthenticate() method of the class specified via the Authenticate class option. The purpose of this method is to perform any custom processing before generating an access token.

   In the default class, this method is a stub.

4. Calls the GenerateAccessToken() method of the class specified via the Generate token class option. The purpose of this method is to generate an access token to return to the user.

   In the default class (%OAuth2.Server.GenerateOpens in a new tab), this method generates an access token that is an opaque string. Caché also provides an alternative class (%OAuth2.Server.JWTOpens in a new tab), in which GenerateAccessToken() generates an access token that is a JWT.

Default Classes

This section describes the default classes in a Caché authorization server, as well as the class %OAuth2.Server.JWTOpens in a new tab, which is provided as another option for the Generate token class.

Optional Custom Processing Before Authentication

The information here applies to all grant types.

To perform custom processing before authenticating the user, implement the BeforeAuthenticate() method of the Authenticate class. This method has the following signature:

ClassMethod BeforeAuthenticate(scope As %ArrayOfDataTypes, 
                               properties As %OAuth2.Server.Properties) As %Status

Where:

• scope is an instance of %ArrayOfDataTypesOpens in a new tab that contains the scopes contained in the original client request. The array keys are the scope values and the array values are the corresponding display forms of those values.

• properties is an instance of %OAuth2.Server.PropertiesOpens in a new tab that contains properties and claims that are used by the authorization server. See “Details for the %OAuth2.Server.Properties Object.”

In your method, optionally modify either or both of these arguments, both of which are later passed to the methods used to identify the user. The method must return a %StatusOpens in a new tab.

Normally, there is no need to implement this method. However, one use case is to implement the launch and launch/patient scopes used by FHIR®, where the scope needs to be adjusted to include a specific patient.

Identifying the User

The information here applies only to the authorization code and implicit grant types.

To identify the user, implement the DisplayLogin() method of the Authenticate class. The DisplayLogin() method has the following signature:

ClassMethod DisplayLogin(authorizationCode As %String, 
                         scope As %ArrayOfDataTypes, 
                         properties As %OAuth2.Server.Properties, 
                         loginCount As %Integer = 1) As %Status

Where:

• authorizationCode

• scope is an instance of %ArrayOfDataTypesOpens in a new tab that contains the scopes contained in the original client request, possibly modified by the BeforeAuthenticate() method. The array keys are the scope values and the array values are the corresponding display forms of the scope values.

• properties is an instance of %OAuth2.Server.PropertiesOpens in a new tab that contains properties and claims received by the authorization server and modified by methods earlier in the processing. See “Details for the %OAuth2.Server.Properties Object.”

• loginCount is the integer count of which login attempt is taking place.

This method is responsible for writing the HTML to display the user login form. The login form must contain a Username field, a Password field, and an AuthorizationCode field (which should be hidden). The default DisplayLogin() method uses of the InsertHiddenField() method of %CSP.PageOpens in a new tab to add the AuthorizationCode hidden field.

Typically, the form also has buttons with the values Login and Cancel. These buttons should submit the form. If the user submits the form with the Login button, the method will accept the username and password. If the user submits the form with the Cancel button, the authorization process will terminate with an error return of access_denied.

In your implementation, you might choose to display permissions on the same page. In that case, your method would display the scopes and would use a button named Accept to submit the page.

The method must return a %StatusOpens in a new tab.

Validating the User and Specifying Claims

The information here applies to all grant types other than the client credentials grant type. (For that grant type, see “Validating the Client.”)

To validate the user and specify any claims to be returned by the token, Userinfo, and token introspection endpoints, define the ValidateUser() method of the Validate user class. This method has the following signature:

ClassMethod ValidateUser(username As %String, 
                         password As %String, 
                         scope As %ArrayOfDataTypes, 
                         properties As %OAuth2.Server.Properties, 
                         Output sc As %Status) As %Boolean

Where:

• username is the username provided by the user.

• password is the password provided by the user. Note that if the user has already logged in, Caché calls this method with password as an empty string. This means that your method should detect when password is an empty string and not attempt to check the password in that case.

• scope is an instance of %ArrayOfDataTypesOpens in a new tab that contains the scopes contained in the original client request, possibly modified by the BeforeAuthenticate() method. The array keys are the scope values and the array values are the corresponding display forms of the scope values.

• properties is an instance of %OAuth2.Server.PropertiesOpens in a new tab that contains properties and claims received by the authorization server and modified by methods earlier in the processing. See “Details for the %OAuth2.Server.Properties Object.”

• sc is the status code set by this method. Use this to communicate details of any errors.

Your method should do the following:

• Make sure that the password applies to the given username.

• Use the scope and properties arguments as needed for your business needs.

• Modify the properties object to specify any claim values, as needed, or to add new claims. For example:

  // Setup claims for profile and email OpenID Connect scopes.
  Do properties.SetClaimValue("sub",username)
  Do properties.SetClaimValue("preferred_username",username)
  Do properties.SetClaimValue("email",email)
  Do properties.SetClaimValue("email_verified",0,"boolean")
  Do properties.SetClaimValue("name",fullname)
  
  

  

• In the case of any errors, set the sc variable.

• Return 1 if the user is considered valid; return 0 in all other cases.

Note that after the return from ValidateUser(), the authorization server automatically sets the following values in the properties object, if these values are missing:

• In properties.ClaimValues:

  • iss — URL of authorization server

  • sub — client_id

  • exp — expiration time in seconds since December 31, 1840

• In properties.CustomProperties:

  • client_id — client_id of the requesting client

Displaying Permissions

The information here applies only to the authorization code and implicit grant types.

To display permissions after validating the user, implement the DisplayPermissions() method of the Authenticate class. This method has the following signature:

ClassMethod DisplayPermissions(authorizationCode As %String, 
                               scopeArray As %ArrayOfDataTypes, 
                               currentScopeArray As %ArrayOfDataTypes, 
                               properties As %OAuth2.Server.Properties) As %Status

Where:

• authorizationCode is the authorization code.

• scopeArray represents the newly requested scopes, for which the user has not yet granted permission. This argument is an instance of %ArrayOfDataTypesOpens in a new tab.

  The array keys are the scope values and the array values are the corresponding display forms of the scope values.

• currentScopeArray represents the scopes for which the user has previously granted permission. This argument is an instance of %ArrayOfDataTypesOpens in a new tab.

  The array keys are the scope values and the array values are the corresponding display forms of the scope values.

• properties is an instance of %OAuth2.Server.PropertiesOpens in a new tab that contains properties and claims received by the authorization server and modified by methods earlier in the processing. See “Details for the %OAuth2.Server.Properties Object.”

This form must have buttons with the values Accept and Cancel. These buttons should submit the form. If the user submits the form with the Accept button, the method should continue with authorization. If the user submits the form with the Cancel button, the authorization process should terminate.

Optional Custom Processing After Authentication

The information here applies to all grant types.

To perform custom processing after authentication, implement the AfterAuthenticate() method of the Authenticate class. This method has the following signature:

ClassMethod AfterAuthenticate(scope As %ArrayOfDataTypes, properties As %OAuth2.Server.Properties) As %Status

Where:

• scope is an instance of %ArrayOfDataTypesOpens in a new tab that contains the scopes as set by the authorization request and all processing before this method was called. The array keys are the scope values and the array values are the corresponding display forms of the scope values.

• properties is an instance of %OAuth2.Server.PropertiesOpens in a new tab that contains properties and claims as set by the authorization request and all processing before this method was called. See “Details for the %OAuth2.Server.Properties Object.”

In your method, optionally modify either or both of these arguments. In particular, you may want to may add properties to the authentication HTTP response; to do so add properties to properties.ResponseProperties.

Normally, there is no need to implement this method. However, one use case is to implement the launch and launch/patient scopes used by FHIR®, where it is necessary to adjust the scope to include a specific patient.

Generating the Access Token

The information here applies to all grant types.

To generate access tokens, implement the GenerateAccessToken() method of the Generate token class. This method has the following signature:

ClassMethod GenerateAccessToken(properties As %OAuth2.Server.Properties, Output sc As %Status) As %String

Where:

• properties is an instance of %OAuth2.Server.PropertiesOpens in a new tab that contains properties and claims received by the authorization server and modified by methods earlier in the processing. See “Details for the %OAuth2.Server.Properties Object.”

• sc, which is returned as output, is the status code set by this method. Set this variable to communicate details of any errors.

The method should return the access token. The access token may be based on the properties argument. In your method, you might also want to add claims to the JSON response object. To do so, set the ResponseProperties array property of the properties object.

Validating the Client

The information here applies only to the client credentials type.

To validate the client credentials and specify any claims to be returned by the token, Userinfo, and token introspection endpoints, define the ValidateClient() method of the Validate user class. This method has the following signature:

ClassMethod ValidateClient(clientId As %String, 
                           clientSecret As %String, 
                           scope As %ArrayOfDataTypes, 
                           Output properties As %OAuth2.Server.Properties, 
                           Output sc As %Status) As %Boolean

Where:

• clientId is the client ID.

• clientSecret is the client secret.

• scope is an instance of %ArrayOfDataTypesOpens in a new tab that contains the scopes contained in the original client request, possibly modified by the BeforeAuthenticate() method. The array keys are the scope values and the array values are the corresponding display forms of the scope values.

• properties is an instance of %OAuth2.Server.PropertiesOpens in a new tab that contains properties and claims received by the authorization server and modified by methods earlier in the processing. See “Details for the %OAuth2.Server.Properties Object.”

• sc is the status code set by this method. Use this to communicate details of any errors.

Your method should do the following:

• Make sure that the client secret applies to the given client ID.

• Use the scope and properties arguments as needed for your business needs.

• Modify the properties object to specify any claim values, as needed. For example:

  // Setup claims for profile and email OpenID Connect scopes.
  Do properties.SetClaimValue("sub",username)
  Do properties.SetClaimValue("preferred_username",username)
  Do properties.SetClaimValue("email",email)
  Do properties.SetClaimValue("email_verified",0,"boolean")
  Do properties.SetClaimValue("name",fullname)
  
  

  

• In the case of any errors, set the sc variable.

• Return 1 if the user is considered valid; return 0 in all other cases.

Note that after the return from ValidateClient(), the authorization server automatically sets the following values in the properties object, if these values are missing:

• In properties.ClaimValues:

  • iss — URL of authorization server

  • sub — client_id

  • exp — expiration time in seconds since December 31, 1840

• In properties.CustomProperties:

  • client_id — client_id of the requesting client

Basic Properties

The %OAuth2.Server.PropertiesOpens in a new tab class has the following basic properties, used to convey information for any internal processing of your custom code:

RequestProperties

Property RequestProperties as array of %String (MAXLEN=16384);

Contains the query parameters from the authorization request.

Because this property is an array, use the usual array interface to work with it. (The same comment applies to the other properties of this class.) For example, to get the value of a query parameter, use RequestProperties.GetAt(parmname), where parmname is the name of the query parameter.

ResponseProperties

Property ResponseProperties as array of %String (MAXLEN=1024);

Contains any properties to be added to the JSON response object to a token request. Set this property as needed.

CustomProperties

Property CustomProperties as array of %String (MAXLEN=1024);

Contains any custom properties to be used to communicate between various pieces of customization code. See the section “Updating properties.CustomProperties.”

ServerProperties

Property ServerProperties as array of %String (MAXLEN=1024);

Contains any properties that the authorization server chooses to share with the customization code. The logo_uri, client_uri, policy_uri and tos_uri client properties are shared in this way for use by the Authentication Class.

Properties Related to Claims

The %OAuth2.Server.PropertiesOpens in a new tab class contains the IntrospectionClaims, IDTokenClaims, UserinfoClaims, and JWTClaims properties, which carry information about required claims, specifically custom claims.

The class also contains the ClaimValues property, which carries the actual claim values. Your customization code should set the values of the claims (typically in the ValidateUser class).

The following list describes these properties:

IntrospectionClaims

Property IntrospectionClaims as array of %OAuth2.Server.Claim;

Specifies the claims to be returned by the Introspection endpoint (beyond the base required claims). The authorization server will return the scope, client_id, username, token_type, exp, iat, nbf, sub, aud, iss, and jti claims even if they are not in this property.

In most cases, the value of this property can be an empty string; this property is included to support the claims request parameter (see OpenID Connect CoreOpens in a new tab section 5.5 for details).

Formally, this property is an array in which the array key is the claim name (which matches the name in the ClaimValues property) and the array value is an instance of %OAuth2.Server.ClaimOpens in a new tab. The %OAuth2.Server.ClaimOpens in a new tab class has the following properties:

• Essential

  property Essential as %Boolean [ InitialExpression = 0 ];
  

  

  Specifies whether the claim is essential or voluntary. The value 1 means essential and the value 0 means voluntary.

• Values

  property Values as list of %String(MAXLEN=2048);
  

  

  Specifies the list of permissible values for this claim.

The value of the claims will usually be set by the ValidateUser class.

IDTokenClaims

Property IDTokenClaims as array of %OAuth2.Server.Claim;

Specifies the claims that the authorization server requires in the IDToken (beyond the base set of required claims). The authorization server requires the iss, sub, exp, aud, and azp claims even if these claims are not in this property.

This property is an array of objects; for details, see the entry for the IntrospectionClaims property.

In most cases, the value of this property can be an empty string; this property is included to support the claims request parameter (see OpenID Connect CoreOpens in a new tab section 5.5 for details).

UserinfoClaims

Property UserinfoClaims as array of %OAuth2.Server.Claim;

Specifies the claims to be returned by the Userinfo endpoint (beyond the base required claims). The authorization server will return the sub claim even if that claim is not in this property.

In most cases, the value of this property can be an empty string; this property is provided to support section 5.5 of OpenID Connect Core.

This property is an array of objects; for details, see the entry for the IntrospectionClaims property.

The claims are defined based on the scope and request claims parameter. The value to be returned for the claim will have the same key in the ClaimValues property. The value of the claims will usually be set by the ValidateUser class.

JWTClaims

Property JWTClaims as array of %OAuth2.Server.Claim;

Specifies the claims that are needed for the JWT access token that is returned by the default JWT-based access token class (%OAuth2.Server.JWTOpens in a new tab) beyond the base set of required claims. The authorization server will return the iss, sub, exp, aud, and jti claims even if they are not in this property.

This property is an array of objects; for details, see the entry for the IntrospectionClaims property.

The claims are defined by the customization code. The value of the claims will usually be set by the ValidateUser class.

ClaimValues

property ClaimValues as array of %String(MAXLEN=1024);

Specifies the actual claim values and their types. To work with this property, use the methods in the next section.

If you need to work with this property directly, note that this property is an array in which:

• The array key is the claim name.

• The array value has the form $LISTBUILD(type,value), where type holds the type of the value, and value holds the actual value. The type can be "string", "boolean", "number", or "object". If type is "object", then value is a JSON object serialized as a string.

  Note that value can be a $LIST structure. In this case, when the claim value is serialized, it is serialized as a JSON array, in which each array item has the given type.

Methods for Working with Claims

The %OAuth2.Server.PropertiesOpens in a new tab class also provides instance methods that you can use to work with that simplify working with the ClaimValues property.

SetClaimValue()

Method SetClaimValue(name As %String, value As %String, type As %String = "string")

Updates the ClaimValues property by setting the value of the claim named by the name argument. The type argument indicates the type of the claim: "string" (the default) , "boolean", "number", or "object". If type is "object", then value must be a JSON object serialized as a string.

Note that value can be a $LIST structure. In this case, when the claim value is serialized, it is serialized as a JSON array, in which each array item has the given type.

RemoveClaimValue()

Method RemoveClaimValue(name As %String)

Updates the ClaimValues property by removing the claim named by the name argument.

GetClaimValue()

Method GetClaimValue(name As %String, output type) As %String

Examines the ClaimValues property and returns the value of the claim named by the name argument. The type argument, which is returned as output, indicates the type of the claim; see SetClaimValue().

NextClaimValue()

Method NextClaimValue(name As %String) As %String

Returns the name of the next claim (in the ClaimValues property) after the given claim.

API for Key Rotation on the Authorization Server

To rotate keys programmatically on the authorization server, call the RotateKeys() method of OAuth2.Server.ConfigurationOpens in a new tab.

To obtain a new client JWKS, call the UpdateJWKS() method of OAuth2.Server.ClientOpens in a new tab.

For details on these methods, see the class reference.