Glossary Item Box

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

# GsoDelegateRights Method

This method creates a Delegated Rights Management (DRM) session that authorises an organisation internal user (employee) to act on specified organisation direct enrolments (and client allocations for an agent organisation).

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

#### Parameters

inputXml
  Input Xml for this method must have the namespace urn:GSO-System-Services:external:2.10:GsoDelegateRightsXmlInput
outputXml
  Output Xml for this method must have the namespace urn:GSO-System-Services:external:2.10:GsoDelegateRightsXmlOutput

#### Remarks

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

- RequestID: A random string (e.g. a GUID) – enhances security by ensuring the content of the GsoDelegateRightsXmlInput element is unique
- ExpiryTime: When the DRM session will expire for this user (maximum value 4 hours)
- UserDetails. The organisation internal user associated with the DRM session:
  - Name: User name
  - OrganisationUserID: Uniquely identifies the user session within organisation (e.g. paroll number)
  - Email: User email address
  - CredentialRole: User's role (can be either DelegatedUser or DelegatedAssistant)
- DirectEnrolments: Service and Identifiers for each DirectEnrolment
- ClientAllocations: Service and Identifiers for each ClientAllocation

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

- GatewayOneTimeToken: Special token used (once) with CAP to get a SAML assertion
- InvalidDirectEnrolments: Direct enrolments from the input that failed validation
- InvalidClientAllocations: Client allocations from the input that failed validation

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:2.10:GsoDelegateRightsXmlInput" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:GSO-System-Services:external:1.65:GsoCore" xmlns="urn:GSO-System-Services:external:2.10:GsoDelegateRightsXmlInput" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0">
      <xs:import namespace="urn:GSO-System-Services:external:1.65:GsoCore"/>
      <xs:element name="GsoDelegateRightsXmlInput">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="RequestID" type="core:DelegatedRightsRequestIDTYPE" />
            <xs:element name="ExpiryTime" type="xs:dateTime"/>
            <xs:element name="UserDetails">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="Name" type="core:DelegatedRightsNameTYPE" />
                  <xs:element name="OrganisationUserID" type="core:DelegatedRightsOrganisationUserIDTYPE" />
                  <xs:element name="Email" type="core:DelegatedRightsEmailTYPE" />
                  <xs:element name="CredentialRole" type="core:DelegatedCredentialRoleTYPE" />
                </xs:sequence>
              </xs:complexType>
            </xs:element>
            <xs:element name="DirectEnrolments" minOccurs="0">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="DirectEnrolment" type="DirectEnrolmentType" maxOccurs="unbounded" />
                </xs:sequence>
              </xs:complexType>
            </xs:element>
            <xs:element name="ClientAllocations" minOccurs="0">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="ClientAllocation" type="ClientAllocationType" maxOccurs="unbounded" />
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:complexType name="DirectEnrolmentType">
        <xs:sequence>
          <xs:element name="ServiceName" type="core:ServiceNameTYPE"/>
          <xs:element name="Identifiers">
            <xs:complexType>
              <xs:sequence>
                <xs:element name="Identifier" type="core:IdentifierTYPE" maxOccurs="unbounded"/>
              </xs:sequence>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="ClientAllocationType">
        <xs:sequence>
          <xs:element name="ServiceName" type="core:ServiceNameTYPE" />
          <xs:element name="Identifiers">
            <xs:complexType>
              <xs:sequence>
                <xs:element name="Identifier" type="core:IdentifierTYPE" maxOccurs="unbounded" />
              </xs:sequence>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </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:2.10:GsoDelegateRightsXmlOutput" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:core="urn:GSO-System-Services:external:1.65:GsoCore" xmlns="urn:GSO-System-Services:external:2.10:GsoDelegateRightsXmlOutput" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0">
      <xs:import namespace="urn:GSO-System-Services:external:1.65:GsoCore"/>
      <xs:element name="GsoDelegateRightsXmlOutput">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="GatewayOneTimeToken" type="core:GatewayOneTimeTokenTYPE" />
            <xs:element name="InvalidDirectEnrolments" minOccurs="0">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="DirectEnrolment" maxOccurs="unbounded" type="DirectEnrolmentTYPE" />
                </xs:sequence>
              </xs:complexType>
            </xs:element>
            <xs:element name="InvalidClientAllocations" minOccurs="0">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="ClientAllocation" maxOccurs="unbounded" type="ClientAllocationTYPE" />
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
          <xs:attribute name="RequestID" type="core:HashTokenTYPE" use="required"/>
        </xs:complexType>
      </xs:element>
      <xs:complexType name="DirectEnrolmentTYPE">
        <xs:sequence>
          <xs:element name="ServiceName" type="core:ServiceNameTYPE"/>
          <xs:element name="Identifiers">
            <xs:complexType>
              <xs:sequence>
                <xs:element name="Identifier" type="core:IdentifierTYPE" maxOccurs="unbounded"/>
              </xs:sequence>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="ClientAllocationTYPE">
        <xs:sequence>
          <xs:element name="ServiceName" type="core:ServiceNameTYPE" />
          <xs:element name="Identifiers">
            <xs:complexType>
              <xs:sequence>
                <xs:element name="Identifier" type="core:IdentifierTYPE" maxOccurs="unbounded" />
              </xs:sequence>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </xs:schema>

