9.6 Information Model for Requesting AccessTokens

9.6.1 Overview

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

9.6.2 AuthorizationServicesFolderType

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

9.6.3 AuthorizationServices

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

9.6.4 AuthorizationServiceType

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

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

The ServiceCertificate Property contains the Certificate required to check any Signature that is included with the AccessTokens. The ServiceCertificate may be a complete chain (see OPC 10000-6 for information on encoding chains). CRLs are not used by the target Server when verifying AccessTokens. It is the responsibility of the AuthorizationService to verify that the ServiceCertificate is not revoked or otherwise invalid before returning any AccessToken to Clients. When a CertificateManager pushes the configuration to a target Server, the CertificateManager is responsible for verifying the ServiceCertificate and automatically updating the target Server if the ServiceCertificate is revoked.

The UserTokenPolicies Property specifies the UserIdentityTokens which are accepted by the RequestAccessToken or FinishRequestToken Methods.

The SupportedRoles Property specifies the system-wide Roles which may be included in an AccessToken. Each target Server uses mapping rules (see OPC 10000-18) to specify the relationship between the system-wide Roles and Roles known to the target Server.

The GetServiceDescription Method is used to read the metadata used to request AccessTokens.

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

The StartRequestToken Method initiates a request for an AccessToken from the AuthorizationService.

The FinishRequestToken Method completes a request for an AccessToken from the AuthorizationService.

The RefreshToken Method is used to request an updated AccessToken.

9.6.5 RequestAccessToken (Deprecated)

It is deprecated because it can only be used with unencrypted UserName IdentityTokens. Use StartRequestToken instead.

RequestAccessToken is used to request an AccessToken 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
);

Method Result Codes (defined in Call Service)

Table 148 specifies the AddressSpace representation for the RequestAccessToken Method.

9.6.6 StartRequestToken

The StartRequestToken Method is used to initiate a new request for an AccessToken.

The PolicyId provided shall identify one of the UserTokenPolicies for the AuthorizationService Object.

The contents of the RequestorData and ServiceData depend on the UserTokenType and the SecurityPolicy. Table 149 specifies the contents for different combinations of UserTokenType and SecurityPolicy.

The AuthorizationService cleans up unused requestIds. Client should call FinishRequestToken immediately after this Method returns. The RequestId is only accessible via the current Session and resources are freed when the Session is closed.

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

Signature

StartRequestToken(
	[in]  String ResourceId
	[in]  String PolicyId
	[in]  ByteString RequestorData
	[out] ByteString ServiceData
	[out] Guid RequestId
);

Method Result Codes (defined in Call Service)

Table 150 specifies the AddressSpace representation for the StartRequestToken Method.

9.6.7 FinishRequestToken

The FinishRequestToken Method is used to complete a request for an AccessToken from an AuthorizationService. It is called after calling StartRequestToken defined in 9.6.6.

The RequestedRoles are used to restrict the permissions that are granted to the AccessToken. If RequestedRoles are not provided the AuthorizationService includes all Roles available to the UserIdentityToken provided in the call. The SupportedRoles Property provides all Roles supported by the AuthorizationService.

The UserIdentityToken contains the credentials that the AccessToken will represent.

The UserTokenSignature is computed using the channel bound signatures defined in OPC 10000-4 where the ServiceData replaces the ServerNonce and the RequestorData replaces the ClientNonce.

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

Signature

FinishRequestToken (
  [in]  Guid RequestId
	[in]  String[] RequestedRoles
	[in]  UserIdentityToken UserIdentityToken
	[in]  SignatureData UserTokenSignature
	[out] String AccessToken
	[out] DateTime AccessTokenExpiryTime
	[out] String RefreshToken
	[out] DateTime RefreshTokenExpiryTime

);

Method Result Codes (defined in Call Service)

Table 148 specifies the AddressSpace representation for the FinishRequestToken Method.

9.6.8 RefreshToken

The RefreshToken Method is used to request an AccessToken from an AuthorizationService using a cached RefreshToken.

The CurrentRefreshToken shall only be accepted if the ClientCertificate used to create the SecureChannel is the same as the ClientCertificate used when the FinishRequestToken Method returned the original RefeshToken.

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

Signature

RefreshToken ( 
	[in]  String ResourceId
	[in]  String CurrentRefreshToken
	[out] String AccessToken
	[out] DateTime AccessTokenExpiryTime
	[out] String NewRefreshToken
	[out] DateTime NewRefreshTokenExpiryTime
	
);

Method Result Codes (defined in Call Service)

Table 148 specifies the AddressSpace representation for the RequestAccessToken Method.

9.6.9 GetServiceDescription

The GetServiceDescription Method is used to read the metadata needed to request AccessTokens from the AuthorizationService.

Signature

GetServiceDescription ( 
	[out] String ServiceUri
	[out] ByteString ServiceCertificate
	[out] UserTokenPolicy[] UserTokenPolicies
);

Method Result Codes (defined in Call Service)

Table 153 specifies the AddressSpace representation for the GetServiceDescription Method.

9.6.10 AccessTokenRequestedAuditEventType

This event is raised when a AccessToken is requested as a result of a FinishRequestToken Method being called.

This Event and its 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 155.

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

9.6.11 AccessTokenIssuedAuditEventType

This event is raised when a AccessToken is issued.

This is the result of a RequestAccessToken Method completing.

This Event and its 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 155.

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