Developer Guide to A&A Web Services
Government Gateway 1.6.3
Government Gateway
Developer Guide to Authentication and Authorisation Web
Services – Secure and Public
Version 1.6.3 (17.04.03)
-1-
Developer Guide to A&A Web Services
Government Gateway 1.6.3
Table of Contents
Government Gateway
1
Developer Guide to Authentication and Authorisation Web Services – Secure and Public 1
1
Introduction
1.1
Document Scope & Audience
1.2
Terms and Abbreviations
1.3
References
4
4
4
4
2
Architecture
2.1
Background Overview
2.2
Scope
2.3
Assumptions
2.3.1
A Note on Identifiers
2.4
Interfaces
2.4.1
External Interfaces – Consumed / Dependant
2.5
Schema
2.5.1
<TicketBook>
2.5.2
<Base64Encode>
2.5.3
<CallerSignature>
2.5.4
<Credential>
2.5.5
<CredentialChange>
2.5.6
<CredentialIdentifier>
2.5.7
<ServiceActivationList>
2.5.8
<ServiceAuthenticateList>
2.5.9
<ServiceList>
2.5.10
<ServiceValidationList>
2.5.11
<UserDetails>
2.5.12
<UserDetailsGet>
2.5.13
<UserDetailsSet>
2.5.14
<UserIdentifier>
2.5.15
<LoginDocument>
2.5.16
<SignedInfoBlock>
2.5.17
<Password>
2.6
Functional Decomposition
2.6.1
GsoRegisterAndEnrol (Implemented in: SecurePortal)
2.6.2
GsoEnrolOnly (Implemented in: SecurePortal)
2.6.3
GsoActivate (Implemented in: SecurePortal)
2.6.4
GsoAuthenticate (Implemented in: SecurePortal and InternetPublic)
2.6.5
GsoValidate (Implemented in: SecurePortal and InternetPublic)
2.6.6
GsoRefresh (Implemented in: SecurePortal and InternetPublic)
2.6.7
GsoDeEnrol (Implemented in: SecurePortal)
2.6.8
GsoGetUserDetails (Implemented in: SecurePortal)
2.6.9
GsoSetUserDetails (Implemented in: SecurePortal)
2.6.10
GsoGetLoginDocument (Implemented in: SecurePortal and
InternetPublic)
2.6.11
GsoLogOut (Implemented in: SecurePortal and InternetPublic)
-2-
5
5
5
5
5
6
6
7
7
8
9
9
11
12
13
14
17
18
20
21
23
24
24
24
24
25
25
26
27
27
29
30
30
30
31
31
31
Developer Guide to A&A Web Services
2.6.12
2.6.13
2.6.14
2.7
Data
2.7.1
2.7.2
2.7.3
2.7.4
Government Gateway 1.6.3
GsoSetPassword (Implemented in: SecurePortal)
GsoResetPassword (Implemented in: SecurePortal)
GsoUserIdResend (Implemented in: SecurePortal)
Persistent State
Data Flows / Transformations
Session State
Temporal State
31
31
32
32
32
32
32
32
3
Error & Exception Processing
3.1
Error Classifications
3.1.1
Business Recoverable Errors
3.1.2
Business Fatal Errors
3.1.3
System Recoverable Errors
3.1.4
System Fatal Errors
3.2
Exception Interface
3.2.1
Exception Types Thrown
3.2.2
Internal Exceptions
3.2.3
Exception Architecture / Policy
3.3
Security Considerations
3.3.1
Privacy
3.3.2
Authentication / Authorisation
33
33
33
33
34
34
34
34
34
34
34
34
35
4
Appendix A – WSDL
4.1
SecurePortal WSDL
4.2
InternetPublic WSDL
36
36
43
-3-
Developer Guide to A&A Web Services
1
Government Gateway 1.6.3
Introduction
1.1
Document Scope & Audience
This document is intended to provide developers with information about the web services
available from the Government Gateway for authentication and authorisation. It describes
the technical specifications for:
n
1.2
1.3
Authentication and Authorisation Web Services (restricted and public)
Terms and Abbreviations
Term or
Abbreviation
Definition
API
Application Program Interface
CA
Certification Authority
DAT
Department Activation Token
R&E
Government Gateway Registration and Enrolment
SOAP
Simple Object Access Protocol
WSDL
Web Services Description Language
WSML
Web Services Meta Language
XML
Extensible Markup Language
XSD
XML Schema Definition
XSL
Extensible Stylesheet Language
References
Document
Comment
GSOSoapSecurePortal and
GSOSoapInternetPublic SOAP Interface
1.5 master technical document (restricted)
Technical Specification – Consolidated
SecurePortal and InternetPublic SOAP
Interface
1.6.3 master technical document (restricted)
-4-
Developer Guide to A&A Web Services
2
Government Gateway 1.6.3
Architecture
2.1 Background Overview
The SOAP interface is required for portals, ISV applications and other applications to
interact programmatically with the Gateway without using the native Gateway web user
interface.
2.2 Scope
This document details the SOAP APIs for:
n
Authentication and Authorisation: the SecurePortal and InternetPublic interfaces
It includes the individual SOAP APIs, their parameters, the SOAP message formats, and
security and error conditions.
2.3 Assumptions
The following assumptions are made for the SecurePortal Web Services security:
n
The Gateway server terminating the client-side certificate HTTPS SSL session
will maintain a CTL (Certificate Trust List). Therefore, when a SOAP request
arrives at the web server hosting the R&E Web Services, no additional
connection authentication will be necessary.
n
All SOAP APIs will ignore the contents of the CallerSignature parameter,
although the XML structure will still be validated. This implementation of the
SOAP APIs will provide no caller authentication. The CallerSignature parameter
is only included as a placeholder for future development.
The following assumptions are made for the InternetPublic web services security:
n
2.3.1
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 Acti ve. 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-
Developer Guide to A&A Web Services
Government Gateway 1.6.3
they weren’t before: however the element in the XSD is optional so this should not cause
problems.
2.4 Interfaces
2.4.1
External Interfaces – Consumed / Dependant
Two separate SOAP interfaces are required in order to segment functionality and
partition security (one for secure portals and another for public internet access).
These separate SOAP interfaces will be partitioned along the following URLs:
•
SecurePortal
https://secure.gateway.gov.uk/soap/SecurePortal
•
Internet
http://secure.gateway.gov.uk/soap/ InternetPublic
The following table illustrates SOAP APIs exposed by the SecurePortal and
InternetPublic interfaces and their associated signatures:
SecurePortal
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<TicketBook>
<CallerSignature>
<ServiceValidationList>
<UserDetails>
<Credential>
<TicketBook>
<CallerSignature>
<ServiceValidationList>
<TicketBook>
<CallerSignature>
<ServiceActivationList>
<TicketBook>
<CallerSignature>
<Credential>
<ServiceList>
<TicketBook>
<CallerSignature>
<ServiceList>
<TicketBook>
<CallerSignature>
<TicketBook>
<CallerSignature>
<ServiceList>
<TicketBook>
<CallerSignature>
<TicketBook>
<CallerSignature>
<UserDetailsSet>
<Base64Encode>
<TicketBook>
<CallerSignature>
<TicketBook>
<CallerSignature>
<CredentialChange>
<CallerSignature>
<UserIdentifier>
<ServiceValidationList>
<CallerSignature>
<Password>
<ServiceValidationList>
GsoRegisterAndEnrol
<TicketBook>
<UserIdentifier>
<CredentialIdentifier>
<ServiceAuthenticateList>
GsoEnrolOnly
<TicketBook>
<ServiceAuthenticateList>
GsoActivate
<TicketBook>
<ServiceAuthenticateList>
GsoAuthenticate
GsoValidate
GsoRefresh
GsoDeEnrol
GsoGetUserDetails
<TicketBook>
<ServiceAuthenticateList>
<CredentialIdentifier>
<UserDetailsGet>
<TicketBook>
<ServiceAuthenticateList>
<CredentialIdentifier>
<UserDetailsGet>
<TicketBook>
<TicketBook>
<ServiceAuthenticateList>
<TicketBook>
<UserDetailsGet>
<TicketBook>
GsoSetUserDetails
GsoGetLoginDocument
GsoLogOut
<LoginDocument>
<SignedInfoBlock>
<TicketBook>
<TicketBook>
GsoSetPassword
GsoResetPassword
GsoUserIdResend
InternetPublic
1
2
3
4
5
<TicketBook>
<CallerSignature>
<ServiceValidationList>
<UserDetails>
<Credential>
<TicketBook>
<CallerSignature>
<TicketBook>
<CallerSignature>
<ServiceList>
<Base64Encode>
<TicketBook>
<CallerSignature>
GsoAuthenticate
GsoRefresh
GsoValidate
GsoGetLoginDocument
GsoLogOut
<TicketBook>
<ServiceAuthenticateList>
<CredentialIdentifier>
<UserDetailsGet>
<TicketBook>
<TicketBook>
<ServiceAuthenticateList>
<CredentialIdentifier>
<UserDetailsGet>
<LoginDocument>
<SignedInfoBlock>
<TicketBook>
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-
Developer Guide to A&A Web Services
Government Gateway 1.6.3
HTTPS session with the Gateway. The Secure Portal URL will therefore only
allow SSL connections with explicitly trusted client-side certificates to access this
URL. All authorised portals will require certificates that are signed by a trusted CA
included in the CTL.
The InternetPublic interface will only be utilising a server-side certificate SSL
connection. No other authentication of the client connection will take place.
However, only subset of the SOAP APIs will be exposed by this URL.
The WSDL files for the SecurePortal and InternetPublic SOAP interfaces are
documented in Appendix A. The WSML files for the SecurePortal and
InternetPublic SOAP interfaces are also documented in Appendix A.
2.5
Schema
All of the parameters included in SOAP messages will be well formed XML
documents conforming to the XML Schema (XSD) defined below. This approach
was chosen in order to maximise re-use across SOAP APIs. In addition, XSD
Schema allow both the SOAP API consumer and provider to agree on the XML
document structures. This allows both parties to validate XML documents (sent
and received) according to a well defined standard.
One of the first tasks performed by a SOAP API is to validate the SOAP request
parameters according to these XML Schema. In addition, each SOAP API will
validate its output parameters prior to transmitting the SOAP response. Note that
the parameters in the WSDL are only defined as xsd:string. It is therefore the
responsibility of the SOAP consumer to make sure that the SOAP message
request parameters contain the proper character references so that the SOAP
message request remains a well-formed XML document. That is, in the actual
XML document that is the SOAP message the ‘<’ character is replaced with the
&lt; character reference in the message parameter. That same applies to ‘>’
(&gt;), ‘&’ (&amp;), ‘’’ (&apos;) and ‘”’ (&quot;).
The following matrix illustrates the use and direction (Input / Output) of XML
documents across the SOAP APIs:
SecurePortal
GsoUserIdResend
GsoAuthenticate
GsoRefresh
GsoValidate
GsoGetLoginDocument
GsoLogOut
8 4 4 7 6 2 4 3 3 3 2 3
2
I
17 I
I
I
I
I
I
I
I
I
I
I
3 I
I
5 O
O O
1
I
2
O
1
I
8 O O O O O
O
5
I
I
I
4 I
I
2
O
15 IO IO IO IO IO IO IO IO IO
IO IO
1 I
5
O O
O
GsoResetPassword
GsoSetPassword
GsoLogOut
GsoGetLoginDocument
GsoSetUserDetails
GsoGetUserDetails
GsoDeEnrol
GsoRefresh
GsoValidate
GsoAuthenticate
GsoActivate
2.5.1
GsoEnrolOnly
<Base64Encode>
<CallerSignature>
<Credential>
<CredentialIdentifier>
<CredentialChange>
<LoginDocument>
<ServiceActivationList>
<ServiceAuthenticateList>
<ServiceList>
<ServiceValidationList>
<SignedInfoBlock>
<TicketBook>
<UserDetails>
<UserDetailsGet>
<Password>
<UserDetailsSet>
<UserIdentifier>
GsoRegisterAndEnrol
API Count
API Count
InternetPublic
3
3
7
2
6
3
I
2
I
I
I
I
O
I
I
0
I
O
O
O
I
I
O
I
I
O
IO IO IO
O
IO
O
I
1
2
I
O
I
<TicketBook>
This XML document is used to manage authentication and single-sign on across
secure portals. Note that the Authentication Manager silo does not differentiate
between A-Tickets issued by different URLs. Therefore an A-Ticket obtained from
the InternetPublic URL will be authenticated on the SecurePortal URL. No
-7-
Developer Guide to A&A Web Services
Government Gateway 1.6.3
distinction is made. The TicketBook must be presented to all SOAP APIs
excluding GsoGetLoginDocument. In addition, the TicketBook as returned in the
SOAP response must be persisted by the consumer as well. It cannot be
assumed that the TicketBook returned is exactly the same as the TicketBook
presented. Lastly, the A-Ticket’s contents will have no meaning to the consumers
of the SOAP APIs. Although there is a structure to the A-Ticket it will be
encrypted and only readable by the Ticket Management silo.
The XSD for a TicketBook is:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema
targetNamespace="urn:GSO-System-Services:external:soap:xsdTicketBook"
xmlns="urn:GSO-System-Services:external:soap:xsdTicketBook"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="1.44"
id="TicketBook">
<xsd:annotation>
<xsd:documentation>Ticket Book Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="TicketBook" type="TicketBookType" />
<xsd:complexType name="TicketBookType">
<xsd:sequence>
<xsd:element name="Ticket" type="TicketTYPE" minOccurs="0"
maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="TicketTYPE">
<xsd:sequence>
<xsd:element name="ServiceName" type="xsd:string" minOccurs="1"
maxOccurs="1" />
<xsd:element name="TicketValue" type="xsd:string" minOccurs="1"
maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
The following XML document is a sample TicketBook:
<?xml version="1.0" encoding="utf-8" ?>
<TicketBook xmlns="urn:GSO-System-Services:external:soap:xsdTicketBook">
<Ticket>
<ServiceName>GsoSoapATicket</ServiceName>
<TicketValue>detpyrcnEmA1</TicketValue>
</Ticket>
<Ticket>
<ServiceName>SecureMessaging</ServiceName>
<TicketValue>nedd1HdnAdegnuM</TicketValue>
</Ticket>
</TicketBook>
2.5.2
<Base64Encode>
This XML document is used to indicate whether the login document to be
returned should be encoded in base64 or clear text.
The XSD for a Base64Encode is:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema
targetNamespace="urn:GSO-System-Services:external:soap:xsdBase64Encode"
xmlns="urn:GSO-System-Services:external:soap:xsdBase64Encode"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="1.44"
id="Base64Encode">
<xsd:annotation>
<xsd:documentation>Base64 Encode Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="Base64Encode">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Mode" minOccurs="1" maxOccurs="1">
-8-
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="base64" />
<xsd:enumeration value="clear" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
The following XML document is a sample Base64Encode:
<?xml version="1.0" encoding="utf-8" ?>
<Base64Encode xmlns="urn:GSO-SystemServices:external:soap:xsdBase64Encode">
<Mode>base64</Mode>
</Base64Encode>
2.5.3
<CallerSignature>
This XML document is used to contain the signature block used to sign the
TicketBook. This parameter is only used as a placeholder for future development
as signed TicketBooks are not within the scope of this implementation of the
SOAP APIs. Note that this XML document must only contain the root element
CallerSignature, no whitespace or any characters are allowed.
The XSD for a CallerSignature is:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema
targetNamespace="urn:GSO-SystemServices:external:soap:xsdCallerSignature"
xmlns="urn:GSO-System-Services:external:soap:xsdCallerSignature"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="1.44"
id="CallerSignature">
<xsd:annotation>
<xsd:documentation>Caller Signature Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="CallerSignature">
<xsd:complexType>
<xsd:complexContent>
<xsd:restriction base="xsd:anyType" />
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
</xsd:schema>
The following XML document is a sample CallerSignature:
<?xml version="1.0" encoding="utf-8" ?>
<CallerSignature xmlns="urn:GSO-SystemServices:external:soap:xsdCallerSignature" />
2.5.4
<Credential>
The Credential parameter will leverage the existing GovTalk XSD definition. This
parameter will take a GovTalk message with a body comprising of
\UserAuthenticationRequest\Timestamp containing the timestamp data.
Credential information will be contained in the IDAuthentication element in the
Header. The IDAuthentication block will either contain the SenderID and Value
elements (containing UserID/Password) or the Value element (containing the
SignedInfoBlock). Note that the Method element can contain either clear or MD5
as the encoding of the password (for UserID/Password). Note MD5 hashes are
assumed to be derived from UTF-8 representations of the data. For certificates
the Value element will contain the SignedInfo block and Method will contain
W3CSigned.
(The XSD for Credential is not included to prevent maintenance of multiple copies
of the XML Schema).
-9-
Developer Guide to A&A Web Services
Government Gateway 1.6.3
The following XML document is a sample Credential for a UserID/Password login:
<?xml version="1.0" ?>
<GovTalkMessage
xmlns="implementation specific1">
<EnvelopeVersion>2.0c</EnvelopeVersion>
<Header>
<MessageDetails>
<Class>ADM-user-authentication-request</Class>
<Qualifier>request</Qualifier>
<Function>submit</Function>
<GatewayTimestamp>2002-02-07T15:01:00-00:00</GatewayTimestamp>
</MessageDetails>
<SenderDetails>
<IDAuthentication>
<SenderID>QB19957JW6VG</SenderID>
<Authentication>
<Method>clear</Method>
<Value>Password123</Value>
</Authentication>
</IDAuthentication>
</SenderDetails>
</Header>
<GovTalkDetails>
<Keys/>
</GovTalkDetails>
<Body>
<UserAuthenticationRequest>
<Timestamp>2002-02-07T15:01:00-00:00</Timestamp>
</UserAuthenticationRequest>
</Body>
</GovTalkMessage>
Note: The URI to be used for this implementation of GSO will be
http://www.govtalk.gov.uk/CM/envelope according to GovTalk XML Schema 2.0.
The following XML document is a sample Credential for Certificate based login:
<?xml version="1.0"?>
<GovTalkMessage>
<EnvelopeVersion>0.8</EnvelopeVersion>
<Header>
<MessageDetails>
<Class>ADM-user-authentication-request</Class>
<Qualifier>request</Qualifier>
<Function>submit</Function>
<GatewayTimestamp>2003-02-20T11:07:17-00:00</GatewayTimestamp>
</MessageDetails>
<SenderDetails>
<IDAuthentication>
<SenderID/>
<Authentication>
<Method>W3Csigned</Method>
<Role>Principal</Role>
<Value></Value>
<Signature>
<SignedInfo>
<CanonicalizationMethod Algorithm="http://www.w3.org/TR/2000/WDxml-c14n-20001011"/>
<SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<Reference>
<Transforms>
<Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath19991116">
<XPath>/GovTalkMessage/Body</XPath>
</Transform>
</Transforms>
<DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>Vl/ARuS47aUh1QIst2UPyU7dOOA=</DigestValue>
</Reference>
</SignedInfo>
1
Note: The URI to be used for this implementation of GSO will be
http://www.govtalk.gov.uk/CM/envelope according to GovTalk XML Schema 2.0c.
- 10 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<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
>
<Email/>
</SenderDetails>
</Header>
<GovTalkDetails>
<Keys/>
</GovTalkDetails>
<Body>
<UserAuthenticationRequest>
<Timestamp>2003-Feb-20 11:07:17</Timestamp>
</UserAuthenticationRequest>
</Body>
</GovTalkMessage>
A detailed explanation of how to sign a document is provided in GG-SignXML.doc “UK Online XML Signing in the Government Gateway” available in the
Portal Pack supplied by The Office of the E-Envoy.
2.5.5
<CredentialChange>
This XML document is used to change a Level-1 (UserID/Password) user’s
password. The CredentialChange document includes the old and new password.
The old password can be optionally hashed with the MD5 algorithm but the new
password must be sent in clear text (in order to be able to administer a password
strength policy). Note MD5 hashes are assumed to be derived from UTF -8
representations of the data.
The XSD for CredentialChange is:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema
targetNamespace="urn:GSO-SystemServices:external:soap:xsdCredentialChange"
xmlns="urn:GSO-System-Services:external:soap:xsdCredentialChange"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="1.44"
id="CredentialChange">
<xsd:annotation>
<xsd:documentation>Credential Change Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="CredentialChange" type="CredentialChangeTYPE" />
<xsd:complexType name="CredentialChangeTYPE">
<xsd:sequence>
<xsd:element name="PasswordOld" minOccurs="1" maxOccurs="1">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Mode" minOccurs="1" maxOccurs="1" >
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="clear" />
<xsd:enumeration value="MD5" />
- 11 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Password" type="xsd:string"
minOccurs="1" maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="PasswordNew" minOccurs="1" maxOccurs="1">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Mode" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="clear" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Password" type="xsd:string"
minOccurs="1" maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
The following XML document is a sample CredentialChange:
<?xml version="1.0" encoding="utf-8" ?>
<CredentialChange xmlns="urn:GSO-SystemServices:external:soap:xsdCredentialChange">
<PasswordOld>
<Mode>MD5</Mode>
<Password>gnikooLxelpmoCyreV</Password>
</PasswordOld>
<PasswordNew>
<Mode>clear</Mode>
<Password>MyNewPassword123</Password>
</PasswordNew>
</CredentialChange>
2.5.6
<CredentialIdentifier>
This XML document will contain the new CredentialIdentifier. The Credential
Identifier will be used by external systems and applications to uniquely identify
users. The CredentialIdentifier value is guaranteed to be unique for each user
and will not change for that user. Note that the CredentialIdentifier has no
meaning to R&E. For example, it is not possible to use the CredentialIdentifier in
place of a UserID.
The XSD for CredentialIdentifier is:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema
targetNamespace="urn:GSO-SystemServices:external:soap:xsdCredentialIdentifier"
xmlns="urn:GSO-System-Services:external:soap:xsdCredentialIdentifier"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="1.44"
id="CredentialIdentifier">
<xsd:annotation>
<xsd:documentation>Credential Identifier Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="CredentialIdentifier">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="38" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
</xsd:schema>
The following XML document is a sample CredentialIdentifier:
- 12 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<?xml version="1.0" encoding="utf-8" ?>
<CredentialIdentifier xmlns="urn:GSO-SystemServices:external:soap:xsdCredentialIdentifier">394830</CredentialIdentifie
r>
2.5.7
<ServiceActivationList>
This XML document is used to activate one or more services.
ServiceActivationList contains the name of the service and the activation key for
each service being activated.
RequestInputData is an optional Boolean which indicates whether the
ActivationKey and optional Identifiers should be included in the
ServiceAuthenticateList response.
Identifiers must be supplied if activating a service in which the credential is
multiply enrolled to uniquely identify the enrolment to be activated, otherwise they
are optional. If Identifiers are not supplied when they are required status
“Ambiguous” is returned.
The Service Sequence attribute is an optional client supplied attribute which can
be used instead of or in conjunction with the RequestInputData attribute to track
the response to each activation request. There are no restrictions on Service
Sequence except that it must be an integer greater than or equal to zero.
The XSD for ServiceActivationList is:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema targetNamespace="urn:GSO-SystemServices:external:soap:xsdServiceActivationList" xmlns="urn:GSO-SystemServices:external:soap:xsdServiceActivationList"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
attributeFormDefault="unqualified" version="1.44"
id="ServiceActivationList">
<xsd:annotation>
<xsd:documentation>Service Activation List Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="ServiceActivationList"
type="ServiceActivationListTYPE" />
<xsd:complexType name="ServiceActivationListTYPE">
<xsd:sequence>
<xsd:element name="Service" type="ServiceTYPE" minOccurs="1"
maxOccurs="unbounded" />
</xsd:sequence>
<xsd:attribute name="RequestInputData" type="xsd:boolean"
use="optional" />
</xsd:complexType>
<xsd:complexType name="ServiceTYPE">
<xsd:sequence>
<xsd:element name="ServiceName" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="50" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="ActivationKey" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="12" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Identifiers" type="IdentifiersTYPE"
minOccurs="0" maxOccurs="1" />
</xsd:sequence>
<xsd:attribute name="Sequence" type="xsd:integer" use="optional" />
</xsd:complexType>
<xsd:complexType name="IdentifiersTYPE">
<xsd:sequence>
<xsd:element name="Identifier" type="IdentifierTYPE"
minOccurs="1" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="IdentifierTYPE">
- 13 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<xsd:simpleContent>
<xsd:extension base="IdentifierValueTYPE">
<xsd:attribute name="IdentifierType" use="required">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="40" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:simpleType name="IdentifierValueTYPE">
<xsd:restriction base="xsd:string">
<xsd:maxLength value="50" />
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
The following XML document is a sample ServiceActivationList:
<?xml version="1.0" encoding="utf-8" ?>
<ServiceActivationList xmlns="urn:GSO-SystemServices:external:soap:xsdServiceActivationList" RequestInputData="true">
<Service Sequence="1">
<ServiceName>HMCE-PDDEVR</ServiceName>
<ActivationKey>N352QN6FB41Q</ActivationKey>
</Service>
<Service Sequence="2">
<ServiceName>IR-PAYE</ServiceName>
<ActivationKey>WSN9QJ5G381E</ActivationKey>
<Identifiers>
<Identifier IdentifierType="UTR">6660000075</Identifier>
</Identifiers>
</Service>
</ServiceActivationList>
2.5.8
<ServiceAuthenticateList>
This XML document is used whenever it is necessary to return a set of services in
response to a SOAP API authenticating a user, validating an A-Ticket in a
TicketBook or querying / modifying a user’s enrolment. Due to the generic nature
of ServiceAuthenticateList, the SOAP APIs that modify a user’s enrolment only
returns the status of the services that were requested in the input parameters
(either ServiceList or ServiceActivationList). It does not explicitly inform the SOAP
API consumer whether the attempted action was successful or nor (assuming
that no fatal business errors were encountered). The exception is GsoEnrol and
GsoRegisterAndEnrol which return “Not Enrolled” if enrolment failed, even if the
reason for the failure was that the enrolment request was a duplicate of a
previous successful enrolment. No fault elements are returned (again assuming
no fatal business errors were encountered). It is then up to the SOAP API
consumer to check the returned service statuses to check whether each state
indicates a success or failure within the context of the SOAP API called. A list of
which statuses should be considered as a success and which should be
considered as a failure is documented in further detail for each SOAP API. Again,
success or failure will not be explicitly stated by ServiceAuthenticateList. The
SOAP API consumer must determine success or failure within the SOAP API’s
context.
For the GsoActivate SOAP API, ServiceAuthenticateList will include the number
of activations that can be attempted before the user is automatically de-enrolled
from the service. The order of events for failed activation attempts will be
(Status/ActivateAttemptsLeft): Enrolled/2, Enrolled/1, Not Enrolled/0.
Status “Ambiguous” can be returned by GsoActivate and GsoDeEnrol if
insufficient information has been supplied to uniquely identify a service
enrolment. This occurs if a credential is multiply enrolled in a service. To uniquely
identify an enrolment instance the service Identifiers should be supplied.
The XSD for ServiceAuthenticateList is:
- 14 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema targetNamespace="urn:GSO-SystemServices:external:soap:xsdServiceAuthenticateList" xmlns="urn:GSO-SystemServices:external:soap:xsdServiceAuthenticateList"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
attributeFormDefault="unqualified" version="1.44"
id="ServiceAuthenticateList">
<xsd:annotation>
<xsd:documentation>Service Authenticate List
Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="ServiceAuthenticateList"
type="ServiceAuthenticateListTYPE" />
<xsd:complexType name="ServiceAuthenticateListTYPE">
<xsd:sequence>
<xsd:element name="Service" type="ServiceTYPE" minOccurs="0"
maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="ServiceTYPE">
<xsd:sequence>
<xsd:element name="ServiceName" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="50" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="ServiceState" type="ServiceStateTYPE"
minOccurs="1" maxOccurs="1" />
<xsd:element name="ActivateAttemptsLeft"
type="xsd:nonNegativeInteger" minOccurs="0" maxOccurs="1" />
<xsd:element name="Identifiers" type="IdentifiersTYPE"
minOccurs="0" maxOccurs="unbounded" />
<xsd:element name="InputData" type="InputDataTYPE" minOccurs="0"
maxOccurs="1" />
</xsd:sequence>
<xsd:attribute name="Sequence" type="xsd:integer" use="optional" />
<xsd:attribute name="IsClientList" type="xsd:boolean"
use="optional" />
</xsd:complexType>
<xsd:simpleType name="ServiceStateTYPE">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Not Enrolled" />
<xsd:enumeration value="Enrolled" />
<xsd:enumeration value="Active" />
<xsd:enumeration value="HandedToAgent" />
<xsd:enumeration value="Suspended" />
<xsd:enumeration value="Ambiguous" />
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="IdentifiersTYPE">
<xsd:sequence>
<xsd:element name="Identifier" type="IdentifierTYPE"
minOccurs="1" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="IdentifierTYPE">
<xsd:simpleContent>
<xsd:extension base="IdentifierValueTYPE">
<xsd:attribute name="IdentifierType" use="required">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="40" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:simpleType name="IdentifierValueTYPE">
<xsd:restriction base="xsd:string">
<xsd:maxLength value="50" />
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="InputDataTYPE">
<xsd:sequence>
- 15 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<xsd:element name="KnownFacts" type="KnownFactsTYPE"
minOccurs="0" maxOccurs="1" />
<xsd:element name="Identifiers" type="IdentifiersTYPE"
minOccurs="0" maxOccurs="1" />
<xsd:element name="ActivationKey" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="12" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="KnownFactsTYPE">
<xsd:sequence>
<xsd:element name="KnownFact" minOccurs="1"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="Sequence"
type="xsd:nonNegativeInteger" use="required" />
<xsd:attribute name="TransformAlgorithm"
use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="255" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
The following XML document is a sample ServiceAuthenticateList (note that the
example has been fleshed out to include a large number of possible Service
combinations from different SOAP APIs and is therefore not a typical, or possible,
response from any of the SOAP APIs):
<?xml version="1.0" encoding="utf-8" ?>
<ServiceAuthenticateList xmlns="urn:GSO-SystemServices: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>
- 16 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<ServiceState>Enrolled</ServiceState>
<ActivateAttemptsLeft>2</ActivateAttemptsLeft>
</Service>
<Service>
<ServiceName>ServiceSeven</ServiceName>
<ServiceState>Enrolled</ServiceState>
<ActivateAttemptsLeft>1</ActivateAttemptsLeft>
</Service>
<Service>
<ServiceName>ServiceEight</ServiceName>
<ServiceState>Not Enrolled</ServiceState>
<ActivateAttemptsLeft>0</ActivateAttemptsLeft>
</Service>
</ServiceAuthenticateList>
2.5.9
<ServiceList>
This document is used to supply none, one or more service names to the SOAP
APIs. The optional attribute RemoveAgent is used specifically for the
GsoSoapDeEnrol API call and is ignored by the other SOAP APIs that use
ServiceList.
RequestInputData is an optional Boolean which indicates whether the optional
Identifiers should be included in the ServiceAuthenticateList response.
Identifiers must be supplied if DeEnroling a service in which the credential is
multiply enrolled to uniquely identify the enrolment to be activated, otherwise they
are optional. If Identifiers are not supplied when they are required status
“Ambiguous” is returned.
The Service Sequence attribute is an optional client supplied attribute which can
be used instead of or in conjunction with the RequestInputData attribute to track
the response to each DeEnrol request. For other types of request Service
Sequence is ignored. There are no restrictions on Service Sequence except that
it must be an integer greater than or equal to zero.
The ClientListIndicator attribute controls whether the Boolean attribute IsClientList
will be attached to all service nodes in the output ServiceAuthenticateList.
ClientListIndicator is ignored by all methods except GsoAuthenticate and
GsoValidate. IsClientList is true if the current Service element is a Client List.
AllServices and AllClients is ignored by all methods except GsoAuthenticate and
GsoValidate. AllServices requests that all services associated with the credential
be included in the output ServiceAuthenticateList. Any service elements in the
ServiceList are ignored unless the service element has an ‘IncludeClients’
attribute in which case all client lists for the marked services are included in the
ServiceAuthenticateList.
AllClients indicates all client lists associated with services in the ServiceList
should be included in the output ServiceAuthenticateList (i.e. it is as if each
service in the ServiceList has IncludeClients = true). AllClients overrides
IncludeClients settings.
If both AllServices and AllClients are set to true, All clients associated with all
services associated with the credential will be output.
GroupIdentifiers is used by GsoAuthenticate and GsoValidate to indicate whether
the identifiers in client list services should be grouped. If True, each set of Client
Identifiers is bounded by its own <Identifiers> tag. If False or not present, all client
identifiers in a client list service are bounded by a single <Identifiers> tag.
The XSD for ServiceList is:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema targetNamespace="urn:GSO-SystemServices:external:soap:xsdServiceList" xmlns="urn:GSO-SystemServices:external:soap:xsdServiceList"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
attributeFormDefault="unqualified" version="1.44" id="ServiceList">
<xsd:annotation>
<xsd:documentation>Service List Schema</xsd:documentation>
- 17 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
</xsd:annotation>
<xsd:element name="ServiceList" type="ServiceListTYPE" />
<xsd:complexType name="ServiceListTYPE">
<xsd:sequence>
<xsd:element name="Service" type="ServiceTYPE" minOccurs="0"
maxOccurs="unbounded" />
</xsd:sequence>
<xsd:attribute name="GroupIdentifiers" type="xsd:boolean"
use="optional" />
<xsd:attribute name="RequestInputData" type="xsd:boolean"
use="optional" />
<xsd:attribute name="ClientListIndicator" type="xsd:boolean"
use="optional" />
<xsd:attribute name="AllServices" type="xsd:boolean" use="optional" />
<xsd:attribute name="AllClients" type="xsd:boolean" use="optional" />
</xsd:complexType>
<xsd:complexType name="ServiceTYPE">
<xsd:sequence>
<xsd:element name="ServiceName" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="50" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Identifiers" type="IdentifiersTYPE"
minOccurs="0" maxOccurs="1" />
</xsd:sequence>
<xsd:attribute name="RemoveAgent" type="xsd:boolean"
use="optional"/>
<xsd:attribute name="IncludeClients" type="xsd:boolean"
use="optional"/>
<xsd:attribute name="Sequence" type="xsd:integer" use="optional" />
</xsd:complexType>
<xsd:complexType name="IdentifiersTYPE">
<xsd:sequence>
<xsd:element name="Identifier" type="IdentifierTYPE"
minOccurs="1" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="IdentifierTYPE">
<xsd:simpleContent>
<xsd:extension base="IdentifierValueTYPE">
<xsd:attribute name="IdentifierType" use="required">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="40" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:simpleType name="IdentifierValueTYPE">
<xsd:restriction base="xsd:string">
<xsd:maxLength value="50" />
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
2.5.10 <ServiceValidationList>
This XML document is used to enrol a user in one or more servi ces. This is either
done as part of a new or existing registration. In addition to specifying the
services for enrolment, this XML document includes the Known Facts required to
validate the user by the service owner. Each Known Fact must include a
Sequence attribute. This is the order in which the Known Facts are passed to the
service’s owner validation procedure. In addition, each Known Fact can have a
TransformAlgorithm specified. This is essentially the name of a predefined
algorithm that the Gateway will use to transform the Known Fact value into a
value type that the service owner expects. The Gateway will be offering a
standard suite of transform algorithms (such as MD5 hashing, SHA1 hashing,
whitespace stripping, etc.) that can be specified as well as custom transforms
- 18 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
created by the service owners. Note hashes are assumed to be derived from
UTF-8 representations of the data.
RequestInputData is an optional Boolean which indicates whether the known
facts should be included in the ServiceAuthenticateList response.
The Service Sequence attribute is an optional client supplied attribute which can
be used instead of or in conjunction with the RequestInputData attribute to track
the response to each Enrolment request. There are no restrictions on Service
Sequence except that it must be an integer greater than or equal to zero.
The SOAP methods GsoUserIdResend and GsoResetPassword accept a
ServiceValidationList but do not return a ServiceAuthenticateList so attributes
such as Service Sequence and RequestInputData are ignored for these methods.
The TransformAlgorithm attribute indicates that a supplied known fact must be
transformed before being matched against the service list of known facts. For
example, setting the TransformAlgorithm = “MD5_CS” allows a known fact to be
supplied in clear text but matched against an MD5 hash of the fact.
The set of available transformations is configurable. The method for configuration
of available transformations is outside the scope of this document. The set of
default available transformations is:
TransformAlgorithm
Description
MD5_CS
MD5 Hash Case Sensitive
SHA1_CS
SHA1 Hash Case Sensitive
MD5_CS_TRIMWS
MD5 Hash Case Sensitive Trim White Space
SHA1_CS_TRIMWS
SHA1 Hash Case Sensitive Trim White Space
MD5_CI
MD5 Hash Case Insensitive
SHA1_CI
SHA1 Hash Case Insensitive
MD5_CI_TRIMWS
MD5 Hash Case Insensitive Trim White Space
SHA1_CI_TRIMWS
SHA1 Hash Case Insensitive Trim White Space
The XSD for ServiceValidationList is:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema targetNamespace="urn:GSO-SystemServices:external:soap:xsdServiceValidationList" xmlns="urn:GSO-SystemServices:external:soap:xsdServiceValidationList"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
attributeFormDefault="unqualified" version="1.44"
id="ServiceValidationList">
<xsd:annotation>
<xsd:documentation>Service Validation List
Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="ServiceValidationList"
type="ServiceValidationListTYPE" />
<xsd:complexType name="ServiceValidationListTYPE">
<xsd:sequence>
<xsd:element name="Service" type="ServiceTYPE" minOccurs="1"
maxOccurs="unbounded" />
</xsd:sequence>
<xsd:attribute name="RequestInputData" type="xsd:boolean"
use="optional" />
</xsd:complexType>
<xsd:complexType name="ServiceTYPE">
<xsd:sequence>
<xsd:element name="ServiceName" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="50" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
- 19 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<xsd:element name="KnownFacts" type="KnownFactsTYPE"
minOccurs="1" maxOccurs="1" />
</xsd:sequence>
<xsd:attribute name="Sequence" type="xsd:integer" use="optional" />
</xsd:complexType>
<xsd:complexType name="KnownFactsTYPE">
<xsd:sequence>
<xsd:element name="KnownFact" minOccurs="1"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="Sequence"
type="xsd:nonNegativeInteger" use="required" />
<xsd:attribute name="TransformAlgorithm"
use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="255" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
The following XML document is a sample ServiceValidationList:
<?xml version="1.0" encoding="utf-8" ?>
<ServiceValidationList xmlns="urn:GSO-SystemServices:external:soap:xsdServiceValidationList">
<Service Sequence="5">
<ServiceName>ServiceOne</ServiceName>
<KnownFacts>
<KnownFact Sequence="0"
TransformAlgorithm="MD5Hash">12</KnownFact>
<KnownFact Sequence="1">DK89 3DP</KnownFact>
</KnownFacts>
</Service>
<Service Sequence="6">
<ServiceName>ServiceTwo</ServiceName>
<KnownFacts>
<KnownFact Sequence="0">woNeMetavitcA</KnownFact>
</KnownFacts>
</Service>
</ServiceValidationList>
2.5.11 <UserDetails>
This XML document contains a user’s name, email address, registration category
(individual, organisation or agent) and the user’s description. If registering an
Agent the AgentID and AgentFriendlyName must also be supplied. If registering
an organisation or individual AgentID and AgentFriendlyName must not be
supplied. This XML document is for capturing registration details. Note that only
the registration category is mandatory. Email address and description are
optional. Name must not be included for Level-2 users, that is, users registering
with a certificate. A user’s name is extracted from the certificate. However, name
must be provided if the user is registering with a UserID/Password.
The AgentID is the agent specified portion of the Agent Group ID used by clients
to hand their enrolment to an agent. (The other portion, also known as the
AgentCode, is generated by R&E and resembles a UserID). For example, An
Agent Group ID may be FRED2-74IU9W8GNRLN, where FRED2 is the AgentID
(specified by the Agent) and 74IU9W8GNRLN is the AgentCode (generated by
R&E).
The AgentFriendlyName is the name displayed to clients when they confirm the
handing of an enrolment to an agent.
The XSD for UserDetails is:
- 20 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema targetNamespace="urn:GSO-SystemServices:external:soap:xsdUserDetails" xmlns="urn:GSO-SystemServices:external:soap:xsdUserDetails"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
attributeFormDefault="unqualified" version="1.44" id="UserDetails">
<xsd:annotation>
<xsd:documentation>User Details Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="UserDetails" type="UserDetailsTYPE" />
<xsd:complexType name="UserDetailsTYPE">
<xsd:all>
<xsd:element name="Name" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="64" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Email" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="255" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="RegistrationCategory" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Individual" />
<xsd:enumeration value="Organisation" />
<xsd:enumeration value="Agent" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Description" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="255" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="AgentID" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:pattern value="([^\&#x20;-\&#x2f;\&#x3a;-\&#x40;\&#x5b;\&#x60;&#x7b;-&#x9f;]){1,12}" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="AgentFriendlyName" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:pattern value=".{1,64}" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
</xsd:all>
</xsd:complexType>
</xsd:schema>
The following XML document is a sample UserDetails:
<?xml version="1.0" encoding="utf-8" ?>
<UserDetails xmlns="urn:GSO-System-Services:external:soap:xsdUserDetails">
<Name>John Patterson</Name>
<Email>JohnP@hotmail.com</Email>
<RegistrationCategory>Individual</RegistrationCategory>
<Description>I am very pleased with this service.</Description>
</UserDetails>
2.5.12 <UserDetailsGet>
This XML document is used to retrieve a user’s details (name, email and
registration category). If retrieving the user details for an agent the AgentID,
AgentCode and AgentFriendlyName are also populated.
- 21 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
The AgentID is the agent specified component of the ID used by clients to hand
their enrolment to an agent.
The AgentCode is the Gateway generated component of the ID used by clients to
hand their enrolment to an agent.
The AgentFriendlyName is the name displayed to clients when they confirm the
handing of an enrolment to an agent.
The XSD for UserDetailsGet is:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema targetNamespace="urn:GSO-SystemServices:external:soap:xsdUserDetailsGet" xmlns="urn:GSO-SystemServices:external:soap:xsdUserDetailsGet"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
attributeFormDefault="unqualified" version="1.44" id="UserDetailsGet">
<xsd:annotation>
<xsd:documentation>User Details Get Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="UserDetailsGet" type="UserDetailsGetTYPE" />
<xsd:complexType name="UserDetailsGetTYPE">
<xsd:all>
<xsd:element name="Name" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="64" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Email" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="255" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Description" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="255" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="RegistrationCategory" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Individual" />
<xsd:enumeration value="Organisation" />
<xsd:enumeration value="Agent" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="AgentID" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="12" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="AgentCode" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="12" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="AgentFriendlyName" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="64" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
</xsd:all>
</xsd:complexType>
- 22 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
</xsd:schema>
The following XML document is a sample UserDetailsGet:
<?xml version="1.0" encoding="utf-8" ?>
<UserDetailsGet xmlns="urn:GSO-SystemServices:external:soap:xsdUserDetailsGet">
<Name>John Walland</Name>
<Email>WallyJohn@email.com</Email>
<RegistrationCategory>Delegate</RegistrationCategory>
</UserDetailsGet>
2.5.13 <UserDetailsSet>
This XML document is used to change a user’s details. A user’s name and/or
email address and / or description can be changed. The name change must
contain at least one character. In addition, only a Level-1 user (UserID/Password)
can change his / her name. For Level-2 users (Certificates) the name associated
with the certificate is embedded within the X.509 certificate structure. Lastly,
these changes will be atomic, either all of the changes requested will be
performed or none will. For example, if a Level-2 user attempts to change his /
her name and email address, neither change will be applied.
Note there is no facility for changing AgentID, AgentCode or AgentFriendlyName.
The XSD for UserDetailsSet is:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema
targetNamespace="urn:GSO-System-Services:external:soap:xsdUserDetailsSet"
xmlns="urn:GSO-System-Services:external:soap:xsdUserDetailsSet"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="1.44"
id="UserDetailsSet">
<xsd:annotation>
<xsd:documentation>User Details Set Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="UserDetailsSet" type="UserDetailsSetTYPE" />
<xsd:complexType name="UserDetailsSetTYPE">
<xsd:all>
<xsd:element name="Name" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:minLength value="1" />
<xsd:maxLength value="64" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Email" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="255" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Description" minOccurs="0" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="255" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
</xsd:all>
</xsd:complexType>
</xsd:schema>
The following XML document is a sample UserDetailsSet:
<?xml version="1.0" encoding="utf-8" ?>
<UserDetailsSet xmlns="urn:GSO-SystemServices:external:soap:xsdUserDetailsSet">
<Name>Alan Patridge</Name>
<Email>Alan.Patridge@bbc.com</Email>
</UserDetailsSet>
- 23 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
2.5.14 <UserIdentifier>
This XML document is used to supply a UserID (e.g. GsoResetPassword) or
return the UserID of users that have successfully enrolled for at least one service
when calling the GsoRegisterAndEnrol SOAP API. Note that the UserID is only
returned for Level-1 (UserID/Password) users. Level-2 (Certificate) users have no
need for a UserID. The UserID is returned so that the user can be subsequently
authenticated on the Gateway before the user has activated his / her first service.
It is therefore important that the consumer of the SOAP API communicate the
UserID back to the user. Without it the user will not be able to authenticate on the
Gateway. Note that this UserID cannot be used to activate any services. This
activation key will be a different value and communicated to the user in the
standard secure fashion (unless the user enrolled in one or more services with a
DAT or the services are set to AutoActivate in which case those services will be
activated immediately).
The XSD for UserIdentifier:
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema
targetNamespace="urn:GSO-System-Services:external:soap:xsdUserIdentifier"
xmlns="urn:GSO-System-Services:external:soap:xsdUserIdentifier"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="1.44"
id="UserIdentifier">
<xsd:annotation>
<xsd:documentation>User Identifier Schema</xsd:documentation>
</xsd:annotation>
<xsd:element name="UserIdentifier">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="12" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
</xsd:schema>
The following document is a sample UserIdentifier:
<?xml version="1.0" encoding="utf-8" ?>
<UserIdentifier xmlns="urn:GSO-SystemServices:external:soap:xsdUserIdentifier"> N352QN6FB41Q</UserIdentifier>
2.5.15 <LoginDocument>
This XML document will be a GovTalk message required for users authenticating
with a certificate (Level-2). It will conform to the existing GovTalk schema and
certificate signing standard. This document is obtained by SOAP API consumers
calling GsoGetLoginDocument. It will either be base64 encoded or in clear text,
according to the mode specified in Base64Encode.
2.5.16 <SignedInfoBlock>
This XML document will contain the SignedInfoBlock required for user
authenticating with a certificate. This document is obtained by SOAP API
consumers calling GsoGetLoginDocument. It will either be base64 encoded or in
clear text, according to the mode specified in Base64Encode.
2.5.17 <Password>
This XML document contains a user’s password. It is used by GsoResendUserId
to assist in identifying the Credential of the user whose UserID is to be resent.
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema targetNamespace="urn:GSO-System-Services:external:soap:xsdPassword"
xmlns="urn:GSO-System-Services:external:soap:xsdPassword"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
attributeFormDefault="unqualified" version="1.44" id="Password">
<xsd:annotation>
<xsd:documentation>Password Schema</xsd:documentation>
</xsd:annotation>
- 24 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<xsd:element name="Password">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Mode">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="clear"/>
<xsd:enumeration value="MD5"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Value" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
2.6
Functional Decomposition
The SOAP interface will consist of the following APIs:
2.6.1
GsoRegisterAndEnrol
(Implemented in: SecurePortal)
This SOAP API allows a user to be registered according the <UserDetails> and
<Credential> information supplied. The <Credential> parameter will be a valid
GovTalk message as defined by the GovTalk XSD schema. It can contain either
the UserID/Password for a Level-1 user or the Signed Login Document signed by
a Level-2 user’s certificate. Utilising the existing GovTalk schema was chosen as
it is already widely used for portal authentication and submissions. Once the
credentials have been validated according to the predefined business rules
(password strength, trusted CAs etc.) the user will be enrolled for the services
specified in <ServiceValidationList>. Note that for Level-1 registrations, the
password contained in <Credential> must be in clear text and must meet the
password strength policy. If either of these conditions are not met then the
registration is aborted and the appropriate fault element returned to the SOAP
API consumer.
Enrolment for the specified services will be validated by the service owner
according to the Known Facts supplied in <ServiceValidationList>. The user must
be successfully validated by at least one service in order to complete the
registration. Failure to do so will result in the appropriate fault element being
returned to the SOAP API consumer and the registration and enrolment aborted.
If the user was enrolled for at least one service then the
<ServiceAuthenticateList> will be populated with all the services specified in
<ServiceValidationList>. Each service will include a status. It is important that the
SOAP API consumer check the status of each service as failure to enrol in a
service will be reflected in that service’s status. The SOAP API consumer should
regard the following service statuses as failure: “Not Enrolled”, “Suspended”,
“HandedToAgent”. The SOAP API consumer should regard the following service
statuses as success: “Enrolled”, “Active”.
The <UserDetails> is populated with the name, email address, description and
registration category. If registering and enrolling an agent (i.e.
RegistrationCategory Agent), the AgentID and AgentFriendlyName must also be
supplied. If they are specified for a RegistrationCategory other than Agent then
they will be ignored. Only registration category is mandatory in all cases. Name,
email address and description are optional. Name must be provided for Level-1
users, i.e. users registering with a UserID/Password. Level-2 users must not
provide a name. Their name is extracted from the certificate that they are
registering with. If a name is provided for a Level-2 user registration then the
registration is aborted and the appropriate fault element is returned. This SOAP
API will accept whatever the user provides as long as it conforms to the
prescribed XML Schema (XSD). Note that eligibility for enrolment in a service is
dependent on the registration category. That is, a service owner must specify
- 25 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
whether the service is for individuals, organisations or agents. If the
<ServiceValidationList> contains a service that the registration category specified
is not eligible for then this indicates that the SOAP API consumer does not have
the correct mapping of services to registration categories. In this case the entire
register and enrolment is aborted and the appropriate fault element is returned to
the SOAP API consumer.
If it was a Level-1 user that successfully registered and enrolled, the
<UserIdentifier> will contain that user’s Gateway generated UserID. This UserID
must be communicated back to the user as he / she will require it to authenticate
on the Gateway at a future date.
The <CredentialIdentifier> will contain the unique identifier generated for that
user. This is only provided for applications or portals that need to uniquely identify
each user. It is not for the user’s consumption nor can it be used to identify a user
to the Gateway (i.e. it cannot be substituted for UserID or used for
GsoGetUserDetails).
If the registration and enrolment was successful a valid A-Ticket will be present in
the TicketBook returned to the SOAP API consumer. This TicketBook can then
be presented to the Gateway for subsequent SOAP APIs that require an
authenticated user.
If the registration and enolment completed successfully an A-Ticket will be
generated and stored in the returned TicketBook. If an existing A-Ticket is found,
the existing A-Ticket will not be validated. It will only be replaced.
If RequestInputData was supplied as True the known facts supplied in the
ServiceValidationList are returned in the ServiceAuthenticateList.
If Service Sequence Numbers were supplied in the ServiceValidationList the
sequence number attributes are returned in the ServiceAuthenticateList.
2.6.2
GsoEnrolOnly
(Implemented in: SecurePortal)
This SOAP API enrols an authenticated user in one or more services. The
<ServiceValidationList> will contain one or more service names. Each service will
have a set of Known Facts that the service owner will use to validate the
enrolment. Each Known Fact must have the correct Sequence attribute. This
Sequence attribute is defined by the service owner and dictates the order in
which the Known Facts will be evaluated. In addition, the Transform attribute can
be specified for each Known Fact. This Transform will contain the name of a
transformation that the Gateway will apply to the Known Fact value before
presenting the Known Facts to the service owner.
Note that this SOAP API also makes use of <ServiceAuthenticateList> to
communicate the service status back to the SOAP API consumer. It is the
responsibility of the consumer to determine whether the service status returned
indicates success or failure within the context of this SOAP API. The SOAP API
consumer should regard the following service statuses as failure: “Not Enrolled”,
“Suspended”, “HandedToAgent”. The SOAP API consumer should regard the
following service statuses as success: “Enrolled”, “Active ”.
Status “Not Enrolled” means the enrolment attempt failed. A status of “Not
Enrolled” can be returned if the credential which attempted the enrolment is
already enrolled in a service with the supplied known facts (i.e. a duplicate
enrolment attempt returns “Not Enrolled”).
Note that eligibility for enrolment in a service is dependent on the registration
category. That is, a service owner must specify whether the service is for
representatives, delegates or agents. If the <ServiceValidationList> contains a
service that the registration category (that the user has previously registered with)
is not eligible for then this indicates that the SOAP API consumer does not have
the correct mapping of services to registration categories. In this case the entire
- 26 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
enrolment is aborted and the appropriate fault element is returned to the SOAP
API consumer.
Execution of this API requires a valid A-Ticket to be present in the presented
TicketBook. Note that if an A-Ticket is found that is valid (in structure and
contents) but that has either expired the rolling-time window or the fixed-time
window then a separate fault element (from authentication failure) is returned.
If RequestInputData was supplied as True the known facts supplied in the
ServiceValidationList are returned in the ServiceAuthenticateList.
If Service Sequence Numbers were supplied in the ServiceValidationList the
sequence number attributes are returned in the ServiceAuthenticateList.
2.6.3
GsoActivate
(Implemented in: SecurePortal)
This SOAP API will activate a service that the user has previously enrolled for.
The list of services that the user is activating are contained in
<ServiceActivationList> with the appropriate activation keys for each service.
Note that again <ServiceAuthenticationList> is used to communicate success or
failure back to the SOAP API consumer through each service’s status. The SOAP
API consumer should regard the following service statuses as failure: “Not
Enrolled”, “Enrolled”, “Suspended”, “HandedToAgent”, “Ambiguous”. Status
“Ambiguous” means the credential is multiply enrolled in the specified service and
Identifiers must be supplied to resolve which service enrolment is to be activated.
The SOAP API consumer should regard the following service statuses as
success: “Active”. Regardless of whether the activation attempt succeeded
Identifiers for the service will be returned if possible (i.e. if the service enrolment
instance exists and the reference is not ambiguous). For services that failed
activation due to an incorrect activation key or the enrolment did not exist, an
additional element is included in <ServiceAuthenticateList>. The
ActivationAttemptsLeft element will contain the number of times that the user will
be permitted to re-attempt to activate the enrolment before the user is
automatically de-enrolled from that service. If the user fails to activate a service
who’s last status in <ServiceAuthenticateList> was “Enrolled” and
ActivateAttemptsLeft was 1, then <ServiceAuthenticateList> will return a status of
“Not Enrolled” and ActivateAttemptsLeft as 0 for that service. This means that the
user cannot attempt to activate the enrolment anymore has he / she has been
automatically de-enrolled for the service as a security measure. Subsequent
attempts to activate the service will only return status “Not Enrolled” and no
ActivateAttemptsLeft element. If an enrolment is not found the status “Not
Enrolled” will be returned with 0 ActivateAttemptsLeft.
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.
2.6.4
GsoAuthenticate
(Implemented in: SecurePortal and InternetPublic)
This SOAP API authenticates a user according to the GovTalk message
presented as the <Credential> parameter. The GovTalk message will either
contain a UserID/Password for Level-1 users or the GovTalk message will be
signed by the user’s certificate for Level-2 users. The GovTalk message must
conform to the GovTalk XML schema. The contents of the GovTalk message will
then be authenticated. Should authentication fail for any reason (the password
- 27 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
specified was incorrect, the UserID specified does not exist, has been suspended
or has been deleted, the certificate was not registered) a generic fault element is
returned only indicating authentication failed. No further reason is offered. The
only exception to this rule is when a certificate user attempts to authenticate with
a login document where the timestamp in the login document has expired. This
expiry is returned as a separate fault element.
The <ServiceList> is used as a mechanism for the SOAP API consumer to
determine what a user’s enrolments are. <ServiceAuthenticateList> will contain
all the services specified in <ServiceList> with their associated statuses.
In addition, the user’s <CredentialIdentifier> will be returned for a successful
authentication. This <CredentialIdentifier> is supplied to allow the SOAP API
consumer to uniquely identify each user. It is guaranteed to be unique for each
user and will not change as a user’s enrolments may change. Note that
<CredentialIdentifier> cannot be presented to the Gateway to identify a user. The
<CredentialIdentifier> cannot be substituted for UserID or any other form of
identification. It is designed to only be of use to systems and applications external
to the Gateway that need a mechanism to identify returning users.
<UserDetailsGet> will contain the authenticated user’s name, email address,
description and registration category. If authenticating an Agent user the
UserDetailsGet will also contain the AgentID, AgentCode and
AgentFriendlyName. See the description of the <UserDetailsGet> document for a
full description of the Agent elements.
If an A-Ticket is found in the TicketBook it is not validated. It will be removed
without checking its contents. GsoLogOut and GsoRegisterAndEnrol are the only
other SOAP API’s that can remove A-Tickets from a TicketBook.
ClientListIndicator is an optional Boolean attribute on ServiceList which controls
whether the attribute “IsClientList” is present in Service nodes which are client
lists (lists of client identifiers associated with the agent credential currently being
authenticated).
IncludeClients is an optional Boolean attribute on ServiceList/Service which
controls whether the clients lists associated with an agent service should also be
listed in the output ServiceAuthenticateList.
GroupIdentifiers is used by GsoAuthenticate and GsoValidate to indicate whether
the identifiers in client list services should be grouped. If True, Each set of Client
Identifiers is bounded by its own <Identifiers> tag. If False or not present, All
client identifiers in a client list service are bounded by a single <Identifiers> tag.
AllServices requests that all services associated with the credential be included in
the output ServiceAuthenticateList. Any service elements in the ServiceList are
ignored unless the service element has an ‘IncludeClients’ attribute in which case
all client lists for the marked services are included in the ServiceAuthenticateList.
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 AllClients attribute
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
- 28 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
specified on <Service> elements.
False
true
Client services with identifiers are included in all cases where the
agent service is explicitly given in the incoming list of services. There
is no need to use “IncludeClients” on any particular <Service>
element.
True
true
Everything returned; all services, with all client services containing
client identifiers. The equivalent of the current Portal Authentication
Service.
2.6.5
GsoValidate
(Implemented in: SecurePortal and InternetPublic)
This SOAP API is used to simulate the authentication of a user that has
previously been authenticated and issued an A-Ticket. This mechanism will be
used when the TicketBook is passed between consumers. The consumer
receiving the TicketBook can present this TicketBook and receive back all the
user information that is returned from a normal authentication. However, the
consumer of this SOAP API must present <ServiceList> to discover a user’s
enrolment in a specific set of services. In response this SOAP API will return all of
the services in <ServiceAuthenticateList> with the associated status for each
service. Note that the <ServiceList> does not need to contain any services at all.
It can be an empty XML document (but must still be a well-formed XML document
and conform to urn:GSO-System-Service:external:soap:xsdServiceList). In this
case all user information is returned as normal but the <ServiceAuthenticateList>
will be an empty XML document (but still be a well-formed XML document and
conform to urn:GSO-System-Service:external:soap:xsdServiceAuthenticateList.
<CredentialIdentifier> will contain the user’s CredentialIdentifier, and
<UserDetailsGet> will contain the user’s name, email address and registration
category. If validating an Agent user the UserDetailsGet will also contain the
AgentID, AgentCode and AgentFriendlyName. See the description of the
<UserDetailsGet> document for a full description of the Agent elements.
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.
- 29 -
Developer Guide to A&A Web Services
2.6.6
Government Gateway 1.6.3
GsoRefresh
(Implemented in: SecurePortal and InternetPublic)
This SOAP API is used to refresh the expiry time of an A-Ticket. The expiry time
for an A-Ticket is for the SOAP interface as a whole (i.e. SecurePortal and
InternetPublic will share the same expiry times). This SOAP API only requires a
valid <TicketBook> and <CallerSignature> to be present.
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.
2.6.7
GsoDeEnrol
(Implemented in: SecurePortal)
This SOAP API is used to de-enrol a user from one or more service(s). The list of
services that the user that the user must be de-enrol for are contained in
<ServiceList>. The optional RemoveAgent attribute can be used to specify
whether the agent (if enrolled) should be removed from the enrolment as well. If
not specified the default will be that the agent will not be removed.
<ServiceAuthenticationList> is used to communicate success or failure back to
the SOAP API consumer through each service’s status. The SOAP API consumer
should regard the following service statuses as failure: “Enrolled”, “Suspended”,
“HandedToAgent”, “Active”, “Ambiguous”. Status “Ambiguous” means the
credential is multiply enrolled in the specified service and Identifiers must be
supplied to resolve which service enrolment is to be deenroled. The SOAP API
consumer should regard the following service statuses as success: “Not
Enrolled”. If identifiers are available they will be returned except for status
Ambiguous. Previously in GSO 1.5 identifiers were not returned if the
deenrolment failed but multiple enrolment functionality mandates their inclusion in
the response. Note that this SOAP API will use existing business layer
components to perform the actual de-enrolment. Any business rule specific logic
must be implemented at that layer and not within this SOAP API.
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.
2.6.8
GsoGetUserDetails
(Implemented in: SecurePortal)
This SOAP API is used to retrieve a user’s name, email address and registration
category through <UserDetailsGet>. If retrieving the details of an Agent user the
UserDetailsGet will also contain the AgentID, AgentCode and
AgentFriendlyName. See the description of the <UserDetailsGet> document for a
full description of the Agent elements. Even though UserDetails are returned
through the GsoAuthenticate and GsoValidate SOAP APIs, this API is provided
for applications that need to retrieve this user information sometime after
authentication.
Execution of this API requires a valid A-Ticket to be present in the presented
TicketBook. Note that if an A-Ticket is found that is valid (in structure and content)
but that has either expired the rolling-time window or the fixed-time window then a
separate fault element (from authentication failure) is returned.
- 30 -
Developer Guide to A&A Web Services
2.6.9
Government Gateway 1.6.3
GsoSetUserDetails
(Implemented in: SecurePortal)
This SOAP API is used to change a user’s name and / or email address. Note
that only Level-1 users (UserID/Password) can change their name. Level-2 users
(Certificate) cannot change their name as this information is extracted from their
X.509 certificate. This API is atomic, i.e. if both a new user name and email
address are supplied but the user is a Level-2 (Certificate) user then neither the
name nor email address will be changed. Only a fault element will be returned.
Note that the user cannot change their name to an empty string. At least one
character must be specified.
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.
2.6.10 GsoGetLoginDocument
(Implemented in: SecurePortal and InternetPublic)
This SOAP API receives <Base64Encode> that indicates whether the SOAP API
consumer requires the LoginDocument and SignedInfoBlock to be base64
encoded or in clear text.
This SOAP API does not accept a ticket book and therefore does not require an
A-Ticket.
2.6.11 GsoLogOut
(Implemented in: SecurePortal and InternetPublic)
This SOAP API provides a mechanism for SOAP API consumers to remove ATickets from their TicketBook. As the consumers should never attempt to inspect
or decode the TicketBook this API is necessary for cleaning up the A-Ticket
should the user want to authenticate with different credentials or the A-Ticket has
expired and the user wishes to re-authenticate. This API does not check the
validity of the A-Ticket. It only removes the elements in the TicketBook that were
put there by the Gateway.
2.6.12 GsoSetPassword
(Implemented in: SecurePortal)
This SOAP API allows a user to change his / her password. The password
change is contained in the <CredentialChange> XML document. Within
CredentialChange are PasswordOld and PasswordNew. The old password can
be supplied as an MD5 hash but the new password must be supplied as clear
text. This is necessary as the password strength policy must be applied to the
new password before the change is persisted. Note MD5 hashes are assumed to
be derived from UTF -8 representations of the data. A fault element is returned
indicating the password strength policy violation.
Execution of this API requires a valid A-Ticket to be present in the presented
TicketBook. Not e 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.
2.6.13 GsoResetPassword
(Implemented in: SecurePortal)
This SOAP API allows a user to reset his / her password. The User must supply
their UserID (via a UserIdentifier document) and a ServiceValidationList which
contains one service + known facts. These details are used to identify the User’s
Credential. If the user supplied correct information a new password which is
compliant with password strength rules is generated and sent to the user via
Secure Mail.
Note GsoResetPassword and GsoUserIdResend can only be called once within a
predefined time limit (stored in the GatewayProperties table ID 4). The default
- 31 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
time limit is 3 days. If GsoResetPassword or GsoUserIdResend is called less
than 3 days after a previous successful call to GsoResetPassword or
GsoUserIdResend an error is returned.
2.6.14 GsoUserIdResend
(Implemented in: SecurePortal)
This SOAP API allows a user to request their UserID be resent to him / her. The
user must supply their Password (via a <Password> document) and a
ServiceValidationList which contains one service + known facts. These details
are used to identify the User’s Credential. If the user supplied correct information
the UserID is sent to the user via Secure Mail.
Note GsoResetPassword and GsoUserIdResend can only be called once within a
predefined time limit (stored in the GatewayProperties table ID 4). The default
time limit is 3 days. If GsoResetPassword or GsoUserIdResend is called less
than 3 days after a previous successful call to GsoResetPassword or
GsoUserIdResend an error is returned.
2.7 Data
2.7.1
Persistent State
The Web Servi ces do not maintain A-Ticket state in the R&E database. All
authentication state is administered through the <TicketBook>. The SOAP API
consumer is required to present a TicketBook for every single SOAP API call.
However, depending on which SOAP API is called, a valid A-Ticket may or may
not be required. For example, GsoEnrolOnly requires a valid A-Ticket but
GsoRegisterAndEnrol does not. In addition, the SOAP API consumer is required
to persist the TicketBook included in a SOAP API response as the A-Ticket in this
TicketBook may not have the same value as the A-Ticket presented in the SOAP
API request.
Contained within the A-Ticket will be date time information of the last successful
SOAP API call. If the time period between the last successful SOAP API call and
the current SOAP API call is longer than the configured rolling-window expiry time
then the A-Ticket will be deemed invalid. In addition, the A-Ticket’s first issue time
is checked against the fixed-window expiry time. It will therefore be impossible for
a SOAP API consumer to keep refreshing an A-Ticket indefinitely. These timeout
periods apply to all SOAP API interfaces as a whole.
The time the User last successfully executed a GsoUserIdResend or
GsoResetPassword transaction is stored with the user’s Credential. This is
required to enforce the business rule that GsoUserIdResend and
GsoResetPassword can only be called once every 3 days (configurable).
2.7.2
Data Flows / Transformations
SOAP API messages will be formatted according to the
GsoSoapSecurePortal.wsdl and GsoSoapInternetPublic.wsdl definitions. These
Web Service Definition Language files conform to the Web Services Description
Language (WSDL) 1.1, W3C Note 15 March 2001 and Simple Object Access
Protocol (SOAP) 1.1, W3C Note 08 May 2000.
2.7.3
Session State
No session state will be maintained between the SOAP API consumer and
provider. Note that the TicketBook is not persisted in the session state.
2.7.4
Temporal State
The A-Ticket will be subject to an rolling-time and fixed-time expiry time interval.
See Persistent State for more information.
- 32 -
Developer Guide to A&A Web Services
3
Government Gateway 1.6.3
Error & Exception Processing
3.1 Error Classifications
3.1.1
Business Recoverable Errors
Due to the restriction of Fault elements in the SOAP specification, no business
recoverable errors are defined through fault elements. A SOAP response cannot
contain the response message as well as Fault elements. Therefore each of the
SOAP APIs is atomic, i.e. either the transaction took place as expected or the
transaction did not take place at all.
All business recoverable errors are interpreted through the
<ServiceAuthenticateList> XML document. These errors are not communicated
explicitly to the SOAP API consumer. It is the consumer’s responsibility to
interpret these service statuses and determine success or failure in the context of
the SOAP API’s business function. The following matrix documents the SOAP
APIs using the <ServiceAuthenticateList> in their response and how the service
status should be interpreted (Success, Failure, Not Applicable):
NA S
NA F
NA F
NA F
NA F
NA F
GsoValidate
NA
NA
NA
NA
NA
NA
GsoAuthenticate
GsoDeEnrol
F
F
S
F
F
F
GsoValidate
F
S
S
S
NA
NA
GsoAuthenticate
F
S
S
S
NA
NA
GsoActivate
3.1.2
GsoEnrolOnly
Not Enrolled
Enrolled
Active
HandedToAgent
Suspended
Ambiguous
GsoRegisterAndEnrol
ServiceAuthenticateList
Status
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
NA
Business Fatal Errors
The following matrix illustrates the possible business fatal errors. Business fatal
errors are returned as fault elements. Note that the fault elements are returned in
the namespace and schema defined by the Microsoft SOAP Toolkit 2.0 SP2. For
more information on how the SOAP Toolkit implements fault elements see
Understanding the SOAP Fault <detail> Contents. The <returnCode> will be the
HRESULT return value of the method in GsoSoapSecurePortal or
GsoSoapInternetPublic. For more information on the structure of an HRESULT
see Platform SDK: COM: Error Handling. Note that some of the error conditions
documented in the Functional Specification of Authentication and Authorisation
are implemented by the XML Schema (XS D) of the relevant XML document /
parameter. An example of this implementation is the passing of a new password
in CredentialChange as an MD5 hash. Note MD5 hashes are assumed to be
derived from UTF-8 representations of the data. The XSD of CredentialChange
(urn:GSO-System-Service:external:soap:xsdCredentialChange) does not allow
MD5 to be specified of the mode for PasswordNew.
Note that the HRESULT is calculated by offsetting the Error Code by
vbObjectError (-2147221504, 0x80040000), also known as SEVERITY_ERROR
with FACILITY_ITF.
- 33 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
SecurePortal
X
X
X
X
X
X
4
GsoLogOut
X
4
GsoGetLoginDocument
X
GsoValidate
X
GsoRefresh
12
X
GsoAuthenticate
7
X
GsoUserIdResend
8
X
GsoResetPassword
6
X
X
X
X
X
GsoSetPassword
12 10
X
GsoLogOut
8
X
GsoGetLoginDocument
GsoSetUserDetails
GsoDeEnrol
GsoGetUserDetails
GsoRefresh
GsoValidate
26 10
9
9
6
10 4
4
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
Description
-2147210503
-2147210502
-2147210501
-2147210500
-2147210499
Authentication of Credential failed.
Certificate issuer not trusted.
Authentication of CallerSignature failed.
Timestamp in LoginDocument has expired.
Authentication of Certificate failed.
-2147209503
-2147209502
-2147209501
-2147129501
-2147209499
-2147209498
-2147209497
-2147209496
-2147209495
-2147209493
-2147209492
-2147209491
-2147209490
Name not supplied for Level-1 registration. Registration aborted.
-2147208503
-2147208502
-2147208501
-2147208500
-2147208499
-2147208498
-2147208497
-2147208496
-2147208495
-2147208494
-2147208493
-2147208492
-2147208491
Level-2 user cannot change name. UserDetailsSet aborted.
13
2
17
2
2
1
1
1
1
1
1
1
1
1
1
1
1
1
Failed enrolment for all services. Registration aborted.
Registration category not eligibile for a service. Registration aborted.
Registration category not eligible for a service. Enrolment aborted.
Password does not meet strength policy. Registration aborted.
Password must be supplied in clear text. Registration aborted.
Name supplied for Level-2 registration. Registration aborted.
Known facts supplied already in use. Registration aborted.
Known facts supplied already in use. Enrolment aborted.
User details or certificate not unique. Registration aborted.
Invalid email address. Registration aborted.
Invalid description. Registration aborted.
Invalid name. Registration aborted.
1
1
1
1
1
1
2
1
1
1
2
1
1
Cannot change name to empty string. UserDetailsSet aborted.
Password does not meet strength policy. SetPassword aborted.
Level-2 user cannot change password. SetPassword aborted.
Invalid email address. SetUserDetails aborted.
Old password supplied is incorrect. SetPassword aborted.
User specified not found. Transaction aborted.
Invalid name. SetUserDetails aborted.
Invalid description. SetUserDetails aborted.
This request occurred too soon after a previous attempt to perform this or a related operation.
The supplied ServiceValidationList contains too many services for the current operation.
AgentID must be specified for RegistrationCategory Agent. Registration aborted.
AgentFriendlyName must be specified for RegistrationCategory Agent. Registration aborted.
-2147207503 A-Ticket has expired.
10
-2147206503
-2147206502
-2147206501
-2147206500
-2147206499
-2147206498
-2147206497
-2147206496
-2147206495
-2147206494
-2147206493
-2147206492
-2147206491
-2147206490
-2147206489
-2147206488
-2147206487
2
17
3
3
1
2
1
8
5
4
2
15
1
5
1
2
1
Validation of Base64Encode structure failed.
Validation of CallerSignature structure failed.
Validation of Credential structure failed.
Validation of CredentialIdentifier structure failed.
Validation of CredentialChange structure failed.
Validation of LoginDocument structure failed.
Validation of ServiceActivationList structure failed.
Validation of ServiceAuthenticateList structure failed.
Validation of ServiceList structure failed.
Validation of ServiceValidationList structure failed.
Validation of SignedInfoBlock structure failed.
Validation of TicketBook structure failed.
Validation of UserDetails structure failed.
Validation of UserDetailsGet structure failed.
Validation of UserDetailsSet structure failed.
Validation of UserIdentifier structure failed..
Validation of Password structure failed..
-2147205503 An internal error occurred. Transaction aborted.
3.1.3
GsoAuthenticate
HRESULT
(Dec)
GsoActivate
HRESULT
(Hex)
GsoEnrolOnly
Error
Code
Authentication Faults
11001 80042AF9
11002 80042AFA
11003 80042AFB
11004 80042AFC
11005 80042AFD
Service Faults
12001 80042EE1
12002 80042EE2
12003 80042EE3
12004 80056763
12005 80042EE5
12006 80042EE6
12007 80042EE7
12008 80042EE8
12009 80042EE9
12011 80042EEB
12012 80042EEC
12013 80042EED
12014 80042EEE
User Faults
13001 800432C9
13002 800432CA
13003 800432CB
13004 800432CC
13005 800432CD
13006 800432CE
13007 800432CF
13008 800432D0
13009 800432D1
13010 800432D2
13011 800432D3
13012 800432D4
13013 800432D5
Ticket Faults
14001 800436B1
XML Faults
15001 80043A99
15002 80043A9A
15003 80043A9B
15004 80043A9C
15005 80043A9D
15006 80043A9E
15007 80043A9F
15008 80043AA0
15009 80043AA1
15010 80043AA2
15011 80043AA3
15012 80043AA4
15013 80043AA5
15014 80043AA6
15015 80043AA7
15016 80043AA8
15017 80043AA9
Internal Faults
16001 80043E81
GsoRegisterAndEnrol
API Count
Fault Count
InternetPublic
19
X
X
X
X
10
8
X
X
X
0
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
System Recoverable Errors
Not Applicable.
3.1.4
System Fatal Errors
Not Applicable.
3.2 Exception Interface
3.2.1
Exception Types Thrown
All exception processing will be done through SOAP fault elements.
3.2.2
Internal Exceptions
The only internal exception that will be returned to the SOAP API consumer will
be Error Code 16001 or HRESULT (0x80043E81 / -2147205503).
3.2.3
Exception Architecture / Policy
All exceptions will be returned as SOAP fault elements.
3.3 Security Considerations
3.3.1
Privacy
All HTTP traffic to the SecurePortal and InternetPublic will be protected by SSL.
In addition, SecurePortal will be protected by client-side certificates.
InternetPublic will only be secured by a server-side certificate. See the Interfaces
section for more detail.
- 34 -
Developer Guide to A&A Web Services
3.3.2
Government Gateway 1.6.3
Authentication / Authorisation
The GsoSoap Authentication and Authorisation implementation is discussed in
detail in the Interfaces section of this document.
- 35 -
Developer Guide to A&A Web Services
4
Government Gateway 1.6.3
Appendix A – WSDL and IDL
4.1 SecurePortal WSDL
The WSDL file for the SecurePortal SOAP interface
(https://secure.gateway.gov.uk/soap/SecurePortal) is as follows. Note that the
Namespace used in all XSDs for the SOAP APIs use parameter specific namespaces
urn:GSO-System-Services:external:soap:xsd<ParameterName>. The
GsoSoapSecurePortalService.wsdl file will be as follows:
<?xml version='1.0' encoding='UTF-8' ?>
<definitions
name='GsoSoapSecurePortalService'
targetNamespace='urn:GSO-System-Services:external:soap:wsdl:'
xmlns:wsdlns='urn:GSO-System-Services:external:soap:wsdl:'
xmlns:typens='urn:GSO-System-Services:external:soap:type'
xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns:stk='http://schemas.microsoft.com/soap-toolkit/wsdl-extension'
xmlns='http://schemas.xmlsoap.org/wsdl/'>
<types>
<schema
targetNamespace='urn:GSO-System-Services:external:soap:type'
xmlns='http://www.w3.org/2001/XMLSchema'
xmlns:SOAP-ENC='http://schemas.xmlsoap.org/soap/encoding/'
xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
elementFormDefault='qualified'>
</schema>
</types>
<message name='SecurePortal.GsoRegisterAndEnrol'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
<part name='ServiceValidationList' type='xsd:string'/>
<part name='UserDetails' type='xsd:string'/>
<part name='Credential' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoRegisterAndEnrolResponse'>
<part name='TicketBook' type='xsd:string'/>
<part name='UserIdentifier' type='xsd:string'/>
<part name='CredentialIdentifier' type='xsd:string'/>
<part name='ServiceAuthenticateList' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoEnrolOnly'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
<part name='ServiceValidationList' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoEnrolOnlyResponse'>
<part name='TicketBook' type='xsd:string'/>
<part name='ServiceAuthenticateList' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoActivate'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
<part name='ServiceActivationList' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoActivateResponse'>
<part name='TicketBook' type='xsd:string'/>
<part name='ServiceAuthenticateList' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoAuthenticate'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
<part name='Credential' type='xsd:string'/>
<part name='ServiceList' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoAuthenticateResponse'>
<part name='TicketBook' type='xsd:string'/>
<part name='ServiceAuthenticateList' type='xsd:string'/>
<part name='CredentialIdentifier' type='xsd:string'/>
<part name='UserDetailsGet' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoValidate'>
- 36 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
<part name='ServiceList' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoValidateResponse'>
<part name='TicketBook' type='xsd:string'/>
<part name='ServiceAuthenticateList' type='xsd:string'/>
<part name='CredentialIdentifier' type='xsd:string'/>
<part name='UserDetailsGet' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoRefresh'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoRefreshResponse'>
<part name='TicketBook' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoDeEnrol'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
<part name='ServiceList' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoDeEnrolResponse'>
<part name='TicketBook' type='xsd:string'/>
<part name='ServiceAuthenticateList' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoGetUserDetails'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoGetUserDetailsResponse'>
<part name='TicketBook' type='xsd:string'/>
<part name='UserDetailsGet' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoSetUserDetails'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
<part name='UserDetailsSet' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoSetUserDetailsResponse'>
<part name='TicketBook' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoGetLoginDocument'>
<part name='Base64Encode' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoGetLoginDocumentResponse'>
<part name='LoginDocument' type='xsd:string'/>
<part name='SignedInfoBlock' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoLogOut'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoLogOutResponse'>
<part name='TicketBook' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoSetPassword'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
<part name='CredentialChange' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoSetPasswordResponse'>
<part name='TicketBook' type='xsd:string'/>
</message>
<message name='SecurePortal.GsoUserIdResend'>
<part name='CallerSignature' type='xsd:string' />
<part name='Password' type='xsd:string' />
<part name='ServiceValidationList' type='xsd:string' />
</message>
<message name='SecurePortal.GsoUserIdResendResponse' />
<message name='SecurePortal.GsoResetPassword'>
<part name='CallerSignature' type='xsd:string' />
<part name='UserIdentifier' type='xsd:string' />
<part name='ServiceValidationList' type='xsd:string' />
</message>
<message name='SecurePortal.GsoResetPasswordResponse' />
<portType name='SecurePortalSoapPort'>
- 37 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<operation name='GsoRegisterAndEnrol' parameterOrder='TicketBook
CallerSignature ServiceValidationList UserDetails Credential UserIdentifier
CredentialIdentifier ServiceAuthenticateList'>
<input message='wsdlns:SecurePortal.GsoRegisterAndEnrol' />
<output message='wsdlns:SecurePortal.GsoRegisterAndEnrolResponse' />
</operation>
<operation name='GsoEnrolOnly' parameterOrder='TicketBook CallerSignature
ServiceValidationList ServiceAuthenticateList'>
<input message='wsdlns:SecurePortal.GsoEnrolOnly' />
<output message='wsdlns:SecurePortal.GsoEnrolOnlyResponse' />
</operation>
<operation name='GsoActivate' parameterOrder='TicketBook CallerSignature
ServiceActivationList ServiceAuthenticateList'>
<input message='wsdlns:SecurePortal.GsoActivate' />
<output message='wsdlns:SecurePortal.GsoActivateResponse' />
</operation>
<operation name='GsoAuthenticate' parameterOrder='TicketBook CallerSignature
Credential ServiceList ServiceAuthenticateList CredentialIdentifier
UserDetailsGet'>
<input message='wsdlns:SecurePortal.GsoAuthenticate' />
<output message='wsdlns:SecurePortal.GsoAuthenticateResponse' />
</operation>
<operation name='GsoValidate' parameterOrder='TicketBook CallerSignature
ServiceList ServiceAuthenticateList CredentialIdentifier UserDetailsGet'>
<input message='wsdlns:SecurePortal.GsoValidate' />
<output message='wsdlns:SecurePortal.GsoValidateResponse' />
</operation>
<operation name='GsoRefresh' parameterOrder='TicketBook CallerSignature'>
<input message='wsdlns:SecurePortal.GsoRefresh' />
<output message='wsdlns:SecurePortal.GsoRefreshResponse' />
</operation>
<operation name='GsoDeEnrol' parameterOrder='TicketBook CallerSignature
ServiceList ServiceAuthenticateList'>
<input message='wsdlns:SecurePortal.GsoDeEnrol' />
<output message='wsdlns:SecurePortal.GsoDeEnrolResponse' />
</operation>
<operation name='GsoGetUserDetails' parameterOrder='TicketBook CallerSignature
UserDetailsGet'>
<input message='wsdlns:SecurePortal.GsoGetUserDetails' />
<output message='wsdlns:SecurePortal.GsoGetUserDetailsResponse' />
</operation>
<operation name='GsoSetUserDetails' parameterOrder='TicketBook
CallerSignature UserDetailsSet'>
<input message='wsdlns:SecurePortal.GsoSetUserDetails' />
<output message='wsdlns:SecurePortal.GsoSetUserDetailsResponse' />
</operation>
<operation name='GsoGetLoginDocument' parameterOrder='Base64Encode
LoginDocument SignedInfoBlock'>
<input message='wsdlns:SecurePortal.GsoGetLoginDocument' />
<output message='wsdlns:SecurePortal.GsoGetLoginDocumentResponse' />
</operation>
<operation name='GsoLogOut' parameterOrder='TicketBook CallerSignature'>
<input message='wsdlns:SecurePortal.GsoLogOut' />
<output message='wsdlns:SecurePortal.GsoLogOutResponse' />
</operation>
<operation name='GsoSetPassword' parameterOrder='TicketBook CallerSignature
CredentialChange'>
<input message='wsdlns:SecurePortal.GsoSetPassword' />
<output message='wsdlns:SecurePortal.GsoSetPasswordResponse' />
</operation>
<operation name='GsoResetPassword' parameterOrder='CallerSignature
UserIdentifier ServiceValidationList'>
<input message='wsdlns:SecurePortal.GsoResetPassword' />
<output message='wsdlns:SecurePortal.GsoResetPasswordResponse' />
</operation>
<operation name='GsoUserIdResend' parameterOrder='CallerSignature Password
ServiceValidationList'>
<input message='wsdlns:SecurePortal.GsoUserIdResend' />
<output message='wsdlns:SecurePortal.GsoUserIdResendResponse' />
</operation>
</portType>
<binding name='SecurePortalSoapBinding' type='wsdlns:SecurePortalSoapPort' >
<stk:binding preferredEncoding='UTF-8'/>
<soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'
/>
<operation name='GsoRegisterAndEnrol' >
- 38 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoRegisterAndEnrol' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoEnrolOnly' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoEnrolOnly' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoActivate' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoActivate' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoAuthenticate' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoAuthenticate' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoValidate' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoValidate' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoRefresh' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoRefresh' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
- 39 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoDeEnrol' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoDeEnrol' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoGetUserDetails' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoGetUserDetails' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoSetUserDetails' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoSetUserDetails' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoGetLoginDocument' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoGetLoginDocument' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoLogOut' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoLogOut' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoSetPassword' >
- 40 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoSetPassword' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoResetPassword' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoResetPassword' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoUserIdResend' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:SecurePortal.GsoUserIdResend' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
</binding>
<service name='GsoSoapSecurePortalService' >
<port name='SecurePortalSoapPort' binding='wsdlns:SecurePortalSoapBinding' >
<soap:address
location='https://secure.gso.eval/soap/SecurePortal/GsoSoapSecurePortalService.WSD
L' />
</port>
</service>
</definitions>
- 41 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
- 42 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
4.2 InternetPublic WSDL
The WSDL file for the InternetPublic SOAP interface
(https://secure.gateway.gov.uk/soap/InternetPublic) is as follows. Note that the
Namespace used in all XSDs for the SOAP APIs use parameter specific namespaces
urn:GSO-System-Services:external:soap:xsd<ParameterName>. The
GsoSoapInternetPublicService.wsdl file will be as follows:
<?xml version='1.0' encoding='UTF-8' ?>
<definitions
name='GsoSoapInternetPublicService'
targetNamespace='urn:GSO-System-Services:external:soap:wsdl:'
xmlns:wsdlns='urn:GSO-System-Services:external:soap:wsdl:'
xmlns:typens='urn:GSO-System-Services:external:soap:type'
xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns:stk='http://schemas.microsoft.com/soap-toolkit/wsdl-extension'
xmlns='http://schemas.xmlsoap.org/wsdl/'>
<types>
<schema
targetNamespace='urn:GSO-System-Services:external:soap:type'
xmlns='http://www.w3.org/2001/XMLSchema'
xmlns:SOAP-ENC='http://schemas.xmlsoap.org/soap/encoding/'
xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
elementFormDefault='qualified'>
</schema>
</types>
<message name='InternetPublic.GsoAuthenticate'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
<part name='Credential' type='xsd:string'/>
<part name='ServiceList' type='xsd:string'/>
</message>
<message name='InternetPublic.GsoAuthenticateResponse'>
<part name='TicketBook' type='xsd:string'/>
<part name='ServiceAuthenticateList' type='xsd:string'/>
<part name='CredentialIdentifier' type='xsd:string'/>
<part name='UserDetailsGet' type='xsd:string'/>
</message>
<message name='InternetPublic.GsoRefresh'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
</message>
<message name='InternetPublic.GsoRefreshResponse'>
<part name='TicketBook' type='xsd:string'/>
</message>
<message name='InternetPublic.GsoValidate'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
<part name='ServiceList' type='xsd:string'/>
</message>
<message name='InternetPublic.GsoValidateResponse'>
<part name='TicketBook' type='xsd:string'/>
<part name='ServiceAuthenticateList' type='xsd:string'/>
<part name='CredentialIdentifier' type='xsd:string'/>
<part name='UserDetailsGet' type='xsd:string'/>
</message>
<message name='InternetPublic.GsoGetLoginDocument'>
<part name='Base64Encode' type='xsd:string'/>
</message>
<message name='InternetPublic.GsoGetLoginDocumentResponse'>
<part name='LoginDocument' type='xsd:string'/>
<part name='SignedInfoBlock' type='xsd:string'/>
</message>
<message name='InternetPublic.GsoLogOut'>
<part name='TicketBook' type='xsd:string'/>
<part name='CallerSignature' type='xsd:string'/>
</message>
<message name='InternetPublic.GsoLogOutResponse'>
<part name='TicketBook' type='xsd:string'/>
</message>
<portType name='InternetPublicSoapPort'>
<operation name='GsoAuthenticate' parameterOrder='TicketBook CallerSignature
Credential ServiceList ServiceAuthenticateList CredentialIdentifier
- 43 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
UserDetailsGet'>
<input message='wsdlns:InternetPublic.GsoAuthenticate' />
<output message='wsdlns:InternetPublic.GsoAuthenticateResponse' />
</operation>
<operation name='GsoRefresh' parameterOrder='TicketBook CallerSignature'>
<input message='wsdlns:InternetPublic.GsoRefresh' />
<output message='wsdlns:InternetPublic.GsoRefreshResponse' />
</operation>
<operation name='GsoValidate' parameterOrder='TicketBook CallerSignature
ServiceList ServiceAuthenticateList CredentialIdentifier UserDetailsGet'>
<input message='wsdlns:InternetPublic.GsoValidate' />
<output message='wsdlns:InternetPublic.GsoValidateResponse' />
</operation>
<operation name='GsoGetLoginDocument' parameterOrder='Base64Encode
LoginDocument SignedInfoBlock'>
<input message='wsdlns:InternetPublic.GsoGetLoginDocument' />
<output message='wsdlns:InternetPublic.GsoGetLoginDocumentResponse' />
</operation>
<operation name='GsoLogOut' parameterOrder='TicketBook CallerSignature'>
<input message='wsdlns:InternetPublic.GsoLogOut' />
<output message='wsdlns:InternetPublic.GsoLogOutResponse' />
</operation>
</portType>
<binding name='InternetPublicSoapBinding' type='wsdlns:InternetPublicSoapPort'
>
<stk:binding preferredEncoding='UTF-8'/>
<soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'
/>
<operation name='GsoAuthenticate' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:InternetPublic.GsoAuthenticate' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoRefresh' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:InternetPublic.GsoRefresh' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoValidate' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:InternetPublic.GsoValidate' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoGetLoginDocument' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:InternetPublic.GsoGetLoginDocument' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
- 44 -
Developer Guide to A&A Web Services
Government Gateway 1.6.3
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='GsoLogOut' >
<soap:operation soapAction='urn:GSO-SystemServices:external:soap:action:InternetPublic.GsoLogOut' />
<input>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='urn:GSO-SystemServices:external:soap:message:'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
</binding>
<service name='GsoSoapInternetPublicService' >
<port name='InternetPublicSoapPort'
binding='wsdlns:InternetPublicSoapBinding' >
<soap:address
location='https://secure.gso.eval/soap/InternetPublic/GsoSoapInternetPublicService
.WSDL' />
</port>
</service>
</definitions>
- 45 -