SPML Provisioning Web Services

SPML clients can use a proprietary authentication scheme based on asymmetric key cryptography.In this scheme, an SPML client authenticates itself to the SPML Provisioning Web Services servlet with its private key and then forwards only the name of the current user.The servlet verifies that it has a valid certificate of the presented private key and if so, accepts the username without further validation.This scheme is also used for Web Center with a setup of SSO to the Request Workflow server.See the DirX Identity Web Center Reference for details.In this case, you need a private key for a client, which is a key generated solely for this purpose; see the section "Creating a Keystore and a Truststore" below for details.

The sample client available in install_path/provisioningServices can use this type of authentication.The keystore access and the alias of the private key must be configured as a part of the configuration for a special authenticator class (see the sample configuration file install_path/provisioningServices/spmlv2/conf-proprietary-auth.xml):

The value of the username property is used as an authenticated user at the server side and will be used as an effective user for any invoked operation.

The properties keyStore and keyStorePassword are used by the test client to access the keystore with the private key used during authentication.

The keyStoreAlias property is the alias of the private key stored in the configured keystore. This property allows the client to identify the correct private key within the keystore. For details about the sample client provided with DirX Identity, see the section "Using the Sample Client".

You need to import a certificate that corresponds to the client’s private key into the Provisioning servlet truststore named as provisioningservices-truststore. The truststore password must match the one with the truststore key in the password.properties file. Note that the truststore key can be missing if the servlet is being redeployed or upgraded. Check to see if the truststore key in the password.properties exists and add it manually if necessary. Both files must be placed in the following directory:

If the client and the SPML Provisioning Web Services run on different hosts, the keystore must reside on the machine with the client and the truststore on the one hosting the servlet.

You can share the same key for each client, or one key per client, or anything in between. When using different keys, choose a unique alias for each key and add a certificate for each key to the servlet’s provisioningservices-truststore.

The use of proprietary authentication does not require any special steps except for creating key material for the client and server sides and configuring the password.properties file. The authentication itself is already enabled by default when the servlet configuration file config.xml located in the folder WEB-INF contains following section under the element authenticators:

Creating a Keystore and a Truststore

The batch file install_path/ssl/generate_ProvSvcKeystore.bat (or .sh) provides a convenient way to:

If the truststore doesn’t exist, it is created. The keystore and the certificate file are overwritten if they already exist.

Before you run the batch file, open it and set the following values:

Next, move the created keystore to the machine hosting the client and then adapt the client’s configuration as described in this section.

Move the truststore to the servlet’s WEB-INF directory and adapt the password.properties file accordingly.

When using the batch file again to generate a key for another client, choose a different dname and alias.

The SSOHeaderFilter is a servlet filter that extracts SSO credentials from an HTTP header and stores them in a session-scoped variable.

The filter can act as a stand-alone SSO module if the client provides unencrypted credentials via an HTTP header. Its other purpose is to copy credentials provided by another SSO module (for example, a Tomcat valve) to session-scope.

Note that the filter does not validate the source of the credentials. So deploying it as a stand-alone SSO module may cause a security breach if untrusted clients can access the Provisioning Web Services directly.

The filter must be defined in the application’s deployment descriptor web.xml as a filter, as shown in the following example:

The filter can be customized via the filter initialization parameters as in this sample:

The parameter “headerName” denotes the HTTP header field from where the filter takes the identifier. The value of the header is obtained by calling

Depending on the given “type” parameter, the filter either searches for a user or for an account with the appropriate filters defined in the context parameters in the deployment descriptor. Here is an example:

If the header identifies a user, the filter takes the userFilter search expression. Otherwise, it searches for an account in the configured target system with the accountFilter. It finds the corresponding user DN via the account’s dxrUserlink attribute.

For password reset scenarios, clients can sign some requests - especially setPassword or checkChallengeResponses - with the end user’s private key. This mechanism serves not only to authenticate, but also to ensure that the new password is for the same user as the one who produced the signature.

To use this Provisioning Web Services feature, a Web Service Security Trust handler needs to be configured. This handler is responsible for verifying the signature and for comparing the attributes found in the certificate with those attributes in the request that identify the user. The trust handler is based on the Apache WSS4J module. For more details on identifying attributes, see the subsection "Identifying Attributes" in the section "Common SPML Aspects".

The handler is activated by adding a <handler> element into the Axis Web Service Description file WEB-INF/server-config.wsdd. The default file contains the following handler snippet, which you only need to uncomment:

Set the signatureIsOptional parameter to true if you expect and accept both signed and non-signed requests. If it is set to false, the handler rejects non-signed requests; if set to true, it leaves the proper handling to the corresponding Web Service operation. This setting is especially important for challenge/response scenarios, where the user authenticates with their challenges rather than with a certificate. See the sub-section "Authentication by Challenge/Response" (in the section "Accounts Management") for details.

The <handler> element references the file crypto.properties. In a default deployment, this file is located in the WEB-INF/classes folder. The file format is defined by Apache WSS4J. It especially sets the class name of the Crypto provider (in this example: MyMerlin) and the location of the server key store. Here are the relevant sample snippets:

You need to adapt the path to the server key store.

When the XML signature verification is successful, the trust handler checks that the certificate matches the identifying attributes in the request. You need to configure the attribute names in the certificate that must be compared with the identifying attributes in the setPassword request. This information is stored in the file WEB-INF/identifierMatcherConfig.xml. The element <identifyingAttributes> contains a XPATH expression to the sub-element in the request, which contains the identifying attributes. There is no need to change the default "identifyingAttributes". The attribute names need to be configured in <matchRule> elements, as shown in the following snippet:

