Developer Guide to Authentication and Authorisation Web Services Secure and Public

Transcription

1 Government Gateway Developer Guide to Authentication and Authorisation Web Services Secure and Public Version ( ) - 1 -

2 Table of Contents Government Gateway 1 Developer Guide to Authentication and Authorisation Web Services Secure and Public 1 1 Introduction Document Scope & Audience Terms and Abbreviations References 4 2 Architecture Background Overview Scope Assumptions A Note on Identifiers Interfaces External Interfaces Consumed / Dependant Schema <Base64Encode> <CallerSignature> <Credential> <CredentialChange> <CredentialIdentifier> <ServiceActivationList> <ServiceAuthenticateList> <ServiceList> <ServiceValidationList> <UserDetails> <UserDetailsGet> <UserDetailsSet> <UserIdentifier> <LoginDocument> <SignedInfoBlock> <Password> Functional Decomposition GsoRegisterAndEnrol (Implemented in: SecurePortal) GsoEnrolOnly (Implemented in: SecurePortal) GsoActivate (Implemented in: SecurePortal) GsoAuthenticate (Implemented in: SecurePortal and InternetPublic) GsoValidate (Implemented in: SecurePortal and InternetPublic) GsoRefresh (Implemented in: SecurePortal and InternetPublic) GsoDeEnrol (Implemented in: SecurePortal) GsoGetUserDetails (Implemented in: SecurePortal) GsoSetUserDetails (Implemented in: SecurePortal) GsoGetLoginDocument (Implemented in: SecurePortal and InternetPublic) GsoLogOut (Implemented in: SecurePortal and InternetPublic)

3 GsoSetPassword (Implemented in: SecurePortal) GsoResetPassword (Implemented in: SecurePortal) GsoUserIdResend (Implemented in: SecurePortal) Data Persistent State Data Flows / Transformations Session State Temporal State 32 3 Error & Exception Processing Error Classifications Business Recoverable Errors Business Fatal Errors System Recoverable Errors System Fatal Errors Exception Interface Exception Types Thrown Internal Exceptions Exception Architecture / Policy Security Considerations Privacy Authentication / Authorisation 35 4 Appendix A WSDL SecurePortal WSDL InternetPublic WSDL

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: Authentication and Authorisation Web Services (restricted and public) 1.2 Terms and Abbreviations Term or Abbreviation API CA DAT R&E SOAP WSDL WSML XML XSD XSL Definition Application Program Interface Certification Authority Department Activation Token Government Gateway Registration and Enrolment Simple Object Access Protocol Web Services Description Language Web Services Meta Language Extensible Markup Language XML Schema Definition Extensible Stylesheet Language 1.3 References Document GSOSoapSecurePortal and GSOSoapInternetPublic SOAP Interface Technical Specification Consolidated SecurePortal and InternetPublic SOAP Interface Comment 1.5 master technical document (restricted) master technical document (restricted) - 4 -

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: 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: 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. 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: 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 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 - 5 -

6 they weren t before: however the element in the XSD is optional so this should not cause problems. 2.4 Interfaces 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 Internet The following table illustrates SOAP APIs exposed by the SecurePortal and InternetPublic interfaces and their associated signatures: SecurePortal <CallerSignature> 1 <ServiceValidationList> GsoRegisterAndEnrol <UserDetails> <Credential> 2 <CallerSignature> GsoEnrolOnly <ServiceValidationList> 3 <CallerSignature> GsoActivate <ServiceActivationList> 4 <CallerSignature> <Credential> GsoAuthenticate <ServiceList> 5 <CallerSignature> <ServiceList> GsoValidate 6 <CallerSignature> GsoRefresh 7 <CallerSignature> GsoDeEnrol <ServiceList> 8 <CallerSignature> GsoGetUserDetails 9 <CallerSignature> GsoSetUserDetails <UserDetailsSet> 10 <Base64Encode> GsoGetLoginDocument 11 <CallerSignature> GsoLogOut 12 <CallerSignature> GsoSetPassword <CredentialChange> <CallerSignature> 13 <UserIdentifier> GsoResetPassword <ServiceValidationList> <CallerSignature> 14 <Password> GsoUserIdResend <ServiceValidationList> InternetPublic <CallerSignature> 1 <ServiceValidationList> GsoAuthenticate <UserDetails> <Credential> 2 <CallerSignature> GsoRefresh 3 <CallerSignature> <ServiceList> GsoValidate 4 <Base64Encode> GsoGetLoginDocument 5 GsoLogOut <CallerSignature> <UserIdentifier> <CredentialIdentifier> <ServiceAuthenticateList> <ServiceAuthenticateList> <ServiceAuthenticateList> <ServiceAuthenticateList> <CredentialIdentifier> <UserDetailsGet> <ServiceAuthenticateList> <CredentialIdentifier> <UserDetailsGet> <ServiceAuthenticateList> <UserDetailsGet> <LoginDocument> <SignedInfoBlock> <ServiceAuthenticateList> <CredentialIdentifier> <UserDetailsGet> <ServiceAuthenticateList> <CredentialIdentifier> <UserDetailsGet> <LoginDocument> <SignedInfoBlock> 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 - 6 -

