Skip to main content

HS.FHIRServer.Util.OAuth2Token

class HS.FHIRServer.Util.OAuth2Token extends HS.FHIRServer.API.OAuth2Token

Class for OAuth 2.0 access token handling. It implements the FHIR request-time handling and evaluation of tokens per the HL7 Smart App Launch Implementation Guide. An instance of this class is expected to be instantiated and set as a property on a FHIRServer Interactions instance. It is used for all interactions that are handled by the Interactions instance.

Method Inventory

Parameters

parameter AlreadyValidated = 0;
If 0, SetInstance() will perform token validation. Otherwise, if 1, the tokens handled by the Interactions instance that uses this class are expected to have already been validated by alternate means.
parameter ErrorOnInvalidPermission = 0;
If 0, a SMART on FHIR resource scope with an invalid permission is ignored. Otherwise if 1, an invalid permission will cause a 401 Unauthorized error.
parameter ErrorOnInvalidScopeName = 1;
If 0, a SMART on FHIR resource scope with an unsupported scope name is ignored. Otherwise if 1, an unsupported scope name will cause a 401 Unauthorized error.
parameter IntrospectionInterval = 5;
Minimum number of seconds between introspection calls for the current access token.
parameter PermissionV1 = 1;
If 1, SMART on FHIR v1-style scope permission strings are supported. Otherwise if 0, v1-style permission strings will cause a scope to be ignored or cause a 401 Unauthorized to be returned, depending on the value of the ErrorOnInvalidPermission class parameter.
parameter ResourceScopeNames;
List of supported SMART on FHIR resource scope names. Reference: http://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html#fhir-resource-scope-syntax
parameter ResourceTypesAllowImplied;
List of resource types that are allowed when no scopes explicitly disallow the resource type on the current interaction. For example, when this class parameter is "OperationOutcome":
- If an OperationOutcome resource is returned by a search, and there are no scopes with a wildcard resource type and no scopes that specify OperationOutcome, then the OperationOutcome is allowed.
- If an OperationOutcome resource is returned by a search, and scope user/OperationOutcome.cu is the only scope present for that resource type, then the OperationOutcome is disallowed.

Methods

method %OnNew(pSchema As HS.FHIRServer.Schema) as %Status
Inherited description: This callback method is invoked by the %New() method to provide notification that a new instance of an object is being created.

If this method returns an error then the object will not be created.

It is passed the arguments provided in the %New call. When customizing this method, override the arguments with whatever variables and types you expect to receive from %New(). For example, if you're going to call %New, passing 2 arguments, %OnNew's signature could be:

Method %OnNew(dob as %Date = "", name as %Name = "") as %Status If instead of returning a %Status code this returns an oref and this oref is a subclass of the current class then this oref will be the one returned to the caller of %New method.

