The UserIdentityToken structure used in the Server Service Set allows Clients to specify the identity of the user they are acting on behalf of. The exact mechanism used to identify users depends on the system configuration. The different types of identity tokens are based on the most common mechanisms that are used in systems today. Table 185 defines the current set of user identity tokens. The ExtensibleParameter type is defined in 7.17.

Table 185 – UserIdentityToken parameterTypeIds

Symbolic Id	Description
AnonymousIdentityToken	No user information is available.
UserNameIdentityToken	A user identified by user name and password.
X509IdentityToken	A user identified by an X.509 v3 Certificate.
IssuedIdentityToken	A user identified by a token issued by an external Authorization Service.

The Client shall always prove possession of a UserIdentityToken when it passes it to the Server. Some tokens include a secret such as a password which the Server will accept as proof. In order to protect these secrets, the Token may be encrypted before it is passed to the Server. Other types of tokens allow the Client to create a signature with the secret associated with the Token. In these cases, the Client proves possession of a UserIdentityToken by creating a signature with the secret and passing it to the Server.

Each UserIdentityToken allowed by an Endpoint shall have a UserTokenPolicy specified in the EndpointDescription. The UserTokenPolicy specifies what SecurityPolicy to use when encrypting or signing. If this SecurityPolicy is null or empty then the Client uses the SecurityPolicy in the EndpointDescription. If the matching SecurityPolicy is set to None then no encryption or signature is required. The possible SecurityPolicies are defined in OPC 10000-7.

It is recommended that applications never set the SecurityPolicy to None for UserIdentityTokens that include a secret because these secrets could be used by an attacker to gain access to the system.

Clients shall validate the Server Certificate and ensure it is trusted before sending a UserIdentityToken encrypted with the Certificate.

The encrypted secret and Signature are embedded in a ByteString which is part of the UserIdentityToken. The format of this ByteString depends on the type of UserIdentityToken and the SecurityPolicy. Clients shall validate the Server Certificate and ensure it is trusted before sending a UserIdentityToken encrypted with the Certificate.

The legacy token secret format defined in 7.41.2.2 is not extensible and provides only encryption but the encrypted data is not signed. It is used together with the USERNAME UserIdentityToken. The password secret exchanged with this format shall not exceed 64 bytes. If the password exceeds 64 bytes, the EncryptedSecret format shall be used or the clear text password is sent over a SecureChannel that is encrypted.

The EncryptedSecret format defined in 7.41.2.3 provides an extensible secret format together with the definition how the secret is signed and encrypted. It allows for the layout to be updated as new token types are defined or new SecurityPolicies are added.

The EncryptedSecret format starts with a TypeId, EncodingMask and Length. These values allow a Server to determine how to handle the secret. If these fields are not valid and a USERNAME UserIdentityToken has been provided then the Server may attempt to handle the secret using the legacy token secret format. If these fields are valid but the TypeId is not recognized or not valid for the SecurityPolicy then the Server rejects the UserIdentityToken.

The UserIdentityToken types and the token formats supported by the Endpoint are identified by the UserTokenPolicy defined in 7.42.

To prevent the leakage of information useful to attackers, Servers shall ensure that the process of validating UserIdentityTokens completes in a fixed interval independent of whether an error occurs or not. The process of validation includes decrypting, check for padding and checking for a valid nonce. If any errors occur the return code is Bad_IdentityTokenInvalid.

Servers shall log details of any failure to validate a UserIdentityToken and shall lock out Client applications after five failures.

When encrypting a UserIdentityToken, the Client appends the last ServerNonce to the secret. The data is then encrypted with the public key from the Server’s Certificate.

A Client should not add any padding after the secret. If a Client adds padding then all bytes shall be zero. A Server shall check for padding added by Clients and ensure that all padding bytes are zeros. Servers shall reject UserIdentityTokens with invalid padding. Administrators shall be able to configure Servers to accept UserIdentityTokens with invalid padding.

If no encryption is applied, the structure is not used and only the secret without any Nonce is passed to the Server.

Table 186 describes how to serialize UserIdentityTokens before applying encryption.

Table 186 – Legacy UserIdentityToken Encrypted Token Secret Format