Enter a <matchRule> for each attribute.The XML attribute op sets the comparison operator, typically "equals".Alternatives are: "startsWith", "endsWith" and "contains".In <op1>, configure the attribute name in the certificate and a Java regular expression for extracting the required value - typically all.In <op2>, do the same thing for the identifying attribute in the SPML request.Note the prefix (here: user) that indicates to the Web Service that this attribute identifies the user.

This section describes how to deploy the Provisioning Servlet.There are the following deployment options:

In this step, you adapt the files in your deployment instance folder to your requirements. In this section, relative file locations are relative to the deployment instance folder. To configure a Web Services deployment:

To test the deployment, start Tomcat or the Java-based Server and then test the deployment as indicated in the section "Deploying the Provisioning Servlet".

This section describes how to customize Web Services runtime to:

The identifiers in all requests are interpreted as the DNs (LDAP distinguished names) of the objects or containers.

If the add request provides an identifier (element <psoID>), the service tries to create the object or container with this DN.If the add instead contains a <containerID>, the service takes it as the DN of the parent container and creates an object beneath it.The RDN (relative DN) must either be passed as an attribute in the request or the object description must calculate a default value.

In some cases, the identifying DN is not known; this is especially true when the user has forgotten the password. In this case, you can set up to pass a list of identifying attributes as a sub-element of the psoID. Here is a sample snippet as part of a setPasswordRequest:

In this sample, the attributes are used to identify an account within a target system. The account is identified by the attribute "dxrName", the target system by "dxrTSDomainName" – for Active Directory, the domain name.

Prefixes in the attribute names are used to identify related entries. For accounts, the prefix "ts." denotes a target system. The prefix "user." denotes the associated user of an account.

For cases where the client does not know about the LDAP attribute names, the Web Service provides an attribute name mapping. This mapping is configured in the Spring bean definition of the accounts handlers. Because a couple of handlers need them, the mapping is separated into an extra bean, which is referenced by all the handlers that need it.

The section "Customizing the Runtime" gives an overview of the Web Service customization. The settings for changing an account password are configured in the file accountsContext.xml. The bean AttributeNameMapping defines the attribute mapping, as shown in this example:

The mapping is configured as a Java map. For the key, you enter the attribute name as sent by the client, but in lowercase format. For the value, you enter the name of the attribute in LDAP format. Note that the names in the map must not contain the prefixes. So "ts.domain" in the request is translated to a target system attribute “dxrTSDomainName”.

Beans that need this mapping reference it as shown here for the setPassword handler:

Besides the normal list of attributes or modifications, add and modify requests may contain the reference capabilities.

To simplify deployment, attribute names are not cross-checked with the definitions made in the respective listTargets response. Hence - not in line with the OASIS SPMLv2 specification - you don’t have to change the listTargets response file, once you extend the LDAP schema and add new attributes or object classes.

For the management of completely new entry types not supported by the DirX Identity domain, see the section "Custom Objects".

You may want to define additional custom object descriptions that extend existing default object descriptions. A sample might be to distinguish between several types of users. In this case keep in mind that the Provisioning Service uses the default object description for creating a new object. For users, this is the "dxrUser" object description. This means that you can create your custom extended user entry, if you provide the appropriate object classes and attributes. Rules for calculating default attribute values are only taken from this default object description, not from your custom one.

When the Service processes a modify or delete, it obtains the appropriate object description the same way as Web Center or Identity Manager by applying the matching rules defined in the object description. This means especially, it associates the proper object description and its rules for attribute values.

Search requests are always processed as LDAP simple paged search requests. The default page size may be changed in the web application’s initial parameters.

The iterate request allows requesting the next pages of a search result.The prerequisite is an initial search having returned a search response that contains an iterator identifier.The request must contain the iterator identifier obtained from a previous search or iterate response.

As it is for a search response, a successful iterate response contains the entries of the next page and - optionally - an iterator identifier for requesting the next pages.Absence of the iterator identifier indicates that no more pages are available and the initial search result can no longer be iterated upon.

The SPMLv2 closeIterator request allows you to inform the Web Services that the related search result is no longer needed.On receipt of such a request, the Web Services will delete the internal overhead related to this result.It is good style for a client to send a closeIterator request when a search result is no longer needed.

The closeIterator response returns success or an error message in case of failure.

Besides the normal attributes and references to other entities (see the sections on references), the add request supports a sub-element <operationalAttributes>. The operational attributes are defined for the XML namespace "urn:siemens:dxm:provisioning:operAttrs:1:0" in the schema file "operAttrs.xsd". As in SPMLv1 they define a list of DSML attributes that have to be evaluated by the addressed web service.

The user web service evaluates the attribute "timeout":

It is of interest when the user creation is delegated to a request workflow. In case a timeout is given, the service waits a maximum of "timeout" seconds until the end of the workflow. If the workflow is not yet finished, the service returns the status "PENDING". Note that - in contrast to the SPMLv2 specification - the client cannot ask for the status of the request or cancel it. In other words: the operations "cancel" and "status" are not supported.

A user can be created without passing its DN, parent DN or a naming attribute. By default, this user will be put into the users subtree (cn=Users,cn=<domain>) with the generated dxrUid as the naming attribute. The folder where the user should be created can be changed in the Spring configuration: in the file usersContext.xml, set the defaultRelUserBase property of the AddUser bean to the required relative DN (DN omitting the domain root), as shown in the following snippet:

You can override the default value for the naming attribute by configuring a naming rule in the user’s object description. Here is an example:

