Glossary Item Box

Government Gateway 2.2.0 (MR-01) ISV Developer Help (Doc Version 06/03/08) | Send comments on this topic.

# UsernameToken

The UsernameToken that the Gateway supports is the standard WS-Security UsernameToken.

The UsernameToken is incorporated in the GsoDelegateRights method (SOAP method request message) – the only method on the DelegatedRights Interface – to authenticate the caller and sign the message.

The username (i.e User ID) and password combination incorporated into the UsernameToken must correspond to the username and password for the DRM user account created through the Gateway UI.

Note:

- The DRM user account can only be created through the Gateway UI (www.Gateway.gov.uk ) - NOT through a Department Portal.
- The DRM user account is created by a registered normal Gateway user within the organisation.

An example of a UsernameToken is given below:

    <wsse:UsernameToken
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
      wsu:Id="SecurityToken-08cd6a36-6b9c-4db7-a727-15916cfe19bc">
      <wsse:Username>513FDQ37JILL</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">
        od61xScYr9hAukzvz/DQXAtdxAA=
      </wsse:Password>
      <wsse:Nonce>dL9uL5lBBm6eHwblHY4lVg==</wsse:Nonce>
      <wsu:Created>2004-06-29T09:10:48Z</wsu:Created>
    </wsse:UsernameToken>

#### Username

The User ID created when a normal user registers the DRM user account through the Gateway UI (e.g. 513FDQ37JILL).

#### Password

The Type attribute in the Password element means the Gateway requires the password to be passed as a digest.

Calculating the password equivalent

To improve security the Gateway does not normally accept clear text passwords. The exception is where an initial or new password is provided, such as at registration or when changing a password (GsoSetPassword) where password rules must be checked.

So, before the required digest can be calculated, the following steps must be performed on the clear text password:

1. Lowercase: The Gateway treats passwords as case-insensitive, this means that the password, for example MyPassword1, has to be changed to mypassword1
2. UTF-8: To ensure that all parties are using the same text encoding the password is converted to UTF-8
3. MD5 Hash: An MD5 hash is performed on the UTF-8 encoded value
4. Base64: To convert the hashed password to something that can be sent in text the Base64 representation is taken.

This means that the password MyPassword1 would become DSjkCA3I9k/JYDY5u3qhuQ==

Calculating the password Digest

Once the lowercased hashed password has been obtained, this is then used to generate the password digest value required by the UsernameToken.

To create the digest value, the two additional nodes in the UsernameToken are used:

- Nonce - this is the SHA-1 of the GsoDelegateRightsXmlInput element – effectively signing the message contents

> > Note: The nonce is not a random value – as it is for constructing the UsernameToken used to access the Security Token Service (STS).

- Created - this is the timestamp (the Gateway will reject timestamps older than five minutes)

The digest value is calculated as follows: Password_Digest = Base64 (SHA-1 (nonce + created + password equivalent))

That is, concatenate the nonce, creation timestamp, and the password equivalent, digest the combination using the SHA-1 hash algorithm, and then Base64 encode the result. This helps obscure the password and (because the nonce contains the GsoDelegatedRightsInput which includes a random value) prevents replay attacks.

Note:

- The nonce is hashed using the octet (i.e. eight-bit byte) sequence of its decoded value while the timestamp is hashed using the octet sequence of its UTF8 encoding as specified in the contents of the element.
- Further details on how to create the password digest value can be found in the OASIS specification: Web Services Security UsernameToken Profile 1.0.

© Crown Copyright 2008. All rights reserved