Name	Type	Description
Length	Byte [4]	The length of the data to be encrypted including the ServerNonce but excluding the length field. This field is a 4-byte unsigned integer encoded with the least significant bytes appearing first.
tokenData	Byte [*]	The token data.
serverNonce	Byte [*]	The last ServerNonce returned by the Server in the CreateSession or ActivateSession response.

The EncryptedSecret uses an extensible format which has the TypeId of a DataType Node as a prefix as defined for the ExtensionObject encoding in OPC 10000-6. The general layout of the EncryptedSecret is shown in Figure 39.

Figure 39 – EncryptedSecret layout

The TypeId specifies how the EncryptedSecret is serialized and secured. For example, the RsaEncryptedSecret requires that the KeyData be encrypted with the public key associated with the EncryptingCertificate before it is serialized.

The SecurityPolicyUri is used to determine what algorithms were used to encrypt and sign the data. Valid SecurityPolicyUris are defined in OPC 10000-7.

The payload is always encrypted using the symmetric encryption algorithm specified by the SecurityPolicyUri. The KeyData is used to create the keys used needed for the symmetric encryption. The structure of the KeyData depends on the EncryptedSecret DataType.

The EncryptedSecret is secured and serialized as follows:

• Serialize the common header;
• Serialize the KeyData;
• If required, encrypt the KeyData and append the result to the common header;
• Update the KeyDataLength with the length of the encrypted KeyData;
• Append the Nonce and the Secret to the encrypted KeyData;
• Calculate padding required on the payload and append after the Secret;
• Encrypt the payload;
• Calculate a Signature;
• Append the Signature.

Individual fields are serialized using the UA Binary encoding (see OPC 10000-6) for the DataType specified in Table 187. The Padding is used to ensure there is enough data to fill an integer multiple of encryption blocks. The size of the encryption block depends on the encryption algorithm. The total length of the Padding, not including the PaddingSize, is encoded as a UInt16. The individual bytes of the Padding are set to the least significant byte of the PaddingSize.

The EncryptedSecret is deserilized and validated as follows:

• Deserialize the common header;
• Verify the Signature if the KeyData is not encrypted;
• Decrypt the KeyData and verify the Signature if the KeyData is encrypted;
• Decrypt the payload;
• Verify the padding on the payload;
• Extract the Secret;

The fields in the EncryptedSecret are described in Table 187. The first three fields TypeId, EncodingMask and Length belong to the ExtensionObject encoding defined in OPC 10000-6.

Table 187 – EncryptedSecret layout

Name	Type	Description
TypeId	NodeId	The NodeId of the DataType Node.
EncodingMask	Byte	This value is always 1.
Length	Int32	The length of the data that follows including the Signature.
SecurityPolicyUri	String	The URI for the SecurityPolicy used to apply security.
Certificate	ByteString	The signing and/or encrypting Certificate.
SigningTime	DateTime	When the Signature was created.
KeyDataLength	UInt16	The length, in bytes, of the KeyData that follows If the KeyData is encrypted this is the length of the encrypted data; Otherwise, it is the length of the unencrypted data.
KeyData	Byte [*]	The key data used to create the keys needed for decrypting and verifying the payload. Each EncryptedSecret DataType describes how the key data is structured for different SecurityPolicies.
Nonce	ByteString	This is the last serverNonce returned in the CreateSession or ActivateSession Response when a UserIdentityToken is passed with the ActivateSession Request. If used outside of an ActivateSession call, the Nonce is created by the sender and is a function of the SecureChannelNonceLength.
Secret	ByteString	The secret to protect. The password when used with UserNameIdentityTokens. The tokenData when used with IssuedIdentityTokens. If the Secret is a String is it encoded using UTF-8 first.
PayloadPadding	Byte[*]	Additional padding added to ensure the size of the encrypted payload is an integer multiple of the InitializationVectorLength specified by the SecurityPolicyUri. If the InitializationVectorLength is less than 16 bytes then 16 bytes are used instead. The value of each byte is the least significant byte of the PayloadPaddingSize.
PayloadPaddingSize	UInt16	The size of the padding added to the payload.
Signature	Byte[*]	The Signature calculated after all encryption is applied. Each EncryptedSecret DataType describes how the Signature is calculated for different SecurityPolicies.

