Using a Caché Web Application as an OAuth 2.0 Client

Creating a Server Description (Using Discovery)

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

   This displays a page that lists any server descriptions that are available on this instance. In any given row, the Issuer endpoint column indicates the issuer endpoint for the server description. The Client Count column indicates the number of client configurations associated with the given server description. In the last column, the Client Configurations link enables you to create, view, edit, and delete the associated client configurations.

2. Select Create Server Configuration.

   The Management Portal then displays a new page where you can enter details for the server description.

3. Specify the following details:

   • Issuer endpoint (required) — Enter the endpoint URL to be used to identify the authorization server.

   • SSL/TLS configuration (required) — Select the SSL/TLS configuration to use when making the dynamic client registration request.

   • Registration access token — Optionally enter the initial registration access token to use as a bearer token to authorize the dynamic client registration request.

4. Select Discover and Save.

   Caché then communicates with the given authorization server, retrieves information needed in the server description, and then saves that information.

   The Management Portal then redisplays the list of server descriptions.

Configuring and Dynamically Registering a Client

This section describes how to create a client configuration and dynamically register the client.

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

   The Management Portal displays the list of server descriptions.

2. Click the Client Configurations link in the row for the server description with which this client configuration should be associated.

   The Management Portal then displays the list of client configurations associated with the server description. This list is initially empty.

3. Click Create Client Configuration.

   The Management Portal then displays a new page where you can enter details.

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

   • Application name — Specify a short name for the application.

   • Client name — Specify the client name to display to the end user.

   • Description — Specify an optional description of the application.

   • Enabled — Optionally clear this check box if you want to prevent this application from being used.

   • Client Type — Select one of the following:

     • Confidential — Specifies that the client is a confidential client, per RFC 6749Opens in a new tab.

       This chapter primarily discusses the scenario in which the client uses the authorization code grant type. For this scenario, specify Client Type as Confidential. For other grant types, see “Variations,” later in this chapter.

     • Public — Specifies that the client is a public client, per RFC 6749Opens in a new tab.

     • Resource Server — Specifies that the client is a resource server which is not also a client.

   • SSL/TLS configuration — Select the SSL configuration you created for use by the client (for example, sslconfig).

   • The client URL to be specified to the authorization server to receive responses — Specify the URL of the internal destination required for a Caché OAuth 2.0 client. At this destination, the access token is saved and then the browser is further redirected back to the client application.

     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 URL has the following form:

     https://hostname:port/prefix/csp/sys/oauth2/OAuth2.Response.cls
     

     

     If you omit Port, the colon is omitted. Similarly, if you omit Prefix, there is only one slash between hostname:port and csp. (Also if the Use TLS/SSL option is cleared, the URL starts with http rather than https.)

   • Use TLS/SSL — Select this option, unless there is a good reason not to use TLS/SSL when opening the redirect page.

   • Required grant types — Specify the OAuth 2.0 grant types that the client will restrict itself to using.

   • Authentication type — Select the type of authentication (as specified in RFC 6749Opens in a new tab or OpenID Connect Core section 9Opens in a new tab) to be used for HTTP requests to the authorization server. Select one of the following: none, basic, form encoded body, client secret JWT, or private key JWT.

   • Authentication signing algorithm — Select the algorithm that must be used for signing the JWTs used to authenticate this client at the token endpoint (if the authentication type is client secret JWT or private key JWT). If you do not select an option, any algorithm supported by the OpenID provider and the relying party may be used.

5. On the Client Information tab, specify the following details:

   • Logo URL — URL of the logo for the client application.

   • Client home page URL — URL of the home page for the client application.

   • Policy URL — URL of the policy document for the client application.

   • Terms of service URL — URL of the terms of service document for the client application.

   • Default scope — Specify the default scope, as a blank separated list, for access token requests. This default should be consistent with the scopes permitted by the authorization server.

   • Contact emails — Comma-separated list of email addresses suitable for use in contacting those responsible for the client application.

   • Default max age — Specify the default maximum authentication age, in seconds. If you specify this option, the end user must be actively re-authenticated when the maximum authentication age is reached. The max_age request parameter overrides this default value. If you omit this option, there is no default maximum authentication age.

