Government Gateway Developer Guide to Authentication and Authorisation Web Services

Developer Guide to A&A Web Services Government Gateway 1.6.3

- 1 -

Government Gateway

Developer Guide to Authentication and Authorisation Web Services – Secure and Public

Version 1.6.3 (17.04.03)


- 2 -

Table of Contents

Government Gateway 1

Developer Guide to Authentication and Authorisation Web Services – Secure and Public 1

1 Introduction 4 1.1 Document Scope & Audience 4 1.2 Terms and Abbreviations 4 1.3 References 4

2 Architecture 5 2.1 Background Overview 5 2.2 Scope 5 2.3 Assumptions 5

2.3.1 A Note on Identifiers 5 2.4 Interfaces 6

2.4.1 External Interfaces – Consumed / Dependant 6 2.5 Schema 7

2.5.1 <TicketBook> 7 2.5.2 <Base64Encode> 8 2.5.3 <CallerSignature> 9 2.5.4 <Credential> 9 2.5.5 <CredentialChange> 11 2.5.6 <CredentialIdentifier> 12 2.5.7 <ServiceActivationList> 13 2.5.8 <ServiceAuthenticateList> 14 2.5.9 <ServiceList> 17 2.5.10 <ServiceValidationList> 18 2.5.11 <UserDetails> 20 2.5.12 <UserDetailsGet> 21 2.5.13 <UserDetailsSet> 23 2.5.14 <UserIdentifier> 24 2.5.15 <LoginDocument> 24 2.5.16 <SignedInfoBlock> 24 2.5.17 <Password> 24

2.6 Functional Decomposition 25 2.6.1 GsoRegisterAndEnrol (Implemented in: SecurePortal) 25 2.6.2 GsoEnrolOnly (Implemented in: SecurePortal) 26 2.6.3 GsoActivate (Implemented in: SecurePortal) 27 2.6.4 GsoAuthenticate (Implemented in: SecurePortal and InternetPublic) 27 2.6.5 GsoValidate (Implemented in: SecurePortal and InternetPublic) 29 2.6.6 GsoRefresh (Implemented in: SecurePortal and InternetPublic) 30 2.6.7 GsoDeEnrol (Implemented in: SecurePortal) 30 2.6.8 GsoGetUserDetails (Implemented in: SecurePortal) 30 2.6.9 GsoSetUserDetails (Implemented in: SecurePortal) 31 2.6.10 GsoGetLoginDocument (Implemented in: SecurePortal and InternetPublic) 31 2.6.11 GsoLogOut (Implemented in: SecurePortal and InternetPublic) 31


- 3 -

2.6.12 GsoSetPassword (Implemented in: SecurePortal) 31 2.6.13 GsoResetPassword (Implemented in: SecurePortal) 31 2.6.14 GsoUserIdResend (Implemented in: SecurePortal) 32

2.7 Data 32 2.7.1 Persistent State 32 2.7.2 Data Flows / Transformations 32 2.7.3 Session State 32 2.7.4 Temporal State 32

3 Error & Exception Processing 33 3.1 Error Classifications 33

3.1.1 Business Recoverable Errors 33 3.1.2 Business Fatal Errors 33 3.1.3 System Recoverable Errors 34 3.1.4 System Fatal Errors 34

3.2 Exception Interface 34 3.2.1 Exception Types Thrown 34 3.2.2 Internal Exceptions 34 3.2.3 Exception Architecture / Policy 34

3.3 Security Considerations 34 3.3.1 Privacy 34 3.3.2 Authentication / Authorisation 35

4 Appendix A – WSDL 36 4.1 SecurePortal WSDL 36 4.2 InternetPublic WSDL 43


- 4 -

1 Introduction

1.1 Document Scope & Audience This document is intended to provide developers with information about the web services available from the Government Gateway for authentication and authorisation. It describes the technical specifications for:

n Authentication and Authorisation Web Services (restricted and public)

1.2 Terms and Abbreviations

Term or Abbreviation

Definition

API Application Program Interface

CA Certification Authority

DAT Department Activation Token

R&E Government Gateway Registration and Enrolment

SOAP Simple Object Access Protocol

WSDL Web Services Description Language

WSML Web Services Meta Language

XML Extensible Markup Language

XSD XML Schema Definition

XSL Extensible Stylesheet Language

1.3 References

Document Comment GSOSoapSecurePortal and GSOSoapInternetPublic SOAP Interface

1.5 master technical document (restricted)

Technical Specification – Consolidated SecurePortal and InternetPublic SOAP Interface

1.6.3 master technical document (restricted)


- 5 -

2 Architecture

2.1 Background Overview

The SOAP interface is required for portals, ISV applications and other applications to interact programmatically with the Gateway without using the native Gateway web user interface.

2.2 Scope This document details the SOAP APIs for:

n Authentication and Authorisation: the SecurePortal and InternetPublic interfaces

It includes the individual SOAP APIs, their parameters, the SOAP message formats, and security and error conditions.

2.3 Assumptions The following assumptions are made for the SecurePortal Web Services security:

n The Gateway server terminating the client-side certificate HTTPS SSL session will maintain a CTL (Certificate Trust List). Therefore, when a SOAP request arrives at the web server hosting the R&E Web Services, no additional connection authentication will be necessary.

n All SOAP APIs will ignore the contents of the CallerSignature parameter, although the XML structure will still be validated. This implementation of the SOAP APIs will provide no caller authentication. The CallerSignature parameter is only included as a placeholder for future development.

The following assumptions are made for the InternetPublic web services security:

n The SSL session used to access the SOAP APIs exposed on the Internet will only be encrypted by a server-side certificate. No additional client-side authentication of the HTTPS connection will take place.

2.3.1 A Note on Identifiers

With the previous 1.5 SOAP interface, specifically the GsoAuthenticate/Validate/Activate/EnrolOnly methods, service identifiers were only returned (in <ServiceAuthenticateList>) if the state of the service enrolment was Active. A particular service enrolment was identified purely on Service Name, under the assumption that a service would only be enrolled in once. Service identifiers were not returned by GsoDeEnrol if a de-enrolment failed and the service state was Active after the attempted de-enrolment.

With the 1.6 SOAP interface (which introduces multiple enrolments), service identifiers will be returned where they exist and a service has been uniquely identified – either by service name only or by service name and identifi ers, irrespective of service state for all SOAP APIs. This applies whether or not the service is flagged for multiple enrolments, or whether the user has enrolled multiple times or not. The logic behind this is that identifiers are now needed to tie down the context of the service, for example the question: “Which service am I enrolled for?” can no longer be answered by only returning “MOSW2”, it now needs “MOSW2 MOSW2Reference=123”. Otherwise we could get into a situation where a service cannot be activated because a user only knows what the known facts were at enrolment time, not necessarily what the identifiers are now. In this case, the service could not be activated as the user couldn’t specify the identifiers required to identify the enrolment.

This is far cleaner and less ambiguous than before, and allows a portal to show identifiers in the same manner as the R&E UI will. The impact to SOAP 1.5 users is that identifiers may be returned (in the <Identifiers> element within <ServiceAuthenticateList>) where


- 6 -

they weren’t before: however the element in the XSD is optional so this should not cause problems.

2.4 Interfaces 2.4.1 External Interfaces – Consumed / Dependant

Two separate SOAP interfaces are required in order to segment functionality and partition security (one for secure portals and another for public internet access). These separate SOAP interfaces will be partitioned along the following URLs:

• SecurePortal https://secure.gateway.gov.uk/soap/SecurePortal

• Internet http://secure.gateway.gov.uk/soap/ InternetPublic

The following table illustrates SOAP APIs exposed by the SecurePortal and InternetPublic interfaces and their associated signatures:

<TicketBook> <TicketBook><CallerSignature> <UserIdentifier>

<ServiceValidationList> <CredentialIdentifier><UserDetails> <ServiceAuthenticateList>

<Credential><TicketBook> <TicketBook>

<CallerSignature> <ServiceAuthenticateList><ServiceValidationList>

<TicketBook> <TicketBook><CallerSignature> <ServiceAuthenticateList>

<ServiceActivationList><TicketBook> <TicketBook>

<CallerSignature> <ServiceAuthenticateList><Credential> <CredentialIdentifier><ServiceList> <UserDetailsGet><TicketBook> <TicketBook>

<CallerSignature> <ServiceAuthenticateList><ServiceList> <CredentialIdentifier>

<UserDetailsGet><TicketBook> <TicketBook>

<CallerSignature><TicketBook> <TicketBook>

<CallerSignature> <ServiceAuthenticateList><ServiceList><TicketBook> <TicketBook>

<CallerSignature> <UserDetailsGet><TicketBook> <TicketBook>

<CallerSignature><UserDetailsSet><Base64Encode> <LoginDocument>

<SignedInfoBlock><TicketBook> <TicketBook>


<CallerSignature><CredentialChange>

<CallerSignature><UserIdentifier>

<ServiceValidationList><CallerSignature>

<Password><ServiceValidationList>

<TicketBook> <TicketBook><CallerSignature> <ServiceAuthenticateList>

<ServiceValidationList> <CredentialIdentifier><UserDetails>

<Credential> <UserDetailsGet><TicketBook> <TicketBook>


<CallerSignature> <ServiceAuthenticateList><ServiceList> <CredentialIdentifier>

<UserDetailsGet><Base64Encode> <LoginDocument>

<SignedInfoBlock><TicketBook> <TicketBook>

<CallerSignature>

GsoSetPassword

13

14 GsoUserIdResend

GsoResetPassword

5 GsoLogOut

InternetPublic

1 GsoAuthenticate

3 GsoValidate

2 GsoRefresh

4

8 GsoGetUserDetails

GsoGetLoginDocument

9 GsoSetUserDetails

10 GsoGetLoginDocument

11 GsoLogOut

12

6 GsoRefresh

7 GsoDeEnrol

4 GsoAuthenticate

5 GsoValidate

3 GsoActivate

SecurePortal

1 GsoRegisterAndEnrol

2 GsoEnrolOnly

The SecurePortal interface will be secured at the Gateway with a Certificate Trust List (CTL). The CTL will contain self-signed certificates, normally root or intermediate Certification Authorities (CAs), of clients allowed to initiate an


- 7 -

HTTPS session with the Gateway. The Secure Portal URL will therefore only allow SSL connections with explicitly trusted client-side certificates to access this URL. All authorised portals will require certificates that are signed by a trusted CA included in the CTL.

The InternetPublic interface will only be utilising a server-side certificate SSL connection. No other authentication of the client connection will take place. However, only subset of the SOAP APIs will be exposed by this URL.

The WSDL files for the SecurePortal and InternetPublic SOAP interfaces are documented in Appendix A. The WSML files for the SecurePortal and InternetPublic SOAP interfaces are also documented in Appendix A.

2.5 Schema

All of the parameters included in SOAP messages will be well formed XML documents conforming to the XML Schema (XSD) defined below. This approach was chosen in order to maximise re-use across SOAP APIs. In addition, XSD Schema allow both the SOAP API consumer and provider to agree on the XML document structures. This allows both parties to validate XML documents (sent and received) according to a well defined standard.

