Glossary Item Box

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

# Logging on to Gateway Using a Security Phrase

When a user logs into the Gateway (see Logging on to Gateway with a User ID and Password) they can optionally use their security phrase to upgrade their GatewayToken from authentication level 1 to 1.5. The following lists the typical interaction between a user, the application and the Gateway to get an authentication level 1.5 GatewayToken:

- User: Requests to use security phrase.
- Application: Uses GsoGetUserDetails to get the position of the 3 characters from the security phrase that the user must supply.
- Application: Displays a login page to collect the 3 characters from the security phrase.
- User: Provides information.
- Application: Builds a GatewaySecurityPhraseToken and submits it in a RequestSecurityToken (RST) message to the Security Token Service (STS).
- STS: Checks supplied credentials (in the UsernameToken and the GatewaySecurityPhraseToken), generates an authentication level 1.5 GatewayToken and returns it to the application in a RequestSecurityTokenResponse (RST) message.

#### RequestSecurityToken (RST)

The following Xml is the RequestSecurityToken message from a client (i.e. Web portal or an ISV application) to the Gateway STS using a GatewaySecurityPhraseToken.

The RST message uses standard WS-Trust, WS-Security, WS-Addressing and WS-Policy specification elements. Any aspects that are Gateway specific are highlighted and discussed below.

    <soap:Envelope xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Header>
        <wsa:Action>http://schemas.xmlsoap.org/ws/2004/04/security/trust/RST/Issue</wsa:Action>
        <wsa:MessageID>uuid:a73e47c6-cf4d-4e1f-aad1-e994150fc269</wsa:MessageID>
        <wsa:ReplyTo>
          <wsa:Address>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:Address>
        </wsa:ReplyTo>
        <wsa:To>http://www.gateway.gov.uk/soap/2007/02/sts</wsa:To>
        <wsse:Security soap:mustUnderstand="1">
          <wsu:Timestamp wsu:Id="Timestamp-8dad22bc-8f55-472e-bbe3-38b169200429">
            <wsu:Created>2007-02-15T08:34:27Z</wsu:Created>
            <wsu:Expires>2007-02-15T08:39:27Z</wsu:Expires>
          </wsu:Timestamp>
          <gateway:GatewayToken xmlns:gateway="urn:GSO-System-Services:external:1.65:gatewaytoken"
            gateway:TokenId="SecurityToken-1ef6b44d-9574-4ad7-ad4a-74682af3a34d">
            <gateway:Created>2007-02-15T08:31:36Z</gateway:Created>
            <gateway:Expires>2007-02-15T12:31:36Z</gateway:Expires>
            <gateway:Usage>Standard</gateway:Usage>
            <gateway:Opaque>bA9OUk5VscGu1inxcQuGMAMzy3ezNcerag+rxaZDcUDLGGFdPGeT1wZKW1Lt5tPxyBgXVJ5fAHqT0/gFeqSHtZ9FMtaw0WAsLFWKk5TVWSw=</gateway:Opaque>
          </gateway:GatewayToken>
        </wsse:Security>
      </soap:Header>
      <soap:Body>
        <wst:RequestSecurityToken xmlns:wst="http://schemas.xmlsoap.org/ws/2004/04/trust">
          <wst:TokenType>urn:GSO-System-Services:external:1.65:gatewaytoken#GatewayToken</wst:TokenType>
          <wst:RequestType>http://schemas.xmlsoap.org/ws/2004/04/security/trust/Issue</wst:RequestType>
          <wst:Base>
            <gateway:GatewaySecurityPhraseToken
              xmlns:gateway="urn:GSO-System-Services:external:1.67:gatewaysecurityphrasetoken"
              gateway:TokenId="SecurityToken-66ad2a63-0801-4c4a-a452-4ca97a51a3c3">
              <gateway:AnswerCharactersDigest>+fUzV7hYuMODWR5UwufpsIHvN6U=</gateway:AnswerCharactersDigest>
              <wsse:Nonce>wArwrT8zZhsXrHFcH37S+g==</wsse:Nonce>
              <wsu:Created>2007-02-15T08:34:27Z</wsu:Created>
            </gateway:GatewaySecurityPhraseToken>
          </wst:Base>
          <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy">
            <wsa:EndpointReference>
              <wsa:Address>urn:GSO-System-Services:external:1.65:GatewayWebServices</wsa:Address>
            </wsa:EndpointReference>
          </wsp:AppliesTo>
          <wst:Lifetime>
            <wsu:Expires>2007-02-15T12:34:27Z</wsu:Expires>
          </wst:Lifetime>
        </wst:RequestSecurityToken>
      </soap:Body>
    </soap:Envelope>

Notes:

> 1. <wsa:To>http://www.gateway.gov.uk/soap/2007/02/sts</wsa:To>

> This is the actor for the STS. If the value is:

> - http://www.gateway.gov.uk/soap/2007/02/sts then the request is sent to the STS endpoint that fully supports the WS-Trust standard – including the <wst:Lifetime> element. This option was introduced in release 1.7.0 of the Gateway. Portals/applications should (be migrated to) use these endpoints.
> - urn:GSO-System-Services:external:1.65:GatewaySecurityTokenService then the request is sent to the STS endpoint that supports the legacy <wst:LifeTime> element (note the upper case "T"), rather than the <wst:Lifetime>.

