OAuth2.ServerDefinition

persistent class OAuth2.ServerDefinition extends %Library.Persistent, %XML.Adaptor, %SYSTEM.Help

SQL Table Name: OAuth2.ServerDefinition

OAuth2. ServerDefinition is a persistent class which defines an authorization server which is available to this InterSystems IRIS instance for OAuth 2.0 client definition. The authorization server definition may be used by multiple client application definitions.

Method Inventory

ClientCount()
DeleteId()
Open()
OpenByIssuer()
RefreshJWKS()
SetPublicJWKS()
UpdateJWKS()
ValidateJWT()

Parameters

parameter RESOURCEREQUIRED = %Admin_OAuth2_Client;

Properties

property AuthorizationEndpoint as %OAuth2.uri;

**** Moved to OAuth2.Server.Metadata when dynamic client support introduced
The endpoint URL to be used for to request an authorization code from the authorization server.
Required if ClientType is public or confidential.
Based on Authorization Server documentation.

Property methods: AuthorizationEndpointDisplayToLogical(), AuthorizationEndpointGet(), AuthorizationEndpointGetStored(), AuthorizationEndpointIsValid(), AuthorizationEndpointLogicalToDisplay(), AuthorizationEndpointLogicalToOdbc(), AuthorizationEndpointNormalize()

relationship Clients as array of OAuth2.Client [ InitialExpression = $listbuild("OAuth2.Client","ServerDefinition",+$this,"many",1,1) , Transient , Inverse = ServerDefinition , Cardinality = many ];

The clients that use this server defintion.

Property methods: ClientsGet(), ClientsGetObject(), ClientsGetObjectId(), ClientsGetSwizzled(), ClientsIsEmpty(), ClientsIsValid(), ClientsNewObject(), ClientsRClose(), ClientsRExec(), ClientsRFetch(), ClientsRelate(), ClientsSQLCompute(), ClientsSet(), ClientsUnRelate()

property InitialAccessToken as %String);

The optional initial registration access token which may be specified out of band and is used as a bearer token to authorize the synamic client registartion request.

Property methods: InitialAccessTokenDisplayToLogical(), InitialAccessTokenGet(), InitialAccessTokenGetStored(), InitialAccessTokenIsValid(), InitialAccessTokenLogicalToDisplay(), InitialAccessTokenLogicalToOdbc(), InitialAccessTokenNormalize(), InitialAccessTokenSet()

property IntrospectionEndpoint as %OAuth2.uri;

**** Moved to OAuth2.Server.Metadata when dynamic client support introduced
The endpoint URL to be used for to make a RFC 7662 based token introspection request using the client_id and client_secret for authorization.

Property methods: IntrospectionEndpointDisplayToLogical(), IntrospectionEndpointGet(), IntrospectionEndpointGetStored(), IntrospectionEndpointIsValid(), IntrospectionEndpointLogicalToDisplay(), IntrospectionEndpointLogicalToOdbc(), IntrospectionEndpointNormalize()

property IssuerEndpoint as %String (COLLATION = "EXACT") [ Required ];

The endpoint URL to be used to identify the authorization server.
Required for all ClientTypes.

Property methods: IssuerEndpointDisplayToLogical(), IssuerEndpointGet(), IssuerEndpointGetStored(), IssuerEndpointIsValid(), IssuerEndpointLogicalToDisplay(), IssuerEndpointLogicalToOdbc(), IssuerEndpointNormalize()

property Metadata as OAuth2.Server.Metadata;

The meta data which describes this authorization server,

Property methods: MetadataGet(), MetadataGetObject(), MetadataGetObjectId(), MetadataGetStored(), MetadataGetSwizzled(), MetadataIsValid(), MetadataNewObject(), MetadataSet(), MetadataSetObject(), MetadataSetObjectId(), MetadataUnSwizzle()

property RevocationEndpoint as %OAuth2.uri;

**** Moved to OAuth2.Server.Metadata when dynamic client support introduced
The endpoint URL to be used for to make a RFC 7009 based token revocation request using the client_id and client_secret for authorization.

Property methods: RevocationEndpointDisplayToLogical(), RevocationEndpointGet(), RevocationEndpointGetStored(), RevocationEndpointIsValid(), RevocationEndpointLogicalToDisplay(), RevocationEndpointLogicalToOdbc(), RevocationEndpointNormalize()

property SSLConfiguration as %String (MAXLEN = 64, MINLEN = 1);

The name of the activated TLS/SSL configuration to use for authorization server Discovery requests.
Chosen by user during configuration.

Property methods: SSLConfigurationDisplayToLogical(), SSLConfigurationGet(), SSLConfigurationGetStored(), SSLConfigurationIsValid(), SSLConfigurationLogicalToDisplay(), SSLConfigurationLogicalToOdbc(), SSLConfigurationNormalize(), SSLConfigurationSet()

