Glossary Item Box

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

# GatewayToken

GatewayToken

The GatewayToken is a WS-Security custom token (as opposed to a standard UsernameToken or an X509SecurityToken) which the Gateway will accept on the SOAP Portal and Public Interfaces. This token is used to allow the client (user) to make calls without representing their original credentials and is valid for a four hour period. An example of a GatewayToken is shown below:

    <gateway:GatewayToken
      xmlns:gateway="urn:GSO-System-Services:external:1.65:gatewaytoken"
      gateway:TokenId="SecurityToken-905d92d0-d4de-49cc-8aff-604c17626e09">
      <gateway:Created>2004-06-29T09:09:58Z</gateway:Created>
      <gateway:Expires>2004-06-29T13:09:58Z</gateway:Expires>
      <gateway:Usage>Standard</gateway:Usage>
      <gateway:Opaque>
        ygk17PMFSK8B1ArP+UNwrF9FJORTcq41b/TK8RXSIJc0zHhGLUkX/K4ub/aJ
        GCs3yFBW9aDz1HL3/3l6KqF6/2jI7vK7QHncfFltXXl9tmDawAKx7yVTAw==
      </gateway:Opaque>
    </gateway:GatewayToken>

The following schema describes the token

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- Gateway Identity Services GatewayToken Schema v1.00 - 29 June 2006 -->
    <xs:schema
      targetNamespace="urn:GSO-System-Services:external:1.65:gatewaytoken"
      elementFormDefault="qualified"
      attributeFormDefault="qualified"
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns="urn:GSO-System-Services:external:1.65:gatewaytoken">
      <xs:element name="GatewayToken">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Created" type="xs:dateTime" minOccurs="1" maxOccurs="1"/>
            <xs:element name="Expires" type="xs:dateTime" minOccurs="1" maxOccurs="1"/>
            <xs:element name="Usage" type="TokenUsageTYPE" minOccurs="1" maxOccurs="1"/>
            <xs:element name="Opaque" type="xs:string" minOccurs="1" maxOccurs="1"/>
          </xs:sequence>
          <xs:attribute name="TokenId" type="xs:string" use="required"/>
        </xs:complexType>
      </xs:element>
      <xs:simpleType name="TokenUsageTYPE">
        <xs:restriction base="xs:string">
          <xs:enumeration value="Standard"/>
          <xs:enumeration value="ExpiredPassword"/>
          <xs:enumeration value="NonRepudiation"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:schema>

The following properties are exposed in the GatewayToken:

- Created - This is the time that the token was created
- Expires - This is the time that the token will expire
- Usage - How this token can be used (see below for further details)
- Opaque - This section allows the Gateway to identify the caller and ensure that the token has not been tampered with

#### GatewayToken Usage

The table describes the different uses (usage) a GatewayToken can have and how such a token is obtained.

Usage | Description | Obtained by
--- | --- | ---
Standard | This is the most common use of the GatewayToken, it allows the user to call the majority of the methods on the SOAP Portal Interface and all of the methods on the Public Interface. | A standard GatewayToken (authentication level 1) is obtained by presenting a valid UsernameToken to the STS. A standard GatewayToken (authentication level 0 to 3) is obtained by presenting a valid X509SecurityToken to the STS. A standard GatewayToken (authentication level 1.5) is obtained by first obtaining a valid GatewayToken and then presenting it with a GatewaySecurityPhraseToken to the Gateway STS. Note: The calling Portal/ISV application needs to check that the STS has not returned an ExpiredPassword token. See Calling methods using a GatewayToken.
ExpiredPassword | This token is used when a user's password has expired. It only allows them to call the method GsoSetExpiredPassword on the Portal Interface. | This token is returned by the STS instead of the Standard GatewayToken when a UsernameToken is presented with an expired password.
NonRepudiation | This token is used to force the calling portal to authenticate the user again before calling the following methods: GsoDeletePeer GsoDeregister GsoUpgradeUserIDToCertificate GsoAllocateAgent GsoSetAssistantPassword GsoCreateUserID (authentication level >= 1) GsoGetUserID (authentication level >= 1) GsoChangePassword (authentication level >= 1) GsoAllocateCertificateToCredential GsoCreateSecurityPhrase GsoChangeSecurityPhrase (authentication level 1.5 or above) This is done to ensure that the user has given their consent to the action. A non-repudiation token can only be used to make one method call. | A Non-Repudiation GatewayToken (with an authentication level 1, 1.5 or 2) is obtained in the same way as a Standard GatewayToken. The difference between getting a Standard and a NonRepudiation token is that requests for NonRepudiation GatewayTokens are sent to a different endpoint to the requests for a Standard GatewayToken. See Security Token Service (STS).

© Crown Copyright 2008. All rights reserved