For the definition of the naming rule, keep in mind that a temporary value is set when the entry is created in memory and before the other attributes are set. Therefore, the property must depend on all the attributes that are used in the rule.

The delete operation can be applied both to users and to containers. If a container is not empty, you have to supply the attribute "recursive" with a value of "true". Otherwise the request is rejected. If auditing is enabled for users, the user entry is not immediately deleted. Instead its state is set to DELETED, the delete date is set and an audit record is stored in its history attribute. Only when the history attribute is read and cleared, a subsequent consistency rule will delete the entry physically.

The following gives an example of a delete request for a non-empty container:

There are no mandatory attributes anymore; even the naming attribute cn and the object class can be omitted. The object class attribute helps to distinguish users and containers in add requests. An object class value of "dxrUser" identifies a user. Otherwise the object is expected to become a container. If no object class is given, the entry is supposed to be a user.

Other attributes are optional. Standard attributes are given in the listTargets response. If you extend the LDAP schema with your custom user attributes, make sure you also extend the user’s object description. Then you will be able to update and read them via the provisioning Web Services.

An important standard attribute is dxrState. For the supported values and their meaning, see the overview in the DirX Identity Provisioning Administration Guide.

All SPML operations support the reference capability. References cover relationships to other objects in the DirX Identity domain.

Most of the references are simple ones. They consist simply of the DN link to the other object. In most cases the name of the reference type equals the LDAP attribute where it is stored.

Some of the references are attributed and support specific reference data. The most important are the user-privilege assignments with their start and end date and account-group memberships with their state. See the respective sections for more information.

In order to search for users with a specific reference, use the <hasReference> clause within a search query:

The above query searches for users with a reference to the organization "My-Company".

If you want to see reference data in the lookup or search response you have to supply the element <includeDataForCapability> for the reference capability.

The reference "dxrRoleLink" controls user-role assignments. The role assignment supports the attributes start and end date and role parameters.

When you want to add a start or end date within the reference data you just have to supply them as a normal DSML attribute. See the following snippet for a sample:

If you want to modify a start or end date, provide a DSML modification in the reference data as in the following snippet:

Note that role assignments with role parameters might not always be uniquely identified by the distinguished name of the assigned role, so it might be necessary to add a "uid" attribute identifying the assignment. You can find an example in the following snippet:

In this case, the value of the "uid" is the value of the "cn" attribute of the assignment object containing the assignment data in LDAP.

The reference data of role parameters follow the XML schema with the namespace "urn:siemens:dxm:provisioning:asg:param:1:0". You’ll find the schema in the list targets response file for users and in "paramAsg.xsd".

In an add request, you supply a role parameter in a <paramAsg> element as in this sample. Note that "asgpar" is the namespace prefix for the above mentioned schema namespace, which you have to define in the XML document somewhere before:

The "dn" attribute denotes the distinguished name of the role parameter, the "uid" its "dxrUid" attribute. Only one of the two attributes is necessary to identify the role parameter. Add one or more values in <asgpar:value> elements.

Modifications to a role parameter must be supplied in <paramAsgModification> elements as in the following sample:

The "uid" attribute identifies the assignment (attribute "cn" in LDAP), whereas the "uid" attribute of the element <paramValueModification> identifies the role parameter (that is, its attribute "dxrUid"). As with normal SPML / DSML modifications, the "operation" attribute tells the service whether to add, replace or delete the value(s). Note that a delete operation without any value deletes all existing values.

The modification shown above deletes all assignments for the role "cn=Project Member".

The modification of dxrRoleLink with the replace operation has a special semantic. It can be used either for update operation of an existing role assignment defined by the "dn" or "uid" attribute or for creation of a new role assignment if supplied with common attributes as shown in the following snippet:

The replace operation for dxrRoleLink does not delete any existing role assignments.

To search for users with a specific permission assignment, use the <hasReference> clause within a search query:

The filter shown above searches for users who have the role "cn=Project Member". Note that reference data such as start or end date are not supported.

For complete samples of how to manage role references, see especially the file "sampleRequestRoleLink.xml".

The reference "dxrPermissionLink" controls user-permission assignments. The permission assignment supports the attributes start and end date.

When you want to add a start or end date within the reference data, you just need to supply them as normal DSML attributes. See the following snippet for a sample:

If you want to modify a start or end date, provide a DSML modification in the reference data as in the following snippet:

The modification shown above replaces the assignment to the permission "cn=Signature Level 2". It deletes the previous start date and sets the end date to the end of the year 2999.

The modification of dxrPermissionLink with the replace operation has a special semantic. It can be used either for update operation of an existing permission assignment defined by the "dn" attribute or for creation of a new permission assignment if supplied with common attributes, as shown in the following snippet:

The replace operation for dxrPermissionLink does not delete any existing permission assignments.

To search for users with a specific permission assignment, use the <hasReference> clause within a search query:

The filter shown above searches for users with the permission "cn=Signature Level 2". Note that reference data such as start or end date are not supported.

For complete samples of how to manage role references, see especially the file "sampleRequestPermissionLink.xml".

The reference "dxrGroupLink" controls user-group assignments. The group assignment supports the attributes start and end date.

When you want to add a start or end date within the reference data, supply them as normal DSML attributes. See the following snippet for a sample:

If you want to modify a start or end date, provide a DSML modification in the reference data, as shown in the following snippet:

The above modification replaces the assignment to the group "Internal" in the target system "Windows Domain Europe". It deletes the previous start date and sets the end date to the year end 2999.

The modification of dxrGroupLink with the replace operation has a special semantic. It can be used either for update operation of an existing group assignment defined by the "dn" attribute or for creation of a new group assignment if supplied with common attributes, as shown in the following snippet:

The replace operation for dxrGroupLink does not delete any existing group assignments.

To search for users with a specific permission assignment, use the <hasReference> clause within a search query:

The above filter searches for users who have the group "Internal" of the target system "Windows Domain Europe". Note that reference data such as start or end date are not supported.

For complete samples of how to manage role references, see especially the file "sampleRequestGroupLink.xml".

The suspend capability allows enabling and disabling a user.

The capability updates the attributes dxrState, dxrDisableStartDate and dxrDisableEndDate. But note that the state is also affected by other operations and attributes, namely by the dxrStartDate and dxrEndDate. A suspend request sets the user’s state to DISABLED, a resume request to ENABLED. A user is considered active if his state is ENABLED.

In suspend or resume requests you can provide the attribute "effectiveDate". The effective date in a suspend request denotes the disable start date. As default, the service takes the day before. The effective date in a resume request denotes the disable end date. If it is not given, the service deletes both disable start and end date.

The following sample shows a suspend request with an effective date of January 1st, 1990:

The service accepts a number of formats for the date representation; especially it supports the IETF standard.Internally it uses the parse method of the JDK class "java.util.Date".See there for more details on the formats.

In a search request you can use the <isActive> query clause to search for enabled users: Simply include the following element into your query filter: <spmlsuspend:isActive/>.

The password capability implementation only supports the requests “validatePassword” and “setPassword”.Reset and ExpirePassword are answered by an error response.

The password is not only stored in the attribute userPassword but also in the attribute dxmPassword.It is encrypted if the service has a certificate; otherwise, it is hashed.To read the certificate from the connectivity configuration tree, the service needs to authenticate as domain administrator.It derives the user name from its own bind credentials.Make sure that the service is bound as domain administrator!

The identifiers in all requests are interpreted as the DNs (LDAP distinguished names) of the objects. An add request may, but need not contain an identifier.

If the add request provides an identifier (element <psoID>) the service tries to create an object with this DN. If the add instead contains a <containerID>, the service takes it as the DN of the parent node and creates an object beneath it. The RDN (relative DN) must either be passed as an attribute in the request or the object description has to calculate a default value. If neither a <psoID> nor a <containerID> are provided, the service creates the new object direct beneath the roles root (cn=rolecatalogue,cn=<your domain>).

Mandatory attributes are the naming attribute cn and the object class. In add requests, roles and role containers can only be distinguished by the object class attribute. A value of “dxrRole” identifies a role, the value “dxrContainer” a role container.

Other attributes are optional and have to be among the list given in the listTargets response. Note that the operational links to junior roles and permissions and the role parameter related attributes are treated as capabilities and are silently ignored, when provided in simple attributes.

All role links to other objects within the Identity domain must be provided as SPMLv2 references. A role object supports the following references:

For role parameter links, see the following match rule section.

Here is a sample snippet for a dxrPermission reference within an addRequest:

If these links are among the attribute list, they are silently ignored.

If a role requires a role parameter, the DN of the role parameter and the corresponding match rule must be provided in the matchrule capability. Here is a sample for a match rule capability:

The <roleparamDN> and the <uid> denote the referenced role parameter object. Within a request one of them is sufficient. The <uid> refers to the dxrUid attribute of the role parameter. It is automatically generated with the role parameter object and does not change when the parameter is moved. Currently, the <type> value has to be “Group” and the <attribute> refers to the group attribute, which in the role resolution process is matched according the <operator> with the DN of the selected role parameter value. For more details see the appropriate section in the manual.

The following sample gives the modification for a match rule within a modify request:

The given value replaces all existing role parameter links and match rules in the role.

The DirX Identity service does not support a delete request with recursive=”true”.That is, the service deletes only the object with the given DN and rejects the request, if the entry has children.

Mandatory attributes are the naming attribute "cn" and the object class. The object class attribute distinguishes permissions and containers in add requests. An object class value of “dxrPermission” identifies a permission. Otherwise the object is expected to become a container.

Other attributes are optional. Standard attributes are given in the listTargets response. If you extend the LDAP schema with your custom permission attributes, make sure you also extend the permission’s object description. Then you will be able to update and read them via the Provisioning Web Services. You don’t need to extend the list targets response.

Besides the normal attributes and simple references to other entities, the add request supports the capability for match rules. For a detailed explanation of the XML schema see the separate chapter on match rules.

Here’s the excerpt of a sample add request containing a reference capability to a group and the match rule capability:

The content of the match rule capability is controlled by the XML schema with the namespace "urn:siemens:dxm:provisioning:permission:matchrule:1:0". You find the schema in the file "perm-matchrule.xsd" and embedded in the list target response for permissions "listTargetsRspPermissions.xml". This schema makes use of some common definitions for role parameters, which are defined in the file "rpmatchrule.xsd" and again in the list targets response for permissions.

A match rule is represented by the XML element <permMatchrules>. Here is a sample:

This sample contains a combined match rule that compares the user attributes "dxrProject" and "c" with the according group attributes.The project values must be the same, the country value of the user must contain that of the group.

A <permMatchrules> contains 1 or more single attribute comparisons, which are represented by elements <permMatchrule>.They are combined by "and" or "or" depending on the boolean XML attribute "or" in <permMatchrules>.

The element <userAttr> specifies the user attribute, the element <operator" the compare operation ("=", "contains", "!=", "<=", etc).