property ServerCredentials as %String;

ServerCredentials is the alias of the %SYS.X509Credentials object which contains the server's certificate.

Property methods: ServerCredentialsDisplayToLogical(), ServerCredentialsGet(), ServerCredentialsGetStored(), ServerCredentialsIsValid(), ServerCredentialsLogicalToDisplay(), ServerCredentialsLogicalToOdbc(), ServerCredentialsNormalize(), ServerCredentialsSet()

property TokenEndpoint as %OAuth2.uri;

**** Moved to OAuth2.Server.Metadata when dynamic client support introduced
The endpoint URL to be used for to request an access token from the authorization server.
Required for all ClientTypes.
Based on Authorization Server documentation.

Property methods: TokenEndpointDisplayToLogical(), TokenEndpointGet(), TokenEndpointGetStored(), TokenEndpointIsValid(), TokenEndpointLogicalToDisplay(), TokenEndpointLogicalToOdbc(), TokenEndpointNormalize()

property UserinfoEndpoint as %OAuth2.uri;

**** Moved to OAuth2.Server.Metadata when dynamic client support introduced
The endpoint URL to be used for to make a userinfo request using an access token from the authorization server for authorization

Property methods: UserinfoEndpointDisplayToLogical(), UserinfoEndpointGet(), UserinfoEndpointGetStored(), UserinfoEndpointIsValid(), UserinfoEndpointLogicalToDisplay(), UserinfoEndpointLogicalToOdbc(), UserinfoEndpointNormalize()

Methods

method ClientCount() as %Integer

Get count of clients for this server definition

classmethod DeleteId(id As %String) as %Status

Delete this server definition.

classmethod Open(serverDefinitionId As %String, Output sc As %Status) as OAuth2.ServerDefinition

Open the OAuth2.ServerDefinition instance.

classmethod OpenByIssuer(issuerEndpoint As %String, Output sc As %Status) as OAuth2.ServerDefinition

Open an OAuth2.ServerDefinition instance based on the IssuerEndpoint property

method RefreshJWKS(force As %Boolean = 0, save As %Boolean = 1, Output sc As %Status) as %Boolean

If the server's public JWKS was specified using the jwks_uri metadata parameter, this method will fetch the jwks if it has expired.

Parameters:

force - refresh the jwks even if the cached version is still valid (default is 0)
save - save the server definition (default is 1)
sc (output) - Status code structure containing any errors

Returns:

1 - if the jwks was updated
0 - if the cached version was still valid

method SetPublicJWKS(publicJWKS As %String = "", jwksUri As %String = "") as %Status

Manually set the authorization server supplied public JWKS and optionally jwks_uri.

deprecated method UpdateJWKS(Output sc As %Status) as %Status

Get and save a new public JWKS for the authorization server if the JWKS was specified using jwks_uri metadata. Returns a status code.
This method is deprecated. New code should use RefreshJWKS() instead.

method ValidateJWT(jwt As %String, scope As %String = "", aud As %String = "", sigJWKS As %String = "", encJWKS As %String = "", retry As %Boolean = 1, Output ops As %DynamicObject) as %DynamicObject

Validate the given JWT using the given JWKS values. This authorization server's public JWKS will be added. In addition to the optional scope and aud validation, the iss claim will be validated against the IssuerEndpoint and the exp and nbf field will be validated using the current time.

Parameters:

jwt - The JWT to validate.
scope - optional a blank separated list of scopes that must be contained in the JWT.
aud - optional the expected audience.
sigJWKS - optional the JWKS to use to validate signatures, in addition to this server's public JWKS. Typically this is only needed if the JWT was signed with a symmetric algorithm.
encJWKS - optional the JWKS to use to decrypt the JWT. Only needed if the token is encrypted.
retry - If true (the default) and validation fails we will refresh the server's JWKS and retry. This will account for the server rotating it's public key.
ops - An array of the encryption and signing operations that were performed on the JWT. See %Net.JSON.JWT for details.

Returns: a %DynamicObject representing the claims contained in the JWT.

This method throws exceptions on failure.

Queries

query List()

SQL Query:
SELECT ID, IssuerEndpoint, ( SELECT COUNT(*) FROM Client WHERE ServerDefinition->ID = sd.ID ) AS ClientCount, ( SELECT COUNT(*) FROM ResourceServer WHERE ServerDefinition->ID = sd.ID ) AS ResourceCount FROM ServerDefinition as sd ORDER BY IssuerEndpoint

List authorization servers available to client applications for SMP page

Indexes

index (IDKEY on ) [IdKey, Type = key];

Index methods: IDKEYCheck(), IDKEYDelete(), IDKEYExists(), IDKEYOpen(), IDKEYSQLCheckUnique(), IDKEYSQLExists(), IDKEYSQLFindPKeyByConstraint(), IDKEYSQLFindRowIDByConstraint()