Provisioning SOAP Web Service

DirX Access provides a provisioning service that facilitates the life cycle management of RBAC authorization and authentication policies based on versions 2.0 and 1.0 of SPML.

The DirX Access provisioning Web service represents a single PST in the sense of SPML 2.0. The target is represented by the DirX Access Server.

Each provisioned object has a unique PSO identifier. The DirX Access provisioning Web service uses the PSO identifier format = for policy service objects. All references to a PSO must be made via the appropriate PSO identifier.

Note that SPML and DSML define the basic vocabulary for a provisioning WS. However, OASIS does not publish a WSDL that provides a universal definition for a provisioning WS. Thus, the DirX Access provisioning WS uses its own WSDL based on OASIS‑defined standard vocabulary (SPML, DSML).

Covered Abstractions

The provisioning WS allows looking up, searching, adding, modifying, and deleting persistent objects that are processed by the DirX Access services. This functionality covers the following abstractions:

  • Policy service: the RBAC‑constraint1 authorization policy and related authentication policy abstractions (as known in DirX Access version 8.0B) are supported by the provisioning WS; that is:

    • Policy services abstractions for authentication:

      • Authentication policies

      • Resources

Note that managing authentication methods is not yet supported via provisioning.

  • Policy services abstractions for authorization:

    • Authorization roles

    • Authorization policies

    • Rules

    • Conditions

    • Actions

    • Resources

Note that the provisioning for policy service abstractions serves role definition and authorization policy‑to‑role assignment. Provisioning of user‑to‑role assignment is performed by the user service.

  • Configuration service: the configuration abstractions are not yet supported through the provisioning WS.

Supported WS Ports

The DirX Access provisioning WS provides the following service ports:

SPML Version 1

A WS port to provision RBAC authorization and authentication policy objects based on version 1.0 of SPML. This port allows obtaining the WSDL via:

http(s)://<hostname or IP address of DirX Access Server>:<tcpPort>/services/provisioning/provisioning/spml1?wsdl

SPML Version 2

A WS port to provision RBAC authorization and authentication policy objects based on version 2.0 of SPML. This port allows obtaining the WSDL via:

http(s)://<hostname or IP address of DirX Access Server>:<tcpPort>/services/provisioning/provisioning/spml2?wsdl

Supported Bindings

The provisioning WS supports SOAP over HTTP as a binding for both WS ports. SOAP1.2 in document‑literal style is used.

Supported Port Types and Operations

The portType elements in the provisioning WS WSDL correspond to the described WS ports. They support the following operations:

SPML Version 1

Allows provisioning RBAC authorization and authentication policy objects through the following operations:

  • add: add an abstraction (see below for details)

  • modify: modify an abstraction (see below for details)

  • search: search an abstraction (see below for details)

  • delete: delete an abstraction (see below for details)

SPML Version 2

Allows provisioning RBAC authorization and authentication policy objects through the following operations:

  • add: add an abstraction (see below for details)

  • modify: modify an abstraction (see below for details)

  • search: search an abstraction (see below for details)

  • lookup: lockup an abstraction (see below for details)

  • listTargets

  • iterate

  • closeIterator

  • delete: delete an abstraction (see below for details)

Constraints

The following functional constraints apply to the operations supported at the provisioning WS ports:

  • Modify requests:

    • Does not include the ability to move an entry to a new superior.

  • Search requests:

    • Composite filters are not supported, except for an <and> primitive that can be used to include objectclass in the filter.

    • The SPML2 search request can specify one of these scopes:
      <spmlsearch:query scope="subTree">
      <spmlsearch:query scope="oneLevel">
      <spmlsearch:query scope="pso">

    • To restrict an SPML2 search result, you can use
      <spmlsearch:basePsoID ID="X">

      • X = domain=DN: limits a search to a certain subtree.

      • X = objectclass=DN: retrieves the identified object.

      • Note that is ignored if a non‑container basePsoID is present.

    • Equality match and substring match can be used for filtering according to the following restrictions:

      • Object class is among {action, authenticationPolicy, authorizationPolicy, resource, role, rule}:

        • Search filters are restricted to dsml:equalityMatch for objectclass, name, and mode

      • Object class is condition:

        • Search filters are restricted to dsml:equalityMatch for objectclass and name

Supported Messages

The provisioning WS WSDL specifies the details about the message syntax.

Handling DirX Access‑Native LDAP Attributes

DirX Access allows provisioning a number of DirX Access‑native LDAP attributes (that is, attributes of which DirX Access is aware) and (to some extent) provisioning of plain LDAP attributes. This section provides details on the handling of DirX Access‑native LDAP attributes that applies to both provisioning WS ports.

