docs.intersystems.com
Using OAuth 2.0 and OpenID Connect with Caché
Using a Caché Web Application as an OAuth 2.0 Client
[Home] [Back] [Next]
 InterSystems: The power behind what matters   
Caché Development Guides  >  Using OAuth 2.0 and OpenID Connect with Caché  >  Using a Caché Web Application as an OAuth 2.0 Client
Search:    

This chapter describes how to use a Caché web application as a client application that uses the OAuth 2.0 framework. It discusses the following:

This chapter primarily discusses the scenario in which a Caché web application is the client of a web server/client application and uses the authorization code grant type. See the last section for details on other grant types and other variations.
Prerequisites for the Caché Client
Before starting the tasks described in this chapter, make sure the following items are available:
Configuration Requirements
To use a Caché web application as an OAuth 2.0 client, perform the following configuration tasks:
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:
  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.
Manually Creating a Server Description (No Discovery)
To manually create a server description (rather than using discovery), first display the server description page (steps 1 and 2 above) and then select Manual. Then the page displays a larger set of options, as follows:
Specify these values and then select Save.
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:
  5. On the Client Information tab, specify the following details:
  6. On the JWT Settings tab, specify the following details:
  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.
Configuring a Client (No Dynamic Registration)
If the authorization server does not support dynamic registration, then do the following instead of the last step above:
  1. Select the Client Credentials tab and specify the following details:
    Do not enter values for Client ID Issued At, Client Secret Expires At, and Registration Client Uri.
  2. Select Save.
Outline of Code Requirements
Note:
This section describes the code needed when the client uses the authorization code grant type when requesting tokens. For other grant types, see “Variations,” later in this chapter.
In order for a Caché web application to act as OAuth 2.0 client, this web application must use logic like the following:
  1. Obtain an access token (and if needed, and ID token). See “Obtaining Tokens.”
  2. Examine the access token and (optionally, an ID token) to determine whether the user has the necessary permissions to use the requested resource. See “Examining the Tokens,” later in this chapter.
  3. If appropriate, call the resource server as described in “Adding an Access Token to an HTTP Request,” later in this chapter.
The following sections provide information on these steps.
Note that the pages of this web application must ultimately be based on %CSP.Page; you can create them with CSP, Zen, or Zen Mojo. It is useful to remember that all these kinds of pages can execute code on the client or on the server. The Caché OAuth 2.0 client API is a set of methods that run on the server.
Obtaining Tokens
Note:
This section provides information on the code needed when the client uses the authorization code grant type when requesting tokens. For other grant types, see “Variations,” later in this chapter.
To obtain tokens, use steps like the following to obtain tokens. The subsection provides details on the methods discussed here.
  1. Call the IsAuthorized() method of the %SYS.OAuth2.AccessToken class. For this, you will need to first determine the desired scope or scopes for the access token.
    For example:
     set myscopes="openid profile scope1 scope2"
 set isAuth=##class(%SYS.OAuth2.AccessToken).IsAuthorized("myclient",,myscopes,
                 .accessToken,.idtoken,.responseProperties,.error)
    This method checks to see whether an access token has already been saved locally.
  2. Check to see if the error argument has returned an error and then handle that error appropriately. Note that if this argument contains an error, the function $ISOBJECT() will return 1; otherwise $ISOBJECT() will return 0. 
        if $isobject(error) {
   //error handling here
 }
  3. If IsAuthorized() returns 1, skip to “Examining the Tokens.”
  4. Otherwise, call the GetAuthorizationCodeEndpoint() method of the %SYS.OAuth2.Authorization class. For this, you will need the following information:
    For example:
     set scope="openid profile scope1 scope2"
 set redirect="https://localhost/csp/openid/SampleClientResult.csp"

 set url=##class(%SYS.OAuth2.Authorization).GetAuthorizationCodeEndpoint("myclient",
       scope,redirect,.properties,.isAuthorized,.sc)
 if $$$ISERR(sc) {
   //error handling here
 }
    This method returns the full URL, including query parameters, of the internal destination required for a Caché OAuth 2.0 client.
  5. Provide an option (such as a button) that opens the URL returned by GetAuthorizationCodeEndpoint(), thus enabling the user to authorize the request.
    At this internal URL, which is never visible to users, Caché obtains an authorization code, exchanges that for an access token, and then redirects the browser to the client’s redirect page.
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.AccessToken. 
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:
GetAuthorizationCodeEndpoint()
Location: This method is in the class %SYS.OAuth2.Authorization. 
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:
Also see “Variation: Performing the Redirect within OnPreHTTP.”
Examining the Token(s)
After the client receives an access token (and, optionally, an ID token), the client should perform additional checks to determine whether the user has the necessary permissions to use the requested resource. To perform this examination, the client can use the methods described here to obtain additional information.
Then examine the dynamic objects returned by reference from these methods. For example, GetIntrospection() returns a dynamic object that contains the claims made by the introspection endpoint. Use these claims as needed to determine whether to proceed.
ValidateJWT()
Location: This method is in the class %SYS.OAuth2.Validation. 
ClassMethod ValidateJWT(applicationName As %String, 
                        accessToken As %String,
                        scope As %String, 
                        aud As %String, 
                        Output jsonObject As %RegisteredObject, 
                        Output securityParameters As %String, 
                        Output sc As %Status) As %Boolean
