Skip to main content

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.

Property Inventory

Method Inventory

Parameters

parameter RESOURCEREQUIRED = %Admin_OAuth2_Client;
parameter VERSION = 1;

Properties

deprecated property AuthorizationEndpoint as %OAuth2.uri;
**** Moved to OAuth2.Server.Metadata when dynamic client support introduced
https://docs.intersystems.com/latest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&PRIVATE=1&CLASSNAME=OAuth2.Server.Metadata#PROPERTY_authorization_endpoint
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 (XMLPROJECTION = "NONE") [ 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()
deprecated property IntrospectionEndpoint as %OAuth2.uri;
**** Moved to OAuth2.Server.Metadata when dynamic client support introduced
https://docs.intersystems.com/latest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&PRIVATE=1&CLASSNAME=OAuth2.Server.Metadata#PROPERTY_introspection_endpoint
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()
deprecated property RevocationEndpoint as %OAuth2.uri;
**** Moved to OAuth2.Server.Metadata when dynamic client support introduced
https://docs.intersystems.com/latest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&PRIVATE=1&CLASSNAME=OAuth2.Server.Metadata#PROPERTY_revocation_endpoint
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()
deprecated property TokenEndpoint as %OAuth2.uri;
**** Moved to OAuth2.Server.Metadata when dynamic client support introduced
https://docs.intersystems.com/latest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&PRIVATE=1&CLASSNAME=OAuth2.Server.Metadata#PROPERTY_token_endpoint
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()
deprecated property UserinfoEndpoint as %OAuth2.uri;
**** Moved to OAuth2.Server.Metadata when dynamic client support introduced
https://docs.intersystems.com/latest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&PRIVATE=1&CLASSNAME=OAuth2.Server.Metadata#PROPERTY_userinfo_endpoint
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 Create(IssuerEndpoint As %String, ByRef Properties As %String)
Create an OAuth2 ServerDefinition IssuerEndpoint - OAuth2 Server defintion's issuer endpoint Properties - Array of properties corresponding to the class properties Invalid or deprecated properties will return an error
classmethod DeleteByIssuer(IssuerEndpoint As %String) as %Status
Delete this server definition. IssuerEndpoint - issuer endpoint of the OAuth2.ServerDefinition to delete This method does not return an error when deleting an object that already doesn't exist
classmethod DeleteId(id As %String) as %Status
Delete this server definition.
classmethod DiscoverServer(IssuerEndpoint As %String, SSLConfiguration As %String)
Create an OAuth2 ServerDefinition with discovery IssuerEndpoint - OAuth2 Server defintion's issuer endpoint SSLConfiguration - Name of SSL configuration to use for OAuth2 Server defintion
classmethod Exists(IssuerEndpoint As %String, Output ServerDefinition As %ObjectHandle, Output Status As %Status) as %Boolean
This method checks for the existence of an OAuth2 Server Definition Parameters: IssuerEndpoint= IssuerEndpoint of the OAuth2.ServerDefinition to check existence Return values: If Value of the method = 0 (ServerDefinition does not exist, or some error occured) ServerDefinition = Null Status = ServerDefinition does not exist, or other error message If Value of the method = 1 (ServerDefinition exists) ServerDefinition = Object handle to ServerDefinition Status = $$$OK
classmethod Export(FileName As %String = "OAuth2ServerDefinitionExport.xml", Servers As %String = "*", Output NumExported As %Integer) as %Status
This method exports OAuth2 Server Definitions and their respective Client configurations to a file in xml format.
Parameters:
Filename - Output file name
Servers - Comma separated list of IssuerEndpoints to export the associated Server Definitions, "*" = All NumExported (byref) - Returns number of server definitions exported.
classmethod Import(FileName As %String = "OAuth2ServerDefinitionExport.xml", Output NumImported As %Integer, Flags As %Integer = 0) as %Status
Import OAuth2 Server Definitions from an xml file.
Parameters:
FileName - Filename to import OAuth2 Server Definitions from
NumImported (byref) - Returns number of Server Definitions imported
Flags - Control import
Bit 0 - Do not import records, just return count
Note: On failure, no records will be imported
classmethod Modify(IssuerEndpoint As %String, ByRef Properties As %String)
Modify the OAuth2 ServerDefinition for this instance IssuerEndpoint - OAuth2 Server defintion's issuer endpoint Properties - Array of properties corresponding to the class properties Invalid or deprecated properties will return an error Note: The Clients property cannot be modified with this method. Use OAuth2.Client:Modify() to add a client to this ServerDefinition.
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()

Inherited Members

Inherited Methods

FeedbackOpens in a new tab