One of the first tasks performed by a SOAP API is to validate the SOAP request parameters according to these XML Schema. In addition, each SOAP API will validate its output parameters prior to transmitting the SOAP response. Note that the parameters in the WSDL are only defined as xsd:string. It is therefore the responsibility of the SOAP consumer to make sure that the SOAP message request parameters contain the proper character references so that the SOAP message request remains a well-formed XML document. That is, in the actual XML document that is the SOAP message the ‘<’ character is replaced with the < character reference in the message parameter. That same applies to ‘>’ (>), ‘&’ (&), ‘’’ (') and ‘”’ (").

The following matrix illustrates the use and direction (Input / Output) of XML documents across the SOAP APIs:

AP

I Co

un

t

GsoR

egisterAndE

nrol

GsoE

nrolOnly

GsoA

ctivate

GsoA

uthenticate

GsoV

alidate

GsoR

efresh

GsoD

eEnrol

GsoG

etUserD

etails

GsoS

etUserD

etails

GsoG

etLoginDocum

ent

GsoLogO

ut

GsoS

etPassw

ord

GsoR

esetPassw

ord

GsoU

serIdResend

GsoA

uthenticate

GsoR

efresh

GsoV

alidate

GsoG

etLoginDocum

ent

GsoLogO

ut

API Count 8 4 4 7 6 2 4 3 3 3 2 3 3 3 7 2 6 3 2 0<Base64Encode> 2 I I<CallerSignature> 17 I I I I I I I I I I I I I I I I I

<Credential> 3 I I I<CredentialIdentifier> 5 O O O O O<CredentialChange> 1 I

<LoginDocument> 2 O O<ServiceActivationList> 1 I

<ServiceAuthenticateList> 8 O O O O O O O O<ServiceList> 5 I I I I I

<ServiceValidationList> 4 I I I I<SignedInfoBlock> 2 O O

<TicketBook> 15 IO IO IO IO IO IO IO IO IO IO IO IO IO IO IO<UserDetails> 1 I

<UserDetailsGet> 5 O O O O O<Password> I

<UserDetailsSet> 1 I<UserIdentifier> 2 O I

SecurePortal InternetPublic

2.5.1 <TicketBook>

This XML document is used to manage authentication and single-sign on across secure portals. Note that the Authentication Manager silo does not differentiate between A-Tickets issued by different URLs. Therefore an A-Ticket obtained from the InternetPublic URL will be authenticated on the SecurePortal URL. No


- 8 -

distinction is made. The TicketBook must be presented to all SOAP APIs excluding GsoGetLoginDocument. In addition, the TicketBook as returned in the SOAP response must be persisted by the consumer as well. It cannot be assumed that the TicketBook returned is exactly the same as the TicketBook presented. Lastly, the A-Ticket’s contents will have no meaning to the consumers of the SOAP APIs. Although there is a structure to the A-Ticket it will be encrypted and only readable by the Ticket Management silo.

The XSD for a TicketBook is:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdTicketBook" xmlns="urn:GSO-System-Services:external:soap:xsdTicketBook" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="TicketBook"> <xsd:annotation> <xsd:documentation>Ticket Book Schema</xsd:documentation> </xsd:annotation> <xsd:element name="TicketBook" type="TicketBookType" /> <xsd:complexType name="TicketBookType"> <xsd:sequence> <xsd:element name="Ticket" type="TicketTYPE" minOccurs="0" maxOccurs="unbounded" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="TicketTYPE"> <xsd:sequence> <xsd:element name="ServiceName" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="TicketValue" type="xsd:string" minOccurs="1" maxOccurs="1" /> </xsd:sequence> </xsd:complexType> </xsd:schema>

The following XML document is a sample TicketBook:

<?xml version="1.0" encoding="utf-8" ?> <TicketBook xmlns="urn:GSO-System-Services:external:soap:xsdTicketBook"> <Ticket> <ServiceName>GsoSoapATicket</ServiceName> <TicketValue>detpyrcnEmA1</TicketValue> </Ticket> <Ticket> <ServiceName>SecureMessaging</ServiceName> <TicketValue>nedd1HdnAdegnuM</TicketValue> </Ticket> </TicketBook>

2.5.2 <Base64Encode>

This XML document is used to indicate whether the login document to be returned should be encoded in base64 or clear text.

The XSD for a Base64Encode is:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdBase64Encode" xmlns="urn:GSO-System-Services:external:soap:xsdBase64Encode" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="Base64Encode"> <xsd:annotation> <xsd:documentation>Base64 Encode Schema</xsd:documentation> </xsd:annotation> <xsd:element name="Base64Encode"> <xsd:complexType> <xsd:sequence> <xsd:element name="Mode" minOccurs="1" maxOccurs="1">


- 9 -

<xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="base64" /> <xsd:enumeration value="clear" /> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>

The following XML document is a sample Base64Encode:

<?xml version="1.0" encoding="utf-8" ?> <Base64Encode xmlns="urn:GSO-System-Services:external:soap:xsdBase64Encode"> <Mode>base64</Mode> </Base64Encode>

2.5.3 <CallerSignature>

This XML document is used to contain the signature block used to sign the TicketBook. This parameter is only used as a placeholder for future development as signed TicketBooks are not within the scope of this implementation of the SOAP APIs. Note that this XML document must only contain the root element CallerSignature, no whitespace or any characters are allowed.

The XSD for a CallerSignature is:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdCallerSignature" xmlns="urn:GSO-System-Services:external:soap:xsdCallerSignature" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="CallerSignature"> <xsd:annotation> <xsd:documentation>Caller Signature Schema</xsd:documentation> </xsd:annotation> <xsd:element name="CallerSignature"> <xsd:complexType> <xsd:complexContent> <xsd:restriction base="xsd:anyType" /> </xsd:complexContent> </xsd:complexType> </xsd:element> </xsd:schema>

The following XML document is a sample CallerSignature:

<?xml version="1.0" encoding="utf-8" ?> <CallerSignature xmlns="urn:GSO-System-Services:external:soap:xsdCallerSignature" />

2.5.4 <Credential>

The Credential parameter will leverage the existing GovTalk XSD definition. This parameter will take a GovTalk message with a body comprising of \UserAuthenticationRequest\Timestamp containing the timestamp data. Credential information will be contained in the IDAuthentication element in the Header. The IDAuthentication block will either contain the SenderID and Value elements (containing UserID/Password) or the Value element (containing the SignedInfoBlock). Note that the Method element can contain either clear or MD5 as the encoding of the password (for UserID/Password). Note MD5 hashes are assumed to be derived from UTF-8 representations of the data. For certificates the Value element will contain the SignedInfo block and Method will contain W3CSigned.

(The XSD for Credential is not included to prevent maintenance of multiple copies of the XML Schema).


- 10 -

The following XML document is a sample Credential for a UserID/Password login:

<?xml version="1.0" ?> <GovTalkMessage xmlns="implementation specific1"> <EnvelopeVersion>2.0c</EnvelopeVersion> <Header> <MessageDetails> <Class>ADM-user-authentication-request</Class> <Qualifier>request</Qualifier> <Function>submit</Function> <GatewayTimestamp>2002-02-07T15:01:00-00:00</GatewayTimestamp> </MessageDetails> <SenderDetails> <IDAuthentication> <SenderID>QB19957JW6VG</SenderID> <Authentication> <Method>clear</Method> <Value>Password123</Value> </Authentication> </IDAuthentication> </SenderDetails> </Header> <GovTalkDetails> <Keys/> </GovTalkDetails> <Body> <UserAuthenticationRequest> <Timestamp>2002-02-07T15:01:00-00:00</Timestamp> </UserAuthenticationRequest> </Body> </GovTalkMessage>

Note: The URI to be used for this implementation of GSO will be http://www.govtalk.gov.uk/CM/envelope according to GovTalk XML Schema 2.0.

The following XML document is a sample Credential for Certificate based login:

<?xml version="1.0"?> <GovTalkMessage> <EnvelopeVersion>0.8</EnvelopeVersion> <Header> <MessageDetails> <Class>ADM-user-authentication-request</Class> <Qualifier>request</Qualifier> <Function>submit</Function> <GatewayTimestamp>2003-02-20T11:07:17-00:00</GatewayTimestamp> </MessageDetails> <SenderDetails> <IDAuthentication> <SenderID/> <Authentication> <Method>W3Csigned</Method> <Role>Principal</Role> <Value></Value> <Signature> <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2000/WD-xml-c14n-20001011"/> <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <Reference> <Transforms> <Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116"> <XPath>/GovTalkMessage/Body</XPath> </Transform> </Transforms> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <DigestValue>Vl/ARuS47aUh1QIst2UPyU7dOOA=</DigestValue> </Reference> </SignedInfo>

1 Note: The URI to be used for this implementation of GSO will be http://www.govtalk.gov.uk/CM/envelope according to GovTalk XML Schema 2.0c.


- 11 -

<SignatureValue>Y0KSSyIOArVFhBA1L+YLtHlMhg4+MbR0St47g7vdPeOkyIDVuUW9aXwKfiyR1VdB6BN1rpPK7BYc59V0pTmmVQ==</SignatureValue> </Signature> </Authentication> </IDAuthentication> <X509Certificate>MIIDYzCCAw2gAwIBAgIKXVYb1gAAAAAA5jANBgkqhkiG9w0BAQUFADBAMQswCQYDVQQGEwJHQjENMAsGA1UEBxMEVUtHRzEPMA0GA1UEChMGVUtHRzE2MREwDwYDVQQDEwhVS0dHMTZDQTAeFw0wMzAxMDcxMjQxNDJaFw0wNDAxMDcxMjUxNDJaMGsxJTAjBgkqhkiG9w0BCQEWFnYtZXJpY3dvQG1pY3Jvc29mdC5jb20xCzAJBgNVBAYTAkdCMQ0wCwYDVQQHEwRVS0dHMQ8wDQYDVQQKEwZVS0dHMTYxFTATBgNVBAMTDFRlc3QgQWNjb3VudDBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQDZLdfKPEqD2R+NwydiI2FosGplnoanSdUmkX7qodAo6Gf5gwDcGMhXZRtDkSs1/S0D8QNS8ccxUih0emLh6AAjAgMBAAGjggG8MIIBuDAOBgNVHQ8BAf8EBAMCBPAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFDToSbgaiJue2ZW04DEbpFDJzF8QMHcGA1UdIwRwMG6AFCdJejd27BQRhdeWXtAGfkdYDbEfoUSkQjBAMQswCQYDVQQGEwJHQjENMAsGA1UEBxMEVUtHRzEPMA0GA1UEChMGVUtHRzE2MREwDwYDVQQDEwhVS0dHMTZDQYIQLTw5+FRESr5PClYzCFA+QTBpBgNVHR8EYjBgMC2gK6AphidodHRwOi8vdWtnZzE2Y2EvQ2VydEVucm9sbC9VS0dHMTZDQS5jcmwwL6AtoCuGKWZpbGU6Ly9cXHVrZ2cxNmNhXENlcnRFbnJvbGxcVUtHRzE2Q0EuY3JsMIGNBggrBgEFBQcBAQSBgDB+MDwGCCsGAQUFBzAChjBodHRwOi8vdWtnZzE2Y2EvQ2VydEVucm9sbC91a2dnMTZjYV9VS0dHMTZDQS5jcnQwPgYIKwYBBQUHMAKGMmZpbGU6Ly9cXHVrZ2cxNmNhXENlcnRFbnJvbGxcdWtnZzE2Y2FfVUtHRzE2Q0EuY3J0MA0GCSqGSIb3DQEBBQUAA0EADQ/dGAcGTSOnvFEFkBbLJBQj+sRr/8I06AkeNkTgpC2PZ4LwmQi4DEMh60e9DEsIr2PChH/sLlFroumQnTwC0g==</X509Certificate> <Email/> </SenderDetails> </Header> <GovTalkDetails> <Keys/> </GovTalkDetails> <Body> <UserAuthenticationRequest> <Timestamp>2003-Feb-20 11:07:17</Timestamp> </UserAuthenticationRequest> </Body> </GovTalkMessage>

A detailed explanation of how to sign a document is provided in GG-Sign-XML.doc “UK Online XML Signing in the Government Gateway” available in the Portal Pack supplied by The Office of the E-Envoy.

2.5.5 <CredentialChange>

This XML document is used to change a Level-1 (UserID/Password) user’s password. The CredentialChange document includes the old and new password. The old password can be optionally hashed with the MD5 algorithm but the new password must be sent in clear text (in order to be able to administer a password strength policy). Note MD5 hashes are assumed to be derived from UTF -8 representations of the data.

The XSD for CredentialChange is:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdCredentialChange" xmlns="urn:GSO-System-Services:external:soap:xsdCredentialChange" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="CredentialChange"> <xsd:annotation> <xsd:documentation>Credential Change Schema</xsd:documentation> </xsd:annotation> <xsd:element name="CredentialChange" type="CredentialChangeTYPE" /> <xsd:complexType name="CredentialChangeTYPE"> <xsd:sequence> <xsd:element name="PasswordOld" minOccurs="1" maxOccurs="1"> <xsd:complexType> <xsd:sequence> <xsd:element name="Mode" minOccurs="1" maxOccurs="1" > <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="clear" /> <xsd:enumeration value="MD5" />


- 12 -

</xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Password" type="xsd:string" minOccurs="1" maxOccurs="1" /> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="PasswordNew" minOccurs="1" maxOccurs="1"> <xsd:complexType> <xsd:sequence> <xsd:element name="Mode" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="clear" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Password" type="xsd:string" minOccurs="1" maxOccurs="1" /> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:schema>

The following XML document is a sample CredentialChange:

<?xml version="1.0" encoding="utf-8" ?> <CredentialChange xmlns="urn:GSO-System-Services:external:soap:xsdCredentialChange"> <PasswordOld> <Mode>MD5</Mode> <Password>gnikooLxelpmoCyreV</Password> </PasswordOld> <PasswordNew> <Mode>clear</Mode> <Password>MyNewPassword123</Password> </PasswordNew> </CredentialChange>

2.5.6 <CredentialIdentifier>

This XML document will contain the new CredentialIdentifier. The Credential Identifier will be used by external systems and applications to uniquely identify users. The CredentialIdentifier value is guaranteed to be unique for each user and will not change for that user. Note that the CredentialIdentifier has no meaning to R&E. For example, it is not possible to use the CredentialIdentifier in place of a UserID.

The XSD for CredentialIdentifier is:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdCredentialIdentifier" xmlns="urn:GSO-System-Services:external:soap:xsdCredentialIdentifier" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="CredentialIdentifier"> <xsd:annotation> <xsd:documentation>Credential Identifier Schema</xsd:documentation> </xsd:annotation> <xsd:element name="CredentialIdentifier"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="38" /> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:schema>

The following XML document is a sample CredentialIdentifier:


- 13 -

<?xml version="1.0" encoding="utf-8" ?> <CredentialIdentifier xmlns="urn:GSO-System-Services:external:soap:xsdCredentialIdentifier">394830</CredentialIdentifier>

2.5.7 <ServiceActivationList>

This XML document is used to activate one or more services. ServiceActivationList contains the name of the service and the activation key for each service being activated.

RequestInputData is an optional Boolean which indicates whether the ActivationKey and optional Identifiers should be included in the ServiceAuthenticateList response.

Identifiers must be supplied if activating a service in which the credential is multiply enrolled to uniquely identify the enrolment to be activated, otherwise they are optional. If Identifiers are not supplied when they are required status “Ambiguous” is returned.

The Service Sequence attribute is an optional client supplied attribute which can be used instead of or in conjunction with the RequestInputData attribute to track the response to each activation request. There are no restrictions on Service Sequence except that it must be an integer greater than or equal to zero.

The XSD for ServiceActivationList is:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdServiceActivationList" xmlns="urn:GSO-System-Services:external:soap:xsdServiceActivationList" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="ServiceActivationList"> <xsd:annotation> <xsd:documentation>Service Activation List Schema</xsd:documentation> </xsd:annotation> <xsd:element name="ServiceActivationList" type="ServiceActivationListTYPE" /> <xsd:complexType name="ServiceActivationListTYPE"> <xsd:sequence> <xsd:element name="Service" type="ServiceTYPE" minOccurs="1" maxOccurs="unbounded" /> </xsd:sequence> <xsd:attribute name="RequestInputData" type="xsd:boolean" use="optional" /> </xsd:complexType> <xsd:complexType name="ServiceTYPE"> <xsd:sequence> <xsd:element name="ServiceName" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="50" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="ActivationKey" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="12" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Identifiers" type="IdentifiersTYPE" minOccurs="0" maxOccurs="1" /> </xsd:sequence> <xsd:attribute name="Sequence" type="xsd:integer" use="optional" /> </xsd:complexType> <xsd:complexType name="IdentifiersTYPE"> <xsd:sequence> <xsd:element name="Identifier" type="IdentifierTYPE" minOccurs="1" maxOccurs="unbounded" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="IdentifierTYPE">


- 14 -

<xsd:simpleContent> <xsd:extension base="IdentifierValueTYPE"> <xsd:attribute name="IdentifierType" use="required"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="40" /> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:extension> </xsd:simpleContent> </xsd:complexType> <xsd:simpleType name="IdentifierValueTYPE"> <xsd:restriction base="xsd:string"> <xsd:maxLength value="50" /> </xsd:restriction> </xsd:simpleType> </xsd:schema>

The following XML document is a sample ServiceActivationList:

<?xml version="1.0" encoding="utf-8" ?> <ServiceActivationList xmlns="urn:GSO-System-Services:external:soap:xsdServiceActivationList" RequestInputData="true"> <Service Sequence="1"> <ServiceName>HMCE-PDDEVR</ServiceName> <ActivationKey>N352QN6FB41Q</ActivationKey> </Service> <Service Sequence="2"> <ServiceName>IR-PAYE</ServiceName> <ActivationKey>WSN9QJ5G381E</ActivationKey> <Identifiers> <Identifier IdentifierType="UTR">6660000075</Identifier> </Identifiers> </Service> </ServiceActivationList>

2.5.8 <ServiceAuthenticateList>

This XML document is used whenever it is necessary to return a set of services in response to a SOAP API authenticating a user, validating an A-Ticket in a TicketBook or querying / modifying a user’s enrolment. Due to the generic nature of ServiceAuthenticateList, the SOAP APIs that modify a user’s enrolment only returns the status of the services that were requested in the input parameters (either ServiceList or ServiceActivationList). It does not explicitly inform the SOAP API consumer whether the attempted action was successful or nor (assuming that no fatal business errors were encountered). The exception is GsoEnrol and GsoRegisterAndEnrol which return “Not Enrolled” if enrolment failed, even if the reason for the failure was that the enrolment request was a duplicate of a previous successful enrolment. No fault elements are returned (again assuming no fatal business errors were encountered). It is then up to the SOAP API consumer to check the returned service statuses to check whether each state indicates a success or failure within the context of the SOAP API called. A list of which statuses should be considered as a success and which should be considered as a failure is documented in further detail for each SOAP API. Again, success or failure will not be explicitly stated by ServiceAuthenticateList. The SOAP API consumer must determine success or failure within the SOAP API’s context.

For the GsoActivate SOAP API, ServiceAuthenticateList will include the number of activations that can be attempted before the user is automatically de-enrolled from the service. The order of events for failed activation attempts will be (Status/ActivateAttemptsLeft): Enrolled/2, Enrolled/1, Not Enrolled/0.

Status “Ambiguous” can be returned by GsoActivate and GsoDeEnrol if insufficient information has been supplied to uniquely identify a service enrolment. This occurs if a credential is multiply enrolled in a service. To uniquely identify an enrolment instance the service Identifiers should be supplied.

The XSD for ServiceAuthenticateList is:


- 15 -

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdServiceAuthenticateList" xmlns="urn:GSO-System-Services:external:soap:xsdServiceAuthenticateList" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="ServiceAuthenticateList"> <xsd:annotation> <xsd:documentation>Service Authenticate List Schema</xsd:documentation> </xsd:annotation> <xsd:element name="ServiceAuthenticateList" type="ServiceAuthenticateListTYPE" /> <xsd:complexType name="ServiceAuthenticateListTYPE"> <xsd:sequence> <xsd:element name="Service" type="ServiceTYPE" minOccurs="0" maxOccurs="unbounded" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="ServiceTYPE"> <xsd:sequence> <xsd:element name="ServiceName" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="50" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="ServiceState" type="ServiceStateTYPE" minOccurs="1" maxOccurs="1" /> <xsd:element name="ActivateAttemptsLeft" type="xsd:nonNegativeInteger" minOccurs="0" maxOccurs="1" /> <xsd:element name="Identifiers" type="IdentifiersTYPE" minOccurs="0" maxOccurs="unbounded" /> <xsd:element name="InputData" type="InputDataTYPE" minOccurs="0" maxOccurs="1" /> </xsd:sequence> <xsd:attribute name="Sequence" type="xsd:integer" use="optional" /> <xsd:attribute name="IsClientList" type="xsd:boolean" use="optional" /> </xsd:complexType> <xsd:simpleType name="ServiceStateTYPE"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="Not Enrolled" /> <xsd:enumeration value="Enrolled" /> <xsd:enumeration value="Active" /> <xsd:enumeration value="HandedToAgent" /> <xsd:enumeration value="Suspended" /> <xsd:enumeration value="Ambiguous" /> </xsd:restriction> </xsd:simpleType> <xsd:complexType name="IdentifiersTYPE"> <xsd:sequence> <xsd:element name="Identifier" type="IdentifierTYPE" minOccurs="1" maxOccurs="unbounded" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="IdentifierTYPE"> <xsd:simpleContent> <xsd:extension base="IdentifierValueTYPE"> <xsd:attribute name="IdentifierType" use="required"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="40" /> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:extension> </xsd:simpleContent> </xsd:complexType> <xsd:simpleType name="IdentifierValueTYPE"> <xsd:restriction base="xsd:string"> <xsd:maxLength value="50" /> </xsd:restriction> </xsd:simpleType> <xsd:complexType name="InputDataTYPE"> <xsd:sequence>


- 16 -

<xsd:element name="KnownFacts" type="KnownFactsTYPE" minOccurs="0" maxOccurs="1" /> <xsd:element name="Identifiers" type="IdentifiersTYPE" minOccurs="0" maxOccurs="1" /> <xsd:element name="ActivationKey" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="12" /> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:sequence> </xsd:complexType> <xsd:complexType name="KnownFactsTYPE"> <xsd:sequence> <xsd:element name="KnownFact" minOccurs="1" maxOccurs="unbounded"> <xsd:complexType> <xsd:simpleContent> <xsd:extension base="xsd:string"> <xsd:attribute name="Sequence" type="xsd:nonNegativeInteger" use="required" /> <xsd:attribute name="TransformAlgorithm" use="optional"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="255" /> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:extension> </xsd:simpleContent> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:schema>

The following XML document is a sample ServiceAuthenticateList (note that the example has been fleshed out to include a large number of possible Service combinations from different SOAP APIs and is therefore not a typical, or possible, response from any of the SOAP APIs):

<?xml version="1.0" encoding="utf-8" ?> <ServiceAuthenticateList xmlns="urn:GSO-System-Services:external:soap:xsdServiceAuthenticateList"> <Service> <ServiceName>MOSW1</ServiceName> <ServiceState>Active</ServiceState> <Identifiers> <Identifier IdentifierType="PostCode">TR5 7ZE</Identifier> <Identifier IdentifierType="NINO">3234KDDDF8</Identifier> </Identifiers> </Service> <Service> <ServiceName>MOSW2</ServiceName> <ServiceState>Active</ServiceState> <Identifiers> <Identifier IdentifierType="IDNo">3940P2</Identifier> <Identifier IdentifierType="Shoesize">5</Identifier> </Identifiers> </Service> <Service> <ServiceName>ServiceThree</ServiceName> <ServiceState>Not Enrolled</ServiceState> </Service> <Service> <ServiceName>ServiceFour</ServiceName> <ServiceState>Suspended</ServiceState> </Service> <Service> <ServiceName>ServiceFive</ServiceName> <ServiceState>HandedToAgent</ServiceState> </Service> <Service> <ServiceName>ServiceSix</ServiceName>


- 17 -

<ServiceState>Enrolled</ServiceState> <ActivateAttemptsLeft>2</ActivateAttemptsLeft> </Service> <Service> <ServiceName>ServiceSeven</ServiceName> <ServiceState>Enrolled</ServiceState> <ActivateAttemptsLeft>1</ActivateAttemptsLeft> </Service> <Service> <ServiceName>ServiceEight</ServiceName> <ServiceState>Not Enrolled</ServiceState> <ActivateAttemptsLeft>0</ActivateAttemptsLeft> </Service> </ServiceAuthenticateList>

2.5.9 <ServiceList>

This document is used to supply none, one or more service names to the SOAP APIs. The optional attribute RemoveAgent is used specifically for the GsoSoapDeEnrol API call and is ignored by the other SOAP APIs that use ServiceList.

RequestInputData is an optional Boolean which indicates whether the optional Identifiers should be included in the ServiceAuthenticateList response.

Identifiers must be supplied if DeEnroling a service in which the credential is multiply enrolled to uniquely identify the enrolment to be activated, otherwise they are optional. If Identifiers are not supplied when they are required status “Ambiguous” is returned.

The Service Sequence attribute is an optional client supplied attribute which can be used instead of or in conjunction with the RequestInputData attribute to track the response to each DeEnrol request. For other types of request Service Sequence is ignored. There are no restrictions on Service Sequence except that it must be an integer greater than or equal to zero.

The ClientListIndicator attribute controls whether the Boolean attribute IsClientList will be attached to all service nodes in the output ServiceAuthenticateList. ClientListIndicator is ignored by all methods except GsoAuthenticate and GsoValidate. IsClientList is true if the current Service element is a Client List.

AllServices and AllClients is ignored by all methods except GsoAuthenticate and GsoValidate. AllServices requests that all services associated with the credential be included in the output ServiceAuthenticateList. Any service elements in the ServiceList are ignored unless the service element has an ‘IncludeClients’ attribute in which case all client lists for the marked services are included in the ServiceAuthenticateList.

AllClients indicates all client lists associated with services in the ServiceList should be included in the output ServiceAuthenticateList (i.e. it is as if each service in the ServiceList has IncludeClients = true). AllClients overrides IncludeClients settings.

If both AllServices and AllClients are set to true, All clients associated with all services associated with the credential will be output.

GroupIdentifiers is used by GsoAuthenticate and GsoValidate to indicate whether the identifiers in client list services should be grouped. If True, each set of Client Identifiers is bounded by its own <Identifiers> tag. If False or not present, all client identifiers in a client list service are bounded by a single <Identifiers> tag.

The XSD for ServiceList is:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdServiceList" xmlns="urn:GSO-System-Services:external:soap:xsdServiceList" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="ServiceList"> <xsd:annotation> <xsd:documentation>Service List Schema</xsd:documentation>


- 18 -

</xsd:annotation> <xsd:element name="ServiceList" type="ServiceListTYPE" /> <xsd:complexType name="ServiceListTYPE"> <xsd:sequence> <xsd:element name="Service" type="ServiceTYPE" minOccurs="0" maxOccurs="unbounded" /> </xsd:sequence> <xsd:attribute name="GroupIdentifiers" type="xsd:boolean" use="optional" /> <xsd:attribute name="RequestInputData" type="xsd:boolean" use="optional" /> <xsd:attribute name="ClientListIndicator" type="xsd:boolean" use="optional" /> <xsd:attribute name="AllServices" type="xsd:boolean" use="optional" /> <xsd:attribute name="AllClients" type="xsd:boolean" use="optional" /> </xsd:complexType> <xsd:complexType name="ServiceTYPE"> <xsd:sequence> <xsd:element name="ServiceName" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="50" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Identifiers" type="IdentifiersTYPE" minOccurs="0" maxOccurs="1" /> </xsd:sequence> <xsd:attribute name="RemoveAgent" type="xsd:boolean" use="optional"/> <xsd:attribute name="IncludeClients" type="xsd:boolean" use="optional"/> <xsd:attribute name="Sequence" type="xsd:integer" use="optional" /> </xsd:complexType> <xsd:complexType name="IdentifiersTYPE"> <xsd:sequence> <xsd:element name="Identifier" type="IdentifierTYPE" minOccurs="1" maxOccurs="unbounded" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="IdentifierTYPE"> <xsd:simpleContent> <xsd:extension base="IdentifierValueTYPE"> <xsd:attribute name="IdentifierType" use="required"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="40" /> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:extension> </xsd:simpleContent> </xsd:complexType> <xsd:simpleType name="IdentifierValueTYPE"> <xsd:restriction base="xsd:string"> <xsd:maxLength value="50" /> </xsd:restriction> </xsd:simpleType> </xsd:schema>

2.5.10 <ServiceValidationList>

This XML document is used to enrol a user in one or more servi ces. This is either done as part of a new or existing registration. In addition to specifying the services for enrolment, this XML document includes the Known Facts required to validate the user by the service owner. Each Known Fact must include a Sequence attribute. This is the order in which the Known Facts are passed to the service’s owner validation procedure. In addition, each Known Fact can have a TransformAlgorithm specified. This is essentially the name of a predefined algorithm that the Gateway will use to transform the Known Fact value into a value type that the service owner expects. The Gateway will be offering a standard suite of transform algorithms (such as MD5 hashing, SHA1 hashing, whitespace stripping, etc.) that can be specified as well as custom transforms


- 19 -

created by the service owners. Note hashes are assumed to be derived from UTF-8 representations of the data.

RequestInputData is an optional Boolean which indicates whether the known facts should be included in the ServiceAuthenticateList response.

The Service Sequence attribute is an optional client supplied attribute which can be used instead of or in conjunction with the RequestInputData attribute to track the response to each Enrolment request. There are no restrictions on Service Sequence except that it must be an integer greater than or equal to zero.

The SOAP methods GsoUserIdResend and GsoResetPassword accept a ServiceValidationList but do not return a ServiceAuthenticateList so attributes such as Service Sequence and RequestInputData are ignored for these methods.

The TransformAlgorithm attribute indicates that a supplied known fact must be transformed before being matched against the service list of known facts. For example, setting the TransformAlgorithm = “MD5_CS” allows a known fact to be supplied in clear text but matched against an MD5 hash of the fact.

The set of available transformations is configurable. The method for configuration of available transformations is outside the scope of this document. The set of default available transformations is:

TransformAlgorithm Description

MD5_CS MD5 Hash Case Sensitive

SHA1_CS SHA1 Hash Case Sensitive

MD5_CS_TRIMWS MD5 Hash Case Sensitive Trim White Space

SHA1_CS_TRIMWS SHA1 Hash Case Sensitive Trim White Space

MD5_CI MD5 Hash Case Insensitive

SHA1_CI SHA1 Hash Case Insensitive

MD5_CI_TRIMWS MD5 Hash Case Insensitive Trim White Space

SHA1_CI_TRIMWS SHA1 Hash Case Insensitive Trim White Space

The XSD for ServiceValidationList is:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdServiceValidationList" xmlns="urn:GSO-System-Services:external:soap:xsdServiceValidationList" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="ServiceValidationList"> <xsd:annotation> <xsd:documentation>Service Validation List Schema</xsd:documentation> </xsd:annotation> <xsd:element name="ServiceValidationList" type="ServiceValidationListTYPE" /> <xsd:complexType name="ServiceValidationListTYPE"> <xsd:sequence> <xsd:element name="Service" type="ServiceTYPE" minOccurs="1" maxOccurs="unbounded" /> </xsd:sequence> <xsd:attribute name="RequestInputData" type="xsd:boolean" use="optional" /> </xsd:complexType> <xsd:complexType name="ServiceTYPE"> <xsd:sequence> <xsd:element name="ServiceName" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="50" /> </xsd:restriction> </xsd:simpleType> </xsd:element>


- 20 -

<xsd:element name="KnownFacts" type="KnownFactsTYPE" minOccurs="1" maxOccurs="1" /> </xsd:sequence> <xsd:attribute name="Sequence" type="xsd:integer" use="optional" /> </xsd:complexType> <xsd:complexType name="KnownFactsTYPE"> <xsd:sequence> <xsd:element name="KnownFact" minOccurs="1" maxOccurs="unbounded"> <xsd:complexType> <xsd:simpleContent> <xsd:extension base="xsd:string"> <xsd:attribute name="Sequence" type="xsd:nonNegativeInteger" use="required" /> <xsd:attribute name="TransformAlgorithm" use="optional"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="255" /> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:extension> </xsd:simpleContent> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:schema>

The following XML document is a sample ServiceValidationList:

<?xml version="1.0" encoding="utf-8" ?> <ServiceValidationList xmlns="urn:GSO-System-Services:external:soap:xsdServiceValidationList"> <Service Sequence="5"> <ServiceName>ServiceOne</ServiceName> <KnownFacts> <KnownFact Sequence="0" TransformAlgorithm="MD5Hash">12</KnownFact> <KnownFact Sequence="1">DK89 3DP</KnownFact> </KnownFacts> </Service> <Service Sequence="6"> <ServiceName>ServiceTwo</ServiceName> <KnownFacts> <KnownFact Sequence="0">woNeMetavitcA</KnownFact> </KnownFacts> </Service> </ServiceValidationList>

2.5.11 <UserDetails>

This XML document contains a user’s name, email address, registration category (individual, organisation or agent) and the user’s description. If registering an Agent the AgentID and AgentFriendlyName must also be supplied. If registering an organisation or individual AgentID and AgentFriendlyName must not be supplied. This XML document is for capturing registration details. Note that only the registration category is mandatory. Email address and description are optional. Name must not be included for Level-2 users, that is, users registering with a certificate. A user’s name is extracted from the certificate. However, name must be provided if the user is registering with a UserID/Password.

The AgentID is the agent specified portion of the Agent Group ID used by clients to hand their enrolment to an agent. (The other portion, also known as the AgentCode, is generated by R&E and resembles a UserID). For example, An Agent Group ID may be FRED2-74IU9W8GNRLN, where FRED2 is the AgentID (specified by the Agent) and 74IU9W8GNRLN is the AgentCode (generated by R&E).

The AgentFriendlyName is the name displayed to clients when they confirm the handing of an enrolment to an agent.

The XSD for UserDetails is:


- 21 -

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdUserDetails" xmlns="urn:GSO-System-Services:external:soap:xsdUserDetails" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="UserDetails"> <xsd:annotation> <xsd:documentation>User Details Schema</xsd:documentation> </xsd:annotation> <xsd:element name="UserDetails" type="UserDetailsTYPE" /> <xsd:complexType name="UserDetailsTYPE"> <xsd:all> <xsd:element name="Name" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="64" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Email" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="255" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="RegistrationCategory" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="Individual" /> <xsd:enumeration value="Organisation" /> <xsd:enumeration value="Agent" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Description" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="255" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="AgentID" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:pattern value="([^\ -\/\:-\@\[-\`{-]){1,12}" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="AgentFriendlyName" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:pattern value=".{1,64}" /> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:all> </xsd:complexType> </xsd:schema> The following XML document is a sample UserDetails:

<?xml version="1.0" encoding="utf-8" ?> <UserDetails xmlns="urn:GSO-System-Services:external:soap:xsdUserDetails"> <Name>John Patterson</Name> <Email>[email protected]</Email> <RegistrationCategory>Individual</RegistrationCategory> <Description>I am very pleased with this service.</Description> </UserDetails>

2.5.12 <UserDetailsGet>

This XML document is used to retrieve a user’s details (name, email and registration category). If retrieving the user details for an agent the AgentID, AgentCode and AgentFriendlyName are also populated.


- 22 -

The AgentID is the agent specified component of the ID used by clients to hand their enrolment to an agent.

The AgentCode is the Gateway generated component of the ID used by clients to hand their enrolment to an agent.

The AgentFriendlyName is the name displayed to clients when they confirm the handing of an enrolment to an agent.

The XSD for UserDetailsGet is:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdUserDetailsGet" xmlns="urn:GSO-System-Services:external:soap:xsdUserDetailsGet" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="UserDetailsGet"> <xsd:annotation> <xsd:documentation>User Details Get Schema</xsd:documentation> </xsd:annotation> <xsd:element name="UserDetailsGet" type="UserDetailsGetTYPE" /> <xsd:complexType name="UserDetailsGetTYPE"> <xsd:all> <xsd:element name="Name" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="64" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Email" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="255" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Description" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="255" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="RegistrationCategory" minOccurs="1" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="Individual" /> <xsd:enumeration value="Organisation" /> <xsd:enumeration value="Agent" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="AgentID" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="12" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="AgentCode" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="12" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="AgentFriendlyName" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="64" /> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:all> </xsd:complexType>


- 23 -

</xsd:schema>

The following XML document is a sample UserDetailsGet:

<?xml version="1.0" encoding="utf-8" ?> <UserDetailsGet xmlns="urn:GSO-System-Services:external:soap:xsdUserDetailsGet"> <Name>John Walland</Name> <Email>[email protected]</Email> <RegistrationCategory>Delegate</RegistrationCategory> </UserDetailsGet>

2.5.13 <UserDetailsSet>

This XML document is used to change a user’s details. A user’s name and/or email address and / or description can be changed. The name change must contain at least one character. In addition, only a Level-1 user (UserID/Password) can change his / her name. For Level-2 users (Certificates) the name associated with the certificate is embedded within the X.509 certificate structure. Lastly, these changes will be atomic, either all of the changes requested will be performed or none will. For example, if a Level-2 user attempts to change his / her name and email address, neither change will be applied.

Note there is no facility for changing AgentID, AgentCode or AgentFriendlyName.

The XSD for UserDetailsSet is:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdUserDetailsSet" xmlns="urn:GSO-System-Services:external:soap:xsdUserDetailsSet" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="UserDetailsSet"> <xsd:annotation> <xsd:documentation>User Details Set Schema</xsd:documentation> </xsd:annotation> <xsd:element name="UserDetailsSet" type="UserDetailsSetTYPE" /> <xsd:complexType name="UserDetailsSetTYPE"> <xsd:all> <xsd:element name="Name" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="1" /> <xsd:maxLength value="64" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Email" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="255" /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Description" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="255" /> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:all> </xsd:complexType> </xsd:schema>

The following XML document is a sample UserDetailsSet:

<?xml version="1.0" encoding="utf-8" ?> <UserDetailsSet xmlns="urn:GSO-System-Services:external:soap:xsdUserDetailsSet"> <Name>Alan Patridge</Name> <Email>[email protected]</Email> </UserDetailsSet>


- 24 -

2.5.14 <UserIdentifier>

This XML document is used to supply a UserID (e.g. GsoResetPassword) or return the UserID of users that have successfully enrolled for at least one service when calling the GsoRegisterAndEnrol SOAP API. Note that the UserID is only returned for Level-1 (UserID/Password) users. Level-2 (Certificate) users have no need for a UserID. The UserID is returned so that the user can be subsequently authenticated on the Gateway before the user has activated his / her first service. It is therefore important that the consumer of the SOAP API communicate the UserID back to the user. Without it the user will not be able to authenticate on the Gateway. Note that this UserID cannot be used to activate any services. This activation key will be a different value and communicated to the user in the standard secure fashion (unless the user enrolled in one or more services with a DAT or the services are set to AutoActivate in which case those services will be activated immediately).

The XSD for UserIdentifier:

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdUserIdentifier" xmlns="urn:GSO-System-Services:external:soap:xsdUserIdentifier" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="UserIdentifier"> <xsd:annotation> <xsd:documentation>User Identifier Schema</xsd:documentation> </xsd:annotation> <xsd:element name="UserIdentifier"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="12" /> </xsd:restriction> </xsd:simpleType> </xsd:element> </xsd:schema>

The following document is a sample UserIdentifier:

<?xml version="1.0" encoding="utf-8" ?> <UserIdentifier xmlns="urn:GSO-System-Services:external:soap:xsdUserIdentifier"> N352QN6FB41Q</UserIdentifier>

2.5.15 <LoginDocument>

This XML document will be a GovTalk message required for users authenticating with a certificate (Level-2). It will conform to the existing GovTalk schema and certificate signing standard. This document is obtained by SOAP API consumers calling GsoGetLoginDocument. It will either be base64 encoded or in clear text, according to the mode specified in Base64Encode.

2.5.16 <SignedInfoBlock>

This XML document will contain the SignedInfoBlock required for user authenticating with a certificate. This document is obtained by SOAP API consumers calling GsoGetLoginDocument. It will either be base64 encoded or in clear text, according to the mode specified in Base64Encode.

2.5.17 <Password>

This XML document contains a user’s password. It is used by GsoResendUserId to assist in identifying the Credential of the user whose UserID is to be resent.

<?xml version="1.0" encoding="utf-8" ?> <xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdPassword" xmlns="urn:GSO-System-Services:external:soap:xsdPassword" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.44" id="Password"> <xsd:annotation> <xsd:documentation>Password Schema</xsd:documentation> </xsd:annotation>


- 25 -

<xsd:element name="Password"> <xsd:complexType> <xsd:sequence> <xsd:element name="Mode"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="clear"/> <xsd:enumeration value="MD5"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Value" type="xsd:string" /> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>

2.6 Functional Decomposition The SOAP interface will consist of the following APIs:

2.6.1 GsoRegisterAndEnrol (Implemented in: SecurePortal)

This SOAP API allows a user to be registered according the <UserDetails> and <Credential> information supplied. The <Credential> parameter will be a valid GovTalk message as defined by the GovTalk XSD schema. It can contain either the UserID/Password for a Level-1 user or the Signed Login Document signed by a Level-2 user’s certificate. Utilising the existing GovTalk schema was chosen as it is already widely used for portal authentication and submissions. Once the credentials have been validated according to the predefined business rules (password strength, trusted CAs etc.) the user will be enrolled for the services specified in <ServiceValidationList>. Note that for Level-1 registrations, the password contained in <Credential> must be in clear text and must meet the password strength policy. If either of these conditions are not met then the registration is aborted and the appropriate fault element returned to the SOAP API consumer.

Enrolment for the specified services will be validated by the service owner according to the Known Facts supplied in <ServiceValidationList>. The user must be successfully validated by at least one service in order to complete the registration. Failure to do so will result in the appropriate fault element being returned to the SOAP API consumer and the registration and enrolment aborted. If the user was enrolled for at least one service then the <ServiceAuthenticateList> will be populated with all the services specified in <ServiceValidationList>. Each service will include a status. It is important that the SOAP API consumer check the status of each service as failure to enrol in a service will be reflected in that service’s status. The SOAP API consumer should regard the following service statuses as failure: “Not Enrolled”, “Suspended”, “HandedToAgent”. The SOAP API consumer should regard the following service statuses as success: “Enrolled”, “Active”.

The <UserDetails> is populated with the name, email address, description and registration category. If registering and enrolling an agent (i.e. RegistrationCategory Agent), the AgentID and AgentFriendlyName must also be supplied. If they are specified for a RegistrationCategory other than Agent then they will be ignored. Only registration category is mandatory in all cases. Name, email address and description are optional. Name must be provided for Level-1 users, i.e. users registering with a UserID/Password. Level-2 users must not provide a name. Their name is extracted from the certificate that they are registering with. If a name is provided for a Level-2 user registration then the registration is aborted and the appropriate fault element is returned. This SOAP API will accept whatever the user provides as long as it conforms to the prescribed XML Schema (XSD). Note that eligibility for enrolment in a service is dependent on the registration category. That is, a service owner must specify


- 26 -

whether the service is for individuals, organisations or agents. If the <ServiceValidationList> contains a service that the registration category specified is not eligible for then this indicates that the SOAP API consumer does not have the correct mapping of services to registration categories. In this case the entire register and enrolment is aborted and the appropriate fault element is returned to the SOAP API consumer.

If it was a Level-1 user that successfully registered and enrolled, the <UserIdentifier> will contain that user’s Gateway generated UserID. This UserID must be communicated back to the user as he / she will require it to authenticate on the Gateway at a future date.

The <CredentialIdentifier> will contain the unique identifier generated for that user. This is only provided for applications or portals that need to uniquely identify each user. It is not for the user’s consumption nor can it be used to identify a user to the Gateway (i.e. it cannot be substituted for UserID or used for GsoGetUserDetails).

If the registration and enrolment was successful a valid A-Ticket will be present in the TicketBook returned to the SOAP API consumer. This TicketBook can then be presented to the Gateway for subsequent SOAP APIs that require an authenticated user.

If the registration and enolment completed successfully an A-Ticket will be generated and stored in the returned TicketBook. If an existing A-Ticket is found, the existing A-Ticket will not be validated. It will only be replaced.

If RequestInputData was supplied as True the known facts supplied in the ServiceValidationList are returned in the ServiceAuthenticateList.

If Service Sequence Numbers were supplied in the ServiceValidationList the sequence number attributes are returned in the ServiceAuthenticateList.

2.6.2 GsoEnrolOnly (Implemented in: SecurePortal)

This SOAP API enrols an authenticated user in one or more services. The <ServiceValidationList> will contain one or more service names. Each service will have a set of Known Facts that the service owner will use to validate the enrolment. Each Known Fact must have the correct Sequence attribute. This Sequence attribute is defined by the service owner and dictates the order in which the Known Facts will be evaluated. In addition, the Transform attribute can be specified for each Known Fact. This Transform will contain the name of a transformation that the Gateway will apply to the Known Fact value before presenting the Known Facts to the service owner.

Note that this SOAP API also makes use of <ServiceAuthenticateList> to communicate the service status back to the SOAP API consumer. It is the responsibility of the consumer to determine whether the service status returned indicates success or failure within the context of this SOAP API. The SOAP API consumer should regard the following service statuses as failure: “Not Enrolled”, “Suspended”, “HandedToAgent”. The SOAP API consumer should regard the following service statuses as success: “Enrolled”, “Active ”.

Status “Not Enrolled” means the enrolment attempt failed. A status of “Not Enrolled” can be returned if the credential which attempted the enrolment is already enrolled in a service with the supplied known facts (i.e. a duplicate enrolment attempt returns “Not Enrolled”).

Note that eligibility for enrolment in a service is dependent on the registration category. That is, a service owner must specify whether the service is for representatives, delegates or agents. If the <ServiceValidationList> contains a service that the registration category (that the user has previously registered with) is not eligible for then this indicates that the SOAP API consumer does not have the correct mapping of services to registration categories. In this case the entire


- 27 -

enrolment is aborted and the appropriate fault element is returned to the SOAP API consumer.

Execution of this API requires a valid A-Ticket to be present in the presented TicketBook. Note that if an A-Ticket is found that is valid (in structure and contents) but that has either expired the rolling-time window or the fixed-time window then a separate fault element (from authentication failure) is returned.

If RequestInputData was supplied as True the known facts supplied in the ServiceValidationList are returned in the ServiceAuthenticateList.

If Service Sequence Numbers were supplied in the ServiceValidationList the sequence number attributes are returned in the ServiceAuthenticateList.

2.6.3 GsoActivate (Implemented in: SecurePortal)

This SOAP API will activate a service that the user has previously enrolled for. The list of services that the user is activating are contained in <ServiceActivationList> with the appropriate activation keys for each service. Note that again <ServiceAuthenticationList> is used to communicate success or failure back to the SOAP API consumer through each service’s status. The SOAP API consumer should regard the following service statuses as failure: “Not Enrolled”, “Enrolled”, “Suspended”, “HandedToAgent”, “Ambiguous”. Status “Ambiguous” means the credential is multiply enrolled in the specified service and Identifiers must be supplied to resolve which service enrolment is to be activated. The SOAP API consumer should regard the following service statuses as success: “Active”. Regardless of whether the activation attempt succeeded Identifiers for the service will be returned if possible (i.e. if the service enrolment instance exists and the reference is not ambiguous). For services that failed activation due to an incorrect activation key or the enrolment did not exist, an additional element is included in <ServiceAuthenticateList>. The ActivationAttemptsLeft element will contain the number of times that the user will be permitted to re-attempt to activate the enrolment before the user is automatically de-enrolled from that service. If the user fails to activate a service who’s last status in <ServiceAuthenticateList> was “Enrolled” and ActivateAttemptsLeft was 1, then <ServiceAuthenticateList> will return a status of “Not Enrolled” and ActivateAttemptsLeft as 0 for that service. This means that the user cannot attempt to activate the enrolment anymore has he / she has been automatically de-enrolled for the service as a security measure. Subsequent attempts to activate the service will only return status “Not Enrolled” and no ActivateAttemptsLeft element. If an enrolment is not found the status “Not Enrolled” will be returned with 0 ActivateAttemptsLeft.


If RequestInputData was supplied as True the supplied identifiers (if any) and activation key supplied in the ServiceActivationList are returned in the ServiceAuthenticateList.

If Service Sequence Numbers were supplied in the ServiceActivationList the sequence number attributes are returned in the ServiceAuthenticateList.

2.6.4 GsoAuthenticate (Implemented in: SecurePortal and InternetPublic)

This SOAP API authenticates a user according to the GovTalk message presented as the <Credential> parameter. The GovTalk message will either contain a UserID/Password for Level-1 users or the GovTalk message will be signed by the user’s certificate for Level-2 users. The GovTalk message must conform to the GovTalk XML schema. The contents of the GovTalk message will then be authenticated. Should authentication fail for any reason (the password


- 28 -

specified was incorrect, the UserID specified does not exist, has been suspended or has been deleted, the certificate was not registered) a generic fault element is returned only indicating authentication failed. No further reason is offered. The only exception to this rule is when a certificate user attempts to authenticate with a login document where the timestamp in the login document has expired. This expiry is returned as a separate fault element.

The <ServiceList> is used as a mechanism for the SOAP API consumer to determine what a user’s enrolments are. <ServiceAuthenticateList> will contain all the services specified in <ServiceList> with their associated statuses.

In addition, the user’s <CredentialIdentifier> will be returned for a successful authentication. This <CredentialIdentifier> is supplied to allow the SOAP API consumer to uniquely identify each user. It is guaranteed to be unique for each user and will not change as a user’s enrolments may change. Note that <CredentialIdentifier> cannot be presented to the Gateway to identify a user. The <CredentialIdentifier> cannot be substituted for UserID or any other form of identification. It is designed to only be of use to systems and applications external to the Gateway that need a mechanism to identify returning users.

<UserDetailsGet> will contain the authenticated user’s name, email address, description and registration category. If authenticating an Agent user the UserDetailsGet will also contain the AgentID, AgentCode and AgentFriendlyName. See the description of the <UserDetailsGet> document for a full description of the Agent elements.

If an A-Ticket is found in the TicketBook it is not validated. It will be removed without checking its contents. GsoLogOut and GsoRegisterAndEnrol are the only other SOAP API’s that can remove A-Tickets from a TicketBook.

ClientListIndicator is an optional Boolean attribute on ServiceList which controls whether the attribute “IsClientList” is present in Service nodes which are client lists (lists of client identifiers associated with the agent credential currently being authenticated).

IncludeClients is an optional Boolean attribute on ServiceList/Service which controls whether the clients lists associated with an agent service should also be listed in the output ServiceAuthenticateList.

GroupIdentifiers is used by GsoAuthenticate and GsoValidate to indicate whether the identifiers in client list services should be grouped. If True, Each set of Client Identifiers is bounded by its own <Identifiers> tag. If False or not present, All client identifiers in a client list service are bounded by a single <Identifiers> tag.

AllServices requests that all services associated with the credential be included in the output ServiceAuthenticateList. Any service elements in the ServiceList are ignored unless the service element has an ‘IncludeClients’ attribute in which case all client lists for the marked services are included in the ServiceAuthenticateList.



The following matrix describes how the AllClients and AllServices attributes effect the output of GsoAuthenticate and GsoValidate:

AllServices attribute

AllClients attribute Results

False false Normal (backwardly -compatible) output as seen with UKGG 1.5

True false ALL enrolled services are returned, but NO client services with identifiers are included EXCEPT where the “IncludeClients” attrbute is


- 29 -

specified on <Service> elements.

False true Client services with identifiers are included in all cases where the agent service is explicitly given in the incoming list of services. There is no need to use “IncludeClients” on any particular <Service> element.

True true Everything returned; all services, with all client services containing client identifiers. The equivalent of the current Portal Authentication Service.

2.6.5 GsoValidate (Implemented in: SecurePortal and InternetPublic)

This SOAP API is used to simulate the authentication of a user that has previously been authenticated and issued an A-Ticket. This mechanism will be used when the TicketBook is passed between consumers. The consumer receiving the TicketBook can present this TicketBook and receive back all the user information that is returned from a normal authentication. However, the consumer of this SOAP API must present <ServiceList> to discover a user’s enrolment in a specific set of services. In response this SOAP API will return all of the services in <ServiceAuthenticateList> with the associated status for each service. Note that the <ServiceList> does not need to contain any services at all. It can be an empty XML document (but must still be a well-formed XML document and conform to urn:GSO-System-Service:external:soap:xsdServiceList). In this case all user information is returned as normal but the <ServiceAuthenticateList> will be an empty XML document (but still be a well-formed XML document and conform to urn:GSO-System-Service:external:soap:xsdServiceAuthenticateList.

<CredentialIdentifier> will contain the user’s CredentialIdentifier, and <UserDetailsGet> will contain the user’s name, email address and registration category. If validating an Agent user the UserDetailsGet will also contain the AgentID, AgentCode and AgentFriendlyName. See the description of the <UserDetailsGet> document for a full description of the Agent elements.


ClientListIndicator is an optional Boolean attribute on ServiceList which controls whether the attribute “IsClientList” is present in Service nodes which are client lists (lists of client identifiers associated with the agent credential currently being authenticated).

IncludeClients is an optional Boolean attribute on ServiceList/Service which controls whether the clients lists associated with an agent service should also be listed in the output ServiceAuthenticateList.

GroupIdentifiers is used by GsoAuthenticate and GsoValidate to indicate whether the identifiers in client list services should be grouped. If True, Each set of Client Identifiers is bounded by its own <Identifiers> tag. If False or not present, All client identifiers in a client list service are bounded by a single <Identifiers> tag.

AllServices requests that all services associated with the credential be included in the output ServiceAuthenticateList. Any service elements in the ServiceList are ignored unless the service element has an ‘IncludeClients’ attribute in which case all client lists for the marked services are included in the ServiceAuthenticateList.




- 30 -

2.6.6 GsoRefresh (Implemented in: SecurePortal and InternetPublic)

This SOAP API is used to refresh the expiry time of an A-Ticket. The expiry time for an A-Ticket is for the SOAP interface as a whole (i.e. SecurePortal and InternetPublic will share the same expiry times). This SOAP API only requires a valid <TicketBook> and <CallerSignature> to be present.


2.6.7 GsoDeEnrol (Implemented in: SecurePortal)

This SOAP API is used to de-enrol a user from one or more service(s). The list of services that the user that the user must be de-enrol for are contained in <ServiceList>. The optional RemoveAgent attribute can be used to specify whether the agent (if enrolled) should be removed from the enrolment as well. If not specified the default will be that the agent will not be removed.

<ServiceAuthenticationList> is used to communicate success or failure back to the SOAP API consumer through each service’s status. The SOAP API consumer should regard the following service statuses as failure: “Enrolled”, “Suspended”, “HandedToAgent”, “Active”, “Ambiguous”. Status “Ambiguous” means the credential is multiply enrolled in the specified service and Identifiers must be supplied to resolve which service enrolment is to be deenroled. The SOAP API consumer should regard the following service statuses as success: “Not Enrolled”. If identifiers are available they will be returned except for status Ambiguous. Previously in GSO 1.5 identifiers were not returned if the deenrolment failed but multiple enrolment functionality mandates their inclusion in the response. Note that this SOAP API will use existing business layer components to perform the actual de-enrolment. Any business rule specific logic must be implemented at that layer and not within this SOAP API.


If RequestInputData was supplied as True the identifiers (if any) supplied in the ServiceList are returned in the ServiceAuthenticateList.

If Service Sequence Numbers were supplied in the ServiceList the sequence number attributes are returned in the ServiceAuthenticateList.

2.6.8 GsoGetUserDetails (Implemented in: SecurePortal)

This SOAP API is used to retrieve a user’s name, email address and registration category through <UserDetailsGet>. If retrieving the details of an Agent user the UserDetailsGet will also contain the AgentID, AgentCode and AgentFriendlyName. See the description of the <UserDetailsGet> document for a full description of the Agent elements. Even though UserDetails are returned through the GsoAuthenticate and GsoValidate SOAP APIs, this API is provided for applications that need to retrieve this user information sometime after authentication.

Execution of this API requires a valid A-Ticket to be present in the presented TicketBook. Note that if an A-Ticket is found that is valid (in structure and content) but that has either expired the rolling-time window or the fixed-time window then a separate fault element (from authentication failure) is returned.


- 31 -

2.6.9 GsoSetUserDetails (Implemented in: SecurePortal)

This SOAP API is used to change a user’s name and / or email address. Note that only Level-1 users (UserID/Password) can change their name. Level-2 users (Certificate) cannot change their name as this information is extracted from their X.509 certificate. This API is atomic, i.e. if both a new user name and email address are supplied but the user is a Level-2 (Certificate) user then neither the name nor email address will be changed. Only a fault element will be returned. Note that the user cannot change their name to an empty string. At least one character must be specified.


2.6.10 GsoGetLoginDocument (Implemented in: SecurePortal and InternetPublic)

This SOAP API receives <Base64Encode> that indicates whether the SOAP API consumer requires the LoginDocument and SignedInfoBlock to be base64 encoded or in clear text.

This SOAP API does not accept a ticket book and therefore does not require an A-Ticket.

2.6.11 GsoLogOut (Implemented in: SecurePortal and InternetPublic)

This SOAP API provides a mechanism for SOAP API consumers to remove A-Tickets from their TicketBook. As the consumers should never attempt to inspect or decode the TicketBook this API is necessary for cleaning up the A-Ticket should the user want to authenticate with different credentials or the A-Ticket has expired and the user wishes to re-authenticate. This API does not check the validity of the A-Ticket. It only removes the elements in the TicketBook that were put there by the Gateway.

2.6.12 GsoSetPassword (Implemented in: SecurePortal)

This SOAP API allows a user to change his / her password. The password change is contained in the <CredentialChange> XML document. Within CredentialChange are PasswordOld and PasswordNew. The old password can be supplied as an MD5 hash but the new password must be supplied as clear text. This is necessary as the password strength policy must be applied to the new password before the change is persisted. Note MD5 hashes are assumed to be derived from UTF -8 representations of the data. A fault element is returned indicating the password strength policy violation.


2.6.13 GsoResetPassword (Implemented in: SecurePortal)

This SOAP API allows a user to reset his / her password. The User must supply their UserID (via a UserIdentifier document) and a ServiceValidationList which contains one service + known facts. These details are used to identify the User’s Credential. If the user supplied correct information a new password which is compliant with password strength rules is generated and sent to the user via Secure Mail.

Note GsoResetPassword and GsoUserIdResend can only be called once within a predefined time limit (stored in the GatewayProperties table ID 4). The default


- 32 -

time limit is 3 days. If GsoResetPassword or GsoUserIdResend is called less than 3 days after a previous successful call to GsoResetPassword or GsoUserIdResend an error is returned.

2.6.14 GsoUserIdResend (Implemented in: SecurePortal)

This SOAP API allows a user to request their UserID be resent to him / her. The user must supply their Password (via a <Password> document) and a ServiceValidationList which contains one service + known facts. These details are used to identify the User’s Credential. If the user supplied correct information the UserID is sent to the user via Secure Mail.

Note GsoResetPassword and GsoUserIdResend can only be called once within a predefined time limit (stored in the GatewayProperties table ID 4). The default time limit is 3 days. If GsoResetPassword or GsoUserIdResend is called less than 3 days after a previous successful call to GsoResetPassword or GsoUserIdResend an error is returned.

2.7 Data 2.7.1 Persistent State

The Web Servi ces do not maintain A-Ticket state in the R&E database. All authentication state is administered through the <TicketBook>. The SOAP API consumer is required to present a TicketBook for every single SOAP API call. However, depending on which SOAP API is called, a valid A-Ticket may or may not be required. For example, GsoEnrolOnly requires a valid A-Ticket but GsoRegisterAndEnrol does not. In addition, the SOAP API consumer is required to persist the TicketBook included in a SOAP API response as the A-Ticket in this TicketBook may not have the same value as the A-Ticket presented in the SOAP API request.

Contained within the A-Ticket will be date time information of the last successful SOAP API call. If the time period between the last successful SOAP API call and the current SOAP API call is longer than the configured rolling-window expiry time then the A-Ticket will be deemed invalid. In addition, the A-Ticket’s first issue time is checked against the fixed-window expiry time. It will therefore be impossible for a SOAP API consumer to keep refreshing an A-Ticket indefinitely. These timeout periods apply to all SOAP API interfaces as a whole.

The time the User last successfully executed a GsoUserIdResend or GsoResetPassword transaction is stored with the user’s Credential. This is required to enforce the business rule that GsoUserIdResend and GsoResetPassword can only be called once every 3 days (configurable).

2.7.2 Data Flows / Transformations

SOAP API messages will be formatted according to the GsoSoapSecurePortal.wsdl and GsoSoapInternetPublic.wsdl definitions. These Web Service Definition Language files conform to the Web Services Description Language (WSDL) 1.1, W3C Note 15 March 2001 and Simple Object Access Protocol (SOAP) 1.1, W3C Note 08 May 2000.

2.7.3 Session State

No session state will be maintained between the SOAP API consumer and provider. Note that the TicketBook is not persisted in the session state.

2.7.4 Temporal State

The A-Ticket will be subject to an rolling-time and fixed-time expiry time interval. See Persistent State for more information.


- 33 -

3 Error & Exception Processing

3.1 Error Classifications 3.1.1 Business Recoverable Errors

Due to the restriction of Fault elements in the SOAP specification, no business recoverable errors are defined through fault elements. A SOAP response cannot contain the response message as well as Fault elements. Therefore each of the SOAP APIs is atomic, i.e. either the transaction took place as expected or the transaction did not take place at all.

All business recoverable errors are interpreted through the <ServiceAuthenticateList> XML document. These errors are not communicated explicitly to the SOAP API consumer. It is the consumer’s responsibility to interpret these service statuses and determine success or failure in the context of the SOAP API’s business function. The following matrix documents the SOAP APIs using the <ServiceAuthenticateList> in their response and how the service status should be interpreted (Success, Failure, Not Applicable):

ServiceAuthenticateListStatus

GsoR

egisterAndE

nrol

GsoE

nrolOnly

GsoA

ctivate

GsoA

uthenticate

GsoV

alidate

GsoD

eEnrol

GsoA

uthenticate

GsoV

alidate

Not Enrolled F F F NA NA S NA NAEnrolled S S F NA NA F NA NA

Active S S S NA NA F NA NAHandedToAgent S S F NA NA F NA NA

Suspended NA NA F NA NA F NA NAAmbiguous NA NA F NA NA F NA NA

3.1.2 Business Fatal Errors

The following matrix illustrates the possible business fatal errors. Business fatal errors are returned as fault elements. Note that the fault elements are returned in the namespace and schema defined by the Microsoft SOAP Toolkit 2.0 SP2. For more information on how the SOAP Toolkit implements fault elements see Understanding the SOAP Fault <detail> Contents. The <returnCode> will be the HRESULT return value of the method in GsoSoapSecurePortal or GsoSoapInternetPublic. For more information on the structure of an HRESULT see Platform SDK: COM: Error Handling. Note that some of the error conditions documented in the Functional Specification of Authentication and Authorisation are implemented by the XML Schema (XS D) of the relevant XML document / parameter. An example of this implementation is the passing of a new password in CredentialChange as an MD5 hash. Note MD5 hashes are assumed to be derived from UTF-8 representations of the data. The XSD of CredentialChange (urn:GSO-System-Service:external:soap:xsdCredentialChange) does not allow MD5 to be specified of the mode for PasswordNew.

Note that the HRESULT is calculated by offsetting the Error Code by vbObjectError (-2147221504, 0x80040000), also known as SEVERITY_ERROR with FACILITY_ITF.


- 34 -

AP

I Co

un

t

ErrorCode

HRESULT(Hex)

HRESULT(Dec)

Description

26 10 8 12 10 6 8 7 12 4 4 10 8 9 9 6 10 4 4 0

11001 80042AF9 -2147210503 Authentication of Credential failed. 13 X X X X X X X X X X X X X11002 80042AFA -2147210502 Certificate issuer not trusted. 2 X X11003 80042AFB -2147210501 Authentication of CallerSignature failed. 17 X X X X X X X X X X X X X X X X X11004 80042AFC -2147210500 Timestamp in LoginDocument has expired. 2 X X11005 80042AFD -2147210499 Authentication of Certificate failed. 2 X X

12001 80042EE1 -2147209503 Name not supplied for Level-1 registration. Registration aborted. 1 X12002 80042EE2 -2147209502 Failed enrolment for all services. Registration aborted. 1 X12003 80042EE3 -2147209501 Registration category not eligibile for a service. Registration aborted. 1 X12004 80056763 -2147129501 Registration category not eligible for a service. Enrolment aborted. 1 X12005 80042EE5 -2147209499 Password does not meet strength policy. Registration aborted. 1 X12006 80042EE6 -2147209498 Password must be supplied in clear text. Registration aborted. 1 X12007 80042EE7 -2147209497 Name supplied for Level-2 registration. Registration aborted. 1 X12008 80042EE8 -2147209496 Known facts supplied already in use. Registration aborted. 1 X12009 80042EE9 -2147209495 Known facts supplied already in use. Enrolment aborted. 1 X12011 80042EEB -2147209493 User details or certificate not unique. Registration aborted. 1 X12012 80042EEC -2147209492 Invalid email address. Registration aborted. 1 X12013 80042EED -2147209491 Invalid description. Registration aborted. 1 X12014 80042EEE -2147209490 Invalid name. Registration aborted. 1 X

13001 800432C9 -2147208503 Level-2 user cannot change name. UserDetailsSet aborted. 1 X13002 800432CA -2147208502 Cannot change name to empty string. UserDetailsSet aborted. 1 X13003 800432CB -2147208501 Password does not meet strength policy. SetPassword aborted. 1 X13004 800432CC -2147208500 Level-2 user cannot change password. SetPassword aborted. 1 X13005 800432CD -2147208499 Invalid email address. SetUserDetails aborted. 1 X13006 800432CE -2147208498 Old password supplied is incorrect. SetPassword aborted. 1 X13007 800432CF -2147208497 User specified not found. Transaction aborted. 2 X X13008 800432D0 -2147208496 Invalid name. SetUserDetails aborted. 1 X13009 800432D1 -2147208495 Invalid description. SetUserDetails aborted. 1 X13010 800432D2 -2147208494 This request occurred too soon after a previous attempt to perform this or a related operation. 1 X X13011 800432D3 -2147208493 The supplied ServiceValidationList contains too many services for the current operation. 2 X X13012 800432D4 -2147208492 AgentID must be specified for RegistrationCategory Agent. Registration aborted. 1 X13013 800432D5 -2147208491 AgentFriendlyName must be specified for RegistrationCategory Agent. Registration aborted. 1 X

14001 800436B1 -2147207503 A-Ticket has expired. 10 X X X X X X X X X X

15001 80043A99 -2147206503 Validation of Base64Encode structure failed. 2 X X15002 80043A9A -2147206502 Validation of CallerSignature structure failed. 17 X X X X X X X X X X X X X X X X X15003 80043A9B -2147206501 Validation of Credential structure failed. 3 X X X15004 80043A9C -2147206500 Validation of CredentialIdentifier structure failed. 3 X X X15005 80043A9D -2147206499 Validation of CredentialChange structure failed. 1 X15006 80043A9E -2147206498 Validation of LoginDocument structure failed. 2 X X15007 80043A9F -2147206497 Validation of ServiceActivationList structure failed. 1 X15008 80043AA0 -2147206496 Validation of ServiceAuthenticateList structure failed. 8 X X X X X X X X15009 80043AA1 -2147206495 Validation of ServiceList structure failed. 5 X X X X X15010 80043AA2 -2147206494 Validation of ServiceValidationList structure failed. 4 X X X X15011 80043AA3 -2147206493 Validation of SignedInfoBlock structure failed. 2 X X15012 80043AA4 -2147206492 Validation of TicketBook structure failed. 15 X X X X X X X X X X X X X X X15013 80043AA5 -2147206491 Validation of UserDetails structure failed. 1 X15014 80043AA6 -2147206490 Validation of UserDetailsGet structure failed. 5 X X X X X15015 80043AA7 -2147206489 Validation of UserDetailsSet structure failed. 1 X15016 80043AA8 -2147206488 Validation of UserIdentifier structure failed.. 2 X X15017 80043AA9 -2147206487 Validation of Password structure failed.. 1 X

16001 80043E81 -2147205503 An internal error occurred. Transaction aborted. 19 X X X X X X X X X X X X X X X X X X XInternal Faults

GsoV

alidate

GsoLogO

ut

GsoLogO

ut

GsoS

etPassw

ord

GsoA

uthenticate

GsoR

efresh

GsoD

eEnrol

GsoG

etUserD

etails

GsoS

etUserD

etails

GsoG

etLoginDocum

entService Faults

GsoA

uthenticate

GsoV

alidate

GsoR

efresh

GsoG

etLoginDocum

ent

GsoR

esetPassw

ord

GsoU

serIdResend

SecurePortal

User Faults

Ticket Faults

XML Faults

InternetPublic

Fault Count

Authentication Faults

GsoR

egisterAndE

nrol

GsoE

nrolOnly

GsoA

ctivate

3.1.3 System Recoverable Errors

Not Applicable.

3.1.4 System Fatal Errors

Not Applicable.

3.2 Exception Interface 3.2.1 Exception Types Thrown

All exception processing will be done through SOAP fault elements.

3.2.2 Internal Exceptions

The only internal exception that will be returned to the SOAP API consumer will be Error Code 16001 or HRESULT (0x80043E81 / -2147205503).

3.2.3 Exception Architecture / Policy

All exceptions will be returned as SOAP fault elements.

3.3 Security Considerations 3.3.1 Privacy

All HTTP traffic to the SecurePortal and InternetPublic will be protected by SSL. In addition, SecurePortal will be protected by client-side certificates. InternetPublic will only be secured by a server-side certificate. See the Interfaces section for more detail.


- 35 -

3.3.2 Authentication / Authorisation

The GsoSoap Authentication and Authorisation implementation is discussed in detail in the Interfaces section of this document.


- 36 -

4 Appendix A – WSDL and IDL

4.1 SecurePortal WSDL

The WSDL file for the SecurePortal SOAP interface (https://secure.gateway.gov.uk/soap/SecurePortal) is as follows. Note that the Namespace used in all XSDs for the SOAP APIs use parameter specific namespaces urn:GSO-System-Services:external:soap:xsd<ParameterName>. The GsoSoapSecurePortalService.wsdl file will be as follows:

<?xml version='1.0' encoding='UTF-8' ?> <definitions name='GsoSoapSecurePortalService' targetNamespace='urn:GSO-System-Services:external:soap:wsdl:' xmlns:wsdlns='urn:GSO-System-Services:external:soap:wsdl:' xmlns:typens='urn:GSO-System-Services:external:soap:type' xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:stk='http://schemas.microsoft.com/soap-toolkit/wsdl-extension' xmlns='http://schemas.xmlsoap.org/wsdl/'> <types> <schema targetNamespace='urn:GSO-System-Services:external:soap:type' xmlns='http://www.w3.org/2001/XMLSchema' xmlns:SOAP-ENC='http://schemas.xmlsoap.org/soap/encoding/' xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/' elementFormDefault='qualified'> </schema> </types> <message name='SecurePortal.GsoRegisterAndEnrol'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> <part name='ServiceValidationList' type='xsd:string'/> <part name='UserDetails' type='xsd:string'/> <part name='Credential' type='xsd:string'/> </message> <message name='SecurePortal.GsoRegisterAndEnrolResponse'> <part name='TicketBook' type='xsd:string'/> <part name='UserIdentifier' type='xsd:string'/> <part name='CredentialIdentifier' type='xsd:string'/> <part name='ServiceAuthenticateList' type='xsd:string'/> </message> <message name='SecurePortal.GsoEnrolOnly'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> <part name='ServiceValidationList' type='xsd:string'/> </message> <message name='SecurePortal.GsoEnrolOnlyResponse'> <part name='TicketBook' type='xsd:string'/> <part name='ServiceAuthenticateList' type='xsd:string'/> </message> <message name='SecurePortal.GsoActivate'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> <part name='ServiceActivationList' type='xsd:string'/> </message> <message name='SecurePortal.GsoActivateResponse'> <part name='TicketBook' type='xsd:string'/> <part name='ServiceAuthenticateList' type='xsd:string'/> </message> <message name='SecurePortal.GsoAuthenticate'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> <part name='Credential' type='xsd:string'/> <part name='ServiceList' type='xsd:string'/> </message> <message name='SecurePortal.GsoAuthenticateResponse'> <part name='TicketBook' type='xsd:string'/> <part name='ServiceAuthenticateList' type='xsd:string'/> <part name='CredentialIdentifier' type='xsd:string'/> <part name='UserDetailsGet' type='xsd:string'/> </message> <message name='SecurePortal.GsoValidate'>


- 37 -

<part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> <part name='ServiceList' type='xsd:string'/> </message> <message name='SecurePortal.GsoValidateResponse'> <part name='TicketBook' type='xsd:string'/> <part name='ServiceAuthenticateList' type='xsd:string'/> <part name='CredentialIdentifier' type='xsd:string'/> <part name='UserDetailsGet' type='xsd:string'/> </message> <message name='SecurePortal.GsoRefresh'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> </message> <message name='SecurePortal.GsoRefreshResponse'> <part name='TicketBook' type='xsd:string'/> </message> <message name='SecurePortal.GsoDeEnrol'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> <part name='ServiceList' type='xsd:string'/> </message> <message name='SecurePortal.GsoDeEnrolResponse'> <part name='TicketBook' type='xsd:string'/> <part name='ServiceAuthenticateList' type='xsd:string'/> </message> <message name='SecurePortal.GsoGetUserDetails'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> </message> <message name='SecurePortal.GsoGetUserDetailsResponse'> <part name='TicketBook' type='xsd:string'/> <part name='UserDetailsGet' type='xsd:string'/> </message> <message name='SecurePortal.GsoSetUserDetails'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> <part name='UserDetailsSet' type='xsd:string'/> </message> <message name='SecurePortal.GsoSetUserDetailsResponse'> <part name='TicketBook' type='xsd:string'/> </message> <message name='SecurePortal.GsoGetLoginDocument'> <part name='Base64Encode' type='xsd:string'/> </message> <message name='SecurePortal.GsoGetLoginDocumentResponse'> <part name='LoginDocument' type='xsd:string'/> <part name='SignedInfoBlock' type='xsd:string'/> </message> <message name='SecurePortal.GsoLogOut'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> </message> <message name='SecurePortal.GsoLogOutResponse'> <part name='TicketBook' type='xsd:string'/> </message> <message name='SecurePortal.GsoSetPassword'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> <part name='CredentialChange' type='xsd:string'/> </message> <message name='SecurePortal.GsoSetPasswordResponse'> <part name='TicketBook' type='xsd:string'/> </message> <message name='SecurePortal.GsoUserIdResend'> <part name='CallerSignature' type='xsd:string' /> <part name='Password' type='xsd:string' /> <part name='ServiceValidationList' type='xsd:string' /> </message> <message name='SecurePortal.GsoUserIdResendResponse' /> <message name='SecurePortal.GsoResetPassword'> <part name='CallerSignature' type='xsd:string' /> <part name='UserIdentifier' type='xsd:string' /> <part name='ServiceValidationList' type='xsd:string' /> </message> <message name='SecurePortal.GsoResetPasswordResponse' /> <portType name='SecurePortalSoapPort'>


- 38 -

<operation name='GsoRegisterAndEnrol' parameterOrder='TicketBook CallerSignature ServiceValidationList UserDetails Credential UserIdentifier CredentialIdentifier ServiceAuthenticateList'> <input message='wsdlns:SecurePortal.GsoRegisterAndEnrol' /> <output message='wsdlns:SecurePortal.GsoRegisterAndEnrolResponse' /> </operation> <operation name='GsoEnrolOnly' parameterOrder='TicketBook CallerSignature ServiceValidationList ServiceAuthenticateList'> <input message='wsdlns:SecurePortal.GsoEnrolOnly' /> <output message='wsdlns:SecurePortal.GsoEnrolOnlyResponse' /> </operation> <operation name='GsoActivate' parameterOrder='TicketBook CallerSignature ServiceActivationList ServiceAuthenticateList'> <input message='wsdlns:SecurePortal.GsoActivate' /> <output message='wsdlns:SecurePortal.GsoActivateResponse' /> </operation> <operation name='GsoAuthenticate' parameterOrder='TicketBook CallerSignature Credential ServiceList ServiceAuthenticateList CredentialIdentifier UserDetailsGet'> <input message='wsdlns:SecurePortal.GsoAuthenticate' /> <output message='wsdlns:SecurePortal.GsoAuthenticateResponse' /> </operation> <operation name='GsoValidate' parameterOrder='TicketBook CallerSignature ServiceList ServiceAuthenticateList CredentialIdentifier UserDetailsGet'> <input message='wsdlns:SecurePortal.GsoValidate' /> <output message='wsdlns:SecurePortal.GsoValidateResponse' /> </operation> <operation name='GsoRefresh' parameterOrder='TicketBook CallerSignature'> <input message='wsdlns:SecurePortal.GsoRefresh' /> <output message='wsdlns:SecurePortal.GsoRefreshResponse' /> </operation> <operation name='GsoDeEnrol' parameterOrder='TicketBook CallerSignature ServiceList ServiceAuthenticateList'> <input message='wsdlns:SecurePortal.GsoDeEnrol' /> <output message='wsdlns:SecurePortal.GsoDeEnrolResponse' /> </operation> <operation name='GsoGetUserDetails' parameterOrder='TicketBook CallerSignature UserDetailsGet'> <input message='wsdlns:SecurePortal.GsoGetUserDetails' /> <output message='wsdlns:SecurePortal.GsoGetUserDetailsResponse' /> </operation> <operation name='GsoSetUserDetails' parameterOrder='TicketBook CallerSignature UserDetailsSet'> <input message='wsdlns:SecurePortal.GsoSetUserDetails' /> <output message='wsdlns:SecurePortal.GsoSetUserDetailsResponse' /> </operation> <operation name='GsoGetLoginDocument' parameterOrder='Base64Encode LoginDocument SignedInfoBlock'> <input message='wsdlns:SecurePortal.GsoGetLoginDocument' /> <output message='wsdlns:SecurePortal.GsoGetLoginDocumentResponse' /> </operation> <operation name='GsoLogOut' parameterOrder='TicketBook CallerSignature'> <input message='wsdlns:SecurePortal.GsoLogOut' /> <output message='wsdlns:SecurePortal.GsoLogOutResponse' /> </operation> <operation name='GsoSetPassword' parameterOrder='TicketBook CallerSignature CredentialChange'> <input message='wsdlns:SecurePortal.GsoSetPassword' /> <output message='wsdlns:SecurePortal.GsoSetPasswordResponse' /> </operation> <operation name='GsoResetPassword' parameterOrder='CallerSignature UserIdentifier ServiceValidationList'> <input message='wsdlns:SecurePortal.GsoResetPassword' /> <output message='wsdlns:SecurePortal.GsoResetPasswordResponse' /> </operation> <operation name='GsoUserIdResend' parameterOrder='CallerSignature Password ServiceValidationList'> <input message='wsdlns:SecurePortal.GsoUserIdResend' /> <output message='wsdlns:SecurePortal.GsoUserIdResendResponse' /> </operation> </portType> <binding name='SecurePortalSoapBinding' type='wsdlns:SecurePortalSoapPort' > <stk:binding preferredEncoding='UTF-8'/> <soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http' /> <operation name='GsoRegisterAndEnrol' >


- 39 -

<soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoRegisterAndEnrol' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoEnrolOnly' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoEnrolOnly' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoActivate' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoActivate' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoAuthenticate' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoAuthenticate' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoValidate' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoValidate' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoRefresh' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoRefresh' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input>


- 40 -

<output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoDeEnrol' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoDeEnrol' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoGetUserDetails' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoGetUserDetails' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoSetUserDetails' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoSetUserDetails' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoGetLoginDocument' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoGetLoginDocument' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoLogOut' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoLogOut' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoSetPassword' >


- 41 -

<soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoSetPassword' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoResetPassword' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoResetPassword' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoUserIdResend' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:SecurePortal.GsoUserIdResend' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> </binding> <service name='GsoSoapSecurePortalService' > <port name='SecurePortalSoapPort' binding='wsdlns:SecurePortalSoapBinding' > <soap:address location='https://secure.gso.eval/soap/SecurePortal/GsoSoapSecurePortalService.WSDL' /> </port> </service> </definitions>


- 42 -


- 43 -

4.2 InternetPublic WSDL The WSDL file for the InternetPublic SOAP interface (https://secure.gateway.gov.uk/soap/InternetPublic) is as follows. Note that the Namespace used in all XSDs for the SOAP APIs use parameter specific namespaces urn:GSO-System-Services:external:soap:xsd<ParameterName>. The GsoSoapInternetPublicService.wsdl file will be as follows:

<?xml version='1.0' encoding='UTF-8' ?> <definitions name='GsoSoapInternetPublicService' targetNamespace='urn:GSO-System-Services:external:soap:wsdl:' xmlns:wsdlns='urn:GSO-System-Services:external:soap:wsdl:' xmlns:typens='urn:GSO-System-Services:external:soap:type' xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:stk='http://schemas.microsoft.com/soap-toolkit/wsdl-extension' xmlns='http://schemas.xmlsoap.org/wsdl/'> <types> <schema targetNamespace='urn:GSO-System-Services:external:soap:type' xmlns='http://www.w3.org/2001/XMLSchema' xmlns:SOAP-ENC='http://schemas.xmlsoap.org/soap/encoding/' xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/' elementFormDefault='qualified'> </schema> </types> <message name='InternetPublic.GsoAuthenticate'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> <part name='Credential' type='xsd:string'/> <part name='ServiceList' type='xsd:string'/> </message> <message name='InternetPublic.GsoAuthenticateResponse'> <part name='TicketBook' type='xsd:string'/> <part name='ServiceAuthenticateList' type='xsd:string'/> <part name='CredentialIdentifier' type='xsd:string'/> <part name='UserDetailsGet' type='xsd:string'/> </message> <message name='InternetPublic.GsoRefresh'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> </message> <message name='InternetPublic.GsoRefreshResponse'> <part name='TicketBook' type='xsd:string'/> </message> <message name='InternetPublic.GsoValidate'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> <part name='ServiceList' type='xsd:string'/> </message> <message name='InternetPublic.GsoValidateResponse'> <part name='TicketBook' type='xsd:string'/> <part name='ServiceAuthenticateList' type='xsd:string'/> <part name='CredentialIdentifier' type='xsd:string'/> <part name='UserDetailsGet' type='xsd:string'/> </message> <message name='InternetPublic.GsoGetLoginDocument'> <part name='Base64Encode' type='xsd:string'/> </message> <message name='InternetPublic.GsoGetLoginDocumentResponse'> <part name='LoginDocument' type='xsd:string'/> <part name='SignedInfoBlock' type='xsd:string'/> </message> <message name='InternetPublic.GsoLogOut'> <part name='TicketBook' type='xsd:string'/> <part name='CallerSignature' type='xsd:string'/> </message> <message name='InternetPublic.GsoLogOutResponse'> <part name='TicketBook' type='xsd:string'/> </message> <portType name='InternetPublicSoapPort'> <operation name='GsoAuthenticate' parameterOrder='TicketBook CallerSignature Credential ServiceList ServiceAuthenticateList CredentialIdentifier


- 44 -

UserDetailsGet'> <input message='wsdlns:InternetPublic.GsoAuthenticate' /> <output message='wsdlns:InternetPublic.GsoAuthenticateResponse' /> </operation> <operation name='GsoRefresh' parameterOrder='TicketBook CallerSignature'> <input message='wsdlns:InternetPublic.GsoRefresh' /> <output message='wsdlns:InternetPublic.GsoRefreshResponse' /> </operation> <operation name='GsoValidate' parameterOrder='TicketBook CallerSignature ServiceList ServiceAuthenticateList CredentialIdentifier UserDetailsGet'> <input message='wsdlns:InternetPublic.GsoValidate' /> <output message='wsdlns:InternetPublic.GsoValidateResponse' /> </operation> <operation name='GsoGetLoginDocument' parameterOrder='Base64Encode LoginDocument SignedInfoBlock'> <input message='wsdlns:InternetPublic.GsoGetLoginDocument' /> <output message='wsdlns:InternetPublic.GsoGetLoginDocumentResponse' /> </operation> <operation name='GsoLogOut' parameterOrder='TicketBook CallerSignature'> <input message='wsdlns:InternetPublic.GsoLogOut' /> <output message='wsdlns:InternetPublic.GsoLogOutResponse' /> </operation> </portType> <binding name='InternetPublicSoapBinding' type='wsdlns:InternetPublicSoapPort' > <stk:binding preferredEncoding='UTF-8'/> <soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http' /> <operation name='GsoAuthenticate' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:InternetPublic.GsoAuthenticate' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoRefresh' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:InternetPublic.GsoRefresh' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoValidate' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:InternetPublic.GsoValidate' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoGetLoginDocument' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:InternetPublic.GsoGetLoginDocument' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />


- 45 -

</input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> <operation name='GsoLogOut' > <soap:operation soapAction='urn:GSO-System-Services:external:soap:action:InternetPublic.GsoLogOut' /> <input> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </input> <output> <soap:body use='encoded' namespace='urn:GSO-System-Services:external:soap:message:' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' /> </output> </operation> </binding> <service name='GsoSoapInternetPublicService' > <port name='InternetPublicSoapPort' binding='wsdlns:InternetPublicSoapBinding' > <soap:address location='https://secure.gso.eval/soap/InternetPublic/GsoSoapInternetPublicService.WSDL' /> </port> </service> </definitions>

Government Gateway Developer Guide to Authentication and Authorisation Web Services

Documents

Transcript of Government Gateway Developer Guide to Authentication and Authorisation Web Services