Use this method only if the access token is a JWT (rather than an opaque token).
This method decrypts the JWT if necessary, validates the JWT, and creates an object (jsonObject) to contain the JWT properties. To validate the JWT, the method checks the audience (if aud is specified), issuer endpoint (must match that specified in server definition), and scope (if scope is specified). The method also makes sure the access token has not expired. If the JWT is signed, the method checks the signature.
This method returns 1 if the JWT is valid or returns 0 otherwise. It also returns several arguments as output.
The arguments are as follows:
If this method returns success (1), examine jsonObject, and use the contained claims as needed to determine whether to allow access to the requested resource. Use securityParameters if needed.
ValidateIDToken()
Location: This method is in the class %SYS.OAuth2.Validation. 
ClassMethod ValidateIDToken(applicationName As %String, 
                            IDToken As %String, 
                            accessToken As %String, 
                            scope As %String, 
                            aud As %String, 
                            Output jsonObject As %RegisteredObject, 
                            Output securityParameters As %String, 
                            Output sc As %Status) As %Boolean
This method validates the signed OpenID Connect ID token (IDToken) and creates an object (jsonObject) to contain the properties of the ID token. To validate the ID token, the method checks the audience (if aud is specified), endpoint (must match that specified in server definition), and scope (if scope is specified), and signature. The method also makes sure the ID token has not expired.
This method also validates the access token (accessToken) based on the at_hash property of the ID token.
This method returns 1 if the ID token is valid or returns 0 otherwise. It also returns several arguments as output.
The arguments are as follows:
If this method returns success (1), examine jsonObject, and use the contained claims as needed to determine whether to allow access to the requested resource. Use securityParameters if needed.
GetIntrospection()
Location: This method is in the class %SYS.OAuth2.AccessToken. 
ClassMethod GetIntrospection(applicationName As %String, 
                             accessToken As %String, 
                             Output jsonObject As %RegisteredObject) As %Status
This method sends the access token to the introspection endpoint, receives a response that contains claims, and creates an object (jsonObject) that contains the claims returned by that endpoint.
The request is authorized using the basic authorization HTTP header with the client_id and client_secret associated with applicationName.
The arguments are as follows:
Note that you cannot use this method if the server does not specify an introspection endpoint or if Client secret is not specified.
If this method returns success (1), examine jsonObject, and use the contained claims as needed to determine whether to allow access to the requested resource.
GetUserinfo()
Location: This method is in the class %SYS.OAuth2.AccessToken. 
ClassMethod GetUserinfo(applicationName As %String, 
                        accessToken As %String, 
                        IDTokenObject As %RegisteredObject, 
                        Output jsonObject As %RegisteredObject, 
                        Output securityParameters As %String) As %Status
