Glossary Item Box

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

# GatewaySoapPortal.GsoGetUserDetails (1.6.7, 1.6.8 and 2.0.0) Method

This method gets the calling credential's details.

(Note this version of GsoGetUserDetails should only be used for portals/applications built for releases 1.6.7, 1.6.8 and 2.0.0 of the Gateway.)

public void GsoGetUserDetails(
string inputXml,
out string outputXml
);

#### Parameters

inputXml
  Input Xml for this method must have the namespace urn:GSO-System-Services:external:1.67:GsoGetUserDetailsXmlInput
outputXml
  Output Xml for this method must have the namespace urn:GSO-System-Services:external:1.67:GsoGetUserDetailsXmlOutput

#### Remarks

The input parameter is an XML document that contains the following elements:

- IncludeGatewayAuthLevel: Information returned to include the credential's current authentication level
- IncludeAvailableGatewayAuthLevels: Information returned to include details of all the authentication types/levels for the credential

The output parameter is an XML document that contains the following elements:

- CredentialName: The name of the credential
- CredentialIdentifier: Unique identifier for credential
- Description: Credential's description
- EmailAddress: Email address registered with Gateway
- PasswordExpiryDateTime: Time out for password
- UserType: Agent or Principal
- AuthenticationType: UserID or Certificate
- RegistrationCategory: Individual, Gov-Individual, Organisation, Gov-Organisation or Agent
- CredentialRole: User or assistant
- TSchemeLevel: For the current authentication type (NoAssurance, SomeAssurance, GoodAssurance or BeyondReasonableDoubt)
- AgentDetails: If the credential is an agent then the following is returned:
  - AgentID: Name selected by Agent
  - AgentCode: Uniquely identifies the Agent (generated by the Gateway when the Agent organisation was created)
  - AgentFriendlyName: Short description selected by Agent
- CurrentGatewayAuthLevel: If requested, returns the current authentication level of the credential (User ID/password, User ID/password and Security Phrase or certificate)
- AvailableAuthenticationTypes: If requested, contains the following elements:
  - UserID:
    - GatewayAuthLevel (optional): Authentication level for the credential's User ID/password
  - Certificates:
    - GatewayAuthLevels (optional): Authentication levels for which the credential has certificates
  - SecurityPhrase:
    - GatewayAuthLevel(optional): Authentication level for the credential's User ID/password with a security phrase
    - SecurityPhraseQuestions: The position of 3 characters in the security phrase that will be used the next time the user is prompted for their security phrase
- SecureMessaging
  - MessageBoxVisited: Whether credential's message box has ever been accessed (i.e. true if not yet accessed)
  - TotalMessages: Number of messages in credential's message box
  - TotalUnreadMessages: Number of unread messages in credential's message box

The schema for the input document is as follows (this xsd references GsoCore.xsd):

    <?xml version="1.0" encoding="utf-8"?>
    <xs:schema targetNamespace="urn:GSO-System-Services:external:1.67:GsoGetUserDetailsXmlInput" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:GSO-System-Services:external:1.65:GsoCore" xmlns="urn:GSO-System-Services:external:1.67:GsoGetUserDetailsXmlInput" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0">
        <xs:import namespace="urn:GSO-System-Services:external:1.65:GsoCore" />
        <xs:element name="GsoGetUserDetailsXmlInput">
            <xs:complexType>
                <xs:sequence>
                    <xs:element name="IncludeGatewayAuthLevel" type="xs:boolean"/>
                    <xs:element name="IncludeAvailableGatewayAuthLevels" type="xs:boolean"/>
                </xs:sequence>
            </xs:complexType>
        </xs:element>
    </xs:schema>