The DirX Access‑native LDAP attributes listed below can be provisioned. Note that the names exposed by DirX Access through its provisioning interface are somewhat like DirX Access provisioning names and are not necessarily LDAP names. However, the mapping to the related LDAP attributes is fairly straightforward in most cases.

Mandatory attributes are in bold.

All attribute names are case sensitive.

Unless stated otherwise, the examples given here are to be understood as snippets from add requests.

Common Attributes

  • description

    • Voluntary description text for given data object.

  • dn

    • Although not really an attribute, the distinguished name can be requested as “requested attribute” to appear in a search response; a dn may also appear as something like an attribute in an add response. Applicable to user service objects only.

    • enabled

  • This attribute is mapped to the internal LDAP attribute dxaStatus.

  • hidden

    • A hidden entry does not appear in DirX Access Manager if set to “true”; it is mapped to the internal LDAP attribute dxaStatus.

  • name

    • The leftmost RDN; it is mapped to cn by default, it can be configured differently through the DirX Access Manager. Mandatory; cannot be modified.

  • objectclass

    • This attribute differentiates between the various types of DirX Access objects. Mandatory; cannot be modified.

  • parentDomain

    • The domain to which the respective object belongs. Mandatory for user service object classes; cannot be modified.

Attributes that belong to DirX Access Object Class authenticationPolicy

  • authenticationMethod (Mandatory)
    Example:

<dsml:attr name="authenticationMethod">
    <dsml:value>Basic Authentication</dsml:value>
</dsml:attr>
<dsml:attr name="authenticationMethod">
    <dsml:value>Form‑Based Authentication</dsml:value>
</dsml:attr>
<dsml:attr name="authenticationMethod">
    <dsml:value>SAML Authentication</dsml:value>
</dsml:attr>
<dsml:attr name="authenticationMethod">
    <dsml:value>X509 Authentication</dsml:value>
</dsml:attr>
<dsml:attr name="authenticationMethod">
    <dsml:value>Windows Integrated Authentication</dsml:value>
</dsml:attr>

  • resources (Mandatory)
    Example:

<dsml:attr name="resources">
    <dsml:value>http://127.0.0.1/someWebPage.html</dsml:value>
</dsml:attr>

Attributes that belong to DirX Access Object Class authorizationPolicy

  • rules (Mandatory unless enabled is set to “false”; see also above)
    Example:

<dsml:attr name="rules">
    <dsml:value>rule= SomeRule </dsml:value>
</dsml:attr>

Attributes that belong to DirX Access Object Class rule

  • actions
    Example:

<dsml:attr name="actions">
    <dsml:value> action= read </dsml:value>
</dsml:attr>

  • conditions
    Example:

<dsml:attr name="conditions">
    <dsml:value>condition= Business hours </dsml:value>
</dsml:attr>

  • resources (Mandatory)
    Example:

<dsml:attr name="resources">
    <dsml:value>http://127.0.0.1/someWebPage.html</dsml:value>
</dsml:attr>

Attributes that belong to DirX Access Object Class condition

  • authenticationMethod (Mandatory if type is set to authenticationMethod; cannot be modified.)
    Examples:

<dsml:attr name="authenticationMethod">
    <dsml:value>Basic Authentication</dsml:value>
</dsml:attr>
<dsml:attr name="authenticationMethod">
    <dsml:value>Form‑Based Authentication</dsml:value>
</dsml:attr>
<dsml:attr name="authenticationMethod">
    <dsml:value>SAML Authentication</dsml:value>
</dsml:attr>
<dsml:attr name="authenticationMethod">
    <dsml:value>X509 Authentication</dsml:value>
</dsml:attr>
<dsml:attr name="authenticationMethod">
    <dsml:value>Windows Integrated Authentication</dsml:value>
</dsml:attr>

  • dateLow
    Example:

<dsml:attr name="dateLow">
    <dsml:value>18963112</dsml:value>
</dsml:attr>

  • dateHigh
    Example:

<dsml:attr name="dateHigh">
    <dsml:value>25253112</dsml:value>
</dsml:attr>

  • ipLow (Mandatory if type is set to ipRange)
    Example:

<dsml:attr name="ipLow">
    <dsml:value>10.0.0.1</dsml:value>
</dsml:attr>

  • ipHigh
    Example:

<dsml:attr name="ipHigh">
    <dsml:value>10.0.0.100</dsml:value>
</dsml:attr>

  • level (Mandatory if type is set to assuranceLevel; cannot be modified.)
    Example:

<dsml:attr name="level">
    <dsml:value>1</dsml:value>
</dsml:attr>

  • timeLow
    Example:

<dsml:attr name="timeLow">
    <dsml:value>123060</dsml:value>
</dsml:attr>

  • timeHigh
    Example:

<dsml:attr name="timeLow">
    <dsml:value>126030</dsml:value>
</dsml:attr>

  • type (Mandatory; cannot be modified.)
    Examples:

<dsml:attr name="type">
    <dsml:value>timePeriod</dsml:value>
</dsml:attr>
<dsml:attr name="type">
    <dsml:value>assuranceLevel</dsml:value>
</dsml:attr>
<dsml:attr name="type">
    <dsml:value>authenticationMethod</dsml:value>
</dsml:attr>
<dsml:attr name="type">
    <dsml:value>ipRange</dsml:value>
</dsml:attr>

Attributes that belong to DirX Access Object Class action

See the chapter “Common Attributes”

Attributes that belong to DirX Access Object Class resource

  • parameters
    Example:

<dsml:attr name="parameters">
 <dsml:value>name,Joe,get,false</dsml:value>
</dsml:attr>

  • pep
    Example:

<dsml:attr name="pep">
    <dsml:value>Some PEP configured in DirX Access</dsml:value>
</dsml:attr>

  • uri
    Example:

<dsml:attr name="uri">
    <dsml:value>http://127.0.0.1/someResource</dsml:value>
</dsml:attr>

Attributes that belong to DirX Access Object Class role

  • authorizationPolicies
    Example:

<dsml:attr name="authorizationPolicies">
    <dsml:value>authorizationPolicy=Some Authz Policy</dsml:value>
</dsml:attr>

  • excludedRoles
    Note that you need to provide the roles as complete DNs;
    Example:

<dsml:attr name="excludedRoles">
    <dsml:value>role=cn=Some excluded role,ou=Role,ou=Business,ou=PolicyRepository,ou=DirX Access,o=My‑Company</dsml:value>
</dsml:attr>

  • juniorRoles
    Note that you need to provide the roles as complete DNs.
    Example:

<dsml:attr name="juniorRoles">
    <dsml:value>role=cn=Some different role,ou=Role,ou=Business,ou=PolicyRepository,ou=DirX Access,o=My‑Company</dsml:value>
</dsml:attr>

Plain LDAP Attributes

Besides provisioning of a number of DirX Access‑native LDAP attributes, DirX Access allows to some extent for provisioning of plain LDAP attributes as well. This section provides details on the handling of plain LDAP attributes that apply to both provisioning WS ports.

  • Plain LDAP attributes are to be provided by specifying their plain LDAP attribute names and values.

  • Provisioning plain LDAP attributes that are also used by DirX Access through the plain LDAP approach (for example, by providing sn instead of lastName) is strictly discouraged. As for the respective mappings, refer to the “Schema and attributes mappings” panel in the DirX Access Manager.

  • Provisioning DirX Access‑native LDAP attributes through the plain LDAP approach (for example, by providing dxaAcctLocked instead of AccountLocked) is not supported. This basically means that attributes beginning with “dxa” cannot be provisioned through the plain LDAP approach.

  • Attributes (for example, preferredHockeyTeams) coming with customer‑provided auxiliary object classes (say yetAnotherUserAuxClass) require a prior schema extension; the respective LDAP auxiliary object classes of those attributes must be provided through an additional clause “repositoryObjectclasses”, for example:

<dsml:attr name="objectclass">
    <dsml:value>user</dsml:value>
</dsml:attr>
<dsml:attr name="repositoryObjectclasses">
    <dsml:value>dlm1ManagedElement</dsml:value>
    <dsml:value>dxaRoleAssociationAuxClass</dsml:value>
    <dsml:value>dxaUserAuxClass</dsml:value>
    <dsml:value>inetOrgPerson</dsml:value>
    <dsml:value>yetAnotherUserAuxClass</dsml:value>
</dsml:attr>
<dsml:attr name="preferredHockeyTeams">
    <dsml:value>HCKometaBrno</dsml:value>
    <dsml:value>BostonBruins</dsml:value>
    <dsml:value>EHCMünchen</dsml:value>
    <dsml:value>Feelfreetoeditaboveteamnames</dsml:value>
</dsml:attr>

Defaults

For the sake of the provisioning client’s convenience, defaults apply for certain data not provided in a request:

Add Requests

  • cardinality defaults to n.

  • enabled defaults to false.

  • hidden defaults to false.

Search Requests

  • Missing scope defaults to subtree.

  • Missing searchbase defaults to root.

  • Missing filter defaults to “all users” (name=*).

Error Handling

Generally speaking, error messages returned in SPML responses are standards‑compliant. The requests are expected to be:

  • Valid

    • Note that in this respect, DirX Access 8.0B (and higher) is stricter than DirX Access 8.0A, where under certain conditions valid responses were returned to invalid requests (in detail: in add requests, the invalid element spml:attr was accepted and interpreted in the same way as if the valid element dsml:attr had been provided instead).

    • Complete (except for the defaults listed in the previous section).

Unexpected errors cause a generic message to be returned; in this case, the log file of the DirX Access Server should provide the details.