AuthorizationServices provide Access Tokens to Clients that may use them to access resources. A Server, such as a GDS, with AuthorizationService capabilities may support one or more AuthorizationService Objects (see 9.6.4) which may represent an internal AuthorizationService or be an API to an external AuthorizationService. The AuthorizationService is best used in conjunction with the Role model defined in OPC 10000-5. In this scenario, the mapping rules assigned to the Roles known to the Server are used to populate an Access Token with the Roles associated with the UserIdentity provided when the Client submits the request. This scenario is illustrated in Figure 29.

Figure 29 – Roles and AuthorizationServices

When requesting Access Tokens from an AuthorizationService Object there are three primary use cases based on where the UserIdentityToken comes from: Implicit, Explicit and Chained. These use cases are discussed below. The Implicit and Explicit use cases are implementations of the ‘Indirect’ model for AuthorizationServices described in OPC 10000-4. The Chained use case is an implementation of the ‘Direct’ model.

AuthorizationServices restrict access to many of the features they provide. These restrictions are described either by referring to well-known Roles which a Session must have access to or by referring to Privileges which are assigned to Sessions using mechanisms other than the well-known Roles. The well-known Roles for an AuthorizationService are listed in Table 142.

Table 142 – Well-known Roles for an AuthorizationService

Name	Description
AuthorizationServiceAdmin	This Role grants the right to manage the configuration of an AuthorizationService.
SecurityAdmin	This Role grants the right to change the security configuration of an AuthorizationService.

The Privileges for an AuthorizationService are listed in Table 143.

Table 143 – Privileges for an AuthorizationService

Name	Description
AccessTokenRequestor	This Privilege grants an OPC UA Application the right to request AccessTokens. The Certificate used to create the SecureChannel is used to determine the identity of the OPC UA Application. A KeyCredential (see 8) provided as a UserIdentityToken may also be used to determine if the Client has access to this Privilege.

The implicit use case means the Client’s Application Certificate and any UserIdentityToken associated with the Session is used to determine whether an Access Token is permitted and what claims are available. This use case is illustrated in Figure 30.

Figure 30 – Implicit Authorization

The Target Server is the Server that the Client wishes to access. It publishes a UserTokenPolicy that indicates that it accepts Access Tokens from an Authorization Server. The parameters needed to connect to the Authorization Server are stored in the IssuerEndpointUrl field of the UserTokenPolicy and are defined in OPC 10000-6. Note these parameters are specified as a JSON object rather than a URL as implied by the field name. The ua:tokenEndpoint field specifies the NodeId of the AuthorizationService Object which then is used to request the Access Token.

The Client needs to be trusted by the Authorization Server and this could require the Client to present user credentials. These credentials can be provided to the Client out-of-band (e.g. an administrator specified them in the Client configuration file). The user credentials used can be any type of user credential including X.509 and JWT.

The Session with the Authorization Server may be created explicitly with a call to CreateSession or it can be implicit via a Session-less Method Call. The DiscoveryUrl for the Server containing the AuthorizationService is a parameter in the UserTokenPolicy.

With this use case, the Client uses the EndpointDescriptions provided by the Authorization Server to determine what credentials to provide when creating a Session. The NodeId of the UserTokenPolicies Property is the ua:authorizationEndpoint field in the UserTokenPolicy provided by the Server (see OPC 10000-6). If this NodeId is null Implicit authorization is required.

After creating the Session, the Client calls the RequestAccessToken Method on the AuthorizationService Object. The NodeId of the AuthorizationService Object is the ua:tokenEndpoint in the UserTokenPolicy. The Authorization Server determines if the Client is permitted to receive an Access Token and populates it with any claims granted to the Client. This claim may include Roles granted to the Session by applying the mapping rules for the Roles (see OPC 10000-3).

Once the Client has the Access Token, it passes the Access Token to the Target Server which validates the Access Token, as described in OPC 10000-4. The Target Server is configured out-of-band with the Certificate needed to validate the Access Tokens issued by the Authorization Server.

The explicit use case means the Client provides the UserIdentityToken used to determine whether an Access Token is permitted and what claims are available in the call to RequestAccessToken. This use case is illustrated in Figure 31.

Figure 31 – Explicit Authorization

