Class Reference
IRIS for UNIX 2019.2
InterSystems: The power behind what matters   
Documentation  Search
  [%SYS] >  [%SYS] >  [OAuth2] >  [AccessToken]
Private  Storage   

class %SYS.OAuth2.AccessToken extends %RegisteredObject

The %SYS.OAuth2.AccessToken class defines the client operations which allow an access token to be used to authorize to a resource server.

The underlying token is stored in OAuth2.AccessToken in the system database. OAuth2.AccessToken is indexed by the combination of SessionId and ApplicationName. Therefore, only one scope may be requested for each SessionId/ApplicationName. If a second request is made with a different scope and access token has yet been granted, the scope in the new request becomes the expected scope.
Note that this class is in library and thus available everywhere. However, token storage is in the system database and thus not directly available to most code.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
14


Summary

Methods
%AddToSaveSet %ClassIsLatestVersion %ClassName %ConstructClone
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Extends
%GetParameter %IsA %IsModified %New
%NormalizeObject %ObjectModified %OriginalNamespace %PackageName
%RemoveFromSaveSet %SerializeObject %SetModified %ValidateObject
AddAccessToken AddAuthentication AuthorizeWithAccessToken GetAccessTokenFromRequest
GetIntrospection GetUserinfo IsAudContained IsAuthorized
IsScopeContained RemoveAccessToken RemoveAuthorizationAccessToken RevokeToken


Methods

• classmethod AddAccessToken(httpRequest As %Net.HttpRequest, type As %String = "header", sslConfiguration As %String, applicationName As %String, sessionId As %String) as %Status
AddAccessToken adds the bearer access token associated with applicationName and sessionId to the resource server request as defined by RFC 6750. The sslConfiguration that is specified for the client is added to the httpRequest object. This method is used to prepare requests from the Client to the Resource Server. The type argument specifies one of three ways defined by RFC 6750 to send the access token to the Resource Server:
"header" to use Bearer token HTTP header.
"body" to use form encoded body. In this case, request must be a POST with form encoded body.
"query" to use a query parameter.
The sslConfiguration is the name of the Security.SSLConfigs object to use for this request. The default for sslConfiguration comes from the OAuth2.Client instance.
• classmethod AddAuthentication(applicationName As %String, httpRequest As %Net.HttpRequest) as %Status
AddAuthication adds the required authentication for the token request and the SSLConfiguration that is specified for the client. See "token_endpoint_auth_method" property of OAuth2.Client.Metadata. This method is used for sending HTTP requests to the Authorization Server.
• classmethod AuthorizeWithAccessToken(httpRequest As %Net.HttpRequest, type As %String = "header", sslConfiguration As %String, applicationName As %String, accessToken As %String) as %Status
AuthorizeWithAccessToken adds the bearer access token which is passed as an argument to this method to the resource server request as defined by RFC 6750. The sslConfiguration that is specified for the client is added to the httpRequest object. This method is used to prepare requests from the Client to the Resource Server. The type argument specifies one of three ways defined by RFC 6750 to send the access token to the Resource Server:
"header" to use Bearer token HTTP header.
"body" to use form encoded body. In this case, request must be a POST with form encoded body.
"query" to use a query parameter.
The sslConfiguration is the name of the Security.SSLConfigs object to use for this request. The default for sslConfiguration comes from the OAuth2.Client instance.
• classmethod GetAccessTokenFromRequest(Output sc As %Status) as %String
GetAccessTokenFromRequest returns the access token which is found in the HTTP request using one of the three RFC 6750 formats (See AddAccessToken above). The access token should be validated using a Validate method or a user written Validate method. This method is used by the Resource Server to authorize requests from the Client.
• classmethod GetIntrospection(applicationName As %String, accessToken As %String, Output jsonObject As %RegisteredObject) as %Status
Retrieves the JSON object which contains claims about accessToken that is returned from the introspection endpoint. The request is authorized using the basic authorization HTTP header with the client_id and client_secret associated with applicationName.
The claims returned by the introspection endpoint are returned as the properties of jsonObject.
• classmethod GetUserinfo(applicationName As %String, accessToken As %String, IDTokenObject As %RegisteredObject, Output jsonObject As %RegisteredObject, Output securityParameters As %String) as %Status
Retrieve the JSON object that is returned from the userinfo endpoint forthee specified access token. The request is authorized using the specified access token. If the userinfo endpoint returns a JWT, then the object is optionally decrypted and the signature checked.
If IDTokenObject is passed as the object returned by ##class(%SYS.OAuth2.Validation).ValidateIDToken and is used to check the sub property.
The claims returned by the userinfo endpoint are returned as the properties of jsonObject.
securityParameters is returned as a local array of Strings that that indicate the algorithms that were used for JSON Object Signature and/or Encryption operations that were performed on the JWT by the authorization server

For JSON Web Signature (JWS):
securityParameters("sigalg") - Signature or MAC algorithm

For JSON Web Encryption (JWE):
securityParameters("keyalg") - Key management algorithm
securityParameters("encalg") - Content encryption algorithm
See %OAuth2.JWT for the list of supported algorithms.
• classmethod IsAudContained(containingAud As %DynamicArray, aud As %String) as %Boolean
Check that specified audience is contained in the containing audience list. containingAud may either be a single audience as %String or a list of audiences as %DynamicArray.
• 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
IsAuthorized returns true if the applicationName and sessionId combination has an access token which authorizes all the scopes that are specified by the scope argument.
applicationName is the name of the application that is being authorized.
sessionId is the session id. sessionId defaults to %session.SessionId and will usually not be specified.
scope is a blank separated list of scopes.
responseProperties will be returned as a local array specifying the properties that were included in the token response in the form properties(name)=value.
The access token is returned in the accessToken argument.
• classmethod IsScopeContained(containingScope As %String, scope As %String) as %Boolean
Check that scope is subset of valid scopes for this token.
• classmethod RemoveAccessToken(applicationName As %String, sessionId As %String) as %Status
Remove the token associated with the specified application and session from the client
• classmethod RemoveAuthorizationAccessToken(httpRequest As %Net.HttpRequest, type As %String = "header") as %Status
RemoveAuthorizationAccessToken removes the access token from the %Net.HttpRequest object.
• classmethod RevokeToken(applicationName As %String, accessToken As %String) as %Status
RevokeToken invalidates the access token using the revocation endpoint. This method will be called automatically when the session holding the token is deleted. This method may also be called from user code to make the token no longer valid. RevokeToken will call %SYS.OAuth2.AccessToken.Remove to remove the token from the client.
The request is authorized using the basic authorization HTTP header with the client_id and client_secret associated with applicationName.


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.