The Identities Service exposes resources to retrieve identity information. The service allows a user to retrieve lists of identities or access specific identities by filter expression or identity ID.
There are several types of resources available for the 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
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
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 19-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 supported PUT – Not supported DELETE – 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 supported PUT – Not supported DELETE – Not supported If 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 supported PUT – Not supported DELETE – Not supported If 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 supported PUT – Not supported DELETE – Not supported Note: application/json will be returned for all attributes except for the attribute types of binary which an “image/gif” content type will be returned. |
|
identities/{GUID} |
GET - Retrieves a user by GUID. |
|
identities/{Fully qualified DN} |
GET - Retrieves a user by fully qualified DN. Example: /v1/identities/cn=ablake,ou=users,ou=idmsample,o=netiq |
|
identities/{GUID}/{ATTRIBUTE} |
GET - Retrieves a specific attribute for a user by GUID. |
|
identities/{Fully qualified DN}/{ATTRIBUTE} |
GET - Retrieves a specific attribute for a user by fully qualified DN. |
Table 19-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. |
This section shows the JSON structures received by the client for each resource. In each case, the HTTP method is GET.
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=netiq",
"GUID": "1b9d83fa6f03b64e5bba1b9d83fa6f03",
"Link": "/RIS/v1/identities/1b9d83fa6f03b64e5bba1b9d83fa6f03",
"Value": "Margo MacKenzie"
}],
"DirectReports": [{}],
"Groups": [{
"DN": "cn=HR,ou=groups,ou=medical-idmsample,o=netiq",
"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%3Dnetiq"
},
{
"Type": "roles",
"Value": "Roles",
"Link": "/RIS/v1/roles?filter=User%3Dcn%3Dablake%2Cou%3Dusers%2Cou%3Dmedical-idmsample%2Co%3Dnetiq"
}
],
DN": "cn=ablake,ou=users,ou=medical-idmsample,o=netiq",
"GUID": "26b65d8611075849e2b226b65d861107",
"Link": "/RIS/v1/identities/26b65d8611075849e2b226b65d861107",
"FirstName": "Allison",
"LastName": "Blake",
"Title": "Payroll",
"Department": "HR",
"Location": "Northeast",
"Email": "mthibault@netiq.com",
"TelephoneNumber": "(555) 555-1222",
"City": "",
"Country": "",
"PostalCode": "",
"State": "",
"Street": ""
},
…. More identities
]
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=netiq",
"GUID": "1b9d83fa6f03b64e5bba1b9d83fa6f03",
"Link": "/RIS/v1/identities/1b9d83fa6f03b64e5bba1b9d83fa6f03",
"Value": "Margo MacKenzie"
}],
"DirectReports": [{}],
"Groups": [{
"DN": "cn=HR,ou=groups,ou=medical-idmsample,o=netiq",
"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%3Dnetiq"
},
{
"Type": "roles",
"Value": "Roles",
"Link": "/RIS/v1/roles?filter=User%3Dcn%3Dablake%2Cou%3Dusers%2Cou%3Dmedical-idmsample%2Co%3Dnetiq"
}
],
DN": "cn=ablake,ou=users,ou=medical-idmsample,o=netiq",
"GUID": "26b65d8611075849e2b226b65d861107",
"Link": "/RIS/v1/identities/26b65d8611075849e2b226b65d861107",
"FirstName": "Allison",
"LastName": "Blake",
"Title": "Payroll",
"Department": "HR",
"Location": "Northeast",
"Email": "mthibault@netiq.com",
"TelephoneNumber": "(555) 555-1222",
"City": "",
"Country": "",
"PostalCode": "",
"State": "",
"Street": ""
}
The identities/{Identity Id} endpoint returns a specific identity attribute.
{
DN": "cn=ablake,ou=users,ou=medical-idmsample,o=netiq",
"GUID": "26b65d8611075849e2b226b65d861107",
"Link": "/RIS/v1/identities/26b65d8611075849e2b226b65d861107",
"FirstName": "Allison"
}
This section shows the event status codes for the available resources:
Table 19-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.