Glossary Item Box

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

# Calling GsoDelegateRights using an X509SecurityToken

Signing the SOAP method request with the user's certificate

To ensure that the key elements of the SOAP method request 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

Example Request

Below is the SOAP Envelope for a client calling GsoDelegateRights using an X509SecurityToken.

Note: The actual XML on the wire that is being sent in GsoDelegateRights has been escaped as it is treated like a string; i.e. "<" becomes "&lt;" and ">" becomes "&gt;".

    <soap:Envelope
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      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">
      <soap:Header>
        <wsa:Action wsu:Id="Id-a0e1136c-0d7f-4cdb-b442-486a3ffb9eb0">
          http://www.gateway.gov.uk/soap/2007/02/delegatedrights/GsoDelegateRights
        </wsa:Action>
        <wsa:MessageID wsu:Id="Id-d80304b0-6527-45f4-876a-a57ce2be18bd">
          uuid:f3325938-e633-4c6c-8e86-44bfa1698cfb
        </wsa:MessageID>
        <wsa:ReplyTo wsu:Id="Id-1e9e419b-68e3-4bf3-8766-fc30eca16de0">
          <wsa:Address>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:Address>
        </wsa:ReplyTo>
        <wsa:To wsu:Id="Id-9c2e99b4-3878-43dd-ab32-258145d95925">
          http://www.gateway.gov.uk/soap/2007/02/delegatedrights
        </wsa:To>
        <wsse:Security soap:mustUnderstand="1">
          <wsu:Timestamp wsu:Id="Timestamp-c8e45f54-0c81-4a7b-a08d-abfcd985f8bc">
            <wsu:Created>2007-02-05T11:11:42Z</wsu:Created>
            <wsu:Expires>2007-02-05T11:16:42Z</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-a6383be0-bb5d-4943-a90f-7d9c6b05e6a0">
            MIIDOjCCAuSgAwIBAgIKGn1xWwAAAADUWzANBgkqhkiG9w0BAQUFADBAMQswCQYD
            VQQGEwJHQjENMAsGA1UEBxMEVUtHRzEPMA0GA1UEChMGVUtHRzE2MREwDwYDVQQD
            EwhVS0dHMTZDQTAeFw0wNDA3MDUxMDUwNDNaFw0wNDEwMTcxMzE0MzdaMEIxCzAJ
            BgNVBAYTAkdCMQ0wCwYDVQQHEwRVS0dHMQ8wDQYDVQQKEwZVS0dHMTYxEzARBgNV
            BAMTCkFkbWluIFVzZXIwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAwpUr4CP/q6PK
            SjEZACfvEtYR4TUwqh/joYj7GbXo3npnq8ko9zhyZxx3pHg20/xVXhTMPomiSL6X
            U7XuUYERBQIDAQABo4IBvDCCAbgwDgYDVR0PAQH/BAQDAgTwMBMGA1UdJQQMMAoG
            CCsGAQUFBwMCMB0GA1UdDgQWBBRfjwmODhdJT/MQLBe47gMHmfa/IzB3BgNVHSME
            cDBugBQnSXo3duwUEYXXll7QBn5HWA2xH6FEpEIwQDELMAkGA1UEBhMCR0IxDTAL
            BgNVBAcTBFVLR0cxDzANBgNVBAoTBlVLR0cxNjERMA8GA1UEAxMIVUtHRzE2Q0GC
            EC08OfhUREq+TwpWMwhQPkEwaQYDVR0fBGIwYDAtoCugKYYnaHR0cDovL3VrZ2cx
            NmNhL0NlcnRFbnJvbGwvVUtHRzE2Q0EuY3JsMC+gLaArhilmaWxlOi8vXFx1a2dn
            MTZjYVxDZXJ0RW5yb2xsXFVLR0cxNkNBLmNybDCBjQYIKwYBBQUHAQEEgYAwfjA8
            BggrBgEFBQcwAoYwaHR0cDovL3VrZ2cxNmNhL0NlcnRFbnJvbGwvdWtnZzE2Y2Ff
            VUtHRzE2Q0EuY3J0MD4GCCsGAQUFBzAChjJmaWxlOi8vXFx1a2dnMTZjYVxDZXJ0
            RW5yb2xsXHVrZ2cxNmNhX1VLR0cxNkNBLmNydDANBgkqhkiG9w0BAQUFAANBAHj7
            oMciwqyOLfgLF0dQSVEORifsQMVfRTEUb5zrafXMHn9B/gGNZJa3JGhwR6ndcKVV
            QGujkBsOGb7VSnG9XyA=
          </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-a0e1136c-0d7f-4cdb-b442-486a3ffb9eb0">
                <Transforms>
                <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                <DigestValue>jI/pSWj7UibNkhsuqdPGlNWCWwI=</DigestValue>
              </Reference>
              <Reference URI="#Id-d80304b0-6527-45f4-876a-a57ce2be18bd">
                <Transforms>
                <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                <DigestValue>RDKGgOzdwahF/w39m53BxRoE/TA=</DigestValue>
              </Reference>
              <Reference URI="#Id-1e9e419b-68e3-4bf3-8766-fc30eca16de0">
                <Transforms>
                <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                <DigestValue>Z/AJtoPiq+pBxYEiW0i0gs3I7mg=</DigestValue>
              </Reference>
              <Reference URI="#Id-9c2e99b4-3878-43dd-ab32-258145d95925">
                <Transforms>
                <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                <DigestValue>LhKQLC8KU19z5b8wqfJc5H0rva8=</DigestValue>
              </Reference>
              <Reference URI="#Timestamp-c8e45f54-0c81-4a7b-a08d-abfcd985f8bc">
                <Transforms>
                <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                <DigestValue>ZGoIROP2ncY45tuxaBt7K2TWC8o=</DigestValue>
              </Reference>
              <Reference URI="#Id-dd687aa5-d3d5-428f-8eef-aa5911b4dc20">
                <Transforms>
                <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                <DigestValue>/0z1H1s6zdLbybeQwDfQOD2XdaM=</DigestValue>
              </Reference>
            </SignedInfo>
            <SignatureValue>TG6OO8neGCK+4YutD5vK6Uke5HOMgZdyMQCkGxX4h5HO+d6u5/Phnd0M4p5KK1EeRFuxLuNF5WZ95plonCbM8A==</SignatureValue>
            <KeyInfo>
            <wsse:SecurityTokenReference>
              <wsse:Reference
                URI="#SecurityToken-a6383be0-bb5d-4943-a90f-7d9c6b05e6a0"
                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-dd687aa5-d3d5-428f-8eef-aa5911b4dc20">
        <GsoDelegateRights xmlns="http://www.gateway.gov.uk/soap/2007/02/delegatedrights">
          <inputXml>
            &lt;?xml version="1.0" encoding="utf-8"?&gt;
            &lt;GsoDelegateRightsXmlInput xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns="urn:GSO-System-Services:external:2.10:GsoDelegateRightsXmlInput"&gt;
              &lt;RequestID&gt;0246DF5AC0984ADEAD6807F7A3797BA7&lt;/RequestID&gt;
              &lt;SecondsToExpiry&gt;600&lt;/SecondsToExpiry&gt;
              &lt;UserDetails&gt;
                &lt;Name&gt;Agent User&lt;/Name&gt;
                &lt;SessionIdentifier&gt;AgentUserPayrollNo&lt;/SessionIdentifier&gt;
                &lt;Email&gt;agent.user@agentorg.co.uk&lt;/Email&gt;
                &lt;CredentialRole&gt;DelegatedUser&lt;/CredentialRole&gt;
              &lt;/UserDetails&gt;
              &lt;DirectEnrolments&gt;
                &lt;DirectEnrolment&gt;
                  &lt;ServiceName&gt;MOSW11AGENT&lt;/ServiceName&gt;
                  &lt;Identifiers&gt;
                     &lt;Identifier IdentifierType="MOSW11AGENTID"&gt;aa11aa&lt;/Identifier&gt;
                   &lt;/Identifiers&gt;
                &lt;/DirectEnrolment&gt;
              &lt;/DirectEnrolments&gt;
              &lt;ClientAllocations&gt;
                &lt;ClientAllocation&gt;
                  &lt;ServiceName&gt;MOSW11&lt;/ServiceName&gt;
                  &lt;Identifiers&gt;
                    &lt;Identifier IdentifierType="MOSW11ID"&gt;bb11bb&lt;/Identifier&gt;
                  &lt;/Identifiers&gt;
                &lt;/ClientAllocation&gt;
                &lt;ClientAllocation&gt;
                  &lt;ServiceName&gt;MOSW11&lt;/ServiceName&gt;
                  &lt;Identifiers&gt;
                    &lt;Identifier IdentifierType="MOSW11ID"&gt;cc11cc&lt;/Identifier&gt;
                  &lt;/Identifiers&gt;
                &lt;/ClientAllocation&gt;
                &lt;ClientAllocation&gt;
                  &lt;ServiceName&gt;MOSW11&lt;/ServiceName&gt;
                  &lt;Identifiers&gt;
                    &lt;Identifier IdentifierType="MOSW11ID"&gt;dd11dd&lt;/Identifier&gt;
                  &lt;/Identifiers&gt;
                &lt;/ClientAllocation&gt;
              &lt;/ClientAllocations&gt;
            &lt;/GsoDelegateRightsXmlInput&gt
          </inputXml>
        </GsoDelegateRights>
      </soap:Body>
    </soap:Envelope>

