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.

image023.png

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.

image024.png

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.

image025.png

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.

image026.png

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.

image027.png

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.

image028.png

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.