method BaseURLGet() as %String
classmethod FSLogScopeMsg(pInteraction As %String = "", pScopeName As %String, pRequiredPermission As %String, pResourceType As %String = "") as %String
method GetContextValues(ByRef pContextValues)
@API.Overrideable
Return the current context values, if any, as a Multidimensional array.
method GetUserInfo(pBAUsername As %String, pBARoles As %String, Output pUserInfo)
@API.Overrideable
Derive user information from the current OAuth 2.0 token, and return that data if desired.
@Input pBAUsername: Existing basic authentication username (e.g., $username value).
@Input pBARoles : Existing basic authentication user roles (e.g., $roles value).
@Output pUserInfo(): Array of user information. Standard return is pUserInfo("Username") and pUserInfo("Roles"). This method may be overridden to derive and return other user info via subscripts in the pUserInfo() array.
method HasScope(pScopeName As %String, pResourceType As %String, pRequiredPermission As %String) as %Boolean
@API.Overrideable
Return a Boolean indicating whether the current token resource scopes allow the specified interaction for the specified resource type, based on the specified required permissions.
@Input pScopeName SMART on FHIR scope name, such as "user", "patient", "system".
@Input pResourceType FHIR resource type.
@Input pRequiredPermission SMART on FHIR scope permission string. SMART on FHIR v1 format ("read", "write", "*") and v2 format ("cruds") are handled here.
method OAuthClientGet() as %String
method ScopesListGet() as %String
method SetInstance(pTokenString As %String = "", pOAuthClient As %String = "", pBaseURL As %String = "", pUsername As %String = "", pJWTObj As %DynamicObject = "", pLastIntrospectionTime As %Integer = 0)
@API
Set or reset the properties of the current token handler instance, based on the input parameters.
@Input pTokenString The access token string.
@Input pOAuthClient The OAuth 2.0 Client Name, as defined in the Management Portal at System Administration > Security > OAuth 2.0 > Client. @Input pBaseURL The base URL, including scheme, host, port and path of the end point for the current FHIR interaction. @Input pUsername (DEPRECATED) The Basic Auth username for the current FHIR interaction.
@Input pJWTObj Access token JSON object previously obtained using the token string. When provided as input, it must indicate the same token indicated by pTokenString.
@Input pLastIntrospectionTime When pJWTObj is provided as input, this is the time in NumericDate format stating the last time the token string had introspection done for it.
method TokenObjectGet() as %String
method TokenStringGet() as %String
method UsernameGet() as %String
deprecated method VerifyEverythingRequest(pResourceType As %String, pResourceId As %String, pResourceJson As %DynamicObject)
DEPRECATED. $everything implementations should do their own finer-grained checking against token scopes.
method VerifyHistoryInstanceResponse(pResourceType As %String, pResourceJson As %DynamicObject, pRequiredPermission As %String)
@API.Overrideable
Verify that the access token allows the history-instance request based on the contents of the interaction response and required permission. If not allowed, this method will Throw. Otherwise, it will simply Return.
@Input pResourceType FHIR resource type.
@Input pResourceJson %DynamicObject representation of FHIR history Bundle resource.
@Input pRequiredPermission SMART on FHIR scope permission string. SMART on FHIR v1 format ("read", "write", "*") and v2 format ("cruds") are supported as inputs.
method VerifyResourceContent(pResourceJson As %DynamicObject, pRequiredPermission As %String, pAllowSharedResource As %Boolean = 0)
@API.Overrideable
Verify that the access token allows the current interaction on the specified resource, based on the content and required permission. If not allowed, this method will Throw. Otherwise, it will simply Return.
@Input pResourceJson %DynamicObject representation of FHIR resource.
@Input pRequiredPermission SMART on FHIR scope permission string. SMART on FHIR v1 format ("read", "write", "*") and v2 format ("cruds") are supported as inputs.
@Input pAllowSharedResource Boolean indicating whether to approve access to shared resource type if it has scope permission (resource type + permission) but the scope is a normally context- relevant scope (e.g., patient scope).
method VerifyResourceIdRequest(pResourceType As %String, pResourceId As %String, pRequiredPermission As %String)
@API.Overrideable
Caution: This implementation of VerifyResourceIdRequest ignores the pResourceId input parameter. It verifies that the access token allows the current interaction request based on the resource type and required permission only. If not allowed, this method will Throw. Otherwise, it will simply Return. Note that despite returning from this call, the corresponding response to the interaction could still fail subsequent verification later in the processing of the current interaction.
method VerifySearchRequest(pResourceType As %String, pCompartmentResourceType As %String, pCompartmentResourceId As %String, pParameters As HS.FHIRServer.API.Data.QueryParameters, pRequiredPermission As %String)
@API.Overrideable
Verify that the access token allows access to all resource types explicitly stated in the search request (pResourceType, pCompartmentResourceType, include and revinclude resource types). Resource types involved in chain and reverse chain (_has) are not subject to this check. Where there is some uncertainty remaining about the resource types that might be returned by the search request (e.g., include or revinclude wildcard resource types), ..%VerifySearchResults will be set to 1 to signal a need to check the search result set contents against the access token. If this method determines that the request is not allowed, this method will Throw.
@Input pResourceType FHIR resource type.
@Input pCompartmentResourceType FHIR resource type for a compartment-based search (e.g., "Patient" in "GET /Patient/123/Observation").
@Input pCompartmentResourceId FHIR resource id for compartment-based search (e.g., "123" in "GET /Patient/123/Observation").
@Input pParameters HS.FHIRServer.API.Data.QueryParameters object representing the search query parameters.
@Input pRequiredPermission SMART on FHIR scope permission string. SMART on FHIR v1 format ("read", "write", "*") and v2 format ("cruds") are supported as inputs.
method VerifySearchResultsGet() as %Boolean
method VerifySystemLevelRequest()
@API.Overrideable
Verify that the access token allows the system-level request. This is for system-history and system-search. Default functionality is to ignore patient context, and require user/*.read and/or user/*.*
If not allowed, this method will Throw. Otherwise, it will simply Return.
method VerifyTypesList(pResourceTypesList As %List, pRequiredPermission As %String)
@API.Overrideable
Verify that the access token scopes authorize the specified permission on ALL the resource types in the specified list. @Input pResourceTypesList $ListBuild of FHIR resource types.
@Input pRequiredPermission SMART on FHIR scope permission string. SMART on FHIR v1 format ("read", "write", "*") and v2 format ("cruds") are supported as inputs.

Inherited Members

Inherited Properties

Inherited Methods

FeedbackOpens in a new tab