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 with a Certificate

The following lists the interaction between a user, the application and the Gateway when a user logs on to the Gateway with a Certificate:

- User: Requests login to Gateway using a certificate.
- Application: Display a list box that allows the user to select the certificate to use from their local certificate store and to sign the RequestSecurityToken message (containing the caller's certificate) to get a GatewayToken from the STS. The signing process is described below.
- User: Provides certificate and signed elements of the RequestSecurityToken (RST) message.
- Application: Sends RequestSecurityToken (RST) message to the Security Token Service (STS).
- STS: Checks the certificate is not on the Certificate Revocation List (CRL) of the certificate issuer and that the supplied signature and credential are valid before it generates a GatewayToken which it returns to the application in a RequestSecurityTokenResponse (RST) message.
- Application: Caches the GatewayToken for use in subsequent method calls; including, GsoGetuserDetails to get user details (and CredentialIdentifier) and GsoGetAssignedEnrolments to get the user current enrolments.

Signing the SOAP RST with the user's certificate

To ensure that the key elements of the RST cannot be tampered with they are signed by the caller using the W3C XML-Signature Syntax and Processing specification:

- A reference (highlighted in green) is added to the following elements: Action, MessageID, ReplyTo, To, Timestamp and Body
- A digest is created for each of these elements
- Each digest value (highlighted in blue) is added to SignedInfo in its own Reference element (highlighted in green).
- The complete SignedInfo element is then digitally signed and put into the SignatureValue element (highlighted in red):
  - The CanonicalizationMethod is the algorithm used to canonicalize (i.e. put into a standard or consistent format) the SignedInfo element before it is digested.
  - The SignatureMethod is the algorithm that is then used to convert the canonicalized SignedInfo into the SignatureValue.
  - The KeyInfo indicates the key to be used to validate the signature (i.e. the public key associated with the certificate).

Validating the request at the Gateway

On receiving the request the Gateway performs the following two processes:

- Validation of the signature over the SignedInfo element (to confirms that each DigestValue has not been tampered with):
  - Recreate the digest across the SignedInfo
  - Decrypt the signature (SignatureValue) with the user's public key (contained in the certificate)
  - Check that these two values are equal.
- Validation of each Reference DigestValue within SignedInfo (to confirm that the content covered by each digest has not been tampered with):
  - Recreate the digest
  - Check it is equal to the corresponding Reference DigestValue.

#### 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 Certificate.

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 wsu:Id="Id-efef0c18-e99d-4902-ac3d-7688d9ffaa0a">
          http://schemas.xmlsoap.org/ws/2004/04/security/trust/RST/Issue
        </wsa:Action>
        <wsa:MessageID wsu:Id="Id-2d0b9811-fd52-4874-b0a1-266767939e00">
          uuid:b264c60a-7698-48c0-b618-cc56108e9ca7
        </wsa:MessageID>
        <wsa:ReplyTo wsu:Id="Id-2be6fdbb-430f-4fac-94aa-7f1064d5e490">
          <wsa:Address>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:Address>
        </wsa:ReplyTo>
        <wsa:To wsu:Id="Id-c3e84212-13b2-4bf5-a18f-69af0f8fe839">
         http://www.gateway.gov.uk/soap/2007/02/sts
        </wsa:To>
        <wsse:Security soap:mustUnderstand="1">
          <wsu:Timestamp wsu:Id="Timestamp-b3c5fe17-726c-4713-bae3-5b14d54e04b5">
            <wsu:Created>2007-02-01T11:45:18Z</wsu:Created>
            <wsu:Expires>2007-02-01T11:50:18Z</wsu:Expires>
          </wsu:Timestamp>
          <wsse:BinarySecurityToken
            ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
            EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
            wsu:Id="SecurityToken-f999debf-3aad-4924-8ce6-1c7f3b48edfe">
              MIIDQjCCAuygAwIBAgIKYEX2IwAAAAC1UzANBgkqhkiG9w0BAQUFADBAMQswCQYD
              VQQGEwJHQjENMAsGA1UEBxMEVUtHRzEPMA0GA1UEChMGVUtHRzE2MREwDwYDVQQD
              EwhVS0dHMTZDQTAeFw0wNDAzMDExNTMxMTNaFw0wNDEwMTcxMzE0MzdaMEoxCzAJ
              BgNVBAYTAkdCMQ0wCwYDVQQHEwRVS0dHMQ8wDQYDVQQKEwZVS0dHMTYxGzAZBgNV
              BAMTElZhbGlkIEdhdGV3YXkgQ2VydDBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQDP
              QPzkRfQDMiGWXcSzXVRrmUN8zmkg/NBGjloV1dyzAI2zGMCXl0gRptjGpqtmCHCH
              Bxi9AvvfbMz6rrevE6OJAgMBAAGjggG8MIIBuDAOBgNVHQ8BAf8EBAMCBPAwEwYD
              VR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFJn555Fo3bqcUmEcSN6EydEOsf56
              MHcGA1UdIwRwMG6AFCdJejd27BQRhdeWXtAGfkdYDbEfoUSkQjBAMQswCQYDVQQG
              EwJHQjENMAsGA1UEBxMEVUtHRzEPMA0GA1UEChMGVUtHRzE2MREwDwYDVQQDEwhV
              S0dHMTZDQYIQLTw5+FRESr5PClYzCFA+QTBpBgNVHR8EYjBgMC2gK6AphidodHRw
              Oi8vdWtnZzE2Y2EvQ2VydEVucm9sbC9VS0dHMTZDQS5jcmwwL6AtoCuGKWZpbGU6
              Ly9cXHVrZ2cxNmNhXENlcnRFbnJvbGxcVUtHRzE2Q0EuY3JsMIGNBggrBgEFBQcB
              AQSBgDB+MDwGCCsGAQUFBzAChjBodHRwOi8vdWtnZzE2Y2EvQ2VydEVucm9sbC91
              a2dnMTZjYV9VS0dHMTZDQS5jcnQwPgYIKwYBBQUHMAKGMmZpbGU6Ly9cXHVrZ2cx
              NmNhXENlcnRFbnJvbGxcdWtnZzE2Y2FfVUtHRzE2Q0EuY3J0MA0GCSqGSIb3DQEB
              BQUAA0EAmpG9hc5rOirc3vdh2MZ0HPORcQoHJ3nONM73XsA42/7aaTil/EHiLwCQ
              knucBNg9pHH6LYxJMoqFRbT+qRY1pA==
          </wsse:BinarySecurityToken>
          <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
            <SignedInfo>
              <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
              <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
              <Reference URI="#Id-efef0c18-e99d-4902-ac3d-7688d9ffaa0a">
                <Transforms>
                  <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>hqJtAIj5x5ogiV8fQ2uCmR2N/Eg=</DigestValue>
              </Reference>
              <Reference URI="#Id-2d0b9811-fd52-4874-b0a1-266767939e00">
                <Transforms>
                  <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </Transforms>
                <DigestMethod Algorithm= "http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>oD1TCR3EHqgnbtbtrnJDSEWwZhw=</DigestValue>
              </Reference>
              <Reference URI="#Id-2be6fdbb-430f-4fac-94aa-7f1064d5e490">
                <Transforms>
                  <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>8vNUX7ozWS2qQksi6WN8vZz86SI=</DigestValue>
              </Reference>
              <Reference URI="#Id-c3e84212-13b2-4bf5-a18f-69af0f8fe839">
                <Transforms>
                  <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>gjMw5y2HkHQwcttwPk8OlN2YGrw=</DigestValue>
              </Reference>
              <Reference URI="#Timestamp-b3c5fe17-726c-4713-bae3-5b14d54e04b5">
                <Transforms>
                  <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                </Transforms>
                <DigestMethod Algorithm= "http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>Av0vPNoTL0QjO96/PHn5o9vwHbI=</DigestValue>
              </Reference>
              <Reference URI="#Id-e9220202-82db-430e-96d7-16b64422dd7a">
                <Transforms>
                  <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                <DigestValue>FwfU5RHKT7iqhpvHt7spCv+6BIQ=</DigestValue>
              </Reference>
            </SignedInfo>
            <SignatureValue>kgt92E/K6845em4TE3zgsvgh9KBmiBxQanT50nOKXgsnqnwYMlmxrojMoOfHrasi8g374RzFlSIlf2gXDDCS8Q==</SignatureValue>
            <KeyInfo>
              <wsse:SecurityTokenReference>
                <wsse:Reference
                  URI="#SecurityToken-f999debf-3aad-4924-8ce6-1c7f3b48edfe"
                  ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>
              </wsse:SecurityTokenReference>
            </KeyInfo>
          </Signature>
        </wsse:Security>
      </soap:Header>
      <soap:Body wsu:Id="Id-e9220202-82db-430e-96d7-16b64422dd7a">
        <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>
            <wsse:SecurityTokenReference>
            <wsse:Reference
              URI="#SecurityToken-f999debf-3aad-4924-8ce6-1c7f3b48edfe"
              ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" />
            </wsse:SecurityTokenReference>
          </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-01T15:45:18Z</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 i f 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. Note that the RSTS message is the same independent of whether the RST message used a UsernameToken or an X509SecurityToken.

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:2505b4f3-a26d-48c5-84ee-088158394e2e</wsa:MessageID>
        <wsa:RelatesTo>uuid:b264c60a-7698-48c0-b618-cc56108e9ca7</wsa:RelatesTo>
        <wsa:To>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:To>
        <wsse:Security>
          <wsu:Timestamp wsu:Id="Timestamp-1f295bc3-7f13-47d0-ae3f-2e0b162cfd14">
            <wsu:Created>2007-02-01T11:45:24Z</wsu:Created>
            <wsu:Expires>2007-02-01T11:50:24Z</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-de68c146-4143-4d6d-9dc7-e711ddcd3329">
              <gateway:Created>2007-02-01T11:45:24Z</gateway:Created>
              <gateway:Expires>2007-02-01T15:45:24Z</gateway:Expires>
              <gateway:Usage>Standard</gateway:Usage>
              <gateway:Opaque>
                  ygk17PMFSK8i22VoM/f2Kv1URUhXfsnVP87hfvzyDXGf5Pjxsa9v/fvGeHCWuZZ5g
                  SBjtK8lGs1Xvc7ZzG6/fqPHDjopCs4gDwwLxccO+mjZdPoknRgzQA==
              </gateway:Opaque>
            </gateway:GatewayToken>
          </wst:RequestedSecurityToken>
          <wst:Lifetime>
            <wsu:Created>2007-02-01T11:45:24Z</wsu:Created>
            <wsu:Expires>2007-02-01T15:45:24Z</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.

> 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