The PayloadPaddingSize adjusted with the following formula:

If (Secret.Length + PayloadPaddingSize < InitializationVectorLength) Then

PayloadPaddingSize = PayloadPaddingSize + InitializationVectorLength

Where the InitializationVectorLength is specified by the SymmetricEncryptionAlgorithm.

The currently available EncryptedSecret DataTypes are defined in Table 188.

Table 188 – EncryptedSecret DataTypes

Type Name	When to Use
RsaEncryptedSecret	Used when the SecurityPolicy requires the use of RSA cryptography. It is described in 7.41.2.4.
EccEncryptedSecret	Used when the SecurityPolicy requires the use of ECC cryptography.It is described in 7.41.2.5.

The RsaEncryptedSecret uses RSA based Asymmetric Cryptography.

Additional semantics for the fields in the EncryptedSecret layout for the RsaEncryptedSecret Structure are described in Table 189.

Table 189 – RsaEncryptedSecret structure

Name	Type	Description
TypeId	NodeId	The NodeId of the RsaEncryptedSecret DataType Node.
EncodingMask	Byte	See Table 187.
Length	UInt32	See Table 187.
SecurityPolicyUri	String	See Table 187.
Certificate	ByteString	The SHA1 hash of the DER form of the Certificate used to encrypt the KeyData.
SigningTime	DateTime	See Table 187.
KeyDataLength	UInt16	The length, in bytes, of the encrypted KeyData.
KeyData		The KeyData is encrypted with the PublicKey associated with the Certificate.
SigningKey	ByteString	The key used to compute the Signature.
EncryptingKey	ByteString	The key used to encrypt payload.
InitializationVector	ByteString	The initialization vector used with the EncryptingKey.
Nonce	ByteString	A Nonce. This is the last ServerNonce returned in the CreateSession or ActivateSession Response when proving a UserIdentityToken passed in the ActivateSession Request. In other contexts, this is a Nonce created by the sender with a length equal to the SecureChannelNonceLength.
Secret	ByteString	See Table 187.
PayloadPadding	Byte[*]	See Table 187.
PayloadPaddingSize	UInt16	See Table 187.
Signature	Byte[*]	The Signature calculated with the SigningKey. The Signature calculated is calculated after encrypting the KeyData and the payload.

The EccEncryptedSecret uses ECC based Asymmetric Cryptography.

Additional semantics for the fields in the EncryptedSecret layout for the EccEncryptedSecret Structure are described in Table 190.

The EccEncryptedSecret uses ECC EphemeralKeys to create the symmetric key used to encrypt the Secret. The handshake required to create and use the EphemeralKeys is described in OPC 10000-6.

Table 190 – EccEncryptedSecret Layout

Name	Type	Description
TypeId	NodeId	The NodeId of the EccEncryptedSecret DataType Node.
EncodingMask	Byte	See Table 187
Length	UInt32	See Table 187
SecurityPolicyUri	String	See Table 187
Certificate	ByteString	The signing Certificate encoded in DER form. The value shall include the entire chain. This value may be null or empty if the SigningCertificate is known to the receiver. This is true if the structure is used to provide a UserIdentityToken to a Server over a SecureChannel and the SigningCertificate is the Client ApplicationInstance Certificate.
SigningTime	DateTime	See Table 187
KeyDataLength	UInt16	The length of the KeyData without encryption.
KeyData		The KeyData is not encrypted.
SenderPublicKey	ByteString	The Public Key for the EphemeralKey created by the sender.
ReceiverPublicKey	ByteString	The Public Key for the EphemeralKey created by the receiver.
Nonce	ByteString	A Nonce. This is the last ServerNonce returned in the CreateSession or ActivateSession Response when proving a UserIdentityToken passed in the ActivateSession Request. In other contexts, this is a Nonce created by the sender with a length equal to the ½ of the SecureChannelNonceLength.
Secret	ByteString	See Table 187
PayloadPadding	Byte [*]	See Table 187
PayloadPaddingSize	UInt16	See Table 187
Signature	Byte [*]	When using AuthenticatedEncryption the Signature has two parts: the Signature produced when the secret is encrypted using the SymmetricEncryptionAlgorithm and the Signature calculated using the Certificate and the AsymmetricSignatureAlgorithm. Both Signatures are calculated from the start of the packet. The AsymmetricSignatureAlgorithm Signature includes the SymmetricEncryptionAlgorithm Signature. When using UnauthenticatedEncryption the Signature is only calculated using the Certificate and the AsymmetricSignatureAlgorithm.