#### Method Details

Enabling an organisation/agent to use its existing (i.e. corporate) users – managed by the organisation's IT systems – to act on direct enrolments (and client allocations for an agent organisation), removes the need for the organisation to create/maintain a parallel set of Gateway Users and Assistants.

UserDetails for the employee are stored by Gateway. These details are incorporated into the SAML Assertion token that the calling application subsequently creates. This information can also be retrieved through GsoGetUserDetails.

DirectEnrolments are the enrolments that the organisation employee can act on (within the session). These direct enrolments must be a subset of the direct enrolments specified through the Gateway UI for the DRM organisation account. Any direct enrolments that are invalid will be returned in InvalidDirectEnrolments.

ClientAllocations are the enrolments that the organisation employee can act on (within the session). Client allocations are only relevant to an agent organisation (i.e. an intermediary) – they are enrolments allocated by individuals (i.e. citizens) or principal organisations to the agent. Any client allocations that the agent organisation does not have the right to act on will be returned in InvalidClientAllocations. This right to act for a client is determined by the (DRM specific) Agent Authentication level configured for the service on Gateway:

- Level 0: Agent enrolled in service, Client enrolled in service and Enrolment allocated by client to agent
- Level 1: Agent enrolled in service and client enrolled in service
- Level 2: Agent enrolled in service, client known facts must exist in service
- Level 3: Agent enrolled in Service (client known facts not checked)

Provided there are some valid enrolments a GatewayOneTimeToken will be returned. This token can then be used (once) to issue a SSO DRM session sign-in to Gateway. The Gateway CAP redirect the corporate user associated with the session to the required Portal – the Portal must support SSO – where they can then interact through a browser session with the Portal and act on the enrolments assigned to them.

Note:

- For an application (or organisation's IT systems) within an principal or agent organisation to be able to successfully call this method a "Delegated Rights Management (DRM) User account" must have been set up through the Gateway UI by a normal Gateway User.
- If this method is subsequently called (with the same DRM User credential) for the same OrganisationUserID the original session is replaced (if it has not expired).

#### Method Steps

This method performs the following steps:

- Checks the callers credential is correct - must be a Delegator
- Checks the number of blocks supplied for DirectEnrolments and ClientAllocations do not exceed the configured limit
- Any invalid DirectEnrolment or ClientAllocations are returned in the corresponding InvalidDirectEnrolments and InvalidClientEnrolments elements
- If there are any valid DirectEnrolment or ClientAllocations returns a GatewayOneTimeToken.

#### Calling Credential

The credential calling the function must meet the following rules

Rule | Error
--- | ---
The Credential must present a UsernameToken (follow this link - the construction of this token is different to elseware in Gateway) or a X509SecurityToken. Note: The construction of the UsernameToken is different for this interface. | wsse:FailedAuthentication Presenting the incorrect token will produce the standard wsse:FailedAuthentication exception
The Credential must be the member of a Group | 8029: The Credential is not a member of an Organisation If the credential's registration category allows either peers or assistants then they are deemed to belong to an Organisation. This exception is raised when a Credential who does not belong to an Organisation attempts to call a method that controls Organisation specific functionality.
The Credential must be in the following roles: Delegator | 8026: The credential has the wrong type of role The credential has the wrong type of role to be used with this function. e.g. The credential is an assistant where a peer is required.

#### 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
--- | ---
8002 | [CredentialType] credentials are denied access Specific methods may not be called by certain types of Credential (e.g. Admin), if the supplied Credential is of the wrong type for the method then this exception will be raised.
8034 | [CredentialType] credentials are denied access Specific methods may not be called by certain types of Credential (e.g. Admin), if the supplied Credential is of the wrong type for the method then this exception will be raised.
23001 | The supplied number of DirectEnrolment blocks exceeds the configured maximum Too many Direct Enrolments have been supplied by the method.
23002 | The supplied number of ClientAllocation blocks exceeds the configured maximum Too many Client Allocations have been supplied by the method.
23003 | No DRM matches found No enrolments could be assigned to the DRM session. All the supplied direct/client enrolments failed validation.
23005 | The supplied expiry time exceeds the configured maximum Currently the limit is set to 4 hour.
23006 | Non existing service(s) in delegation request [ServiceName] One (or more) of the services supplied is not a valid service.
23009 | No DRM enrolmnents specified No enrolments were provided.

#### 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
--- | ---
627 | Delegate Rights (Success)
628 | Delegate Rights ( (Failure)
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"?>
    <GsoDelegateRightsXmlInput xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:GSO-System-Services:external:2.10:GsoDelegateRightsXmlInput">
      <RequestID>0246DF5AC0984ADEAD6807F7A3797BA7</RequestID>
      <ExpiryTime>2007-10-14T12:15:01Z</ExpiryTime>
      <UserDetails>
        <Name>Agent User</Name>
        <OrganisationUserID>AgentUserPayrollNo</OrganisationUserID>
        <Email>agent.user@agentorg.co.uk</Email>
        <CredentialRole>DelegatedUser</CredentialRole>
      </UserDetails>
      <DirectEnrolments>
        <DirectEnrolment>
          <ServiceName>MOSW11AGENT</ServiceName>
          <Identifiers>
            <Identifier IdentifierType="MOSW11AGENTID">aa11aa</Identifier>
          </Identifiers>
        </DirectEnrolment>
      </DirectEnrolments>
      <ClientAllocations>
        <ClientAllocation>
          <ServiceName>MOSW11</ServiceName>
          <Identifiers>
            <Identifier IdentifierType="MOSW11ID">bb11bb</Identifier>
          </Identifiers>
        </ClientAllocation>
        <ClientAllocation>
        <ServiceName>MOSW11</ServiceName>
        <Identifiers>
          <Identifier IdentifierType="MOSW11ID">cc11cc</Identifier>
        </Identifiers>
        </ClientAllocation>
        <ClientAllocation>
        <ServiceName>MOSW11</ServiceName>
        <Identifiers>
          <Identifier IdentifierType="MOSW11ID">dd11dd</Identifier>
        </Identifiers>
        </ClientAllocation>
      </ClientAllocations>
    </GsoDelegateRightsXmlInput>

The following is a sample of an output document:

    <?xml version="1.0" encoding="utf-8"?>
    <GsoDelegateRightsXmlOutput xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" RequestID="261D16719D3040807A8993BD05289A6C" xmlns="urn:GSO-System-Services:external:2.10:GsoDelegateRightsXmlOutput">
      <GatewayOneTimeToken>dnsfweyt4876irehgy4248fk3</GatewayOneTimeToken>
      <InvalidClientAllocations>
        <ClientAllocation>
          <ServiceName>MOSW11</ServiceName>
          <Identifiers>
            <Identifier IdentifierType="MOSW11ID">dd11dd</Identifier>
          </Identifiers>
        </ClientAllocation>
      </InvalidClientAllocations>
    </GsoDelegateRightsXmlOutput>

#### See Also

DelegatedRights Interface

© Crown Copyright 2008. All rights reserved