The Target Server is the Server that the Client wishes to access. It publishes a UserTokenPolicy that indicates that it accepts Access Tokens from an Authorization Server. The parameters needed to connect to the Authorization Server are stored in the IssuerEndpointUrl field of the UserTokenPolicy and are defined in OPC 10000-6. More details are described by the Implicit use case in 9.3.

With this use case, the Client reads the UserTokenPolicies Property of the AuthorizationService to determine what credentials to provide in the RequestAccessToken Method. The NodeId of the UserTokenPolicies Property is the ua:authorizationEndpoint field in the UserTokenPolicy provided by the Server (see OPC 10000-6).

The Session may be created explicitly with a call to CreateSession or it can be implicit via a Session-less Method Call.

After creating the Session, the Client reads the available UserTokenPolicies from the AuthorizationService Object if it has not previously cached the information. It then chooses one that matches credentials that it has been provided out-of-band. The Client then calls the RequestAccessToken Method on the AuthorizationService Object.

The Authorization Server determines if the Client is permitted to receive an Access Token. The rest of the interactions are the same as described in 9.3.

The chained use case means the Client provides an Access Token issued by another AuthorizationService acting as an Identity Provider. This use case is illustrated in Figure 32.

Figure 32 – Chained Authorization

The Target Server is the Server that the Client wishes to access. The initial interactions are the same as with the Implicit use case described in 9.3.

The Session may be created explicitly with a call to CreateSession or it can be implicit via a Session-less Method Call.

After creating the Session, the Client reads the available UserTokenPolicies from the AuthorizationService Object if it has not previously cached the information. It then chooses one that references an Identity Provider for the user identities that it has available. The user identities may be provided out-of-band or they may be provided by an interactive user. The Client then requests an Access Token from the Identity Provider.

The Client then calls the RequestAccessToken Method on the AuthorizationService Object and passes the Access Token from the Identity Provider.

The Authorization Server determines if the Client is permitted to receive an Access Token based on the claims granted by the Identity Provider. The rest of the interactions are the same as described in 9.3.

The information model for AuthorizationServices which allow Clients to request Access Tokens from a Server is shown in Figure 33.

Figure 33 – The Model for Requesting Access Tokens from AuthorizationServices

This ObjectType represents a folder that contains AuthorizationService Objects which may be accessed via the Server. It is defined in Table 144.

Table 144 – AuthorizationServicesFolderType Definition

Attribute	Value
BrowseName	2:AuthorizationServicesFolderType
IsAbstract	False
References	NodeClass	BrowseName	TypeDefinition	Modelling Rule
Subtype of the FolderType defined in OPC 10000-5.
0:Organizes	Object	2:<ServiceName>	2:AuthorizationServiceType	OptionalPlaceholder
Conformance Units
GDS Authorization Service Server

This Object is an instance of AuthorizationServicesFolderType. It contains the AuthorizationService Objects which may be accessed via the GDS. It is the target of an Organizes reference from the Objects Folder defined in OPC 10000-5. It is defined in Table 145.

Table 145 – AuthorizationServices Object Definition

Attribute	Value
BrowseName	2:AuthorizationServices
TypeDefinition	2:AuthorizationServicesFolderType defined in 9.6.2.
References	NodeClass	BrowseName	TypeDefinition	Modelling Rule
Conformance Units
GDS Authorization Service Server

This ObjectType is the TypeDefinition for an Object that allows access to an AuthorizationService. It is defined in Table 146.

Table 146 – AuthorizationServiceType Definition

Attribute	Value
BrowseName	2:AuthorizationServiceType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the BaseObjectType defined in OPC 10000-5.
0:HasProperty	Variable	2:ServiceUri	0:String	0:PropertyType	Mandatory
0:HasProperty	Variable	2:ServiceCertificate	0:ByteString	0:PropertyType	Mandatory
0:HasProperty	Variable	2:UserTokenPolicies	0:UserTokenPolicy []	0:PropertyType	Optional
0:HasComponent	Method	2:GetServiceDescription	Defined in 9.6.6.		Mandatory
0:HasComponent	Method	2:RequestAccessToken	Defined in 9.6.5.		Optional
Conformance Units
GDS Authorization Service Server

The ServiceUri is a globally unique identifier that allows a Client to correlate an instance of AuthorizationServiceType with instances of AuthorizationServiceConfigurationType (see 9.7.4).

