5 Service Sets ToC Previous Next

5.6 Session Service Set ToC Previous Next

5.6.3 ActivateSession ToC Previous Next

5.6.3.1 Description ToC

This Service is used by the Client to specify the identity of the user associated with the Session. This Service request shall be issued by the Client before it issues any Service request other than CloseSession after CreateSession. Failure to do so shall cause the Server to close the Session.

Whenever the Client calls this Service the Client shall prove that it is the same application that called the CreateSession Service. The Client does this by creating a signature with the private key associated with the clientCertificate specified in the CreateSession request. This signature is created by appending the last serverNonce provided by the Server to the serverCertificate and calculating the signature of the resulting sequence of bytes.

Once used, a serverNonce cannot be used again. For that reason, the Server returns a new serverNonce each time the ActivateSession Service is called.

When the ActivateSession Service is called for the first time then the Server shall reject the request if the SecureChannel is not same as the one associated with the CreateSession request. Subsequent calls to ActivateSession may be associated with different SecureChannels. If this is the case then the Server shall verify that the Certificate the Client used to create the new SecureChannel is the same as the Certificate used to create the original SecureChannel. In addition, the Server shall verify that the Client supplied a UserIdentityToken that is identical to the token currently associated with the Session. Once the Server accepts the new SecureChannel it shall reject requests sent via the old SecureChannel.

The ActivateSession Service is used to associate a user identity with a Session. When a Client provides a user identity then it shall provide proof that it is authorized to use that user identity. The exact mechanism used to provide this proof depends on the type of the UserIdentityToken. If the token is a UserNameIdentityToken then the proof is the password that is included in the token. If the token is an X509IdentityToken then the proof is a signature generated with private key associated with the Certificate. The data to sign is created by appending the last serverNonce to the serverCertificate specified in the CreateSession response. If a token includes a secret then it should be encrypted using the public key from the serverCertificate.

Servers shall take proper measures to protect against attacks on user identity tokens. Such an attack is assumed if repeated connection attempts with invalid user identity tokens happen. One option is to lock out an OPC UA Client for a period of time if the user identity token validation fails several times. The OPC UA Client is either detected by IP address for unsecured connections or by the ApplicationInstanceUri for secured connections. Another option is delaying the Service response when the validation of a user identity fails. This delay time could be increased with repeated failures. Sporadic failures shall not delay connections with valid tokens.

Clients can change the identity of a user associated with a Session by calling the ActivateSession Service. The Server validates the signatures provided with the request and then validates the new user identity. If no errors occur the Server replaces the user identity for the Session. Changing the user identity for a Session may cause discontinuities in active Subscriptions because the Server may have to tear down connections to an underlying system and re-establish them using the new credentials.

When a Client supplies a list of locale ids in the request, each locale id is required to contain the language component. It may optionally contain the <country/region> component. When the Server returns a LocalizedText in the context of the Session, it also may return both the language and the country/region or just the language as its default locale id.

When a Server returns a string to the Client, it first determines if there are available translations for it. If there are, then the Server returns the string whose locale id exactly matches the locale id with the highest priority in the Client-supplied list.

If there are no exact matches, then the Server ignores the <country/region> component of the locale id, and returns the string whose <language> component matches the <language> component of the locale id with the highest priority in the Client supplied list.

If there still are no matches, then the Server returns the string that it has along with the locale id.

A Gateway Server is expected to impersonate the user provided by the Client when it connects to the underlying Server. This means it shall re-calculate the signatures on the UserIdentityToken using the nonce provided by the underlying Server. The Gateway Server will have to use its own user credentials if the UserIdentityToken provided by the Client does not support impersonation.

5.6.3.2 Parameters ToC

Table 17 defines the parameters for the Service.

Table 17 – ActivateSession Service Parameters

Name Type Description
Request    
   requestHeader RequestHeader Common request parameters. The type RequestHeader is defined in 7.28.
   clientSignature SignatureData This is a signature generated with the private key associated with the clientCertificate. This parameter is calculated by appending the serverNonce to the serverCertificate and signing the resulting sequence of bytes.
If the serverCertificate contains a chain, the signature calculation shall be done only with the leaf Certificate. For backward compatibility a Server shall check the signature with the full chain if the check with the leaf Certificate fails.
The SignatureAlgorithm shall be the AsymmetricSignatureAlgorithm specified in the SecurityPolicy for the Endpoint.
The SignatureData type is defined in 7.32.
   clientSoftwareCertificates [] SignedSoftwareCertificate Reserved for future use.
The SignedSoftwareCertificate type is defined in 7.33.
   localeIds [] LocaleId List of locale ids in priority order for localized strings. The first LocaleId in the list has the highest priority. If the Server returns a localized string to the Client, the Server shall return the translation with the highest priority that it can. If it does not have a translation for any of the locales identified in this list, then it shall return the string value that it has and include the locale id with the string. See OPC 10000-3 for more detail on locale ids. If the Client fails to specify at least one locale id, the Server shall use any that it has.
This parameter only needs to be specified during the first call to ActivateSession during a single application Session. If it is not specified the Server shall keep using the current localeIds for the Session.
   userIdentityToken Extensible Parameter
UserIdentityToken
The credentials of the user associated with the Client application. The Server uses these credentials to determine whether the Client should be allowed to activate a Session and what resources the Client has access to during this Session.
The UserIdentityToken is an extensible parameter type defined in 7.36.
The EndpointDescription specifies what UserIdentityTokens the Server shall accept.
Null or empty user token shall always be interpreted as anonymous.
   userTokenSignature SignatureData If the Client specified a user identity token that supports digital signatures, then it shall create a signature and pass it as this parameter. Otherwise the parameter is null.
The SignatureAlgorithm depends on the identity token type.
The SignatureData type is defined in 7.32.
     
Response    
   responseHeader ResponseHeader Common response parameters (see 7.29 for ResponseHeader definition).
   serverNonce ByteString A random number that should never be used in any other request.
This number shall have a minimum length of 32 bytes.
The Client shall use this value to prove possession of its Application Instance Certificate in the next call to ActivateSession request.
   results [] StatusCode List of validation results for the SoftwareCertificates (see 7.34 for StatusCode definition).
   diagnosticInfos [] DiagnosticInfo List of diagnostic information associated with SoftwareCertificate validation errors (see 7.8 for DiagnosticInfo definition). This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

5.6.3.3 Service results ToC

Table 18 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 18 – ActivateSession Service Result Codes

Symbolic Id Description
Bad_IdentityTokenInvalid See Table 177 for the description of this result code.
Bad_IdentityTokenRejected See Table 177 for the description of this result code.
Bad_UserAccessDenied See Table 177 for the description of this result code.
Bad_ApplicationSignatureInvalid The signature provided by the Client application is missing or invalid.
Bad_UserSignatureInvalid The user token signature is missing or invalid.
Bad_NoValidCertificates The Client did not provide at least one Software Certificate that is valid and meets the profile requirements for the Server.
Bad_IdentityChangeNotSupported The Server does not support changing the user identity assigned to the session.

Previous Next