Notes:

> 1. <wsa:Action> ... </wsa:Action>

> The URL (or urn) for the method.

> 2. <wsa:To>... </wsa:To>

> This is the actor for the delegatedrights Interface.

> 3. <GsoDelegateRights xmlns="...">

> This has the same value as (2.).

> 4. 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.

#### Example Response

Below is the response from the GsoDelegateRights call; the message is the same independent of whether the method request used a UsernameToken or an X509SecurityToken.

Note: The actual XML on the wire that is being sent back from GsoDelegateRights, has been escaped as it is treated like a string; i.e. "<" becomes "&lt;" and ">" becomes "&gt;".

    <soap:Envelope
        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        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">
      <soap:Header>
        <wsa:Action>http://www.gateway.gov.uk/soap/2007/02/delegatedrights/GsoDelegateRightsResponse</wsa:Action>
        <wsa:MessageID>uuid:f88ed6cb-ca09-47c6-aea6-31f568584347</wsa:MessageID>
        <wsa:RelatesTo>uuid:f3325938-e633-4c6c-8e86-44bfa1698cfb</wsa:RelatesTo>
        <wsa:To>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:To>
        <wsse:Security>
        <wsu:Timestamp wsu:Id="Timestamp-028e8164-4658-407b-b4e7-05f5ff309da9">
          <wsu:Created>2007-02-05T11:11:42Z</wsu:Created>
          <wsu:Expires>2007-02-05T11:16:42Z</wsu:Expires>
        </wsu:Timestamp>
        </wsse:Security>
      </soap:Header>
      <soap:Body>
        <GsoDelegateRightsResponse xmlns="http://www.gateway.gov.uk/soap/2007/02/delegatedrights">
          <outputXml>
            &lt;?xml version="1.0" encoding="utf-8"?&gt;
            &lt;GsoDelegateRightsXmlOutput xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            RequestID="261D16719D3040807A8993BD05289A6C"
            xmlns="urn:GSO-System-Services:external:2.10:GsoDelegateRightsXmlOutput"&gt;
              &lt;GatewayOneTimeToken&gt;dnsfweyt4876irehgy4248fk3&lt;/GatewayOneTimeToken&gt;
              &lt;InvalidClientAllocations&gt;
                &lt;ClientAllocation&gt;
                  &lt;ServiceName&gt;MOSW11&lt;/ServiceName&gt;
                  &lt;Identifiers&gt;
                    &lt;Identifier IdentifierType="MOSW11ID"&gt;dd11dd&lt;/Identifier&gt;
                  &lt;/Identifiers&gt;
                &lt;/ClientAllocation&gt;
              &lt;/InvalidClientAllocations&gt;
            &lt;/GsoDelegateRightsXmlOutput&gt;
          </outputXml>
        </GsoDelegateRightsResponse>
      </soap:Body>
    </soap:Envelope>

Notes:

> 1. <wsa:Action> ... </wsa:Action>

> This value relates to the request.

> 2. 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