The ServiceCertificate is the Certificate required to check any Signature that is included with the Access Tokens. The ServiceCertificate may be a complete chain (see OPC 10000-6 for information on encoding chains).

The UserTokenPolicies Property specifies the UserIdentityTokens which are accepted by the RequestAccessToken Method.

The GetServiceDescription Method is used to read the metadata needed to request Access Tokens.

The RequestAccessToken Method is used to request an Access Token from the AuthorizationService.

RequestAccessToken is used to request an Access Token from an AuthorizationService. The scenarios where this Method is used are described fully in 9.3, 9.4 and 9.5.

The PolicyId and UserTokenType of the identityToken shall match one of the elements of the UserTokenPolicies Property. If the identityToken is not provided the Server should use the ApplicationInstanceCertificate and/or the UserIdentityToken provided for the Session (or the request if using a Session-less Method Call) to determine privileges.

If the associated UserTokenPolicy provides a SecurityPolicyUri, then the identityToken is encrypted and digitally signed using the format defined for UserIdentityToken secrets in OPC 10000-4.

This Method shall be called from an encrypted SecureChannel and from a Client that has access to the AccessTokenRequestor Privilege (see 9.2).

Signature

RequestAccessToken (

[in] UserIdentityToken identityToken

[in] String resourceId

[out] String accessToken

);

Argument	Description
identityToken	The identity used to authorize the Access Token request.
resourceId	The identifier for the Resource that the Access Token is used to access. This is usually the ApplicationUri for a Server.
accessToken	The Access Token granted to the application.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_IdentityTokenInvalid	The identityToken does not match one of the allowed UserTokenPolicies.
Bad_IdentityTokenRejected	The identityToken was rejected.
Bad_NotFound	The resourceId is not known to the Server.
Bad_UserAccessDenied	The current user does not have the rights required.
Bad_SecurityModeInsufficient	The SecureChannel is not encrypted.

Table 147 specifies the AddressSpace representation for the RequestAccessToken Method.

Table 147 – RequestAccessToken Method AddressSpace Definition

Attribute	Value
BrowseName	2:RequestAccessToken
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
0:HasProperty	Variable	0:InputArguments	0:Argument[]	0:PropertyType	Mandatory
0:HasProperty	Variable	0:OutputArguments	0:Argument[]	0:PropertyType	Mandatory

GetServiceDescription is used to read the metadata needed to request Access Tokens from the AuthorizationService.

Signature

GetServiceDescription (

[out] String serviceUri

[out] ByteString serviceCertificate

[out] UserTokenPolicy[] userTokenPolicies

);

Argument	Description
serviceUri	A globally unique identifier for the AuthorizationService.
serviceCertificate	The complete chain of Certificates needed to validate the Access Tokens provided by the AuthorizationService.
userTokenPolicies	The UserIdentityTokens accepted by the AuthorizationService.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_UserAccessDenied	The current user does not have the rights required.

Table 148 specifies the AddressSpace representation for the GetServiceDescription Method.

Table 148 – GetServiceDescription Method AddressSpace Definition

Attribute	Value
BrowseName	2:GetServiceDescription
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
0:HasProperty	Variable	0:OutputArguments	0:Argument[]	0:PropertyType	Mandatory

This event is raised when a AccessToken is issued.

This is the result of a RequestAccessToken Method completing.

This Event and it subtypes are security related and Servers shall only report them to users authorized to view security related audit events.

Its representation in the AddressSpace is formally defined in Table 149.

Table 149 – AccessTokenIssuedAuditEventType Definition

Attribute	Value
BrowseName	2:AccessTokenIssuedAuditEventType
IsAbstract	True
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the 0:AuditUpdateMethodEventType defined in OPC 10000-5.
Conformance Units
GDS Authorization Service Server

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.

The information model used to provide Servers with the information needed to accept Access Tokens from AuthorizationServices in Figure 34.

Figure 34 – The Model for Configuring Servers to use AuthorizationServices

If a Server is also a Client that needs to access the AuthorizationService, the necessary KeyCredentials can be provided with the push configuration management model (see 8.4).

This ObjectType represents a folder that contains AuthorizationServiceConfiguration Objects which may be accessed via the Server. It is defined in Table 150.

Table 150 – AuthorizationServicesConfigurationFolderType Definition

