26.2 Accessing and Using the Identities Service

The Identities Service exposes resources to retrieve identity information. The service allows a user is able to retrieve lists of identities or access specific identities by filter expression or identity ID.

26.2.1 Available Resources

There are several types of resources available for the service. These resources are described in the sections that follow:

Identities Service

The service provides a resource URI for every object exposed. The Identities resource supports two basic URI patterns:

  • Resource for returning a collection of identities

  • Resource for returning a specific identity instance

Services for Filtering, Debugging, and Displaying Schema Information

The service supports the following paramters to allow you to perform operations on the primary identities data set:

  • A filter parameter to enable the filtering of result sets

  • A debug matrix parameter to enable you to return the JSON structures in a human readable format

  • A schema matrix parameter to enable you to return the schema for the data set

26.2.2 Complete URI Syntax

The following table shows the complete URI syntax for all resource end points associated with the Identities Service, along with a description for each URI and a list of supported HTTP methods:

Table 26-1 Resource URIs

URI

Description

/v1

Entry point for the service.

/vi/identities

Will return a list of identities with minimum information and a list of identity URI links that include the identity GUID. The VDX services will be used to provide identity information. This information will be based on how the DAL user entity is defined. All attributes defined by the DAL entry will be made available to the identity JSON payload.

The following HTTP methods are supported with this URI:

GET - This will return a collection of identies (JSON Array).POST – Not supportedPUT – Not supportedDELETE – Not supported

identities?filter={identity filter}

GET - The Identity ID parameter will be a GUID to identify a specific identity within the LDAP realm. The payload will include links to the identity's roles, resources, and work items. The VDX services will be used to provide identity information. This information will be based on how the DAL user entity is defined. All attributes defined by the DAL entry will be made available to the identity JSON payload. POST – Not supportedPUT – Not supportedDELETE – Not supportedIf the “Accept” header is “image/gif”, then the identity photo will be returned.

identities/{Identity Id}

GET - The Identity ID parameter will be a GUID to identify a specific identity within the LDAP realm. The payload will include links to the identity's roles, resources, and work items. The VDX services will be used to provide identity information. This information will be based on how the DAL user entity is defined. All attributes defined by the DAL entry will be made available to the identity JSON payload. In the case of image type data, this might be just a link to this information (still needs to be flushed out)POST – Not supportedPUT – Not supportedDELETE – Not supportedIf the “Accept” header is “image/gif”, then the identity photo will be returned.

identities/{Identity Id}/{attribute ID}

GET -A specific attribute for a specific identity ID.POST – Not supportedPUT – Not supportedDELETE – Not supportedNote: application/json will be returned for all attributes except for the attribute types of binary which an “image/gif” content type will be returned.

Table 26-2 Matrix Parameters for Debugging and Displaying the Schema

URI

Description

identities;debug

This debug matrix parameter displays the identities JSON structure in human readable format, as opposed to compressed format. This matrix parameter can be put anywhere in the URI.

identities;schema

The schema matrix parameter can be put anywhere in the URI and in combination with the “Accept” header type will return the appropriate schema document for the content type. In this case a JSON schema document is returned for the workitems.

26.2.3 JSON Representations Received by the Client

This section shows the JSON structures received by the client for each resource. In each case, the HTTP method is GET.

Identities Endpoint

The identities end point (/identities) returns a collection (JSON Array) of identities available to the Directory Abstraction Layer (DAL).