The schema for the output document is as follows (this xsd references GsoCore.xsd):

    <?xml version="1.0" encoding="utf-8"?>
    <xs:schema targetNamespace="urn:GSO-System-Services:external:1.67:GsoGetUserDetailsXmlOutput" xmlns="urn:GSO-System-Services:external:1.67:GsoGetUserDetailsXmlOutput" xmlns:core="urn:GSO-System-Services:external:1.65:GsoCore" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" version="2.0">
      <xs:import namespace="urn:GSO-System-Services:external:1.65:GsoCore" />
      <xs:element name="GsoGetUserDetailsXmlOutput">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="CredentialName" type="core:CredentialNameTYPE"/>
            <xs:element name="CredentialIdentifier" type="core:CredentialIdentifierTYPE"/>
            <xs:element name="Description" type="core:CredentialDescriptionTYPE"/>
            <xs:element name="EmailAddress" type="core:EmailAddressTYPE"/>
            <xs:element name="PasswordExpiryDateTime" type="xs:dateTime"/>
            <xs:element name="UserType" type="core:UserTypeTYPE"/>
            <xs:element name="AuthenticationType" type="core:AuthenticationTypeTYPE"/>
            <xs:element name="RegistrationCategory" type="core:RegistrationCategoryTYPE"/>
            <xs:element name="CredentialRole" type="core:CredentialRoleTYPE"/>
            <xs:element name="TSchemeLevel" type="core:TSchemeLevelTYPE"/>
            <xs:element name="AgentDetails" minOccurs="0">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="AgentID" type="core:AgentIDTYPE"/>
                  <xs:element name="AgentCode" type="core:AgentCodeTYPE"/>
                  <xs:element name="AgentFriendlyName" type="core:AgentFriendlyNameTYPE"/>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
            <xs:element name="CurrentGatewayAuthLevel" type="core:GatewayAuthLevelTYPE" minOccurs="0" maxOccurs="1"/>
            <xs:element name="AvailableAuthenticationTypes" minOccurs="0" maxOccurs="1">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="UserID" minOccurs="0">
                    <xs:complexType>
                      <xs:sequence>
                        <xs:element name="GatewayAuthLevel" type="core:GatewayAuthLevelTYPE"/>
                      </xs:sequence>
                    </xs:complexType>
                  </xs:element>
                  <xs:element name="Certificate" minOccurs="0">
                    <xs:complexType>
                      <xs:sequence minOccurs="1" maxOccurs="1">
                        <xs:element name="GatewayAuthLevels">
                          <xs:complexType>
                            <xs:sequence maxOccurs="unbounded">
                              <xs:element name="GatewayAuthLevel" type="core:GatewayAuthLevelTYPE"/>
                            </xs:sequence>
                          </xs:complexType>
                        </xs:element>
                      </xs:sequence>
                    </xs:complexType>
                  </xs:element>
                  <xs:element name="SecurityPhrase" minOccurs="0">
                    <xs:complexType>
                      <xs:sequence>
                        <xs:element name="GatewayAuthLevel" type="core:GatewayAuthLevelTYPE"/>
                        <xs:element name="SecurityPhraseQuestions" type="core:SecurityPhraseQuestionTYPE"/>
                      </xs:sequence>
                    </xs:complexType>
                  </xs:element>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
            <xs:element name="SecureMessaging">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="MessageBoxVisited" type="xs:boolean"/>
                  <xs:element name="TotalMessages" type="xs:int"/>
                  <xs:element name="TotalUnreadMessages" type="xs:int"/>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
          <xs:attribute name="RequestID" type="core:HashTokenTYPE" use="required"/>
        </xs:complexType>
      </xs:element>
    </xs:schema>

#### Method Details

Once a GatewayToken has been obtained, it is recommended this method is immediately used by the portal/application to get the caller's information, including their CredentialIdentifier.

The credential’s available authentication types (User ID/password, SecurityPhrase and Certificates) are listed. The credential can have multiple certificates and therefore multiple authentication levels. Note that if the credential has, for example, two level 2 certificates only one entry for level 2 will be shown.

SecurityPhrase lists the position of the 3 characters that a portal/application would prompt the user to enter to verify the credential's security phrase (associated with the User ID/password). These 3 positions are changed after every successful authentication (logon) or when the security phrase is changed or reset through the various SOAP Portal Interface methods.

Core information on the credential's secure message box is also available.

#### Method Steps

This method performs the following steps:

- Returns the relevant data about the caller's credential

#### Calling Credential

The credential calling the function must meet the following rules

Rule | Error
--- | ---
The Credential must present a 'Standard' GatewayToken | wsse:FailedAuthentication Presenting the incorrect token will produce the standard wsse:FailedAuthentication exception
The Credential's state must be: Active | 8005: The Credential has an invalid state for this action Each Credential has a number of states (e.g. Registered, Suspended), and specific methods require the Credential to be in a certain state. If the Credential is in the wrong state then this exception will be raised
The Credential must NOT be of the following type: Admin | 8006: The Credential type specified is invalid Specific methods can only be performed for certain types of Credential (e.g. Principal, Agent, Admin etc.), if the supplied Credential is of the wrong type for the method then this exception will be raised.

#### Business Rules

All errors will return a SOAP fault. The GatewayDetails node will include ErrorNumber. It also contains a Message node with a detailed description of the cause of the error. The following is a list of the Error Numbers that may be returned from this method, each one represents a business rule that has been broken:

SOAP Fault Error Number | Description
--- | ---
13006 | The Registration Profile does not exist The Registration Profile that has been supplied does not exist

#### Audit Events

Audit Events are stored in the Audit Database. These events are not available publicly. Please contact Live Services for more information

Audit ID | Description
--- | ---
506 | GsoAuthorisation (Failure)

#### Notifications

Notifications are messages that originate from the Gateway and sent to an external source.

Notification | Description
--- | ---

#### Example

The following is a sample of an input document:

    <?xml version="1.0" encoding="utf-8"?>
    <GsoGetUserDetailsXmlInput xmlns="urn:GSO-System-Services:external:1.67:GsoGetUserDetailsXmlInput">
        <IncludeGatewayAuthLevel>true</IncludeGatewayAuthLevel>
        <IncludeAvailableGatewayAuthLevels>true</IncludeAvailableGatewayAuthLevels>
    </GsoGetUserDetailsXmlInput>

The following is a sample of an output document:

    <?xml version="1.0" encoding="utf-8"?>
    <GsoGetUserDetailsXmlOutput xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" RequestID="9C6198E73EF14B0BA1ADE1DAC0530201" xmlns="urn:GSO-System-Services:external:1.67:GsoGetUserDetailsXmlOutput">
        <CredentialName>Test User</CredentialName>
        <CredentialIdentifier>0000001223179602</CredentialIdentifier>
        <Description/>
        <EmailAddress>user@hotmail.com</EmailAddress>
        <PasswordExpiryDateTime>2008-12-31T23:59:59.9999999-00:00</PasswordExpiryDateTime>
        <UserType>Principal</UserType>
        <AuthenticationType>Certificate</AuthenticationType>
        <RegistrationCategory>Individual</RegistrationCategory>
        <CredentialRole>User</CredentialRole>
        <TSchemaLevel>GoodAssurance</TSchemaLevel>
        <CurrentGatewayAuthLevel>2.00</CurrentGatewayAuthLevel>
        <AvailableAuthenticationTypes>
            <Certificate>
                <GatewayAuthLevels>
                    <GatewayAuthLevel>2.00</GatewayAuthLevel>
                    <GatewayAuthLevel>3.00</GatewayAuthLevel>
                </GatewayAuthLevels>
            </Certificate>
            <UserID>
                <GatewayAuthLevel>1.00</GatewayAuthLevel>
            </UserID>
            <SecurityPhrase>
                <SecurityPhraseQuestions>1,5,20</SecurityPhraseQuestions>
                <GatewayAuthLevel>1.50</GatewayAuthLevel>
            </SecurityPhrase>
        </AvailableAuthenticationTypes>
        <SecureMessaging>
            <MessageBoxVisited>false</MessageBoxVisited>
            <TotalMessages>10</TotalMessages>
            <TotalUnreadMessages>5</TotalUnreadMessages>
        </SecureMessaging>
    </GsoGetUserDetailsXmlOutput>

#### See Also

Public Interface

© Crown Copyright 2008. All rights reserved