The element <groupConst> specifies whether the user attribute must be compared to a group attribute or a constant allowing the values "Group" or "Const".The element <groupAttr> contains either the group attribute or the constant value.

For handling of match rule modifications, see the section on "Add, Modify and Delete".

Organizations or companies can be managed by SPMLv2 requests using the target identifier “organizations”.

Organizations support the following simple references: dxrApprover, dxrContextLink, dxrCategoryLink, dxrLocationLink, dxrOULink, dxrPrivilegeLink.

Mandatory attributes are the naming attribute o and the object class. The object class attribute distinguishes organizations and containers in add requests. An object class value of “dxrOrganization” identifies an organization. Otherwise the object is expected to become a container.

Organization Units can be managed by SPMLv2 requests using the target identifier "organizationalUnit".

Organizational units support the following simple references: dxrApprover, dxrContextLink, dxrCategoryLink, dxrLocationLink, dxrCostUnitLink, dxrPrivilegeLink.

Mandatory attributes are the naming attribute "ou" and the object class. The object class attribute distinguishes organizational units and containers in add requests. An object class value of “dxrOrganizationalUnit” identifies an organizational unit. Otherwise the object is expected to become a container. One special container may be an organization identified by object class "dxrOrganization" (with target identifier "organizations").

Context objects can be managed by SPMLv2 requests using the target identifier “context”.

They support the following simple references: dxrApprover, dxrContextLink, dxrCategoryLink, dxrPrivilegeLink.

Mandatory attributes are the naming attribute cn and the object class. The object class attribute distinguishes context objects and containers in add requests. An object class value of “dxrContext” identifies a context object. Otherwise the object is expected to become a container.

Location objects can be managed by SPMLv2 requests using the target identifier “location”.

They support the following simple references: dxrApprover, dxrContextLink, dxrCategoryLink, dxrLocationLink.

Mandatory attributes are the naming attribute l and the object class. The object class attribute distinguishes locations and containers in add requests. An object class value of “dxrLocation” identifies a location and “dxrCountry” a country container. Otherwise the object is expected to become a container.

Cost Units can be managed by SPMLv2 requests using the target identifier “costUnit”.

Cost units support the following simple references: dxrApprover, dxrContextLink, dxrCategoryLink.

Mandatory attributes are the naming attribute "cn" and the object class.The object class attribute distinguishes cost units and containers in add requests.An object class value of “dxrCostUnit” identifies a cost unit.Otherwise the object is expected to become a container.

The identifiers in all requests are interpreted as the DNs (LDAP distinguished names) of the objects. An add request may, but need not contain an identifier.

If the add request provides an identifier (element <psoID>) the service tries to create the target system or container with this DN. If the add instead contains a <containerID> the service takes it as the DN of the parent node and creates an object beneath it. The RDN (relative DN) must either be passed as an attribute in the request or the object description has to calculate a default value. If neither a <psoID> nor a <containerID> is provided the service creates the new object direct beneath the target systems root (cn=targetSystems,cn=your_domain).

Mandatory attributes are the naming attribute cn and the object class. The values of the object class or the dxrType attribute distinguish target systems, cluster, and (cluster-) containers in add requests. Specify the following values:

Other attributes are optional and must be specified in the list provided in the listTargets response. By default the DirX Identity provides the file “listTargetsRspTSMgmt.xml”.

The namespace URI “urn:siemens:dxm:provisioning:ts:connectionOptions:1:0” identifies the capability for custom connection options. It is evaluated for target systems (not for containers) in add, modify, lookup and search operations.

The options are stored at the target system and are only evaluated by a special type of workflows: cluster-enabled realtime workflows. Note that the target system already supports default connection parameters as normal attributes: dxmAddress, dxmDataPort, dxmSecurePort (if SSL enabled), dxmSSL, dxmBindProfile-DN (link to bind account), dxmKeyStore, dxmKeyStoreAlias, dxmTrustStore, dxmTrustStoreAlias, dxmAuthenticationMode.

With the “connectionOptions” capability the client can pass an arbitrary list of additional connection parameters. Before an account or group of this target system is provisioned, the workflow sets these and the default connection options in the connection configuration of the target system connector. Use the following default option names as far as possible: filename, driverDBType, url.

The parameters are passed as DSMLv2 <attr> elements within the capability. See the following XML snippet for a sample:

The namespace URI “urn:siemens:dxm:provisioning:ts:environmentProperties:1:0” identifies the capability for environment properties. It is evaluated for target systems (not for containers) in add, modify, lookup and search operations.

The properties are stored at the target system and are only evaluated by a special type of workflows: cluster-enabled realtime workflows.

With the “environmentProperties” capability the client can pass an arbitrary list of environment parameters. The provisioning workflow sets them before an account or group of this target system is provisioned.

The parameters are passed as DSMLv2 <attr> elements within the capability. See the following XML snippet for a sample:

The namespace URI “urn:siemens:dxm:provisioning:ts:options:1:0” identifies the capability for target system options. It is evaluated for target systems (not for containers) in add, modify, lookup and search operations.

Like the environment or connection options the attributes are passed as DSMLv2 <attr> elements.

The add request supports the following capabilities: connection options, environment properties and create options.

The create options contain two optional child elements:

<accountsAndGroupsSeparate>: This flag specifies whether the accounts and groups are stored in the same or in separate folders. This decision cannot be changed later on in a modify request!

<templateTS>: This element contains the DN of the template target system. If it exists, it overrules the “type/cluster” approach to select the template system (see below).