[
{
   "Managers": [{
      "DN": "cn=mmackenzie,ou=users,ou=medical-idmsample,o=novell",
      "GUID": "1b9d83fa6f03b64e5bba1b9d83fa6f03",
      "Link": "/RIS/v1/identities/1b9d83fa6f03b64e5bba1b9d83fa6f03",
      "Value": "Margo MacKenzie"
   }],
   "DirectReports": [{}],
   "Groups": [{
      "DN": "cn=HR,ou=groups,ou=medical-idmsample,o=novell",
      "GUID": "7f7f381d9cc3ad4694967f7f381d9cc3",
      "Link": "",
      "Value": "Human Resources"
   }],
   "Links": [
      {
         "Type": "wf/workitems",
         "Value": "Workitems",
         "Link": "/RIS/v1/wf/workitems?filter=Addressee%3Dcn%3Dablake%2Cou%3Dusers%2Cou%3Dmedical-idmsample%2Co%3Dnovell"
      },
      {
         "Type": "roles",
         "Value": "Roles",
         "Link": "/RIS/v1/roles?filter=User%3Dcn%3Dablake%2Cou%3Dusers%2Cou%3Dmedical-idmsample%2Co%3Dnovell"
      }
   ],
   DN": "cn=ablake,ou=users,ou=medical-idmsample,o=novell",
   "GUID": "26b65d8611075849e2b226b65d861107",
   "Link": "/RIS/v1/identities/26b65d8611075849e2b226b65d861107",
   "FirstName": "Allison",
   "LastName": "Blake",
   "Title": "Payroll",
   "Department": "HR",
   "Location": "Northeast",
   "Email": "mthibault@novell.com",
   "TelephoneNumber": "(555) 555-1222",
   "City": "",
   "Country": "",
   "PostalCode": "",
   "State": "",
   "Street": ""
},
…. More identities
]

Identities/{Identity Id} Endpoint

The identities/{Identity Id} endpoint returns specific identity information from the Directory Abstraction Layer This information will be based on how the DAL user entity is defined. All attributes defined by the DAL entry are made available to the identity JSON payload.

{
   "Managers": [{
      "DN": "cn=mmackenzie,ou=users,ou=medical-idmsample,o=novell",
      "GUID": "1b9d83fa6f03b64e5bba1b9d83fa6f03",
      "Link": "/RIS/v1/identities/1b9d83fa6f03b64e5bba1b9d83fa6f03",
      "Value": "Margo MacKenzie"
   }],
   "DirectReports": [{}],
   "Groups": [{
      "DN": "cn=HR,ou=groups,ou=medical-idmsample,o=novell",
      "GUID": "7f7f381d9cc3ad4694967f7f381d9cc3",
      "Link": "",
      "Value": "Human Resources"
   }],
   "Links": [
      {
         "Type": "wf/workitems",
         "Value": "Workitems",
         "Link": "/RIS/v1/wf/workitems?filter=Addressee%3Dcn%3Dablake%2Cou%3Dusers%2Cou%3Dmedical-idmsample%2Co%3Dnovell"
      },
      {
         "Type": "roles",
         "Value": "Roles",
         "Link": "/RIS/v1/roles?filter=User%3Dcn%3Dablake%2Cou%3Dusers%2Cou%3Dmedical-idmsample%2Co%3Dnovell"
      }
   ],
   DN": "cn=ablake,ou=users,ou=medical-idmsample,o=novell",
   "GUID": "26b65d8611075849e2b226b65d861107",
   "Link": "/RIS/v1/identities/26b65d8611075849e2b226b65d861107",
   "FirstName": "Allison",
   "LastName": "Blake",
   "Title": "Payroll",
   "Department": "HR",
   "Location": "Northeast",
   "Email": "mthibault@novell.com",
   "TelephoneNumber": "(555) 555-1222",
   "City": "",
   "Country": "",
   "PostalCode": "",
   "State": "",
   "Street": ""
}

identities/{Identity Id}/{attribute ID} Endpoint

The identities/{Identity Id} endpoint returns a specific identity attribute.

{
   DN": "cn=ablake,ou=users,ou=medical-idmsample,o=novell",
   "GUID": "26b65d8611075849e2b226b65d861107",
   "Link": "/RIS/v1/identities/26b65d8611075849e2b226b65d861107",
   "FirstName": "Allison"
}

26.2.4 Event Status Codes

This section shows the event status codes for the available resources:

Table 26-3 Event Status Codes

URI

Status codes

identities

HTTP GET - Status 200 - OK

identities?filter={identity filter}

HTTP GET - Status 200 - OK

identities/{Identity Id}

HTTP GET - Status 200 - OK

identities/{Identity Id}/{attribute ID}

HTTP GET - Status 200 - OK

The Jersey implemented error conditions are used. When server errors are found, Jersey returns the appropriate 400 and 500 level codes.