6. On 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 Client,” 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. The dynamic registration process also copies the public JWKS to the authorization server, so that the authorization server can encrypt and verify signatures of JWTs from this client.

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

   • Encryption algorithm — Select the encryption algorithm used to create encrypted JWTs. Or leave this blank if JWTs are not to be encrypted. If you select a value, you must also specify Key algorithm.

   • Key algorithm — Select the key management algorithm used to create encrypted JWTs. Or leave this blank if JWTs are not to be encrypted.

7. If the authorization server supports dynamic registration, double-check all the data you have entered and then press Dynamic Registration and Save. Caché then contacts the authorization server, registers the client, and obtains the client ID and client secret.

   If the authorization server does not support dynamic registration, see the following subsection.

Method Details

This subsection provides the details on the methods described in the previous subsection.

IsAuthorized()

Location: This method is in the class %SYS.OAuth2.AccessTokenOpens in a new tab.

ClassMethod IsAuthorized(applicationName As %String, 
                         sessionId As %String, 
                         scope As %String = "", 
                         Output accessToken As %String, 
                         Output IDToken As %String, 
                         Output responseProperties, 
                         Output error As %OAuth2.Error) As %Boolean

This method returns 1 if there is a locally stored access token for this client and this session, and if that access token authorizes all the scopes given by the scope argument. (Note that this method looks for the access token in the CACHESYS database, and that tokens are removed automatically after they have expired.)

Otherwise the method returns 0.

The arguments are as follows:

• applicationName is the name of the client application.

• sessionId specifies the session ID. Specify this only if you want to override the default session (%session.SessionId).

• scope is a space-delimited list of scopes, for example: "openid profile scope1 scope2"

  Note that openid and profile are special scopes defined by OpenID Connect CoreOpens in a new tab.

• accessToken, which is returned as output, is the access token, if any.

• IDToken, which is returned as output, is the ID token, if any. (This applies only if you are using OpenId ConnectOpens in a new tab, specifically if the request used the scope openid.) Note that an ID token is a JWT.

• responseProperties, which is returned as output, is a multidimensional array that contains any parameters of the response. This array has the following structure:

  Array node	Array value
  responseProperties(parametername) where parametername is the name of a parameter (such as token_type or expires_in)	Value of the given parameter.

• error, which is returned as output, is either (when there is no error) an empty string or (in the case of error) an instance of %OAuth2.ErrorOpens in a new tab containing error information.

  %OAuth2.ErrorOpens in a new tab has three string properties: Error, ErrorDescription, and ErrorUri.

GetAuthorizationCodeEndpoint()

Location: This method is in the class %SYS.OAuth2.AuthorizationOpens in a new tab.

ClassMethod GetAuthorizationCodeEndpoint(applicationName As %String, 
                                         scope As %String, 
                                         redirectURL As %String, 
                                         ByRef properties As %String, 
                                         Output isAuthorized As %Boolean, 
                                         Output sc As %Status, 
                                         responseMode As %String
                                         sessionId As %String = "") As %String

This method returns the URL, with all needed query parameters, of the local, internal page that Caché uses to request the authorization code. (Note that this page is never visible to users.)

The arguments are as follows:

• applicationName is the name of the client application.

• scope is a space-delimited list of scopes for which access is requested, for example: "scope1 scope2 scope3"

  The default is determined by the client configuration for the given applicationName.

• redirectURL is the full URL of the client’s redirect page, the page to which the authorization server should redirect the browser after returning the access token to the client.

• properties, which is passed by reference, is a multidimensional array that contains any parameters to be added to the request. This array must have the following structure:

  Array node

  Array value

  properties(parametername) where parametername is the name of a parameter

  Value of the given parameter. The value can be a scalar value, an instance of a dynamic object, or the UTF-8 encoded serialized form of a dynamic object. Use a dynamic object if you want the request to include a parameter whose value is a JSON object; a scenario is the claims parameter that is defined by OpenID Connect. For details on dynamic objects, see Using JSON in Caché. To use the request or request_uri parameter, see the section “Passing Request Objects as JWTs.”

• isAuthorized, which is returned as output, equals 1 if there is a locally stored access token for this client and this session (scope is not checked). This parameter equals 0 otherwise. There is no need to check this output argument, because we have just called the IsAuthorized() method.

• sc, which is returned as output, contains the status code set by this method.

• responseMode specifies the mode of the response from the authorization server. This can be "query" (the default), "fragment" or "form_post". The default is almost always appropriate.