The XML format is conveyed by the schema “urn:siemens:dxm:provisioning:TScreateOptions:1:0“, which is delivered in the file “tsCreateOptions.xsd”. Here a sample snippet for the capability:

How to select the target system template?

The web service searches a template target system in the system domain (cn=TargetSystems,cn=DirXmetaRole-SystemDomain) in the following sequence:

If the create options capability contains an element <templateTS>, it uses this DN to read the target system.

Then it searches a target system matching the attributes “dxrType” and “dxrCluster” contained in the request.

If this search does not yield exactly one target system, it searches a target system matching the given “dxrType” alone.

Note that you can import appropriate target system sub-trees into the system domain for each cluster you need. This allows you to select the correct template simply by providing the “dxrCluster” and “dxrType” attributes.

By default, the target system configurations (which are the object descriptions, Java scripts and obligations) are stored directly beneath the target system entry. If you want to deploy many target systems into a common cluster, you should reduce the number of object descriptions by providing only one set of object descriptions that is shared between all the target systems of that cluster. In this case, you need to specify the destination folder for the configuration sub-tree in the normal attribute “dxmTSConfigurationLink”. Set it to the cluster folder to which the new target system belongs. If this attribute is set, the service stores the configuration folder beneath the designated entry. If the configuration folder already exists, the service does not change it.

Please note that the attribute “dxmTSconfigurationLink” is exclusively used by the Web Services when configuring target systems. It’s not used or evaluated by any other component (such as DirX Identity Manager, Services, and so on). You should not create the object descriptions, Java scripts, and so on in any other folder, because other components (such as DirX Identity Manager, Services, etc.) will not evaluate the attribute “dxmTSconfigurationLink”; these components expect the objects descriptions, Java scripts and so on to reside below the target system folder or below the cluster folder in parallel with the target systems of which the cluster consists, but nowhere else.

A modify request supports the capabilities “connectionOptions” and “environmentProperties”, but no others. This means especially that you cannot switch how to store accounts and groups: in the same or in separate folders.

The delete request allows deleting a target system or a target system container.

You must set the XML attribute recursive=”true” if you want to delete a non-empty target system container.You do not need to set the flag if you want to delete a target system.

The provisioning service supports a “tombstone” feature.It is realized as a user hook and activated in the default configuration.For more details see the section on user hooks.

Search requests return containers or target system entries, never accounts, groups or configuration objects.

Pass the respective <includeDataForCapability> element if you want only part of the capabilities to be returned.Note that create or delete options are not part of the returned entry.

Mandatory attributes are the naming attribute cn and the object class. The object class attribute distinguishes accounts and containers in add requests. An object class value of “dxrTargetSystemAccount” identifies an account. Otherwise the object is expected to become a container.

Other attributes are optional. Standard attributes are given in the listTargets response. Each target system will have its own set of proprietary attributes that DirX Identity does not check. Make sure that the attributes are defined in the respective object description of the domain.

Important standard attributes are dxrState and dxrTSState. The dxrTSState reflects the state of the account in the remote target system, i.e. as requested by the Web Service client.

The dxrState reflects the state of the account as requested by DirX Identity. Thus the resulting state may be different from the requested, since it considers also the state of the associated user and user-group assignments. Note that the account state is also controlled by the suspend capability.

This reference is simply mapped to the account attribute “dxrUserlink” and contains the DN of the associated user.

This reference is simply mapped to the account attribute “dxrUsedBy”. It is intended for functional accounts and denotes the users that are allowed to work with this account.

This reference is simply mapped to the account attribute “dxrPwdPolicyLink”. It references a password policy and is only applicable for functional accounts, for which a separate password is managed different from that of the associated user.

This reference controls the group memberships of the account. The account-group memberships are associated with their state and stored in the attributes “dxrGroupMember*”. Valid states are: OK, ADD, DELETED, IMPORTED, IGNORE, REMOTE. (See the respective documentation on account states for details.)

The resulting member state might be different from the requested state. It is set by DirX Identity considering the previous state, the states of the account and the associated user, and the user-group assignments.

The XML format of the membership is conveyed by the schema file "accountGroupMembership.xsd" with the namespace "urn:siemens:dxm:provisioning:account:groupmember:1:0" (see also the file listTargetsRspAccounts.xml). See the following request snippet for a sample:

A missing state is interpreted as "OK".

Besides the normal list of attributes or modifications, add and modify requests may contain the reference capabilities.

To simplify deployment, attribute names are not cross-checked with the definitions made in the respective listTargets response. Hence - not in line with the OASIS SPMLv2 specification - you don’t have to change the listTargets response file, once you extend the LDAP schema and add new attributes or object classes.

For the management of completely new entry types not supported by the DirX Identity domain, see the section "Custom Objects".

You may want to define additional custom object descriptions that extend existing default object descriptions. A sample might be to distinguish between several types of users. In this case keep in mind that the Provisioning Service uses the default object description for creating a new object. For users, this is the "dxrUser" object description. This means that you can create your custom extended user entry, if you provide the appropriate object classes and attributes. Rules for calculating default attribute values are only taken from this default object description, not from your custom one.

When the Service processes a modify or delete, it obtains the appropriate object description the same way as Web Center or Identity Manager by applying the matching rules defined in the object description. This means especially, it associates the proper object description and its rules for attribute values.

If you want to see reference data in the lookup or search response you must pass the element <includeDataForCapability> for the reference capability.

The search request supports the suspend capability and its <isActive> query clause. Here a sample of a query element asking for active accounts being an imported member in the group “Firmware Tests”:

The suspend capability allows enabling and disabling an account.