The AnonymousIdentityToken is used to indicate that the Client has no user credentials.

Table 191 defines the AnonymousIdentityToken parameter.

Table 191 – AnonymousIdentityToken

Name	Type	Description
AnonymousIdentityToken	Structure	An anonymous user identity.
policyId	String	An identifier for the UserTokenPolicy that the token conforms to. The UserTokenPolicy structure is defined in 7.42. Servers that provide a null or empty PolicyId shall accept null or empty and treat them as equal.

The UserNameIdentityToken is used to pass simple username/password credentials to the Server.

This token shall be encrypted by the Client if required by the SecurityPolicy of the UserTokenPolicy. The Server should specify a SecurityPolicy for the UserTokenPolicy if the SecureChannel has a SecurityPolicy of None and no transport layer encryption is available. If None is specified for the UserTokenPolicy and SecurityPolicy is None then the password only contains the UTF-8 encoded password. The SecurityPolicy of the SecureChannel is used if no SecurityPolicy is specified in the UserTokenPolic y. The Server shall specify a SecurityPolicy for the UserTokenPolicy if the SecureChannel has a SecurityPolicy other than None and the MessageSecurityMode is not SIGNANDENCRYPT. See Table 193 for possible combinations.

If the token is to be encrypted the password shall be converted to a UTF-8 ByteString, encrypted and then serialized according to the following rules. When using an RSA based SecurityPolicy and the password exceeds 64 bytes, it is encrypted and serialized as described in 7.41.2.4. For passwords that do not exceed 64 bytes, it is encrypted and serialized as described in 7.41.2.2. When using the ECC based SecurityPolicies the password is encrypted and serialized as described in 7.41.2.5.

The Server shall decrypt the password and verify the ServerNonce.

If the SecurityPolicy is None then the password only contains the UTF-8 encoded password. This configuration should not be used unless the network traffic is encrypted in some other manner such as a VPN. The use of this configuration without network encryption would result in a serious security fault, in that it would cause the appearance of a secure user access, but it would make the password visible in clear text.

Table 192 defines the UserNameIdentityToken parameter.

Table 192 – UserNameIdentityToken

Name	Type	Description
UserNameIdentityToken	Structure	UserName value.
policyId	String	An identifier for the UserTokenPolicy that the token conforms to. The UserTokenPolicy structure is defined in 7.42. Servers that provide a null or empty PolicyId shall accept null or empty and treat them as equal.
userName	String	A string that identifies the user.
password	ByteString	The password for the user. The password can be an empty string. The format used for the encrypted data is described in 7.41.2.2.
encryptionAlgorithm	String	A string containing the URI of the AsymmetricEncryptionAlgorithm. The URI string values are defined names that may be used as part of the security profiles specified in OPC 10000-7. This parameter is null or empty if the password is not encrypted.

Table 193 describes the dependencies for selecting the AsymmetricEncryptionAlgorithm for the UserNameIdentityToken. The SecureChannel SecurityPolicy URI is specified in the EndpointDescription and used in subsequent OpenSecureChannel requests. The UserTokenPolicy SecurityPolicy URI is specified in the EndpointDescription. The encryptionAlgorithm is specified in the UserNameIdentityToken or IssuedIdentityToken provided by the Client in the ActivateSession call. The SecurityPolicy Other in the table refers to any SecurityPolicy other than None. The selection of the EncryptionAlgorithm is based on the UserTokenPolicy. The SecureChannel SecurityPolicy is used if the UserTokenPolicy is null or empty.

Table 193 – EncryptionAlgorithm selection