> 2. <wst:TokenType>urn:GSO-System-Services:external:1.65:gatewaytoken#GatewayToken</wst:TokenType>

> This is the urn for the GatewayToken that is being requested.

> 3. <wsa:Address>urn:GSO-System-Services:external:1.65:GatewayWebServices</wsa:Address>

> This is the urn for all of the Gateway SOAP Web services

> 4. <wst:Lifetime>

> This is the WS-Trust standard element used if the actor for the STS is http://www.gateway.gov.uk/soap/2007/02/sts. If the actor for the STS is urn:GSO-System-Services:external:1.65:GatewaySecurityTokenService then this element must be the legacy <wst:LifeTime> (note the upper case "T").

> 5. Identifiers need to be unique across the message (this implementation is based on GUIDs, e.g. 82c56821-1970-49fa-8edd-6da6fa327fd3); including a label as part of an identifier aids readability.

#### RequestSecurityTokenResponse (RSTR)

The following Xml is the RequestSecurityTokenResponse message returned by the Gateway STS in response to the RST message.

The RSTR message uses standard WS-Trust, WS-Security, WS-Addressing and WS-Policy specification elements. Any aspects that are Gateway specific are highlighted and discussed below.

    <soap:Envelope xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Header>
        <wsa:Action>http://schemas.xmlsoap.org/ws/2004/04/security/trust/RSTR/Issue</wsa:Action>
        <wsa:MessageID>uuid:b4e49506-2434-4522-a5c5-61ae1805d6e3</wsa:MessageID>
        <wsa:RelatesTo>uuid:a73e47c6-cf4d-4e1f-aad1-e994150fc269</wsa:RelatesTo>
        <wsa:To>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:To>
        <wsse:Security>
          <wsu:Timestamp wsu:Id="Timestamp-e57ad02b-ac7e-4ba5-bc44-bbe66c16f82a">
            <wsu:Created>2007-02-15T08:34:27Z</wsu:Created>
            <wsu:Expires>2007-02-15T08:39:27Z</wsu:Expires>
          </wsu:Timestamp>
        </wsse:Security>
      </soap:Header>
      <soap:Body>
        <wst:RequestSecurityTokenResponse xmlns:wst="http://schemas.xmlsoap.org/ws/2004/04/trust">
          <wst:TokenType>urn:GSO-System-Services:external:1.65:gatewaytoken#GatewayToken</wst:TokenType>
          <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy">
            <wsa:EndpointReference>
              <wsa:Address>urn:GSO-System-Services:external:1.65:GatewayWebServices</wsa:Address>
            </wsa:EndpointReference>
          </wsp:AppliesTo>
          <wst:RequestedSecurityToken>
            <gateway:GatewayToken xmlns:gateway="urn:GSO-System-Services:external:1.65:gatewaytoken"
              gateway:TokenId="SecurityToken-c3ded8b5-7b5f-4b67-96b6-e1d4fc90e847">
              <gateway:Created>2007-02-15T08:34:27Z</gateway:Created>
              <gateway:Expires>2007-02-15T12:34:27Z</gateway:Expires>
              <gateway:Usage>Standard</gateway:Usage>
              <gateway:Opaque>bA9OUk5VscGu1inxcQuGMGjN1yx9rAHN3MGV4fhB7TZ3Id1uds7C97c+2Cwz1DbAj94m39XAhU45eWcW8rGakSKgNbmgjuVz1GKatygd36w=</gateway:Opaque>
            </gateway:GatewayToken>
          </wst:RequestedSecurityToken>
          <wst:Lifetime>
            <wsu:Created>2007-02-15T08:34:27Z</wsu:Created>
            <wsu:Expires>2007-02-15T12:34:27Z</wsu:Expires>
          </wst:Lifetime>
        </wst:RequestSecurityTokenResponse>
      </soap:Body>
    </soap:Envelope>

Notes:

> 1. <wst:TokenType>urn:GSO-System-Services:external:1.65:gatewaytoken#GatewayToken</wst:TokenType>

> This is the urn for the GatewayToken requested.

> 2. <wsa:Address>urn:GSO-System-Services:external:1.65:GatewayWebServices</wsa:Address>

> This is the urn for all of the Gateway SOAP Web services

> 3. <wst:RequestSecurityToken> ... </wst:RequestSecurityToken>

> This is the GatewayToken that was requested. A GatewayToken is a customise WS-Security security token.

> 4. <wst:Lifetime>

> This is the WS-Trust standard element used if the actor for the STS is http://www.gateway.gov.uk/soap/2007/02/sts. If the actor for the STS is urn:GSO-System-Services:external:1.65:GatewaySecurityTokenService then this element must be the legacy <wst:LifeTime> (note the upper case "T").

> 5. Identifiers need to be unique across the message (this implementation is based on GUIDs, e.g. 82c56821-1970-49fa-8edd-6da6fa327fd3); including a label as part of an identifier aids readability.

© Crown Copyright 2008. All rights reserved