7 2.5 Schema 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. 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 > (>), & (&), (&apos;) and ("). The following matrix illustrates the use and direction (Input / Output) of XML documents across the SOAP APIs: SecurePortal InternetPublic GsoLogOut GsoGetLoginDocument GsoValidate GsoRefresh GsoAuthenticate GsoUserIdResend GsoResetPassword GsoSetPassword GsoLogOut GsoGetLoginDocument GsoSetUserDetails GsoGetUserDetails GsoDeEnrol GsoRefresh GsoValidate GsoAuthenticate GsoActivate GsoEnrolOnly GsoRegisterAndEnrol API Count API Count <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 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 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 - 7 -

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: <xsd:schema targetnamespace="urn:gso-system-services:external:soap:xsdticketbook" xmlns="urn:gso-system-services:external:soap:xsdticketbook" xmlns:xsd=" 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 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:schema> The following XML document is a sample TicketBook: <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> <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: <xsd:schema targetnamespace="urn:gso-system-services:external:soap:xsdbase64encode" xmlns="urn:gso-system-services:external:soap:xsdbase64encode" xmlns:xsd=" 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"> - 8 -

9 <xsd:enumeration value="base64" /> <xsd:enumeration value="clear" /> </xsd:sequence> </xsd:schema> The following XML document is a sample Base64Encode: <Base64Encode xmlns="urn:gso-system- Services:external:soap:xsdBase64Encode"> <Mode>base64</Mode> </Base64Encode> <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: <xsd:schema targetnamespace="urn:gso-system- Services:external:soap:xsdCallerSignature" xmlns="urn:gso-system-services:external:soap:xsdcallersignature" xmlns:xsd=" 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:schema> The following XML document is a sample CallerSignature: <CallerSignature xmlns="urn:gso-system- Services:external:soap:xsdCallerSignature" /> <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 specific 1 "> <EnvelopeVersion>2.0c</EnvelopeVersion> <Header> <MessageDetails> <Class>ADM-user-authentication-request</Class> <Qualifier>request</Qualifier> <Function>submit</Function> <GatewayTimestamp> T15: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> T15:01:00-00:00</Timestamp> </UserAuthenticationRequest> </Body> </GovTalkMessage> Note: The URI to be used for this implementation of GSO will be 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> T11:07:17-00:00</GatewayTimestamp> </MessageDetails> <SenderDetails> <IDAuthentication> <SenderID/> <Authentication> <Method>W3Csigned</Method> <Role>Principal</Role> <Value></Value> <Signature> <SignedInfo> <CanonicalizationMethod Algorithm=" <SignatureMethod Algorithm=" <Reference> <Transforms> <Transform Algorithm=" "> <XPath>/GovTalkMessage/Body</XPath> </Transform> </Transforms> <DigestMethod Algorithm=" <DigestValue>Vl/ARuS47aUh1QIst2UPyU7dOOA=</DigestValue> </Reference> </SignedInfo> 1 Note: The URI to be used for this implementation of GSO will be according to GovTalk XML Schema 2.0c

11 <SignatureValue>Y0KSSyIOArVFhBA1L+YLtHlMhg4+MbR0St47g7vdPeOkyIDVuUW9aXwKf iyr1vdb6bn1rppk7byc59v0ptmmvq==</signaturevalue> </Signature> </Authentication> </IDAuthentication> <X509Certificate>MIIDYzCCAw2gAwIBAgIKXVYb1gAAAAAA5jANBgkqhkiG9w0BAQUFADBA MQswCQYDVQQGEwJHQjENMAsGA1UEBxMEVUtHRzEPMA0GA1UEChMGVUtHRzE2MREwDwYDVQQDEwh VS0dHMTZDQTAeFw0wMzAxMDcxMjQxNDJaFw0wNDAxMDcxMjUxNDJaMGsxJTAjBgkqhkiG9w0BCQ EWFnYtZXJpY3dvQG1pY3Jvc29mdC5jb20xCzAJBgNVBAYTAkdCMQ0wCwYDVQQHEwRVS0dHMQ8wD QYDVQQKEwZVS0dHMTYxFTATBgNVBAMTDFRlc3QgQWNjb3VudDBcMA0GCSqGSIb3DQEBAQUAA0sA MEgCQQDZLdfKPEqD2R+NwydiI2FosGplnoanSdUmkX7qodAo6Gf5gwDcGMhXZRtDkSs1/S0D8QN S8ccxUih0emLh6AAjAgMBAAGjggG8MIIBuDAOBgNVHQ8BAf8EBAMCBPAwEwYDVR0lBAwwCgYIKw YBBQUHAwIwHQYDVR0OBBYEFDToSbgaiJue2ZW04DEbpFDJzF8QMHcGA1UdIwRwMG6AFCdJejd27 BQRhdeWXtAGfkdYDbEfoUSkQjBAMQswCQYDVQQGEwJHQjENMAsGA1UEBxMEVUtHRzEPMA0GA1UE ChMGVUtHRzE2MREwDwYDVQQDEwhVS0dHMTZDQYIQLTw5+FRESr5PClYzCFA+QTBpBgNVHR8EYjB gmc2gk6aphidodhrwoi8vdwtnzze2y2evq2vydevucm9sbc9vs0dhmtzdqs5jcmwwl6atocugkw ZpbGU6Ly9cXHVrZ2cxNmNhXENlcnRFbnJvbGxcVUtHRzE2Q0EuY3JsMIGNBggrBgEFBQcBAQSBg DB+MDwGCCsGAQUFBzAChjBodHRwOi8vdWtnZzE2Y2EvQ2VydEVucm9sbC91a2dnMTZjYV9VS0dH MTZDQS5jcnQwPgYIKwYBBQUHMAKGMmZpbGU6Ly9cXHVrZ2cxNmNhXENlcnRFbnJvbGxcdWtnZzE 2Y2FfVUtHRzE2Q0EuY3J0MA0GCSqGSIb3DQEBBQUAA0EADQ/dGAcGTSOnvFEFkBbLJBQj+sRr/8 I06AkeNkTgpC2PZ4LwmQi4DEMh60e9DEsIr2PChH/sLlFroumQnTwC0g==</X509Certificate > < /> </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 <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: <xsd:schema targetnamespace="urn:gso-system- Services:external:soap:xsdCredentialChange" xmlns="urn:gso-system-services:external:soap:xsdcredentialchange" xmlns:xsd=" 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:enumeration value="clear" /> <xsd:enumeration value="md5" />

12 <xsd:element name="password" type="xsd:string" minoccurs="1" maxoccurs="1" /> </xsd:sequence> <xsd:element name="passwordnew" minoccurs="1" maxoccurs="1"> <xsd:complextype> <xsd:sequence> <xsd:element name="mode" minoccurs="1" maxoccurs="1"> <xsd:enumeration value="clear" /> <xsd:element name="password" type="xsd:string" minoccurs="1" maxoccurs="1" /> </xsd:sequence> </xsd:sequence> </xsd:schema> The following XML document is a sample CredentialChange: <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> <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: <xsd:schema targetnamespace="urn:gso-system- Services:external:soap:xsdCredentialIdentifier" xmlns="urn:gso-system-services:external:soap:xsdcredentialidentifier" xmlns:xsd=" 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:maxlength value="38" /> </xsd:schema> The following XML document is a sample CredentialIdentifier:

13 <CredentialIdentifier xmlns="urn:gso-system- Services:external:soap:xsdCredentialIdentifier">394830</CredentialIdentifie r> <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: <xsd:schema targetnamespace="urn:gso-system- Services:external:soap:xsdServiceActivationList" xmlns="urn:gso-system- Services:external:soap:xsdServiceActivationList" xmlns:xsd=" 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 name="servicetype"> <xsd:sequence> <xsd:element name="servicename" minoccurs="1" maxoccurs="1"> <xsd:maxlength value="50" /> <xsd:element name="activationkey" minoccurs="1" maxoccurs="1"> <xsd:maxlength value="12" /> <xsd:element name="identifiers" type="identifierstype" minoccurs="0" maxoccurs="1" /> </xsd:sequence> <xsd:attribute name="sequence" type="xsd:integer" use="optional" /> <xsd:complextype name="identifierstype"> <xsd:sequence> <xsd:element name="identifier" type="identifiertype" minoccurs="1" maxoccurs="unbounded" /> </xsd:sequence> <xsd:complextype name="identifiertype">

14 <xsd:simplecontent> <xsd:extension base="identifiervaluetype"> <xsd:attribute name="identifiertype" use="required"> <xsd:maxlength value="40" /> </xsd:attribute> </xsd:extension> </xsd:simplecontent> <xsd:simpletype name="identifiervaluetype"> <xsd:maxlength value="50" /> </xsd:schema> The following XML document is a sample ServiceActivationList: <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"> </Identifier> </Identifiers> </Service> </ServiceActivationList> <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 <xsd:schema targetnamespace="urn:gso-system- Services:external:soap:xsdServiceAuthenticateList" xmlns="urn:gso-system- Services:external:soap:xsdServiceAuthenticateList" xmlns:xsd=" 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 name="servicetype"> <xsd:sequence> <xsd:element name="servicename" minoccurs="1" maxoccurs="1"> <xsd:maxlength value="50" /> <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:simpletype name="servicestatetype"> <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:complextype name="identifierstype"> <xsd:sequence> <xsd:element name="identifier" type="identifiertype" minoccurs="1" maxoccurs="unbounded" /> </xsd:sequence> <xsd:complextype name="identifiertype"> <xsd:simplecontent> <xsd:extension base="identifiervaluetype"> <xsd:attribute name="identifiertype" use="required"> <xsd:maxlength value="40" /> </xsd:attribute> </xsd:extension> </xsd:simplecontent> <xsd:simpletype name="identifiervaluetype"> <xsd:maxlength value="50" /> <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:maxlength value="12" /> </xsd:sequence> <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:maxlength value="255" /> </xsd:attribute> </xsd:extension> </xsd:simplecontent> </xsd:sequence> </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): <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> <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: <xsd:schema targetnamespace="urn:gso-system- Services:external:soap:xsdServiceList" xmlns="urn:gso-system- Services:external:soap:xsdServiceList" xmlns:xsd=" 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 name="servicetype"> <xsd:sequence> <xsd:element name="servicename" minoccurs="1" maxoccurs="1"> <xsd:maxlength value="50" /> <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 name="identifierstype"> <xsd:sequence> <xsd:element name="identifier" type="identifiertype" minoccurs="1" maxoccurs="unbounded" /> </xsd:sequence> <xsd:complextype name="identifiertype"> <xsd:simplecontent> <xsd:extension base="identifiervaluetype"> <xsd:attribute name="identifiertype" use="required"> <xsd:maxlength value="40" /> </xsd:attribute> </xsd:extension> </xsd:simplecontent> <xsd:simpletype name="identifiervaluetype"> <xsd:maxlength value="50" /> </xsd:schema> <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 MD5_CS SHA1_CS MD5_CS_TRIMWS SHA1_CS_TRIMWS MD5_CI SHA1_CI MD5_CI_TRIMWS SHA1_CI_TRIMWS Description MD5 Hash Case Sensitive SHA1 Hash Case Sensitive MD5 Hash Case Sensitive Trim White Space SHA1 Hash Case Sensitive Trim White Space MD5 Hash Case Insensitive SHA1 Hash Case Insensitive MD5 Hash Case Insensitive Trim White Space SHA1 Hash Case Insensitive Trim White Space The XSD for ServiceValidationList is: <xsd:schema targetnamespace="urn:gso-system- Services:external:soap:xsdServiceValidationList" xmlns="urn:gso-system- Services:external:soap:xsdServiceValidationList" xmlns:xsd=" 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 name="servicetype"> <xsd:sequence> <xsd:element name="servicename" minoccurs="1" maxoccurs="1"> <xsd:maxlength value="50" />