• sessionId specifies the session ID. Specify this only if you want to override the default session (%session.SessionId).

Also see “Variation: Performing the Redirect within OnPreHTTP.”

Creating and Using a ZAUTHENTICATE Routine for an OAuth 2.0 Client

To create and use a ZAUTHENTICATE routine for a Caché web client that is used as an OAuth 2.0 client, do all of the following:

• In your client code, after you call the IsAuthorized() method of the %SYS.OAuth2.AccessTokenOpens in a new tab class and successfully obtain an access token, call the Login() method of the %session variable. For the username, specify the OAuth 2.0 application name; for the password, specify the CSP session ID.

• Create the ZAUTHENTICATE routine. This routine must perform basic setup for a user account, such as specifying roles and other user properties.

  To create this routine, copy OAUTH2.ZAUTHENTICATE.mac from the SAMPLES namespace to the %SYS namespace and rename it to ZAUTHENTICATE.mac. Then modify this routine as needed. See “Notes about the OAUTH2.ZAUTHENTICATE.mac Sample,” later in this section. For more general information, see “Creating Delegated (User-Defined) Authentication Code” in the chapter “Using Delegated Authentication” in the Caché Security Administration Guide.

• Enable delegated authentication for the Caché instance on the Authentication Options page.

  For information on this step and the next step, see the chapter “Using Delegated Authentication” in Caché Security Administration Guide.

• Enable delegated authentication for the relevant web application.

Creating and Using a Custom Login Page for an OAuth 2.0 Client

To create and use a custom login page for a Caché web client that is used as an OAuth 2.0 client, do all of the following:

• Create a subclass of %OAuth2.LoginOpens in a new tab. In your subclass:

  • Specify the application name, scope list, and (optionally) response mode. You can specify these items in either or both of the following ways:

    • By specifying parameters of your subclass of %OAuth2.LoginOpens in a new tab.

    • By overriding the DefineParameters() class method. In contrast to specifying parameters, this technique enables you to set these values at runtime.

    The parameters are as follows:

    • APPLICATION — This must be the application name for the application being logged into.

    • SCOPE — This specifies the scope list to be used for the access token request. This must be a blank-separated list of strings.

    • RESPONSEMODE — This specifies the mode of the response. The allowed values are "query" (the default), "fragment" or "form_post".

    The DefineParameters() class method has the following signature:

    ClassMethod DefineParameters(Output application As %String, Output scope As %String, Output responseMode As %String)
    

    

    This method returns the application name, scope list, and response mode as output arguments. The default implementation of this method returns the values of the APPLICATION, SCOPE, and RESPONSEMODE class parameters.

  • In your subclass of %OAuth2.LoginOpens in a new tab, also specify the properties list for the GetAccessTokenAuthorizationCode() call. To do so, override the DefineProperties() class method. This method has the following signature:

    ClassMethod DefineProperties(Output properties As %String)
    

    

    This method returns (as output) the properties array, which is a local array specifying additional properties to be included in a token request. The properties array has the following form:

    Node	Value
    properties(name), where name is the name of a parameter.	Value of the given parameter.

    To add a request parameter that is a JSON object, create a properties element which is an instance of %DynamicObjectOpens in a new tab. Or create a string that is the UTF-8 encoded serialized object.

    To add the request or request_uri request parameters, use the %SYS.OAuth2.RequestOpens in a new tab class to create the JWT. Then, as appropriate, set properties("request") equal to the JWT or set properties("request_uri") equal to the URL of the JWT.

• Configure the relevant web application to use the custom login page.

• Create and use a ZAUTHENTICATE routine as described in the previous section, except for the first bullet item. (In this scenario, there is no need for the client code to call %session.Login().)

Notes about the OAUTH2.ZAUTHENTICATE.mac Sample

The OAUTH2.ZAUTHENTICATE.mac sample supports both scenarios described in the previous subsections. In this sample, the GetCredentials() subroutine looks like this:

GetCredentials(ServiceName,Namespace,Username,Password,Credentials) Public {
    If ServiceName="%Service_CSP" {
        // Supply user name and password for authentication via a subclass of %OAuth2.Login
        Set Username="OAuth2"
        Set Password=$c(1,2,3)
    }
    Quit $$$OK
}

