User Authentication

User authentication identifies the application user associated with a message.

The sender of a message may optionally identify the user by including one of two types of data:

• User authentication data with the user credentials.
• A user ID token containing the user identity.

A message may also choose to include both user authentication data and a user ID token to confirm that the user is still in possession of their user credentials and that the user credentials have not been revoked. In this case the user authentication data and user ID token must both identify the same user or the message will be rejected. The frequency at which this occurs should be chosen to achieve a balance between confidence of a user’s identity and the cost of performing user authentication, and should be enforced by the entity receives the message.

It is generally desirable to migrate from user authentication to user ID token authentication because:

• Authentication of user credentials is generally more computationally expensive.
• Limiting the time during which user credentials are known reduces the chance of accidental leakage.

User authentication must occur after entity authentication, although possibly within the same MSL transaction. User authentication only applies to messages that are associated with a user; messages may be associated with an entity without also being associated with a user.

Since users must interact with the sending application to provide the initial user credentials, associating messages with specific users is entirely dictated by the sending application. This should be taken into consideration by the receiving application: a modified or erroneous sending application may have associated a message with an incorrect user, with a user when the message should not be associated with a user, or without a user when the message should be associated with a user.

User Authentication Data

The following are some examples of user authentication schemes and their corresponding user authentication data contents. A more detailed description of user authentication schemes is documented in the Configuration Guide.

Scheme	User Authentication Data
Email/Password	User email address and password.
HTTP Cookies	User HTTP cookies.

User Authentication Data Representation

userauthdata = {
  "#mandatory" : [ "scheme", "authdata" ],
  "scheme" : "string",
  "authdata" : object
}

Field	Description
authdata	scheme-specific user authentication data
scheme	user authentication scheme

Authentication Data

The authentication data must contain enough information to uniquely and securely identify the user associated with the message.

User ID Tokens

A user ID token contains a user identity.

The sender of a message may request user authentication by including user authentication data in the MSL header of the request. The recipient can then issue a user ID token and return the user ID token to the sender by including it in the MSL header of the response.

From then on, the sender may use the user ID token to identify the user associated with a message. User ID tokens are bound to a master token by the master token’s serial number to prevent unauthorized use. If user ID tokens were not bound to a master token then it would be possible to assume a user identity by including it in a message sent by a different entity.

When renewing a user ID token, the issuing entity has an opportunity to decide if the user ID token should be renewed or not. It may be the user no longer exists or is no longer authorized to use the sending entity and thus the user ID token will not be renewed.

Secret keys are used by the issuing entity to encrypt the user ID token user data and generate the user ID token verification data. Other entities cannot decrypt the user ID token user data or generate the user ID token verification data unless they also have access to these keys. These secret keys should be adequately protected to prevent unauthorized access to the user identity. It is also recommended that the secret keys be periodically rotated.

The master token entity is expected to persist the user ID tokens associated with any persisted master tokens. After successful user ID token renewal the previous user ID token associated with a local user may be discarded.

It is not necessary, although permitted, for the issuing entity to persist user ID tokens. User ID tokens will be included on any received messages associated with a user.

User ID Token Representation

useridtoken = {
  "#mandatory" : [ "tokendata", "signature" ],
  "tokendata" : "binary",
  "signature" : "binary"
}

Field	Description
signature	signature envelope verifying the tokendata
tokendata	user ID token data (usertokendata)

User ID Token Data

usertokendata = {
  "#mandatory" : [ "renewalwindow", "expiration", "mtserialnumber", "serialnumber", "userdata" ],
  "renewalwindow" : "int64(0,2^53^)",
  "expiration" : "int64(0,2^53^)",
  "mtserialnumber" : "int64(0,2^53^)",
  "serialnumber" : "int64(0,2^53^)",
  "userdata" : "binary",
}

Field	Description
expiration	expiration timestamp in seconds since the epoch
mtserialnumber	master token serial number
renewalwindow	when the renewal window opens in seconds since the epoch
serialnumber	user ID token serial number
userdata	ciphertext envelope containing user identification data (userdata)

Renewal Window & Expiration

User ID tokens contain a renewal window timestamp and expiration timestamp. The renewal window timestamp identifies the time after which a user ID token shall be renewed if the message renewal flag is also set. The expiration timestamp identifies the time after which user ID tokens are renewed no matter what.

User ID Token Renewal Pseudocode

boolean renewUserIdToken = (userIdToken.isRenewable() && message.isRenewable()) || userIdToken.isExpired();

Serial Number

The serial number is a random number against which service tokens are bound.

A randomly generated serial number should be used when issuing the first user ID token. The serial number should not be changed when renewing the user ID token; the primary purpose of the serial number is to prevent migration of service tokens between users. Changing the serial number when the user ID token is renewed invalidates any bound service tokens.

Master Token Serial Number

The master token serial number binds the user ID token to a specific master token. The user ID token must be rejected if its master token serial number does not match the master token included in the same message.

User Data

userdata = {
  "#mandatory" : [ "identity" ],
  "issuerdata" : object,
  "identity" : "string",
}

Field	Description
identity	user identity data
issuerdata	user ID token issuer data

Issuer Data

The issuer data contains data provided by the issuer which may be useful to services that accept the user ID token.

Identity

The identity is an opaque user identification string, that is understood by the issuing entity. Examples of the identity value might be a numeric user ID or GUID, or the Base64-encoded serialization of a proprietary user data object.