ActiveVOS Identity Service API

ActiveVOS server provides an identity service to enable processes to look up users and groups in an enterprise directory service. This document describes the identity service API and includes a few examples on using the API via SOAP and indirectly via Java code using JAX-WS (ActiveVOS IdentityService4J api).

1. Package Contents
2. Identity Service Endpoints
3. Setup
4. Interacting With Identity Service API
5. Using JAX-WS Based ActiveVOS IdentityService4J API
   1. Building IdentityService4J
   2. IdentityService4J Samples
   3. Listing Role Names Using IdentityService4J API

Package Contents

The Identity Service API using JAX-WS (IdentityService4J) and samples code project contains the following artifacts:

Identity Service Endpoints

The following table shows the Identity Service related web service endpoints. Note, you should change the hostname (e.g. localhost) to reflect the actual host name where the service is being hosted.

Setup

The ActiveVOS Identity Service is normally available only to processes executing inside the ActiveVOS server via the identity service invoke handler.

In order to access the service operations from outside a process, the internal service operations must be exposed to an endpoint. To do this, the ActiveVOS system process aeidentitysvc must be deployed to the server.

1. From ActiveVOS Administration Console, click on the Deploy button located on the top right.
2. Browse and select the bpr located at /orchestration/IdentityService/aeidentitysvc.bpr. This bpr contains the aeidentitysvc process.

Note: if your server was configured for secured access, then you will need to provide credentials for the abIdentityListConsumer role per <security-constraint> definition in the active-bpel.war web.xml:

<security-constraint>
   <web-resource-collection>
   <web-resource-name>Identity List Consumer</web-resource-name>
   <description>Endpoint that exposes an operation on the identity service.</description>
   <url-pattern>/services/AeIdentityService</url-pattern>
   <http-method>POST</http-method>
   <http-method>PUT</http-method>
   <http-method>DELETE</http-method>
   </web-resource-collection>  
   <!--IDENTITYLISTCONSUMER Uncomment to restrict access to the task client services
   <auth-constraint>
      <role-name>abIdentityListConsumer</role-name>
   </auth-constraint>
   IDENTITYLISTCONSUMER-->
</security-constraint>

Interacting With Identity Service API