The capability controls the attribute dxrTSState and partly dxrState. It sets dxrState only if the account has no associated user. An account is considered active if its state is “ENABLED” or if it is IMPORTED with dxrTSState “ENABLED”.

In requests, the attribute effectiveDate is ignored. The state is always set immediately. The reason is that such a feature does not make sense for DirX Identity accounts: their state in Identity is mainly controlled by the associated user.

The password capability implementation only supports the requests "validatePassword" and "setPassword". Reset and ExpirePassword requests are answered with an error response.

For normal accounts, the password is not stored in the Identity domain. The Web Service sends an event to change the password of the account. The applicable workflow(s) perform the change at the connected system. Only if the account is privileged, the workflow stores the password also at the account in the Identity domain in the attributes userPassword and encrypted in the dxmPassword. For details, see the section "Password Capability" in "User Management".

For reset password scenarios, the Web Service supports identifying the account by using identifying attributes of the account itself, the target system and optionally the associated user. For details, see the section "Identifying Attributes" in "Common SPML Aspects". Especially in this case, normal basic authentication will not be possible. It can be replaced by either signing the request with the user’s certificate or by challenge/response authentication.

The Web Service delivers the password policy associated with the identified account either in the response to an explicit getPasswordPolicy request or implicitly in the response for checking the challenge responses. For details, see the section "Authentication by Challenge/Response".

The SPML Provisioning Web Services implement only a subset of the Async capability defined in SPMLv2: the status request, but not the cancel request. The status request serves only one purpose in the context of password reset:

The setPassword request indirectly triggers a workflow to change the password in the related connected system. The Web Service indicates this action by sending the status "pending" in the response. This response always contains the attribute "requestID". The client can use this ID to ask for the status of the password change. It must send a status request and pass the ID in the attribute "asyncRequestID".

The Web Service checks an account attribute for obtaining the result of the setPassword workflow. If the workflow is finished, it updates its state in the account. In this case, the Web Service returns the result (success or failure). Otherwise, it returns the state "pending".

If end users have forgotten their passwords, they can set new ones after authenticating themselves by answering their challenges. The Web Service provides the following operations to support this scenario:

The next sections provide more detail about these operations.

The sendOtp operation generates a one-time password and sends it to the requestor’s mobile phone via an SMS message.

The sendOtp request must contain a psoID with the identifying attributes for the end user’s account. Typically, these items are the login name and the name of the Active Directory domain.

The status attribute in the sendOtp response indicates whether the operation succeeded or failed. On success, the response includes:

The format and validity period of the generated one-time password, the SMS message format and the name of the account or user attribute with the mobile phone number are configured in properties of the SendOtpAccountsHandler bean (see the file accountsContext.xml):

The setPassword request must contain the psoID for the end user’s account as in the sendOtp request. For authentication, the request must include the one-time password the user received via SMS. And finally, the request includes the new account password.

The status attribute in the setPassword response indicates whether the operation succeeded or failed. On error, the error attribute and the errorMessage element give more details.

On failure, the sendOtp and setPassword request may return custom errors to indicate the cause of the failure; for example:

The list of custom error messages includes:

otpGenerationFailed - generating the one-time password failed.

otpNoAddress - neither the account nor the user have a mobile phone number.

otpSendFailed - sending the one-time password via SMS to the end user failed.

otpMismatch - the one-time password presented in a setPassword request doesn’t match.

otpTtlReached - the one-time presented in a setPassword request has expired.

otpLocked -the account is locked from authenticating via one-time password.

pwdPolicyMismatch - the new password presented in a setPassword request doesn’t comply with the password policies.

The identifiers in all requests are interpreted as the DNs (LDAP distinguished names) of the groups or containers.

If the add request provides an identifier (element <psoID>) the service tries to create the group or container with this DN. If the add instead contains a <containerID>, the service takes it as the DN of the parent container and creates an object beneath it. The RDN (relative DN) must either be passed as an attribute in the request or the object description has to calculate a default value.

Mandatory attributes are the naming attribute cn and the object class. The object class attribute distinguishes groups and containers in add requests. An object class value of “dxrTargetSystemGroup” identifies a group. Otherwise the object is expected to become a container.

Other attributes are optional. Standard attributes are given in the listTargets response. Each target system will have its own set of proprietary attributes that DirX Identity does not check. Make sure that the attributes are defined in the respective object description of the domain.

The reference values are simply mapped to the respective attributes with the same name.

The following references are supported:

The capability "urn:siemens:dxm:provisioning:group:RPValues:1:0" supports the management of role parameter values, which are modelled as specific properties.

Besides the normal list of attributes or modifications add and modify requests may contain the reference capabilities.

The delete request sets the attribute dxrTSState to DELETED.It only deletes the group physically if its attribute dxrState has the value DELETED.

If you want to see reference data in the lookup or search response you must pass the element <includeDataForCapability> for the reference capability.

The custom bean configurations for one entity type should be configured in a separate Spring bean configuration file: one file per entity type. This file is to be imported into applicationContext.xml. These configuration items should be kept separate from the standard product configuration files in order to minimize migration effort for version upgrades.

Copy the file customContext.xml delivered with the product in the spmlv2/custom folder to the WEB-INF folder of your Web Services application. Optionally rename it to myEntity*Context.xml*. In this file, define your custom handlers and adjust their properties. If you need to support more than one custom entity type, you must rename the sample bean names (not the Java class names).

You need to configure a handler for each operation and each capability supported by your custom entity types. The following section explains your changes for the handlers needed for one custom entity type.

