Skip to main content

%OAuth2.ResourceServer.Authenticator

abstract class %OAuth2.ResourceServer.Authenticator extends %Library.RegisteredObject, %JSON.Adaptor

This abstract class represents an authentication strategy to be used with an OAuth2.ServerDefinition. IRIS provides an implementation: %OAuth2.ResourceServer.SimpleAuthenticator, but the behavior can be further customized by extending this class and defining the desired logic in the Authenticate() method.

An instance of the authenticator can be associated with the OAuth2.ServerDefinition with the following code. 
  set server = ##class(OAuth2.ResourceServer).%OpenId(id)
  set server.Authenticator = ##class(%OAuth2.ResourceServer.SimpleAuthenticator).%New()
  set server.Authenticator.UserClaim = "username"
  set server.Authenticator.RoleClaim = "scope"
  set server.Authenticator.Prefix = "iris:"
For convenience, you can also pass the property values to the constructor: 
  set server.Authenticator = ##Class(%OAuth2.ResourceServer.SimpleAuthenticator).%New({
  	"UserClaim": "username",
  	"RoleClaim": "scope",
  	"Prefix": "iris:"
  })
Alternatively, in the case where the Authenticator implementation exists in a namespace other than %SYS, you can specify the values using a %DynamicObject or JSON string: 
  set server.Authenticator = {
  	"Implementation": "User.CustomAuthenticator",
  	"Namespace": "USER",
  	"CustomProp": "customvalue"
  }

Method Inventory

Parameters

parameter %JSONIGNOREINVALIDFIELD = 1;
Inherited description: The %JSONIGNOREINVALIDFIELD parameter allows the programmer to control handling of unexpected fields in the JSON input. The default (%JSONIGNOREINVALIDFIELD = 0) will treat an unexpected field as an error. If %JSONIGNOREINVALIDFIELD is set = 1, then unexpected fields will be ignored.

Methods

abstract method Authenticate(claims As %DynamicObject, oidc As %Boolean, Output properties As %String) as %Status
Authenticate a connection based on the validated claims from the Authorization Server. When this is called, the access token has already been validated, and the claims have been retrieved from the access token and/or the Authorization Server (depending on how the OAuth2.ResourceServer is configured.) This method is used to determine the user context and roles to use for the connection. At a minimum the Username and Roles must be defined. For example, the following implementation will retrieve the Username from the subject ("sub") claim, and retrieve predefined role values from the scope claim. 
  set properties("Username") = claims.sub // use the subject claim as the username
  // extract the expected role names from the scope list:
  set scopeList = $listfromstring(claims.scope, " ")
  set roles = ""
  for r = "MyRole1","MyRole2","MyRole3" {
  	if $listfind(scopeList,r) {
  		set roles = roles_r_","
  	}
  }
  set properties("Roles") = $extract(roles,1,*-1)
  return $$$OK
See Security.Users for supported user properties.

Arguments:
  • claims - A %DynamicObject containing the claim values determined from the access token, OAuth2 introspection endpoint and/or the OpenID Connect userinfo endpoint.
  • oidc - A boolean flag indicating whether OpenID Connect claims are included in the claims array.
  • properties - A subscripted array containing, at a minimum, the Username and Roles to use for the connection.
Returns: a Status code indicating success or failure. Errors will be logged to the Audit Log.
method ProcessOIDC(claims As %DynamicObject, verified As %Boolean, Output properties As %String)
This convenience method will load the standard OpenID Connect claims into the associated properties array. The "EmailAddress", "PhoneNumber" and "FullName" properties will be mapped from the "email", "phone_number" and "name" fields, respectively.
  • claims - a %DynamicObject containing the claims associated with the access token. This should contain ODIC claims. see Authenticate()
  • verified - If true, the Email Address and Phone Number will only be included if they have been verified by the Authorization Server.
  • properties - Output - the properties array containing any matching fields found from the specified claims.

Inherited Members

Inherited Methods

Subclasses

FeedbackOpens in a new tab