SecureChannel SecurityPolicy	SecureChannel SecurityMode	UserTokenPolicy SecurityPolicy	UserIdentityToken EncryptionAlgorithm
Security Policy - None	NONE	Null or empty	No encryption (a)
Security Policy - None	NONE	Security Policy - None	No encryption (a)
Security Policy - None	NONE	Security Policy - Other	Asymmetric algorithm for "Other"
Security Policy - Other	Other than NONE	Null or empty	Asymmetric algorithm for "Other"
Security Policy - Other	Other than NONE	Security Policy - Yet another	Asymmetric algorithm for "Yet another"
Security Policy - Other	Other than NONE	Security Policy - Other	Asymmetric algorithm for "Other"
Security Policy - Other	SIGNANDENCRYPT	Security Policy - None	No encryption but encrypted SecureChannel
Security Policy - Other	SIGN	Security Policy - None	Invalid configuration shall be rejected.
(a)The use of this configuration without network encryption would result in a serious security fault.

The X509IdentityToken is used to pass an X.509 v3 Certificate which is issued by the user.

This token shall always be accompanied by a Signature in the userTokenSignature parameter of ActivateSession if required by the SecurityPolicy. The Server should specify a SecurityPolicy for the UserTokenPolicy if the SecureChannel has a SecurityPolicy of None.

Table 194 defines the X509IdentityToken parameter.

Table 194 – X.509 v3 Identity Token

Name	Type	Description
X509IdentityToken	structure	X.509 v3 value.
policyId	String	An identifier for the UserTokenPolicy that the token conforms to. The UserTokenPolicy structure is defined in 7.42. Servers that provide a null or empty PolicyId shall accept null or empty and treat them as equal.
certificateData	ByteString	The X.509 v3 Certificate in DER format.

The IssuedIdentityToken is used to pass SecurityTokens issued by an external Authorization Service to the Server. These tokens may be text or binary.

OAuth2 defines a standard for Authorization Services that produce JSON Web Tokens (JWT). These JWTs are passed as an Issued Token to an OPC UA Server which uses the signature contained in the JWT to validate the token. OPC 10000-6 describes OAuth2 and JWTs in more detail. If the token is encrypted, it shall use the EncryptedSecret format defined in 7.41.2.3.

This token shall be encrypted by the Client if required by the SecurityPolicy of the UserTokenPolicy. The Server should specify a SecurityPolicy for the UserTokenPolicy if the SecureChannel has a SecurityPolicy of None and no transport layer encryption is available. The SecurityPolicy of the SecureChannel is used If no SecurityPolicy is specified in the UserTokenPolic y.

If the SecurityPolicy is not None, the tokenData shall be encoded in UTF-8 (if it is not already binary), signed and encrypted according the rules specified for the tokenType of the associated UserTokenPolicy (see 7.42).

If the SecurityPolicy is None then the tokenData only contains the UTF-8 encoded tokenData. This configuration should not be used unless the network is encrypted in some other manner such as a VPN. The use of this configuration without network encryption would result in a serious security fault, in that it would cause the appearance of a secure user access, but it would make the token visible in clear text.

IssuedIdentityTokens have an expiration time, and a Server shall invalidate the credentials of the Session within a configurable time after the token expires. The Session shall stay valid with an Anonymous user token if the Server allows Anonymous users. Clients should renew the token with ActivateSession before the expiration time to avoid communication interruption.

Table 195 defines the IssuedIdentityToken parameter.

Table 195 – IssuedIdentityToken

Name	Type	Description
IssuedIdentityToken	structure	The token provided by an Authorization Service.
policyId	String	An identifier for the UserTokenPolicy that the token conforms to. The UserTokenPolicy structure is defined in 7.42. Servers that provide a null or empty PolicyId shall accept null or empty and treat them as equal.
tokenData	ByteString	The text or binary representation of the token. The format of the data depends on the associated UserTokenPolicy.
encryptionAlgorithm	String	The URI of the AsymmetricEncryptionAlgorithm. The list of OPC UA-defined names that may be used is specified in OPC 10000-7. See Table 193 for details on picking the correct URI. This parameter is null or empty if the tokenData is not encrypted or if the EncryptedSecret format is used.