This subroutine is called if no username and password are provided (which is the case when the custom login page is being used). For the service %Service_CSP, this sample sets the username and password to specific values that are also used in the ZAUTHENTICATE() subroutine (which is called in later processing).

The ZAUTHENTICATE() subroutine includes the following:

If Username="OAuth2",Password=$c(1,2,3) {
    // Authentication is via a subclass of %OAuth2.Login that sets the query parameter CSPOAUTH2
    // with a hash value that allows GetCurrentApplication to determine the application -- 
    // username/password is supplied by GetCredentials.
    Set sc=##class(OAuth2.Response).GetCurrentApplication(.applicationName)
    Set sessionId=%session.SessionId
} Else {
    // If authentication is based on %session.Login, then application and session id are passed in.
    Set applicationName=Username
    Set sessionId=Password
}

A later step calls the isAuthorized() method like this:

Set isAuthorized=##class(%SYS.OAuth2.AccessToken).IsAuthorized(applicationName,sessionId,,.accessToken,,,.error)

If isAuthorized() returns 1, then later code calls the introspection endpoint and uses the information obtained there to define a user:

Set sc=##class(%SYS.OAuth2.AccessToken).GetIntrospection(applicationName,accessToken,.jsonObject)
...
Set Username="OAuth2"_jsonObject.sub
Set Properties("FullName")="OAuth account "_Username
Set Properties("Username")=Username
Set Properties("Password")=""    // we don't really care about oauth2 account password
// Set the roles and other Properties as appropriate.
Set Properties("Roles")=roles

Your code could use different logic to obtain the information needed to define the user. You could instead obtain this information in the following ways:

• From the JWT if the access token is a JWT. In this case, call the ValidateJWT() method of %SYS.OAuth2.Validate.

• From IDToken if you are using OpenID Connect. In this case, call the ValidateIDToken() of %SYS.OAuth2.Validate.

• From Userinfo endpoint if you are OpenID Connect. In this case, call the GetUserinfo() of %SYS.OAuth2.AccessTokenOpens in a new tab.

In any case, it is necessary to define a user whose username does not match a normal Caché username.

Your routine would also need to set roles and other parts of the Properties array as needed for your application. See “Creating Delegated (User-Defined) Authentication Code” in the chapter “Using Delegated Authentication” in Caché Security Administration Guide.

Variation: Implicit Grant Type

In this variation, the client uses the implicit grant type when requesting tokens.

Configuration requirements: See the instructions in “Configuring a Client,” but specify Client Type as appropriate for your use case.

Code requirements: The overall flow is similar to the one for the authorization code grant type, but do not call GetAuthorizationCodeEndpoint(). Instead call the GetImplicitEndpoint() method of the %SYS.OAuth2.AuthorizationOpens in a new tab class:

ClassMethod GetImplicitEndpoint(applicationName As %String, 
                                scope As %String, 
                                redirectURL As %String, 
                                idtokenOnly As %Boolean = 0, 
                                responseMode As %String, 
                                ByRef properties As %String, 
                                Output isAuthorized As %Boolean, 
                                Output sc As %Status
                                sessionId as %String="") As %String

The arguments are as follows:

• applicationName is the name of the client application.

• scope is a space-delimited list of scopes for which access is requested, for example: "openid profile scope3 scope4"

  The default is determined by the client configuration for the given applicationName.

• redirectURL is the URL of the page to which the authorization server should redirect the browser after returning the access token to the client server.

• idtokenOnly enables you to obtain only an ID token. If this argument is 0, the method obtains both an access token and (if the request includes the appropriate scope) an ID token. If this argument is 1, the method does not obtain an access token.

• responseMode specifies the mode of the response from the authorization server. This can be "query" (the default), "fragment" or "form_post".

• properties, which is passed by reference, is a multidimensional array that contains any parameters to be added to the request. This array must have the following structure:

  Array node

  Array value

  properties(parametername) where parametername is the name of a parameter

  Value of the given parameter. The value can be a scalar value, an instance of a dynamic object, or the UTF-8 encoded serialized form of a dynamic object. Use a dynamic object if you want the request to include a parameter whose value is a JSON object; a scenario is the claims parameter that is defined by OpenID Connect. For details on dynamic objects, see Using JSON in Caché. To use the request or request_uri parameter, see the section “Passing Request Objects as JWTs.”

• isAuthorized, which is returned as output, equals 1 if there is a locally stored access token for this client and this session, and if that access token authorizes all the scopes given by the scope argument. This parameter equals 0 otherwise.

• sc, which is returned as output, contains the status code set by this method.

• sessionId specifies the session ID. Specify this only if you want to override the default session (%session.SessionId).

Also see “Variation: Performing the Redirect within OnPreHTTP.”

Variation: Password Credentials Grant Type

In this variation, the client uses the password credentials grant type when requesting tokens. You can use this grant type when the client has the password belonging to the resource owner. The client application can simply perform an HTTP POST operation to the token endpoint, without any page redirection; Caché provides a method to do this.

Configuration requirements: See the instructions in “Configuring a Client,” but note that you do not need to specify Client Secret. (In general, you should use the client secret only when the client secret is needed and it is possible to protect the client secret.)

Code requirements: Your application should do the following:

1. Call the IsAuthorized() method of %SYS.OAuth2.AccessTokenOpens in a new tab and check the returned value (and possible error), as described in “Obtaining Tokens,” earlier in this chapter.

2. If IsAuthorized() returned 0, call the GetAccessTokenPassword() method of %SYS.OAuth2.AuthorizationOpens in a new tab.

   ClassMethod GetAccessTokenPassword(applicationName As %String, 
                                      username As %String, 
                                      password As %String, 
                                      scope As %String, 
                                      ByRef properties As %String,
                                      Output error As %OAuth2.Error) As %Status
   

   

   The arguments are as follows:

   • applicationName is the name of the client application.

   • username is a username.

   • password is the corresponding password.

   • scope is a space-delimited list of scopes for which access is requested, for example: "scope1 scope2 scope3"

     The default is determined by the client configuration for the given applicationName.

   • properties, which is passed by reference, is a multidimensional array that contains any parameters to be added to the request. This array must have the following structure:

     Array node	Array value
     properties(parametername) where parametername is the name of a parameter	Value of the given parameter. The value can be a scalar value, an instance of a dynamic object, or the UTF-8 encoded serialized form of a dynamic object. Use a dynamic object if you want the request to include a parameter whose value is a JSON object; a scenario is the claims parameter that is defined by OpenID Connect. For details on dynamic objects, see Using JSON in Caché.

   • error, which is returned as output, is either null or is an instance of OAuth2.Error that contains error information.

   This method performs an HTTP POST operation to the token endpoint, and then receives and saves the access token (if any).

3. Check the error argument and proceed accordingly.

4. Continue as described in “Examining the Token(s)” and “Adding an Access Token to an HTTP Request.”

Variation: Client Credentials Grant Type

In this variation, the client uses the client credentials grant type when requesting tokens. This grant type enables the client application to communicate with the resource server independently from any user. There is no user context. The client application can simply perform an HTTP POST operation to the token endpoint, without any page redirection; Caché provides a method to do this.

Configuration requirements: See the instructions in “Configuring a Client.” Make sure to specify the Client Type as Private and specify Client Secret.

Code requirements: Your application should do the following:

1. Call the IsAuthorized() method of %SYS.OAuth2.AccessTokenOpens in a new tab and check the returned value (and possible error), as described in “Obtaining Tokens,” earlier in this chapter.

2. If IsAuthorized() returned 0, call the GetAccessTokenClient() method of %SYS.OAuth2.AuthorizationOpens in a new tab.

   ClassMethod GetAccessTokenClient(applicationName As %String, 
                                    scope As %String, 
                                    ByRef properties As %String, 
                                    Output error As %OAuth2.Error) As %Status
   

   

   The arguments are as follows:

   • applicationName is the name of the client application.

   • scope is a space-delimited list of scopes for which access is requested, for example: "scope1 scope2 scope3"

     The default is determined by the client configuration for the given applicationName.

   • properties, which is passed by reference, is a multidimensional array that contains any parameters to be added to the request. See the properties argument for GetAccessTokenPassword(), in the previous subsection.

   • error, which is returned as output, is either null or is an instance of OAuth2.Error that contains error information.

   This method performs an HTTP POST operation to the token endpoint, and then receives and saves the access token (if any).

3. Check the error argument and proceed accordingly.

4. Continue as described in “Examining the Token(s)” and “Adding an Access Token to an HTTP Request.”

Variation: Performing the Redirect within OnPreHTTP

For the authorization code and implicit grant types, the previous instructions use the following steps:

1. Call the IsAuthorized() method of %SYS.OAuth2.AccessTokenOpens in a new tab.

2. Call the GetAuthorizationCodeEndpoint() method (for the authorization code grant type) or call the GetImplicitEndpoint() method (for the implicit grant type).

3. Provide an option (such as a button) that opens the URL returned by the previous step, thus enabling the user to authorize the request

An alternative is to modify the OnPreHttp() method of the page class (in your application), so that it calls either the GetAccessTokenAuthorizationCode() method (for the authorization code grant type) or call the GetAccessTokenImplicit() method (for the implicit grant type). These methods cause the browser to navigate directly (if needed) to the authentication form of the authorization server, without first displaying any content of your page.

Variation: Passing Request Objects as JWTs

Caché also supports passing the request object as a JWT, as specified in section 6Opens in a new tab of the OpenID Connect Core specification. You can pass the request object by value or by reference.

In both cases, you use methods of the %SYS.OAuth2.RequestOpens in a new tab class. See the class reference for additional methods not described in this section.

Variation: Calling Other Endpoints of the Authorization Server

The methods in %SYS.OAuth2.AuthorizationOpens in a new tab enable you to call a specific set of endpoints in the authorization server. If the authorization server has other endpoints, use the following general process to call them:

1. Create an instance of %Net.HttpRequestOpens in a new tab, set its properties as needed, and call methods as needed, in order to define the request.

   Set httpRequest=##class(%Net.HttpRequest).%New()
   Set httpRequest.ContentType="application/x-www-form-urlencoded"
   ...
   

   

   For details on this class, see “Sending HTTP Requests” in Using Caché Internet Utilities.

2. To add authentication to the request, call the AddAuthentication() method of %SYS.OAuth2.AccessTokenOpens in a new tab.

   ClassMethod AddAuthentication(applicationName As %String, httpRequest As %Net.HttpRequest) As %Status
   

   

   Where:

   • applicationName is the name of the OAuth 2.0 client.

   • httpRequest is the instance of %Net.HttpRequestOpens in a new tab

   Caché looks up the given client and uses its Authentication type, SSL configuration, and other information to add the appropriate authentication to the request.

3. Optionally open the client configuration so that you can use properties contained in it. To do so, switch to the %SYS namespace and call the Open() method of OAuth2.ClientOpens in a new tab, passing the client name as the argument:

    New $NAMESPACE
    set $NAMESPACE="%SYS"
    Set client=##class(OAuth2.Client).Open(applicationName,.sc)
    If client="" Quit

   

4. Call the Post(), Get(), or Put() method (as appropriate) of the HTTP request object, providing the authorization server’s token endpoint as the argument. For example:

    set sc=httpRequest.Post(client.ServerDefinition.TokenEndpoint)

   

5. Perform additional processing as needed.

Revoking a User’s Access Tokens

To revoke all the access tokens for a given user, do the following:

1. Select System Administration > Security > OAuth 2.0 > Administration.

2. Type the user ID into the field Revoke tokens for user.

3. Select Revoke.

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

Revoking Access Tokens Programmatically

If it is necessary for the client to revoke an access token, use the RevokeToken() method of %SYS.OAuth2.AccessTokenOpens in a new tab. Note that when the session holding a given token is deleted, the system automatically calls this method (if a revocation endpoint is specified).

ClassMethod RevokeToken(applicationName As %String, accessToken As %String) As %Status

The arguments are as follows:

• applicationName is the name of the client application.

• accessToken is the access token.

The request is authorized using the basic authorization HTTP header with the client_id and client_secret associated with applicationName.

For example:

set sc=##class(%SYS.OAuth2.AccessToken).RevokeToken("myclient",accessToken)
if $$$ISERR(sc) {
    //error handling here
}

Note that you cannot use this method if the server does not specify a revocation endpoint or if Client secret is not specified.

%SYS.OAuth2.AccessTokenOpens in a new tab also provides the method RemoveAccessToken(), which removes the access token from the client but does not remove the token from the server.

API for Key Rotation on the Client

To rotate keys programmatically on the client, call the RotateKeys() method of OAuth2.ClientOpens in a new tab.

To obtain a new authorization server public JWKS, call the UpdateJWKS() method of OAuth2.ServerDefinitionOpens in a new tab.

For details on these methods, see the class reference.