Product Documentation

Obtaining a List of Applications for which Credentials are Stored - lookupRequest

Mar 24, 2011

Use the lookupRequest operation to obtain the list of applications for which a user has stored credentials. The value of the returnData attribute determines the level of detail returned.


<lookupRequest requestID='optional-client-generated-ID' 
returnData='identifier' executionMode='synchronous'> 
   <psoID ID='userFQDN'/> 


requestID (mandatory) This is the client-generated ID that associates the return values with this request.
returnData (mandatory)

data - details of a secondary credential

identifier - list of credentials for a user

name - not supported in Single Sign-on

everything - application definitions available to the specified user

executionMode (mandatory) Single Sign-on supports synchronous execution mode.
authentication-token (mandatory) The authentication-token element is mandatory, but is not used at this time.
psoID (mandatory) The psoID is a unique identifier for each end user; PSOID is the credential's GUID returned by the lookupResponse.

Syntax for Return Values - lookupResponse

<lookupResponse status='success' requestID='client-generated-ID'> 
   <psoID ID=ID='userFQDN'/> 
   <ctxs:user xmlns:ctxs=""> 
   <ctxs:credential ctxs:status="queued" ctxs:pendingAction="modify" 
      <ctxs:description>Aviva 5250 Demo</ctxs:description> 
      <ctxs:provision-description>Aviva 5250 
            <ctxs:name>Aviva 5250 Demo</ctxs:name> 
            <ctxs:group password-sharing='false'>AppGroup 
 <!-- Example of a return value for a credential  
      added by an end user in Manage Passwords --> 
      <ctxs:credential ctxs:status="active" 
         <ctxs:name>Dynamic App1</ctxs:name> 

Parameters for Return Values

status (mandatory) Possible values: Success, Failure, Pending
requestID (mandatory) This is the client-generated ID that associates these return values with the associated request.
pso (mandatory) The data of the pso is a credential as described in ctxs:credential.
psoID (mandatory) The psoID is a unique identifier for each end user; PSOID is the user's FQDN. According to Single Sign-on's SPML model, the data of the pso is a credential as described in ctxs:credential. This would be included if returnData attribute was set to data or everything. There is exactly one pso element for each secondary credential. The ID attribute of the psoID provides the credential's GUID.
data (mandatory) Data is the description of the data that was looked up. This is the credential element and may include any child elements of the credential and application elements.
ctxs:credential (mandatory) The credential element is used to describe a single secondary credential. The name and description children of the credential element are optional. If not provided, the plug-in uses the name and description from the application definition. See ctxs:credential for more information.
ctxs:application (mandatory) The application element is used both to describe an application definition and to describe details of a credential. The application element must correspond to one previously obtained from a lookupApplicationRequest operation. There is exactly one application element for each application definition in the user's user configuration. See ctxs:application for more information.


When a lookupRequest operation specifies a credential, the response contains the details of the credential. In general, the secrets of each credential are encrypted by the plug-in software and cannot be accessed by the Provisioning module. That means the character data of the specific field elements is empty for credentials already managed by the plug-in software.

Provisioning is a two-step process. First, the Provisioning Module queues provisioning commands. Next, the plug-in software executes the queued commands. To enable you to verify an action you have just performed, the credential list returned must account for the queued commands. Since the queued commands are protected by the Provisioning Module and not the plug-in software, the Provisioning Module is able to decrypt the command parameters. The credentials that have queued add or modify commands also have the accessible command parameters listed in the lookupResponse operation. Note that the command parameters may include the userID, password, and custom-field values.