Authorization Services provide Access Tokens to Clients that may use them to access resources. A Server, such as a GDS, with Authorization Service capabilities may support one or more AuthorizationService Objects (see 9.5.2) which may represent an internal Authorization Service or be an API to an external Authorization Service. The Authorization Service 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 20.

Figure 20 – Roles and Authorization Services

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 Authorization Services described in OPC 10000-4. The Chained use case is an implementation of the ‘Direct’ model.

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 21.

Figure 21 – 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 the 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 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 22.

Figure 22 – 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.2.

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

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

Figure 23 – 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.2.

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

The information model for Authorization Services which allow Clients to request Access Tokens from a Server is shown in Figure 24.

Figure 24 – The Model for Requesting Access Tokens from Authorization Services

This Object is an instance of FolderType. 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 61.

Table 61 – AuthorizationServices Object Definition

Attribute	Value
BrowseName	AuthorizationServices
Namespace	GDS (see 3.3)
TypeDefinition	FolderType defined in OPC 10000-5.
References	NodeClass	BrowseName	TypeDefinition	Modelling Rule

This ObjectType is the TypeDefinition for an Object that allows access to an Authorization Service. It is defined in Table 62.

Table 62 – AuthorizationServiceType Definition

Attribute	Value
BrowseName	AuthorizationServiceType
Namespace	GDS (see 3.3)
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the BaseObjectType defined in OPC 10000-5.
HasProperty	Variable	ServiceUri	String	PropertyType	Mandatory
HasProperty	Variable	ServiceCertificate	ByteString	PropertyType	Mandatory
HasProperty	Variable	UserTokenPolicies	UserTokenPolicy []	PropertyType	Optional
HasComponent	Method	GetServiceDescription		Defined in 9.5.5.	Mandatory
HasComponent	Method	RequestAccessToken		Defined in 9.5.4.	Optional

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

The ServiceCertificate is the complete chain of Certificates needed to validate the Access Tokens (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 Authorization Service.

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

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 v3IdentityTokens 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 requires an encrypted channel and that the Client provides credentials with administrative rights for the application which is having the credentials revoked.

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.

Table 63 specifies the AddressSpace representation for the RequestAccessToken Method.

Table 63 – RequestAccessToken Method AddressSpace Definition

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

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

Signature

GetServiceDescription (

[out] String serviceUri

[out] ByteString serviceCertificate

[out] UserTokenPolicy[] policies

);

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

Method Result Codes (defined in Call Service)

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

Table 64 specifies the AddressSpace representation for the GetServiceDescription Method.

Table 64 – GetServiceDescription Method AddressSpace Definition

Attribute	Value
BrowseName	GetServiceDescription
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	OutputArguments	Argument[]	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 65.

Table 65 – AccessTokenIssuedAuditEventType Definition

Attribute	Value
BrowseName	AccessTokenIssuedAuditEventType
Namespace	GDS (see 3.3)
IsAbstract	True
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the AuditUpdateMethodEventType defined in OPC 10000-5.

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 Authorization Services in Figure 24.

Figure 25 – The Model for Configuring Servers to use Authorization Services

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

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.7.2. It is defined in Table 61.

Table 66 – AuthorizationServices Object Definition

Attribute	Value
BrowseName	AuthorizationServices
Namespace	CORE (see 3.3)
TypeDefinition	FolderType defined in OPC 10000-5.
References	NodeClass	BrowseName	TypeDefinition	Modelling Rule

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

Table 67 – AuthorizationServiceConfigurationType Definition

Attribute	Value
BrowseName	AuthorizationServiceConfigurationType
Namespace	CORE (see 3.3)
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the BaseObjectType defined in OPC 10000-5.
HasProperty	Variable	ServiceUri	String	PropertyType	Mandatory
HasProperty	Variable	ServiceCertificate	ByteString	PropertyType	Mandatory
HasProperty	Variable	IssuerEndpointUrl	String	PropertyType	Mandatory

The ServiceUri Property uniquely identifies the Authorization Service.

The ServiceCertificate Property has the Certificate(s) needed to verify Access Tokens issued by the Authorization Service. 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 Authorization Service. This contents of the field depend on the Authorization Service and are described in OPC 10000-6.