20 <xsd:element name="knownfacts" type="knownfactstype" minoccurs="1" maxoccurs="1" /> </xsd:sequence> <xsd:attribute name="sequence" type="xsd:integer" use="optional" /> <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:maxlength value="255" /> </xsd:attribute> </xsd:extension> </xsd:simplecontent> </xsd:sequence> </xsd:schema> The following XML document is a sample ServiceValidationList: <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> <UserDetails> This XML document contains a user s name, 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. 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 <xsd:schema targetnamespace="urn:gso-system- Services:external:soap:xsdUserDetails" xmlns="urn:gso-system- Services:external:soap:xsdUserDetails" xmlns:xsd=" 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:maxlength value="64" /> <xsd:element name=" " minoccurs="0" maxoccurs="1"> <xsd:maxlength value="255" /> <xsd:element name="registrationcategory" minoccurs="1" maxoccurs="1"> <xsd:enumeration value="individual" /> <xsd:enumeration value="organisation" /> <xsd:enumeration value="agent" /> <xsd:element name="description" minoccurs="0" maxoccurs="1"> <xsd:maxlength value="255" /> <xsd:element name="agentid" minoccurs="0" maxoccurs="1"> <xsd:pattern value="([^\ \`{-&#x9f;]){1,12}" /> <xsd:element name="agentfriendlyname" minoccurs="0" maxoccurs="1"> <xsd:pattern value=".{1,64}" /> </xsd:all> </xsd:schema> The following XML document is a sample UserDetails: <UserDetails xmlns="urn:gso-system-services:external:soap:xsduserdetails"> <Name>John Patterson</Name> < >[email protected]</ > <RegistrationCategory>Individual</RegistrationCategory> <Description>I am very pleased with this service.</description> </UserDetails> <UserDetailsGet> This XML document is used to retrieve a user s details (name, 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: <xsd:schema targetnamespace="urn:gso-system- Services:external:soap:xsdUserDetailsGet" xmlns="urn:gso-system- Services:external:soap:xsdUserDetailsGet" xmlns:xsd=" 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:maxlength value="64" /> <xsd:element name=" " minoccurs="1" maxoccurs="1"> <xsd:maxlength value="255" /> <xsd:element name="description" minoccurs="1" maxoccurs="1"> <xsd:maxlength value="255" /> <xsd:element name="registrationcategory" minoccurs="1" maxoccurs="1"> <xsd:enumeration value="individual" /> <xsd:enumeration value="organisation" /> <xsd:enumeration value="agent" /> <xsd:element name="agentid" minoccurs="0" maxoccurs="1"> <xsd:maxlength value="12" /> <xsd:element name="agentcode" minoccurs="0" maxoccurs="1"> <xsd:maxlength value="12" /> <xsd:element name="agentfriendlyname" minoccurs="0" maxoccurs="1"> <xsd:maxlength value="64" /> </xsd:all>

23 </xsd:schema> The following XML document is a sample UserDetailsGet: <UserDetailsGet xmlns="urn:gso-system- Services:external:soap:xsdUserDetailsGet"> <Name>John Walland</Name> < >WallyJohn@ .com</ > <RegistrationCategory>Delegate</RegistrationCategory> </UserDetailsGet> <UserDetailsSet> This XML document is used to change a user s details. A user s name and/or 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 address, neither change will be applied. Note there is no facility for changing AgentID, AgentCode or AgentFriendlyName. The XSD for UserDetailsSet is: <xsd:schema targetnamespace="urn:gso-system-services:external:soap:xsduserdetailsset" xmlns="urn:gso-system-services:external:soap:xsduserdetailsset" xmlns:xsd=" 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:minlength value="1" /> <xsd:maxlength value="64" /> <xsd:element name=" " minoccurs="0" maxoccurs="1"> <xsd:maxlength value="255" /> <xsd:element name="description" minoccurs="0" maxoccurs="1"> <xsd:maxlength value="255" /> </xsd:all> </xsd:schema> The following XML document is a sample UserDetailsSet: <UserDetailsSet xmlns="urn:gso-system- Services:external:soap:xsdUserDetailsSet"> <Name>Alan Patridge</Name> < >[email protected]</ > </UserDetailsSet>

24 <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: <xsd:schema targetnamespace="urn:gso-system-services:external:soap:xsduseridentifier" xmlns="urn:gso-system-services:external:soap:xsduseridentifier" xmlns:xsd=" 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:maxlength value="12" /> </xsd:schema> The following document is a sample UserIdentifier: <UserIdentifier xmlns="urn:gso-system- Services:external:soap:xsdUserIdentifier"> N352QN6FB41Q</UserIdentifier> <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 <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 <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. <xsd:schema targetnamespace="urn:gso-system-services:external:soap:xsdpassword" xmlns="urn:gso-system-services:external:soap:xsdpassword" xmlns:xsd=" 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:enumeration value="clear"/> <xsd:enumeration value="md5"/> <xsd:element name="value" type="xsd:string" /> </xsd:sequence> </xsd:schema> 2.6 Functional Decomposition The SOAP interface will consist of the following APIs: 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, 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, 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 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 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. 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 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 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, 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. 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. 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 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, 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. 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. 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. 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

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 and <CallerSignature> to be present. 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 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. 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 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 GsoGetUserDetails (Implemented in: SecurePortal) This SOAP API is used to retrieve a user s name, 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 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 address are supplied but the user is a Level-2 (Certificate) user then neither the name nor 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. 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 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 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 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. 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 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 GsoUserIdResend (Implemented in: SecurePortal) 2.7 Data 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 Persistent State The Web Servi ces do not maintain A-Ticket state in the R&E database. All authentication state is administered through the. 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) 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 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 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 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): ServiceAuthenticateList Status GsoRegisterAndEnrol GsoEnrolOnly GsoActivate GsoAuthenticate GsoValidate GsoDeEnrol GsoAuthenticate GsoValidate Business Fatal Errors Not Enrolled F F F NA NA S NA NA Enrolled S S F NA NA F NA NA Active S S S NA NA F NA NA HandedToAgent S S F NA NA F NA NA Suspended NA NA F NA NA F NA NA Ambiguous NA NA F NA NA F NA NA 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 ( , 0x ), also known as SEVERITY_ERROR with FACILITY_ITF

34 SecurePortal InternetPublic Fault Count API Count GsoRegisterAndEnrol GsoEnrolOnly GsoActivate GsoAuthenticate GsoValidate GsoRefresh GsoDeEnrol GsoGetUserDetails GsoSetUserDetails GsoGetLoginDocument GsoLogOut GsoSetPassword GsoResetPassword GsoUserIdResend GsoAuthenticate GsoRefresh GsoValidate GsoGetLoginDocument GsoLogOut Error Code HRESULT (Hex) HRESULT (Dec) Description Authentication Faults AF Authentication of Credential failed. 13 X X X X X X X X X X X X X AFA Certificate issuer not trusted. 2 X X AFB Authentication of CallerSignature failed. 17 X X X X X X X X X X X X X X X X X AFC Timestamp in LoginDocument has expired. 2 X X AFD Authentication of Certificate failed. 2 X X Service Faults EE Name not supplied for Level-1 registration. Registration aborted. 1 X EE Failed enrolment for all services. Registration aborted. 1 X EE Registration category not eligibile for a service. Registration aborted. 1 X Registration category not eligible for a service. Enrolment aborted. 1 X EE Password does not meet strength policy. Registration aborted. 1 X EE Password must be supplied in clear text. Registration aborted. 1 X EE Name supplied for Level-2 registration. Registration aborted. 1 X EE Known facts supplied already in use. Registration aborted. 1 X EE Known facts supplied already in use. Enrolment aborted. 1 X EEB User details or certificate not unique. Registration aborted. 1 X EEC Invalid address. Registration aborted. 1 X EED Invalid description. Registration aborted. 1 X EEE Invalid name. Registration aborted. 1 X User Faults C Level-2 user cannot change name. UserDetailsSet aborted. 1 X CA Cannot change name to empty string. UserDetailsSet aborted. 1 X CB Password does not meet strength policy. SetPassword aborted. 1 X CC Level-2 user cannot change password. SetPassword aborted. 1 X CD Invalid address. SetUserDetails aborted. 1 X CE Old password supplied is incorrect. SetPassword aborted. 1 X CF User specified not found. Transaction aborted. 2 X X D Invalid name. SetUserDetails aborted. 1 X D Invalid description. SetUserDetails aborted. 1 X D This request occurred too soon after a previous attempt to perform this or a related operation. 1 X X D The supplied ServiceValidationList contains too many services for the current operation. 2 X X D AgentID must be specified for RegistrationCategory Agent. Registration aborted. 1 X D AgentFriendlyName must be specified for RegistrationCategory Agent. Registration aborted. 1 X Ticket Faults B A-Ticket has expired. 10 X X X X X X X X X X XML Faults A Validation of Base64Encode structure failed. 2 X X A9A Validation of CallerSignature structure failed. 17 X X X X X X X X X X X X X X X X X A9B Validation of Credential structure failed. 3 X X X A9C Validation of CredentialIdentifier structure failed. 3 X X X A9D Validation of CredentialChange structure failed. 1 X A9E Validation of LoginDocument structure failed. 2 X X A9F Validation of ServiceActivationList structure failed. 1 X AA Validation of ServiceAuthenticateList structure failed. 8 X X X X X X X X AA Validation of ServiceList structure failed. 5 X X X X X AA Validation of ServiceValidationList structure failed. 4 X X X X AA Validation of SignedInfoBlock structure failed. 2 X X AA Validation of TicketBook structure failed. 15 X X X X X X X X X X X X X X X AA Validation of UserDetails structure failed. 1 X AA Validation of UserDetailsGet structure failed. 5 X X X X X AA Validation of UserDetailsSet structure failed. 1 X AA Validation of UserIdentifier structure failed.. 2 X X AA Validation of Password structure failed.. 1 X Internal Faults E 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 X System Recoverable Errors Not Applicable System Fatal Errors Not Applicable. 3.2 Exception Interface Exception Types Thrown All exception processing will be done through SOAP fault elements Internal Exceptions The only internal exception that will be returned to the SOAP API consumer will be Error Code or HRESULT (0x80043E81 / ) Exception Architecture / Policy All exceptions will be returned as SOAP fault elements. 3.3 Security Considerations 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 ( 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=' xmlns:xsd=' xmlns:stk=' xmlns=' <types> <schema targetnamespace='urn:gso-system-services:external:soap:type' xmlns=' xmlns:soap-enc=' xmlns:wsdl=' elementformdefault='qualified'> </schema> </types> <message name='secureportal.gsoregisterandenrol'> <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 name='secureportal.gsoregisterandenrolresponse'> <part name='useridentifier' type='xsd:string'/> <part name='credentialidentifier' type='xsd:string'/> <part name='serviceauthenticatelist' type='xsd:string'/> <message name='secureportal.gsoenrolonly'> <part name='callersignature' type='xsd:string'/> <part name='servicevalidationlist' type='xsd:string'/> <message name='secureportal.gsoenrolonlyresponse'> <part name='serviceauthenticatelist' type='xsd:string'/> <message name='secureportal.gsoactivate'> <part name='callersignature' type='xsd:string'/> <part name='serviceactivationlist' type='xsd:string'/> <message name='secureportal.gsoactivateresponse'> <part name='serviceauthenticatelist' type='xsd:string'/> <message name='secureportal.gsoauthenticate'> <part name='callersignature' type='xsd:string'/> <part name='credential' type='xsd:string'/> <part name='servicelist' type='xsd:string'/> <message name='secureportal.gsoauthenticateresponse'> <part name='serviceauthenticatelist' type='xsd:string'/> <part name='credentialidentifier' type='xsd:string'/> <part name='userdetailsget' type='xsd:string'/> <message name='secureportal.gsovalidate'>

37 <part name='callersignature' type='xsd:string'/> <part name='servicelist' type='xsd:string'/> <message name='secureportal.gsovalidateresponse'> <part name='serviceauthenticatelist' type='xsd:string'/> <part name='credentialidentifier' type='xsd:string'/> <part name='userdetailsget' type='xsd:string'/> <message name='secureportal.gsorefresh'> <part name='callersignature' type='xsd:string'/> <message name='secureportal.gsorefreshresponse'> <message name='secureportal.gsodeenrol'> <part name='callersignature' type='xsd:string'/> <part name='servicelist' type='xsd:string'/> <message name='secureportal.gsodeenrolresponse'> <part name='serviceauthenticatelist' type='xsd:string'/> <message name='secureportal.gsogetuserdetails'> <part name='callersignature' type='xsd:string'/> <message name='secureportal.gsogetuserdetailsresponse'> <part name='userdetailsget' type='xsd:string'/> <message name='secureportal.gsosetuserdetails'> <part name='callersignature' type='xsd:string'/> <part name='userdetailsset' type='xsd:string'/> <message name='secureportal.gsosetuserdetailsresponse'> <message name='secureportal.gsogetlogindocument'> <part name='base64encode' type='xsd:string'/> <message name='secureportal.gsogetlogindocumentresponse'> <part name='logindocument' type='xsd:string'/> <part name='signedinfoblock' type='xsd:string'/> <message name='secureportal.gsologout'> <part name='callersignature' type='xsd:string'/> <message name='secureportal.gsologoutresponse'> <message name='secureportal.gsosetpassword'> <part name='callersignature' type='xsd:string'/> <part name='credentialchange' type='xsd:string'/> <message name='secureportal.gsosetpasswordresponse'> <message name='secureportal.gsouseridresend'> <part name='callersignature' type='xsd:string' /> <part name='password' type='xsd:string' /> <part name='servicevalidationlist' type='xsd:string' /> <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 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 name='gsoenrolonly' parameterorder='ticketbook CallerSignature ServiceValidationList ServiceAuthenticateList'> <input message='wsdlns:secureportal.gsoenrolonly' /> <output message='wsdlns:secureportal.gsoenrolonlyresponse' /> <operation name='gsoactivate' parameterorder='ticketbook CallerSignature ServiceActivationList ServiceAuthenticateList'> <input message='wsdlns:secureportal.gsoactivate' /> <output message='wsdlns:secureportal.gsoactivateresponse' /> <operation name='gsoauthenticate' parameterorder='ticketbook CallerSignature Credential ServiceList ServiceAuthenticateList CredentialIdentifier UserDetailsGet'> <input message='wsdlns:secureportal.gsoauthenticate' /> <output message='wsdlns:secureportal.gsoauthenticateresponse' /> <operation name='gsovalidate' parameterorder='ticketbook CallerSignature ServiceList ServiceAuthenticateList CredentialIdentifier UserDetailsGet'> <input message='wsdlns:secureportal.gsovalidate' /> <output message='wsdlns:secureportal.gsovalidateresponse' /> <operation name='gsorefresh' parameterorder='ticketbook CallerSignature'> <input message='wsdlns:secureportal.gsorefresh' /> <output message='wsdlns:secureportal.gsorefreshresponse' /> <operation name='gsodeenrol' parameterorder='ticketbook CallerSignature ServiceList ServiceAuthenticateList'> <input message='wsdlns:secureportal.gsodeenrol' /> <output message='wsdlns:secureportal.gsodeenrolresponse' /> <operation name='gsogetuserdetails' parameterorder='ticketbook CallerSignature UserDetailsGet'> <input message='wsdlns:secureportal.gsogetuserdetails' /> <output message='wsdlns:secureportal.gsogetuserdetailsresponse' /> <operation name='gsosetuserdetails' parameterorder='ticketbook CallerSignature UserDetailsSet'> <input message='wsdlns:secureportal.gsosetuserdetails' /> <output message='wsdlns:secureportal.gsosetuserdetailsresponse' /> <operation name='gsogetlogindocument' parameterorder='base64encode LoginDocument SignedInfoBlock'> <input message='wsdlns:secureportal.gsogetlogindocument' /> <output message='wsdlns:secureportal.gsogetlogindocumentresponse' /> <operation name='gsologout' parameterorder='ticketbook CallerSignature'> <input message='wsdlns:secureportal.gsologout' /> <output message='wsdlns:secureportal.gsologoutresponse' /> <operation name='gsosetpassword' parameterorder='ticketbook CallerSignature CredentialChange'> <input message='wsdlns:secureportal.gsosetpassword' /> <output message='wsdlns:secureportal.gsosetpasswordresponse' /> <operation name='gsoresetpassword' parameterorder='callersignature UserIdentifier ServiceValidationList'> <input message='wsdlns:secureportal.gsoresetpassword' /> <output message='wsdlns:secureportal.gsoresetpasswordresponse' /> <operation name='gsouseridresend' parameterorder='callersignature Password ServiceValidationList'> <input message='wsdlns:secureportal.gsouseridresend' /> <output message='wsdlns:secureportal.gsouseridresendresponse' /> </porttype> <binding name='secureportalsoapbinding' type='wsdlns:secureportalsoapport' > <stk:binding preferredencoding='utf-8'/> <soap:binding style='rpc' transport=' /> <operation name='gsoregisterandenrol' >

39 <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoRegisterAndEnrol' /> <input> </input> <output> </output> <operation name='gsoenrolonly' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoEnrolOnly' /> <input> </input> <output> </output> <operation name='gsoactivate' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoActivate' /> <input> </input> <output> </output> <operation name='gsoauthenticate' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoAuthenticate' /> <input> </input> <output> </output> <operation name='gsovalidate' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoValidate' /> <input> </input> <output> </output> <operation name='gsorefresh' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoRefresh' /> <input> </input>

40 <output> </output> <operation name='gsodeenrol' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoDeEnrol' /> <input> </input> <output> </output> <operation name='gsogetuserdetails' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoGetUserDetails' /> <input> </input> <output> </output> <operation name='gsosetuserdetails' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoSetUserDetails' /> <input> </input> <output> </output> <operation name='gsogetlogindocument' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoGetLoginDocument' /> <input> </input> <output> </output> <operation name='gsologout' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoLogOut' /> <input> </input> <output> </output> <operation name='gsosetpassword' >

41 <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoSetPassword' /> <input> </input> <output> </output> <operation name='gsoresetpassword' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoResetPassword' /> <input> </input> <output> </output> <operation name='gsouseridresend' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:SecurePortal.GsoUserIdResend' /> <input> </input> <output> </output> </binding> <service name='gsosoapsecureportalservice' > <port name='secureportalsoapport' binding='wsdlns:secureportalsoapbinding' > <soap:address location=' L' /> </port> </service> </definitions>

42 - 42 -

43 4.2 InternetPublic WSDL The WSDL file for the InternetPublic SOAP interface ( 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=' xmlns:xsd=' xmlns:stk=' xmlns=' <types> <schema targetnamespace='urn:gso-system-services:external:soap:type' xmlns=' xmlns:soap-enc=' xmlns:wsdl=' elementformdefault='qualified'> </schema> </types> <message name='internetpublic.gsoauthenticate'> <part name='callersignature' type='xsd:string'/> <part name='credential' type='xsd:string'/> <part name='servicelist' type='xsd:string'/> <message name='internetpublic.gsoauthenticateresponse'> <part name='serviceauthenticatelist' type='xsd:string'/> <part name='credentialidentifier' type='xsd:string'/> <part name='userdetailsget' type='xsd:string'/> <message name='internetpublic.gsorefresh'> <part name='callersignature' type='xsd:string'/> <message name='internetpublic.gsorefreshresponse'> <message name='internetpublic.gsovalidate'> <part name='callersignature' type='xsd:string'/> <part name='servicelist' type='xsd:string'/> <message name='internetpublic.gsovalidateresponse'> <part name='serviceauthenticatelist' type='xsd:string'/> <part name='credentialidentifier' type='xsd:string'/> <part name='userdetailsget' type='xsd:string'/> <message name='internetpublic.gsogetlogindocument'> <part name='base64encode' type='xsd:string'/> <message name='internetpublic.gsogetlogindocumentresponse'> <part name='logindocument' type='xsd:string'/> <part name='signedinfoblock' type='xsd:string'/> <message name='internetpublic.gsologout'> <part name='callersignature' type='xsd:string'/> <message name='internetpublic.gsologoutresponse'> <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 name='gsorefresh' parameterorder='ticketbook CallerSignature'> <input message='wsdlns:internetpublic.gsorefresh' /> <output message='wsdlns:internetpublic.gsorefreshresponse' /> <operation name='gsovalidate' parameterorder='ticketbook CallerSignature ServiceList ServiceAuthenticateList CredentialIdentifier UserDetailsGet'> <input message='wsdlns:internetpublic.gsovalidate' /> <output message='wsdlns:internetpublic.gsovalidateresponse' /> <operation name='gsogetlogindocument' parameterorder='base64encode LoginDocument SignedInfoBlock'> <input message='wsdlns:internetpublic.gsogetlogindocument' /> <output message='wsdlns:internetpublic.gsogetlogindocumentresponse' /> <operation name='gsologout' parameterorder='ticketbook CallerSignature'> <input message='wsdlns:internetpublic.gsologout' /> <output message='wsdlns:internetpublic.gsologoutresponse' /> </porttype> <binding name='internetpublicsoapbinding' type='wsdlns:internetpublicsoapport' > <stk:binding preferredencoding='utf-8'/> <soap:binding style='rpc' transport=' /> <operation name='gsoauthenticate' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:InternetPublic.GsoAuthenticate' /> <input> </input> <output> </output> <operation name='gsorefresh' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:InternetPublic.GsoRefresh' /> <input> </input> <output> </output> <operation name='gsovalidate' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:InternetPublic.GsoValidate' /> <input> </input> <output> </output> <operation name='gsogetlogindocument' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:InternetPublic.GsoGetLoginDocument' /> <input>

45 </input> <output> </output> <operation name='gsologout' > <soap:operation soapaction='urn:gso-system- Services:external:soap:action:InternetPublic.GsoLogOut' /> <input> </input> <output> </output> </binding> <service name='gsosoapinternetpublicservice' > <port name='internetpublicsoapport' binding='wsdlns:internetpublicsoapbinding' > <soap:address location=' /> </port> </service> </definitions>