You only need to provide a listTargets response file to comply with the SPMLv2 specification. It requires the implementation of a listTargets request, which returns a definition of all supported target identifiers. The Web Service creates the listTargets response by composing the content of all configured listTargets response files into one single response document.

The custom handler does not evaluate the entity and schema definitions so you don’t need to ensure the correct attribute names and entity schema definitions in the response file.

For each entity type, one listTargets response file must be supplied and referenced from the applicationContext. It describes the schema and capabilities of entities associated with a target identifier.

Copy the file listTargetsRspCustom.xml and optionally rename it according your entity type; for example, listTargetsRspMyEntity.xml.

In the element <target> replace the value of the attribute 'targetID' with your entity type, for example:

As the schema information is not evaluated by the Web Service, you can leave the attribute and object class definitions as they are. Just for clarity, change the objectClassDefinition name from "dxrContext" to a name that reflects your entity; for example, 'myEntity'.

Next, adapt the supportedSchemaEntity accordingly:

Make sure that the capabilities are correct: Typically references to other objects are modeled as reference capabilities. The sample in listTargetsRspCustom.xml has 2 references: dxrContextLink and dxrCategoryLink. Adapt these parts as you need. Typically the reference names equal the LDAP attribute names. The attribute 'entityName' in <appliesTo> and <schemaEntity> has to refer to your entity, e.g. entityName="myEntity".

The SPMLv2 Web Services are configured using Spring beans. The root configuration file needs to be the applicationContext.xml file in the WEB-INF folder of the deployed Web Service. This file mainly contains the configuration of the dispatcher beans for the SPML operations (add, modify, and so on) and imports entity type-specific configurations from corresponding files.

To enable the management of custom entity types, the handlers for this entity type must be added to the central dispatchers. This task must be performed in the one-and-only applicationContext.xml. For a template on how to do this, see the file customApplicationContext.xml delivered in the spmlv2/custom folder of the product installation.

This Spring bean configuration file contains the dispatcher configurations for the SPML operations: add, modify, and so on. The appropriate handler for each custom object must be added to the dispatcher.

Make sure to import your handler bean configurations from your custom context file (see the section “Custom Objects Custom Context” for a description of how to generate this):

There is one dispatcher for each operation. Mandatory operations are: add, modify, delete, lookup and most often you will want to search. In these cases, you need to extend the handler map of the following dispatchers.

This chapter gives information on how the operations (add, modify, etc) are implemented in the generic handlers.

When receiving a SPMLv2 request the request processor checks if a user hook is configured.If a user hook is configured the processor performs the user hook before and after processing the request.

A user hook must implement the interface “ISpmlv2Userhook” and it can optionally also implement “ISpmlv2UserhookSetContext”.For a Java documentation see the folder Documentation/DirXIdentity/ProvisioningWebServices of your installation media.

The interface “ISpmlv2Userhook” defines two methods:

The method must return a SPMLv2 response that is then returned to the client.

The interface “ISpmlv2UserhookSetContext” defines one method:

DirX Identity returns the response from the user hook to the web service client.

For a sample implementation see the folder Additions/ProvisioningWebServices/samples on your installation media. It contains the class “TombstoneUserhook”. This class considers only delete requests for target systems. In its method “beforeRequest” it copies the target system subtree to the subtree denoted by the configured root DN.

User hooks are configured using Spring dependency injection. In the file

servlet-home/WEB-INF/applicationContext.xml

a bean “DispatcherWithUserhooks” is defined with a map of references to user hook beans. The target identifiers are used as keys for the user hooks. Thus, you can define a different user hook for each target identifier.

The following sample shows how to configure the user hook “TombstoneUserhook” for the target identifier “targetSystems”:

The relevant key for user hooks in Iterate operations is calculated from the initial searchRequest related to the Iterate operation.

Configuring the user hook as a Spring bean allows a very flexible configuration.In the sample above, the user hook class has got a public field named “tombstoneDN” that is set with the value “l=tombstone,cn=My-Company”.

A test client is available in install_path/provisioningServices/spmlv2. It is based on the DirX Identity Connector Integration Framework and can be used for initiating sample requests and obtaining sample responses. Perform these steps to get started:

To get started, we recommend running the test client with the samples in following order:

Before you can test the sample client functionality, make sure you have performed the steps described the section "Getting Started with the Test Client", including at a minimum the successful execution of the operations listTargets, adding role container and deleting role container.

Perform these steps to test other functions using the related samples; for example, the samples delivered for users:

Typically you obtain a client for the Web Service by using some tool, which generates the Java (or .Net or …​) classes from the wsdl and XML schema files. In order to do this you should be aware of the wsdl component model shown in the next diagram:

The subfolder WEB-INF/etc of a deployment instance contains a file provisioning-service.wsdl which in turn contains the wsdl description for the Web Service. It imports the services types in the file provisioning-types.wsdl, which in turn imports the necessary SPML schemata. But for implementing a client you need to generate classes from one or more other XML schemata:

For selected features, the Web Services need some proprietary XML schemata:

To support easy implementation of a SPMLv2 SOAP client, a convenience class com.siemens.dxm.provisioning.framework.client.SampleSpmlv2Client is delivered as part of the Web Services client library. It provides a method for sending SPMLv2 requests via the SOAP connector and accepts configuration options in a variety of ways.

You can simply instantiate the class from your Java application, pass the connector’s configuration via one of the open() methods, create SPMLv2 requests using the classes of the library and pass them to the client’s processSpmlv2Request() method. The client sends the appropriate SOAP request to the configured URL of the provisioning web service and hands the response back as a SPML ResponseType class.