Attribute	Value
BrowseName	0:AuthorizationServicesConfigurationFolderType
IsAbstract	False
References	NodeClass	BrowseName	TypeDefinition	Modelling Rule
Subtype of the 0:FolderType defined in OPC 10000-5.
0:HasComponent	Object	0:<ServiceName>	0:AuthorizationServiceConfigurationType	OptionalPlaceholder
Conformance Units
Authorization Service Configuration Server

This Object is an instance of AuthorizationServicesConfigurationFolderType. It contains The AuthorizationServiceConfiguration Objects which may be accessed via the Server. It is the target of an HasComponent reference from the ServerConfiguration Object defined in 7.10.4. It is defined in Table 151.

Table 151 – AuthorizationServices Object Definition

Attribute	Value
BrowseName	0:AuthorizationServices
TypeDefinition	0:AuthorizationServicesConfigurationFolderType defined in 9.6.2.
References	NodeClass	BrowseName	TypeDefinition	Modelling Rule
Conformance Units
Authorization Service Configuration Server

This ObjectType is the TypeDefinition for an Object that allows the configuration of an AuthorizationService used by a Server. It is defined in Table 152.

Table 152 – AuthorizationServiceConfigurationType Definition

Attribute	Value
BrowseName	0:AuthorizationServiceConfigurationType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the 0:BaseObjectType defined in OPC 10000-5.
0:HasProperty	Variable	0:ServiceUri	0:String	0:PropertyType	Mandatory
0:HasProperty	Variable	0:ServiceCertificate	0:ByteString	0:PropertyType	Mandatory
0:HasProperty	Variable	0:IssuerEndpointUrl	0:String	0:PropertyType	Mandatory
Conformance Units
Authorization Service Configuration Server

The ServiceUri Property uniquely identifies the AuthorizationService.

The ServiceCertificate Property has the Certificate(s) needed to verify Access Tokens issued by the AuthorizationService. The value is the complete chain of Certificate needed for verification (see OPC 10000-6 for information on encoding chains).

The IssuerEndpointUrl is the value of the IssuerEndpointUrl in UserTokenPolicies which require the use of the AuthorizationService. The contents of this field depend on the AuthorizationService and are described in OPC 10000-6.

This type is used to serialize the AuthorizationService configuration. It is defined in Table 153.

This type is used as part of the ApplicationConfigurationDataType defined in 7.10.19 which allows multiple of AuthorizationServices in a Server to be updated at once.

The Name of the record is the name portion of the BrowseName of the associated AuthorizationServiceConfiguration Object in the AddressSpace.

If multiple ServiceCertificates are specified the first entry in the list is exposed with the ServerCertificate Property on the AuthorizationServiceConfiguration Obect.

Note that when a new AuthorizationServiceConfiguration is added, Clients need to browse the AuthorizationServices folder to discover the NodeId assigned by the Server that is needed for Certificate Management Methods.

Table 153 – AuthorizationServiceConfigurationDataType Structure

Name	Type	Description
AuthorizationServiceConfigurationDataType	Structure
ServiceUri	0:UriString	A URI uniquely identifies the AuthorizationService.
ServiceCertificate	0:ByteString[]	The CertificateChain needed to verify Access Tokens issued by the AuthorizationService. The Certificates appear in the array starting with the end-entity followed by its issuer.
Certificate	0:ByteString	The Certificate needed to verify Access Tokens issued by the AuthorizationService.
Issuers	0:ByteString[]	The Issuers needed to verify the Certificate. The Certificates appear in the array starting with the issuer of the Certificate.
ValidFrom	0:UtcTime	When the Certificate may be used to verify AccessTokens. If null then the Certificate can be used any time after ValidFrom field within the Certificate.
ValidTo	0:UtcTime	After this time, the Certificate may not be used to verify AccessTokens. If null there is no expiry time other than the ValidTo field within the Certificate.
IssuerEndpointSettings	0:String	The AuthorizationService specific settings that Clients need to know before requesting Access Tokens from the AuthorizationService. The syntax depends on the AuthorizationService.

Its representation in the AddressSpace is defined in Table 154.

Table 154 – AuthorizationServiceConfigurationDataType Definition

Attribute		Value
BrowseName		0:AuthorizationServiceConfigurationDataType
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:BaseConfigurationRecordDataType defined in 7.8.5.5.
Conformance Units
Authorization Service Configuration Server