The identity service exposes the operations shown in the table below. You can use SOAP-UI or similar tool (such as the Eclipse's Web Services Explorer) to interact with the Identity Service.

findRoles

This operation returns list of roles available to the Identity Service. A sample findRoles SOAP request looks 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>

Response contains one or more role names as shown in the following sample:

<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:roleList xmlns:aeidsvc="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl">
         <aeidsvc:role>loanreps</aeidsvc:role>
         <aeidsvc:role>loanmgrs</aeidsvc:role>
         <aeidsvc:role>loancsr</aeidsvc:role>
      </aeidsvc:roleList>
   </soapenv:Body>
</soapenv:Envelope>

findRolesByPrincipal

This operation returns a list of roles (groups) the given principal belongs to. Sample request looks 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:principalName>loanrep1</iden:principalName>  
      </soapenv:Body>
</soapenv:Envelope>

Sample findRolesByPrincipal() response:

<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:roleList 
         xmlns:aeidsvc="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl">
         <!-- one or more roles -->
         <aeidsvc:role>loanreps</aeidsvc:role>
      </aeidsvc:roleList>
   </soapenv:Body>
</soapenv:Envelope>

findIdentitiesByRole

The findIdentitiesByRole() operation return a list of identities given a role name. A sample request and response is shown below:

<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 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 screenshot shown below, the LDAP (Active Directory) givenName attribute is mapped to firstName (in the ActiveVOS domain). This means, the LDAP givenName attribute is available via 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 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 given an identity query. An identity query (<iden:identityQuery>) is comprised of include and exclude statements. The roles or principals listed under the include element will be included in the result set while the ones listed under the excluded element will be excluded.

Sample request to construct query that fetches all loanreps members but loanrep2 and also include 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>

Sample contains zero or more <aeid:identity> elements.:

<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>
      <aeid:identityResultSet xmlns:aeid="http://schemas.active-endpoints.com/identity/2007/01/identity.xsd">
         <aeid:totalRowCount>3</aeid:totalRowCount>
         <aeid:completeRowCount>true</aeid:completeRowCount>
         <aeid:identities>
            <aeid:identity>
               <!-- aeid:identity child elements -->
            </aeid:identity>
            <!-- Additional aeid:identity elements -->
         </aeid:identities>
      </aeid:identityResultSet   
   </soapenv:Body>
</soapenv:Envelope>

assertPrincipalInQueryResult

The assertPrincipalInQueryResult operation checks to see if the given principal exists for an identity query. That is, the principal exists in the result of evaluating the identity query. This operation faults if the principal is not in the result set.

Sample request to check if user user1 is a member of either loanreps or loanmgrs group:

<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 the assertPrincipalInQueryResult() operation faults, the response looks similar to:

<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>   
      <Fault xmlns="http://schemas.xmlsoap.org/soap/envelope/">
         <faultcode xmlns:ns1="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl" xmlns="">ns1:searchFault</faultcode>
         <faultstring xmlns=""/>
         <faultactor xmlns=""/>
         <detail xmlns="">
            <aeidsvc:identityFault xmlns:aeidsvc="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl">
               <aeidsvc:code>10</aeidsvc:code>
               <aeidsvc:message>Principal user1 was not found in query.</aeidsvc:message>
            </aeidsvc:identityFault>
         </detail>
      </Fault>   
   </soapenv:Body>
</soapenv:Envelope>

assertPrincipalInQueryResultWithResponse

This is similar to the previous operation, that is, asserts that the given principal is returned as part of one of the identity queries passed in. All of the identity queries passed in will be evaluated and the response will indicate 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 the 1-based index to the first identity query that contained the principal. For example, if the request element (<iden:principalQueryAssertionWithResponse>) has 3 identity queries (<iden:identityQuery> elements), and the principal was found in the 2nd query, then the response looks similar to:

<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:assertionQueryResponse 
            xmlns:aeidsvc="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl">2</aeidsvc:assertionQueryResponse>         
   </soapenv:Body>
</soapenv:Envelope>

countIdentities

This is a simple operation that returns the total number of identities matched after evaluating all of the identity queries that were passed. A sample request and response is shown below:

<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: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>

<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>
      <aeid:identitiesCount 
         xmlns:aeid="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl">6</aeid:identitiesCount>
   </soapenv:Body>
</soapenv:Envelope>

Using JAX-WS Based ActiveVOS IdentityService4J API

The ActiveVOS IdentityService4J API is a client based on JAX-WS (version 2.1.5). To use the client api, include the avos-identityservice4j.jar along with the dependent libraries (for JAX-WS) in your classpath. The JAX-WS dependent jars are:

Building IdentityService4J

You can build the api using the provided ant build script. The built avos-identityservice4j.jar is copied to the dist/ directory. JDK 1.5 or later is required to build this project.

IdentityService4J Samples

Samples using the IdentityService4J API can be found under the /src-examples/ source tree.

Listing Role Names Using IdentityService4J API

The following sample snippet shows how to list roles via identity service using the IdentityService4J api. Please see the com.activevos.examples.identityservice.FindAllRolesDemo class for the complete example.

import com.activevos.api.identityservice.AeIdentityService;
import com.activevos.api.identityservice.IdentitySearchPortType;
import com.activevos.api.identityservice.SearchFault;
import com.activevos.api.identityservice.wsdl.EmptyElement;
import com.activevos.api.identityservice.wsdl.TRoleList;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.List;
import javax.xml.namespace.QName;

/** Identity Service endpoint WSDL  */
String ID_SERVICE_WSDL = "http://localhost:8080/active-bpel/services/AeIdentityService?wsdl";
/** Identity Service endpoint QName  */
QName  ID_SERVICE_QNAME = new QName("http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl", "AeIdentityService");

try 
{
   // Create service using WSDL location and service qname.
   AeIdentityService idService = new AeIdentityService(new URL(ID_SERVICE_WSDL), ID_SERVICE_QNAME);
   // Get service port to invoke operations.
   IdentitySearchPortType idServicePort = idService.getAeIdentityServicePort();
   
   // Invoke findRoles() operation.
   TRoleList roleList = idServicePort.findRoles(new EmptyElement() );
   List roleNames =  roleList.getRole();
   System.out.println("Found role count: " + roleNames.size());
   for (String roleName : roleNames) 
   {
      System.out.println("Role name: " + roleName);
   }
}
catch(MalformedURLException mue)
{
   // Invalid service url format
   mue.printStackTrace();
}
catch(SearchFault searchFault)
{
   // identity service related fault.
   System.out.println("Fault Message: " + searchFault.getMessage());
   if (searchFault.getFaultInfo() != null) 
   {
      // Fault details.
      System.out.println("FaultInfo Code: " + searchFault.getFaultInfo().getCode());
      System.out.println("FaultInfo Message: " + searchFault.getFaultInfo().getMessage());
   }
   searchFault.printStackTrace();
}
catch(Exception e) 
{
   e.printStackTrace();
}

Listing Identities Using IdentityService4J API

This sample snippet illustrates on the use of findIdentitiesByRole() operation using API. Please see the com.activevos.examples.identityservice.FindIdentitiesByRoleDemo class for the complete example.

import com.activevos.api.identityservice.AeIdentityService;
import com.activevos.api.identityservice.IdentitySearchPortType;
import com.activevos.api.identityservice.SearchFault;
import com.activevos.api.identityservice.wsdl.TIdentityList;
import com.activevos.api.identityservice.xsd.TIdentity;
import com.activevos.api.identityservice.xsd.TProperty;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.List;
import javax.xml.namespace.QName;

/** Identity Service endpoint WSDL  */
String ID_SERVICE_WSDL = "http://localhost:8080/active-bpel/services/AeIdentityService?wsdl";
/** Identity Service endpoint QName  */
QName  ID_SERVICE_QNAME = new QName("http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl", "AeIdentityService");

try 
{
   // Create service using WSDL location and service qname.
   AeIdentityService idService = new AeIdentityService(new URL(ID_SERVICE_WSDL), ID_SERVICE_QNAME);
   // Get service port to invoke operations.
   IdentitySearchPortType idServicePort = idService.getAeIdentityServicePort();

   // Invoke findIdentitiesByRole() operation.
   // In this example, get the list of identities for role 'loanreps'.
   TIdentityList idList = idServicePort.findIdentitiesByRole("loanreps");
   
   // get list of Identities from resultset
   List identities = idList.getIdentity();
   System.out.println("Found identities count: " + identities.size());
   for (TIdentity identity : identities) 
   {
      System.out.println("ID: " + identity.getId()); // id, such as DN of LDAP entry.
      // List of roles this person  belongs to.
      List memberRoles = identity.getRoles().getRole();
      for (String role : memberRoles)
      {
         System.out.println("Member Of : " + role);
      }
      // List all attributes. E.g. firstName, lastName, email etc. 
      List properties = identity.getProperties().getProperty();
      for (TProperty  prop : properties)
      {
         System.out.println("property[" + prop.getName() + "] = " + prop.getValue() );
      }
      System.out.println();
   }
   
}
catch(MalformedURLException mue)
{
   // Invalid service url format
   mue.printStackTrace();
}
catch(SearchFault searchFault)
{
   // identity service related fault.
   System.out.println("Fault Message: " + searchFault.getMessage());
   if (searchFault.getFaultInfo() != null) 
   {
      // Fault details.
      System.out.println("FaultInfo Code: " + searchFault.getFaultInfo().getCode());
      System.out.println("FaultInfo Message: " + searchFault.getFaultInfo().getMessage());
   }
   searchFault.printStackTrace();
}
catch(Exception e) 
{
   e.printStackTrace();
}

Constructing An Identity Query Using IdentityService4J API

This sample snippet shows how to construct an IdentityQuery, which used in findIdentities(), assertPrincipalInQueryResult(), assertPrincipalInQueryResultWithResponse(), and countIdentities() operations.

Please see the com.activevos.examples.identityservice.FindIdentitiesDemo class for the complete example.

// imports similar to previous examples
try 
{
   // Create service and get service port 'idServicePort' similar to previous examples.
   // ...
   // ...
   
   // Create identity query with includes and excludes:
   // 1) include groups : loanreps,  user: loancsr
   TIdentityQueryValues includeQueryValues = new TIdentityQueryValues();
   includeQueryValues.getGroup().add("loanreps"); // group
   includeQueryValues.getUser().add("loancsr"); // user
   
   // 2) exclude groups : loanmgrs
   TIdentityQueryValues excludeQueryValues = new TIdentityQueryValues();
   excludeQueryValues.getGroup().add("loanmgrs"); // group
   
   // Create query with includes and excludes
   TIdentityQuery query = new TIdentityQuery();
   query.setInclude(includeQueryValues);
   query.setExclude(excludeQueryValues);
   
   // Invoke findIdentites() operation.
   TIdentityResultSet resultSet = idServicePort.findIdentities(query);
   System.out.println("Query match count : " + resultSet.getTotalRowCount());         
   // get list of Identities from resultset
   List identities = resultSet.getIdentities().getIdentity();
   System.out.println("Found identities count: " + identities.size());
   for (TIdentity identity : identities) 
   {
      // print details, similar to previous example
   }   
}
catch(Exception e) 
{
   e.printStackTrace();
}