This method sends the access token to the Userinfo endpoint, receives a response that contains claims, and creates an object (jsonObject) that contains the claims returned by that endpoint. If the response returns a JWT, then the response is decrypted and the signature is checked before jsonObject is created. If the argument IDTokenObject is specified, the method also verifies that the sub claim from the User info endpoint matches the sub claim in IDTokenObject.
The request is authorized using the specified access token.
The arguments are as follows:
If this method returns success (1), examine jsonObject, and use the contained claims as needed to determine whether to allow access to the requested resource. Use securityParameters if needed.
Adding an Access Token to an HTTP Request
After the client application has received and examined an access token, the application can make HTTP requests to the resource server. Depending on the application, those HTTP requests may need the access token.
To add an access token to an HTTP request (as a bearer token HTTP authorization header), do the following:
  1. Create an instance of %Net.HttpRequest and set properties as needed.
    For details on this class, see “Sending HTTP Requests” in Using Caché Internet Utilities.
  2. Call the AddAccessToken() method of %SYS.OAuth2.AccessToken, which adds the access token to the HTTP request. This method is as follows: 
    ClassMethod AddAccessToken(httpRequest As %Net.HttpRequest, 
                           type As %String = "header", 
                           sslConfiguration As %String,  
                           applicationName As %String,  
                           sessionId As %String) As %Status
    This method adds the bearer access token associated with the given application and session to the resource server request as defined by RFC 6750. The arguments are as follows:
    This method returns a status code, which your code should check.
  3. Send the HTTP request (as described in “Sending HTTP Requests” in Using Caché Internet Utilities. To do so, you call a method such as Get() or Put().
  4. Check the status returned by the previous step.
  5. Optionally examine the HTTP response, which is available as the HttpResponse property of the HTTP request.
    See “Sending HTTP Requests” in Using Caché Internet Utilities.
For example:
 set httpRequest=##class(%Net.HttpRequest).%New()
 // AddAccessToken adds the current access token to the request.
 set sc=##class(%SYS.OAuth2.AccessToken).AddAccessToken(httpRequest,,"sslunittest",applicationName)
 if $$$ISOK(sc) {
    set sc=httpRequest.Get("https://myresourceserver/csp/openid/openid.SampleResource.cls")
 }
Optionally Defining Delegated Authentication for the Web Client
You can optionally define delegated authentication for a Caché web client that is used as an OAuth 2.0 client. Caché provides two ways that you can do this:
The following subsections give the details. A final subsection discusses the ZAUTHENTICATE sample.
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:
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:
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:
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.
Variations
This chapter primarily discusses the scenario in which a Caché web application uses the authorization code grant type. This section discusses some variations:
In the basic scenario described earlier in this chapter, the client receives an access token from the authorization server and then optionally calls additional endpoints in the authorization server: the introspection endpoint, the Userinfo endpoint, or both. After that, the client calls the resource server. Notice that it is also possible for the resource server to independently call these endpoints.
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.Authorization 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:
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.AccessToken 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.Authorization. 
    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:
    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.AccessToken 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.Authorization. 
    ClassMethod GetAccessTokenClient(applicationName As %String, 
                                 scope As %String, 
                                 ByRef properties As %String, 
                                 Output error As %OAuth2.Error) As %Status
    The arguments are as follows:
    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.AccessToken.
  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 6 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.Request class. See the class reference for additional methods not described in this section.
Passing a Request Object by Value
To use the request parameter to pass the request object as a JWT:
  1. Call the MakeRequestJWT() method of the %SYS.OAuth2.Request class: 
    ClassMethod MakeRequestJWT(applicationName As %String, 
                           ByRef properties As %String, 
                           Output sc As %Status) As %String
    Where:
    This method returns a string, which is the JWT. For example:
     // create jwt 
 set jwt=##class(%SYS.OAuth2.Request).MakeRequestJWT("myapp",.properties,.sc)
  2. Modify the properties array that you will use as the argument for GetAuthorizationCodeEndpoint() or GetImplicitEndpoint(). Set the node properties("request") equal to the JWT that you created in the previous step. For example: 
     set properties("request")=jwt
  3. When you call GetAuthorizationCodeEndpoint() or GetImplicitEndpoint(), include the properties array. For example: 
     set url=##class(%SYS.OAuth2.Authorization).GetAuthorizationCodeEndpoint("myapp",
       scope,redirect,.properties,.isAuthorized,.sc, responseMode)
