Interacting with the Identity Service API
The Identity Service exposes the operations shown in the following table. You can use SOAP-UI or similar tool (such as the Eclipse's Web Services Explorer) to interact with the Identity Service.
Operation | Description |
|---|
findRoles | Returns a list of role/group names. |
findRolesByPrincipal | Returns a list of role/group names for a principal name. |
findIdentitiesByRole | Returns a list of identities associated with role. |
findIdentities | Returns a list of identities given an identity search query. |
assertPrincipalInQueryResult | Asserts that the a principal is in the resultant identity query. This faults if the principal is not in the result. |
assertPrincipalInQueryResultWithResponse | Asserts that a principal is in the resultant identity query and returns the result. This faults if the principal is not in the result. |
countIdentities | Returns the total number of identities found in the result after evaluating one or more identity search queries. |
findRoles
This operation returns a list of roles available to the Identity Service. A sample findRoles SOAP request is similar to:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:iden="http://docs.active-endpoints/wsdl/identity/2007/
03/identity.wsdl">
<soapenv:Header/>
<soapenv:Body>
<iden:emptyElement/>
</soapenv:Body>
</soapenv:Envelope>
The response contains one or more role names, as is shown in the following sample:
findRolesByPrincipal
This operation returns a list of roles (groups) that a principal belongs to. Here is an example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:iden="http://docs.active-endpoints/wsdl/identity/
2007/03/identity.wsdl">
<soapenv:Header/>
<soapenv:Body>
<iden:principalName>loanrep1</iden:principalName>
</soapenv:Body>
</soapenv:Envelope>
Here is a findRolesByPrincipal() response:
findIdentitiesByRole
The findIdentitiesByRole() operation return a list of identities associated with a role. Here is an example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:iden="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl">
<soapenv:Header/>
<soapenv:Body>
<iden:roleName>loanreps</iden:roleName>
</soapenv:Body>
</soapenv:Envelope>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<aeidsvc:identityList
xmlns:aeidsvc="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl">
<aeid:identity
xmlns:aeid="http://schemas.active-endpoints.com/identity/2007/01/identity.xsd">
<aeid:id>CN=John Smith,CN=Users,DC=example,DC=com</aeid:id>
<aeid:properties>
<aeid:property
name="http://www.activebpel.org/ontologies/higgins/2008/
identity-search.owl#firstName">John</aeid:property>
<aeid:property
name="http://www.activebpel.org/ontologies/higgins/2008/
identity-search.owl#lastName">Smith</aeid:property>
<aeid:property
name="http://www.activebpel.org/ontologies/higgins/2008/
identity-search.owl#email">john.smith@example.com</aeid:property>
<aeid:property
name="http://www.activebpel.org/ontologies/higgins/2008/
identity-search.owl#userName">jsmith</aeid:property>
</aeid:properties>
<aeid:roles>
<aeid:role>loanreps</aeid:role>
<!-- Additional 'aeid:role' elements -->
</aeid:roles>
</aeid:identity>
<!-- Additional 'aeid:identity' elements -->
</aeidsvc:identityList >
</soapenv:Body>
</soapenv:Envelope>
Notice the <aeid:identity> element in the result set. Within this element, the <aeid:id> represents the distinguished name (DN) for an LDAP based identity service providers. The <aeid:identity> also has one or more<aeid:property>elements, representing the identity service user model attributes.
For example, in the following figure, the LDAP (Active Directory) givenName attribute is mapped to firstName (in the ActiveVOS domain). This means, the LDAP givenName attribute is available using the http://www.activebpel.org/ontologies/higgins/2008/identity-search.owl#firstName property name.
To extract the email address from the result (say assigned to variable $identityList), use the following expression:
$identityList/aeid:identity/aeid:properties/aeid:property
[@name='http://www.activebpel.org/ontologies/higgins/2008/
identity-search.owl#email']/text()
findIdentities
This operation returns a list of identities based on an identity query. An identity query (<iden:identityQuery>) has include and exclude elements. The roles or principals listed within the include element are included in the result set while the ones listed within the exclude element are excluded.
Here is a sample request that constructs a query that fetches all loanreps members except for loanrep2 and also includes user loancsr:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:iden="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl">
<soapenv:Header/>
<soapenv:Body>
<iden:identityQuery>
<iden:include>
<iden:group>loanreps</iden:group>
<iden:user>loancsr</iden:user>
</iden:include>
<!-- Additional iden:include elements. -->
<iden:exclude>
<iden:user>loanrep2</iden:user>
</iden:exclude>
<!-- Additional iden:exclude elements. -->
</iden:identityQuery>
</soapenv:Body>
</soapenv:Envelope>
The response contains zero or more <aeid:identity> elements.:
assertPrincipalInQueryResult
The assertPrincipalInQueryResult operation checks to see if the a principal exists for an identity query. Restated, it checks if the principal exists in the result set of the evaluating the identity query. This operation faults if the principal is not in the result set.
Here is a sample request to check if user user1 is a member of either the loanreps or loanmgrs groups:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:iden="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl">
<soapenv:Header/>
<soapenv:Body>
<iden:principalQueryAssertion>
<iden:principalName>user1</iden:principalName>
<iden:identityQuery>
<iden:include>
<iden:group>loanreps</iden:group>
<iden:group>loanmgrs</iden:group>
</iden:include>
</iden:identityQuery>
<!-- Additional iden:identityQuery elements. -->
<iden:principalQueryAssertion>
</soapenv:Body>
</soapenv:Envelope>
If assertPrincipalInQueryResult() operation faults, the response is similar to:
assertPrincipalInQueryResultWithResponse
This is similar to the previous operation; that is, it asserts that a principal is returned as part of one of the identity queries. All of the identity queries are evaluated and the response indicates which results contained the principal.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:iden="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl">
<soapenv:Header/>
<soapenv:Body>
<iden:principalQueryAssertionWithResponse>
<iden:principalName>user1</iden:principalName>
<iden:identityQuery>
<iden:include>
<iden:group>loanreps</iden:group>
<iden:group>loanmgrs</iden:group>
</iden:include>
</iden:identityQuery>
<!-- Additional iden:identityQuery elements. -->
<iden:principalQueryAssertionWithResponse>
</soapenv:Body>
</soapenv:Envelope>
The response contains a 1-based index to the first identity query that contained the principal. For example, if the request element (<iden:principalQueryAssertionWithResponse>) has three identity queries (<iden:identityQuery> elements), and the principal was found in the second, the response looks similar to:
countIdentities
This operation returns the total number of identities matched after evaluating all of the identity queries. Here is a sample request and response:
