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

class %SYS.OAuth2.Authorization extends %RegisteredObject

The %SYS.OAuth2.Authorization class contains the operations which are used to authorize a client by obtaining an access token.

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 databse and thus available everywhere. However, token storage storage is in the system database and thus not difrectly 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
GetAccessTokenAuthorizationCode GetAccessTokenClient GetAccessTokenImplicit
GetAccessTokenJWT GetAccessTokenPassword GetAccessTokenRefresh
GetAuthorizationCodeEndpoint GetImplicitEndpoint SetEndpoints


Methods

• classmethod GetAccessTokenAuthorizationCode(applicationName As %String, scope As %String, redirectURL As %String, ByRef properties As %String, responseMode As %String, sessionId As %String = "") as %Status
GetAccessTokenAuthorizationCode may be called from the OnPreHttp method of a CSP page to redirect authorization requests to the Authorization Server based on the authorization code grant type.
GetAccessTokenAuthorizationCode will only request a new access token if their is no existing access toekn which includes all the scopes that are being requested.
The scope argument is a blank separated list of scopes for which access is requested. The default for scope is the DefaultScope property of OAuth2.Client for applicationName.
The redirectURL argument is the URL of the CSP page which should be invoked after the request for the access token is completed and the access token is stored indexed by the ApplicationName and SessionId. The responseMode argument specifies the mode of the response as either query, fragment or form_post. The default is query.
properties is a local array specifying additional properties to be included in a token request in the form properties(name)=value. To add a request parameter which is a JSON object, you may either create a properties element which is a %DynamicObject or is a string that is the UTF-8 encoded serialized object. For example the claims parameter that is defined by OpenID Connect. If the request or request_uri request parameters are to be used, then the %SYS.OAuth2.Request class is used to create the JWT. The the JWT is assigned to properties("request") or the URL for the JWT is assigned to properties("request_uri")
• classmethod GetAccessTokenClient(applicationName As %String, scope As %String, ByRef properties As %String, Output error As %OAuth2.Error, sessionId As %String = "") as %Status
GetAccessTokenClient may be called from any method to send authorization requests to the Authorization Server based on the resource owner client credentials grant type. The access token will be stored indexed by the ApplicationName and SessionId before this method returns.
The scope argument is a blank separated list of scopes for which access is requested.
properties is a local array specifying additional properties to be included in a token request in the form properties(name)=value. To add a request parameter which is a JSON object, you may either create a properties element which is a %DynamicObject or is a string that is the UTF-8 encoded serialized object.
• classmethod GetAccessTokenImplicit(applicationName As %String, scope As %String, redirectURL As %String, idtokenOnly As %Boolean, responseMode As %String, ByRef properties As %String, sessionId As %String = "") as %Status
GetAccessTokenImplicit may be called from the OnPreHttp method of a CSP page to redirect authorization requests to the Authorization Server based on the implicit grant type.
GetAccessTokenAuthorizationCode will only request a new access token if their is no existing access token which includes all the scopes that are being requested.
The scope argument is a blank separated list of scopes for which access is requested. The default for scope is the DefaultScope property of OAuth2.Client for applicationName.
The idtokenOnly argument should be specified as true in order to get an IDToken but not an access token.
The responseMode argument specifies the mode of the response as either query, fragment or form_post. The default is fragment.
The redirectURL argument is the URL of the CSP page which should be invoked after the request for the access token is completed and the access token is stored indexed by the ApplicationName and SessionId.
properties is a local array specifying additional properties to be included in a token request in the form properties(name)=value. To add a request parameter which is a JSON object, you may either create a properties element which is a %DynamicObject or is a string that is the UTF-8 encoded serialized object. For example the claims parameter that is defined by OpenID Connect. If the request or request_uri request parameters are to be used, then the %SYS.OAuth2.Request class is used to create the JWT. The the JWT is assigned to properties("request") or the URL for the JWT is assigned to properties("request_uri")
• classmethod GetAccessTokenJWT(applicationName As %String, sub As %String, scope As %String, ByRef properties As %String, Output error As %OAuth2.Error, sessionId As %String = "") as %Status
GetAccessTokenJWT may be called from any method to send authorization requests to the Authorization Server based on the resource owner JWT grant type specified in RFC 7523. The access token will be stored indexed by the applicationName and sessionId before this method returns.
The scope argument is a blank separated list of scopes for which access is requested.
properties is a local array specifying additional properties to be included in a token request in the form properties(name)=value. To add a request parameter which is a JSON object, you may either create a properties element which is a %DynamicObject or is a string that is the UTF-8 encoded serialized object.
sub is the subject of the JWT which usually a user which is defined on the authorization server. The signing algorithm to be used to sign the JWT is specified by OAuth2.Client.Metadata."token_endpoint_auth_signing_alg", the same signing algorithm as used for client authentication JWT.
• classmethod GetAccessTokenPassword(applicationName As %String, username As %String, password As %String, scope As %String, ByRef properties As %String, Output error As %OAuth2.Error, sessionId As %String = "") as %Status
GetAccessTokenPassword may be called from any method to send authorization requests to the Authorization Server based on the resource owner password credentials grant type. The access token will be stored indexed by the ApplicationName and SessionId before this method returns.
The scope argument is a blank separated list of scopes for which access is requested.
properties is a local array specifying additional properties to be included in a token request in the form properties(name)=value. To add a request parameter which is a JSON object, you may either create a properties element which is a %DynamicObject or is a string that is the UTF-8 encoded serialized object.
• final classmethod GetAccessTokenRefresh(accessToken As OAuth2.AccessToken, Output refreshed As %Boolean, Output error As %OAuth2.Error) as %Status
GetAccessTokenRefresh sends a request to the Authorization Server in order to get a new access token based on the refresh token. The access token will be stored indexed by the ApplicationName and SessionId before this method returns.
• 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
GetAuthorizationEndpoint returns the URL to be used to redirect authorization requests to the Authorization Server based on the authorization code grant type. The location part of the URL will be a class in this InterSystems IRIS instance which will further redirect to the authorization server. This URL should be used for a button, anchor or in Javascript code in a page.
The scope argument is a blank separated list of scopes for which access is requested. The default for scope is the DefaultScope property of OAuth2.Client for applicationName.
The redirectURL argument is the URL of the CSP page which should be invoked after the request for the access token is completed and the access token is stored indexed by the ApplicationName and SessionId.
The responseMode argument specifies the mode of the response as either query, fragment or form_post. The default is query.
properties is a local array specifying additional properties to be included in a token request in the form properties(name)=value. To add a request parameter which is a JSON object, you may either create a properties element which is a %DynamicObject or is a string that is the UTF-8 encoded serialized object. For example the claims parameter that is defined by OpenID Connect. If the request or request_uri request parameters are to be used, then the %SYS.OAuth2.Request class is used to create the JWT. The the JWT is assigned to properties("request") or the URL for the JWT is assigned to properties("request_uri")
isAuthorized is an output argument which is returned true if an access token has already been granted for this SessionId/ApplicationName combiation.
• 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
GetImplicitEndpoint returns the URL to be used to redirect authorization requests to the Authorization Server based on the implicit grant type. The location part of the URL will be a class in this InterSystems IRIS instance which will further redirect to the authorization server. This URL should be used for a button, anchor or in Javascript code in a page.
The scope argument is a blank separated list of scopes for which access is requested. The default for scope is the DefaultScope property of OAuth2.Client for applicationName.
The idtokenOnly argument should be specified as true in order to get an IDToken but not an access token.
The responseMode argument specifies the mode of the response as either query, fragment or form_post. The default is fragment.
The redirectURL argument is the URL of the CSP page which should be invoked after the request for the access token is completed and the access token is stored indexed by the ApplicationName and SessionId.
properties is a local array specifying additional properties to be included in a token request in the form properties(name)=value. To add a request parameter which is a JSON object, you may either create a properties element which is a %DynamicObject or is a string that is the UTF-8 encoded serialized object. For example the claims parameter that is defined by OpenID Connect. If the request or request_uri request parameters are to be used, then the %SYS.OAuth2.Request class is used to create the JWT. The the JWT is assigned to properties("request") or the URL for the JWT is assigned to properties("request_uri")
isAuthorized is an output argument which is returned true if an access token has already been granted for this SessionId/ApplicationName combination.
• classmethod SetEndpoints(applicationName As %String, authorizationEndpoint As %String, tokenEndpoint As %String) as %Status
SetEndpoints will update the authorization endpoint and the token endpoint for the specified client application. If either endpoint is not specified, then it will not be modified.


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