Passing a Request Object by Reference
To use the request_uri parameter to pass the request object as a JWT:
  1. Call the UpdateRequestObject() method of the %SYS.OAuth2.Request class: 
    ClassMethod UpdateRequestObject(applicationName As %String, 
                                requestName As %String, 
                                ByRef properties As %String, 
                                Output sc As %Status) As %SYS.OAuth2.Request
    Where:
    This method creates, saves, and returns an instance of %SYS.OAuth2.Request. 
     // create requestobject 
 set requestobject=##class(%SYS.OAuth2.Request).UpdateRequestObject("myapp","myrequest",.properties,.sc)
  2. Get the URL of the saved request object. To do so, call the GetURL() method of the instance. Note that GetURL() returns a status code as output in the first argument; your code should check that. 
     Set requesturl=requestobject.GetURL()
  3. Modify the properties array that you will use as the argument for GetAuthorizationCodeEndpoint() or GetImplicitEndpoint(). Set the node properties("request_uri") equal to the URL obtained in the previous step. For example: 
    set properties("request_uri")=requesturl
  4. When you call GetAuthorizationCodeEndpoint() or GetImplicitEndpoint(), include the properties array. For example: 
     set url=##class(%SYS.OAuth2.Authorization).GetAuthorizationCodeEndpoint("myapp",
       scope,redirect,.properties,.isAuthorized,.sc, responseMode)
Variation: Calling Other Endpoints of the Authorization Server
The methods in %SYS.OAuth2.Authorization 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.HttpRequest, 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.AccessToken. 
    ClassMethod AddAuthentication(applicationName As %String, httpRequest As %Net.HttpRequest) As %Status
    Where:
    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.Client, 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 Access Tokens
If the authorization server supports token revocation, you can revoke access tokens via the Management Portal or programmatically.
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.AccessToken. 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:
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.AccessToken also provides the method RemoveAccessToken(), which removes the access token from the client but does not remove the token from the server.
Rotating Keys Used for JWTs
In most cases, you can cause the client to generate new public/private key pairs; this applies only to the RSA keys used for the asymmetric RS256, RS384, and RS512 algorithms. (The exception is if you specify Source other than dynamic registration as X509 certificate. In this case, it is not possible to generate new keys.)
Generating new public/private key pairs is known as key rotation; this process adds new private RSA keys and associated public RSA keys to the private and public JWKSs.
When you perform key rotation on the client, the client uses the new private RSA keys to sign JWTs to be sent to the authorization server. Similarly, the client uses the new public RSA keys to encrypt JWTs to be sent to the authorization server. To decrypt JWTs received from the authorization server, the client uses the new RSA keys, and if that fails, uses the old RSA keys; thus the client can decrypt a JWT that was created using its old public RSA keys. Last, if the client cannot verify a signed JWT received from the authorization server, then if the client has the URL for the authorization server public JWKS, the client obtains a new public JWKS and tries again to verify the signature. (Note that the client has a URL for the authorization server public JWKS if the client was registered dynamically or if the configuration specified the JWKS from URL option; otherwise, the client does not have this URL.)
To rotate keys for a given client configuration:
  1. In the Management Portal, select System Administration > Security > OAuth 2.0 > Client Configuration.
  2. Select the server description with which the client configuration is associated.
    The system then displays all client configurations associated with that server description.
  3. Select the configuration of the client whose keys you want to rotate.
  4. Select the Rotate Keys button.
Note:
The symmetric HS256, HS384, and HS512 algorithms always use the client secret as the symmetric key.
API for Key Rotation on the Client
To rotate keys programmatically on the client, call the RotateKeys() method of OAuth2.Client.
To obtain a new authorization server public JWKS, call the UpdateJWKS() method of OAuth2.ServerDefinition.
For details on these methods, see the class reference.
Getting a New Public JWKS from the Authorization Server
In most cases, the authorization server generates a public/private pair of JWKSs. There are different ways in which the client can receive the public JWKS. One way is for the authorization server to provide the public JWKS at a URL; see the JWKS from URL option in “Manually Creating a Server Description (No Discovery).”
If the authorization server was defined with JWKS from URL and if the authorization server generates a new pair of JWKSs, you can cause the client to obtain the new public JWKS from the same URL. To do so:
  1. In the Management Portal, select System Administration > Security > OAuth 2.0 > Client Configuration.
  2. Select the server description with which the client configuration is associated.
    The system then displays all client configurations associated with that server description.
  3. Select the configuration of the client.
  4. Select the Update JWKS button.
If the authorization server was not defined with JWKS from URL and if the authorization server generates a new pair of JWKSs, it is necessary to obtain the public JWKS, send it to the client, and load it from a file.

[Home] [Back] [Next] [Top of Page] 
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content for this page loaded from GOAUTH.xml on 2019-04-23 10:17:32
View this book as PDF   |  Download all PDFs