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.2) 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 27.

Figure 27 – 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 102.

Table 102 – 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 103.

Table 103 – 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 0) 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 28.

Figure 28 – 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 at a URL specified in the policy. The policy also contains 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 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 calls the RequestAccessToken Method on the AuthorizationService Object. 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 claims 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 29.

Figure 29 – Explicit 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 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 30.

Figure 30 – 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 31.

Figure 31 – 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 104.

Table 104 – 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 105.

Table 105 – 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 106.

Table 106 – 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 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.

For UserNameIdentityTokens the secret is the password and the signature is created with the Client ApplicationInstanceCertificate. The signed and encrypted secret is passed in the password field.

For X.509 v3 IdentityTokens the secret is null and signature is created with the key associated with user Certificate. The signed and encrypted secret is passed in the certificateData field.

For IssuedIdentityTokens the secret is the token and the signature is created with the key associated a user Certificate or the Client ApplicationInstanceCertificate. The signed and encrypted secret is passed in the tokenData field.

The Server shall check the signingTime in against the current system clock. The Server shall reject the request if the signingTime is outside of a configurable range. A suitable default value is 5 minutes. The permitted clock skew is a Server configuration parameter.

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 107 specifies the AddressSpace representation for the RequestAccessToken Method.

Table 107 – 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 108 specifies the AddressSpace representation for the GetServiceDescription Method.

Table 108 – 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 109.

Table 109 – 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 32.

Figure 32 – 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 110.

Table 110 – AuthorizationServicesFolderType 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 FolderType. 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.3. It is defined in Table 111.

Table 111 – 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 112.

Table 112 – 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. This contents of the field depend on the AuthorizationService and are described in OPC 10000-6.