DirX Identity REST Services

DirX Identity provides Representational State Transfer (REST) services for reading and modifying a user’s profile data and privilege assignments and for performing his approval tasks.

The DirX Identity REST Services

  • Don’t use HTTP sessions.

  • Expect each request to present appropriate user credentials.

  • Are deployed into a stand-alone Tomcat Web container.

The REST Services functionality is divided into modules. Each module implements a specific subset of the services’ functionality:

  • Basic Functionality

    • Domain Service - generic operations on arbitrary entries. The current version supports creating, reading, updating, deleting, and searching entries.

    • User Service - operations to read and update user data, to read or change a user’s privilege assignments, and to assign privileges to or withdraw privileges from a user.

    • User Password Service - operations to read a user’s password policy and to reset his password.

    • User Certification Service - operations to view certification tasks for a user.

    • Self Service - operations to read and update the authenticated user’s data, to read or change the authenticated user’s privilege assignments, and to assign privileges to or withdraw privileges from the authenticated user.

    • Password Service - operations to read the authenticated user’s password policy and to change his password.

    • Delegation Service - operations to create, read, update, delete and list delegations. Note that the delegations supported by the REST Services are incompatible with the original DirX Identity delegation model.

    • Certification Service - operations to view and perform certification tasks for the authenticated user.

    • Workflow Service - operations to create, process, list and manage request workflows.

    • Ticket Service - operations to list tickets and to delete a ticket.

  • Approval Task-Related Functionality

    • Approval Service - operations to read the authenticated user’s task list, to get details of a task, to complete tasks.

The design of the REST Services interfaces is based on the System for Cross-domain Identity Management (SCIM) (see the “References” section for details) but the services are not SCIM-compliant. For example, SCIM schemas contained in request bodies are ignored, while responses will often include standard SCIM schemas but no schema extensions for proprietary resources and attributes.

This chapter describes how to configure and deploy the DirX Identity REST Services and how to use the operations it provides. The chapter also provides information about authentication and authorization.

Overview of Installed Files

After installation and configuration, the DirX Identity REST Services are available in the folder install_path/restServices/DirXIdentityRestServices.

Folder DirXIdentityRestService.org

This is the source folder used by the DirX Identity Configurator to create REST Services for a specific domain.

Folder DirXIdentityRestService-domain

This folder contains the REST Services for a specific domain.It is created by the DirX Identity Configurator.

Folder Endorsed

The DirX Identity Configurator copies the jar file in the subfolder lib to the folder tomcat_install_path/dxilib and appends it to Tomcat’s classpath.

Folder META-INF

  • File context.xml - An empty default context element for the application. It’s currently unused since we deploy a specific context file in the folder tomcat_install_path/conf/enginename/hostname.

Folder WEB-INF

  • applicationContext.xml - A REST Services configuration file. There is usually no need to change this file unless you want to disable unused REST services.

  • approval.properties - Settings for operations that perform approval tasks.

  • domain.properties - Some common settings for the basic service operations.

  • password.properties - The password of the domain admin in the LDAP database; PIN and previous PIN for password encryption.

  • resources.json - Settings for the basic service operations.

  • security.properties - Settings to access the LDAP database and to perform certificate-based authentication.

  • security.xml - A configuration file for Spring HTTP handling and user authentication. There is usually no need to change this file since the REST Services provide a couple of sample configuration files for supporting different authentication methods and combinations of them that should work out-of-the-box.

  • web.xml - The application’s deployment descriptor. There is usually no need to change this file.

  • Folder authenticationSamples - Alternatives to the file security.xml for different authentication scenarios. To activate one of them, copy the corresponding file to WEB-INF/security.xml.

  • Folder classes - The files that enable and configure logging for the various application components.

  • Folder lib - The jar files that implement the REST Services functionality.

Folder OpenAPI

This folder contains the OpenAPI documents for the REST Services.The files allServices.json and allServices.yaml describe the operations of all REST Services.The files service.json and service.yaml describe the operations of the corresponding sub-service.

The REST Services are not fully compliant with OpenAPI.They include a single GET request and a couple of DELETE requests with request bodies.Such requests are not supported by OpenAPI.

Folder Test

This folder contains a web application to test the REST Service requests.The application is a specifically configured instance of the Swagger UI.

Deploying the REST Services into Tomcat

The REST Services are deployed as a Web application into Tomcat 8.5 or 9.0 running with Java 11.

Context Descriptor

The DirX Identity REST Services are deployed into Tomcat by placing a context descriptor file in the folder tomcat_install_path/conf/Catalina/localhost:

<?xml version="1.0" encoding="UTF-8"?>
<Context
   docBase="install_path/restServices/
       DirXIdentityRestServices/DirXIdentityRestService-domain"/>

The docBase context attribute must point to the folder where the DirX Identity REST Services files are located.

Note that the name of the context descriptor file defines the application’s context path. The context path is part of the REST Services’ URL.

The DirX Identity Configurator creates a context descriptor file with the name DirXIdentityRestService-domain when integrating the REST Services into Tomcat. In this case, the URL to access the services is http://localhost:8080/DirXIdentityRestService-domain if Tomcat runs on port 8080 on the local host.

If you change the file name to dxiRest.xml, for example, the URL changes to http://localhost:8080/dxiRest.

The path name for Tomcat’s context descriptor folder depends on the specific Tomcat installation. The general folder name scheme is conf/[enginename]/[hostname].

Shared JAR Files

At runtime, the following JAR file used by the REST Services must be available via Tomcat’s classpath:

  • dxmStorageURL.jar

The DirX Identity Configurator copies the jar file to the folder tomcat_install_path/dxilib when integrating the REST Services into Tomcat and then adds it to Tomcat’s classpath.

File password.properties

The file contains passwords and PINs. To add a password or PIN, assign the cleartext value to the corresponding key. To change a password or a PIN, overwrite its encrypted or cleartext value with the new cleartext value and then restart Tomcat. The new value is encrypted during restart.

Set the password file permissions so that

  • The Tomcat server can read and write the file.

  • Authorized users can read and write the file in order to change a value.

  • No one else can read or write the file.

Deploying the REST Services Manually

There are several ways to deploy applications into Tomcat. In this section, we describe just one particular way.

To deploy the REST Services manually into Tomcat, proceed as follows:

  • Create an empty deployment folder on the machine where Tomcat is installed.

  • Copy the content of folder install_path/restServices/DirXIdentityRestServices/DirXIdentityRestService.org to the deployment folder.

  • Configure files security.properties and password.properties in subfolder WEB-INF of the deployment folder as described in the section “Configuring the DirX Identity REST Services”.

  • Create the folder tomcat_install_path/dxilib.

  • Copy the jar file dxmStorageURL.jar from the subfolder shared of the deployment folder to tomcat_install_path/dxilib.

  • If Tomcat runs as a Windows service:

    • Open Tomcat’s configuration program either by selecting "Configure Tomcat" from the Windows start menu, or by starting it directly via tomcat_install_path/bin/Tomcat9w.exe.

    • Open the "Java" tab and then append the full path names of the shared jar files to the "Java Classpath:

      …; tomcat_install_path\dxilib\dxmStorageURL.jar

    • Replace the placeholder tomcat_install_path in the classpath with Tomcat’s installation folder.

  • If Tomcat runs on Windows but not as a Windows service:

    • Create the file tomcat_install_path*\bin\setenv.bat* if it doesn’t exist already.

    • Open the file and extend Tomcat’s classpath manually:

      set CLASSPATH=%CLASSPATH%;
    %CATALINA_HOME%\dxilib\dxmStorageURL.jar;

    • Do not add the new lines and spaces to the classpath. They are added here for better readability only.

    • The file setenv.bat is automatically evaluated by Tomcat.

  • If Tomcat runs on Linux:

    • Create the file tomcat_install_path/bin/setenv.sh if it doesn’t already exist.

  • Open the file and extend Tomcat’s classpath manually:

    CLASSPATH=$CLASSPATH:
$CATALINA_HOME/dxilib/dxmStorageURL.jar:

    • Do not add the new lines and spaces to the classpath.They are added here for better readability only.

    • The file setenv.sh is automatically evaluated by Tomcat.

    • Make sure that the Tomcat service has read access to the created files.

    • Copy the file DirXIdentityRestService.xml to Tomcat’s context descriptor folder and edit and rename it as described in the section “Context Descriptor”.

Testing the REST Services

The folder install_path/restServices/DirXIdentityRestServices/Test contains a zipped web application to test the REST Service requests.The application is a specifically configured instance of the Swagger UI.

Installing the Test Application

Copy the archive DirXIdentityRestService-API.zip to the folder tomcat_install_path/webapps/ROOT.

Change to the folder tomcat_install_path/webapps/ROOT.Extract the files from the archive.Delete the archive.The extracted files are in the folder DirXIdentityRestService-API.

Starting the Test Application

Open a browser (Edge, Firefox, Chrome) and enter http://localhost:8080/DirXIdentityRestService-API (replacing protocol, host, and port as appropriate).

Test Application Files

The folder DirXIdentityRestService-API contains

  • dxi-openapi-docs - A folder with copies of the OpenAPI documents.

  • dxi-config - A folder with the configuration file for the Swagger UI.

  • dxi-layout - A stylesheet, an SVG image, and favorite icons to adapt the layout of the Swagger UI.

  • The files implementing the Swagger UI. The file index.html has been slightly adapted; all other files are the originals.

Changing the REST Services URL

The test application accesses the REST Services by default with the relative URI “/DirXIdentityRestServices-My-Company”. This works fine if you’ve deployed the REST Services into the same Tomcat as the test application, and if your domain is “My-Company”.

You can enter a different URI in the Swagger UI, but since you must redo this every time you reload the UI, it is not a very convenient solution.

So, if your REST Services instance runs on a different Tomcat or your domain name is different, we recommend adapting the URI in the OpenAPI documents in the folder dxi-openapi-docs.

In each document, change the server URL

  "servers" : [ {
    "url" : "/DirXIdentityRestService-My-Company",

as appropriate, for example to

  "servers" : [ {
    "url" : "/DirXIdentityRestService-CustomDomain",

or

  "servers" : [ {
    "url" : "https://alpha.com:8443/DirXIdentityRestService-Custom",

Socket Connections

The REST Services interact with several servers via socket connections.They read the servers’ host names, ports and SSL flags from configuration files or the configuration database.

The host names must be appropriately specified.Names like “localhost” and “127.0.0.1” or simple host names will not work if the REST Services and the server reside on different machines or in different domains.We recommend using fully qualified host names or IP addresses.

Also, if a server is located on a different host than the REST Services, any intermediate firewall must grant the REST Services access to the server port.

Directory Server for Provisioning Sockets

Host, port, and SSL flag are taken from file security.properties.The default ports are 389 for non-SSL connections and 636 for SSL-connections.

Directory Server for Connectivity Sockets

Host, port, and SSL flag are taken from the Provisioning directory. In the DirX Identity Manager, open the view Provisioning → Domain Configuration and select the General tab of the domain object.

The default ports are 389 for non-SSL connections and 636 for SSL connections.

Message Broker Sockets

The REST Services contact the message broker for sending events like password change events or events to notify the Java-based Servers about workflow changes.

Host, port, and SSL flag are taken from the Connectivity directory. In the DirX Identity Manager, open the view Connectivity → Expert View and go to the object Configuration → Services → System → Message Broker index.

The default port is 61616 for non-SSL connections and 61617 for SSL connections.

In a high-availability scenario, ensure access to primary and secondary message brokers.

Java-based Server Sockets

The REST Services contact the Java-based Server, for example, to start approval workflows for object modifications or privilege assignments.

Host, port, and SSL flag are taken from the Connectivity directory.In the DirX Identity Manager, open the view Connectivity → Expert View.For port and SSL flag, go to the object Configuration → Services → System → Java-based Server name.For the host name, open the system object that is referenced on that page.

The default port is 40000 for both SSL and non-SSL connections.

In a high-availability scenario, ensure access to all Java-based Servers.

Configuring the DirX Identity REST Services

This section describes how to configure the REST Services.

Disabling Specific REST Services

The file applicationContext.xml lists the REST services that are enabled in the respective installation:

<jaxrs:serviceBeans>
    <ref bean="approvalResource" />
     <ref bean="workflowResource" />
    <ref bean="ticketResource" />
     <ref bean="domainResource" />
    <ref bean="userCertificationResource" />
    <ref bean="userPasswordResource" />
     <ref bean="userResource" />
    <ref bean="certificationResource" />
    <ref bean="delegationResource" />
    <ref bean="passwordResource" />
     <ref bean="selfResource" />
</jaxrs:serviceBeans>

The following table shows the mapping between services and beans:

Service Beans

Approval Service

approvalResource

Certification Service

certificationResource

Delegation Service

delegationResource

Domain Service

domainResource

Password Service

passwordResource

Self Service

selfResource

Ticket Service

ticketResource

User Certification Service

userCertificationResource

User Password Service

userPasswordResource

User Service

userResource

Workflow Service

workflowResource

If you don’t need particular REST services, just uncomment the corresponding lines. To disable the delegation service and both password services, for example, change the configuration to:

<jaxrs:serviceBeans>
     <ref bean="approvalResource" />
     <ref bean="workflowResource" />
     <ref bean="ticketResource" />
     <ref bean="domainResource" />
     <ref bean="userCertificationResource />
     <!-- <ref bean="userPasswordResource" /> -->
     <ref bean="userResource" />
     < ref bean="certificationResource" />
     <!-- <ref bean="delegationResource" /> -->
     <!-- <ref bean="passwordResource" /> -->
     <ref bean="selfResource" />
</jaxrs:serviceBeans>

Configuring LDAP Access

LDAP access data is used

  • In Spring based HTTP basic authentication via user name and password to identify the user and to verify the password against the DirX Identity Provisioning database. Spring is configured to perform the authentication against the DirX Identity Provisioning database. You may, however, configure Spring to authenticate the user against a different LDAP server.

  • In DirX Identity based HTTP basic authentication via user name or DN and password to identify the user and to verify the password against the DirX Identity Provisioning database. This implementation is usually faster than the corresponding Spring implementation.

  • In certificate-based authentication to find the DirX Identity user that matches the certificate subject. Note that verification of the certificate is handled by Tomcat, not by the REST Services.

  • In DirX Access-based authentication to find the DirX Identity user authenticated by DirX Access.

  • By the REST Services to perform its operations against the DirX Identity Provisioning database.

File security.properties

The general LDAP access parameters are:

  • ldap.domain - The distinguished name of the DirX Identity Provisioning domain; for example, cn=My-Company.

  • ldap.domainadmin - The distinguished name of the domain admin of the DirX Identity Provisioning domain; for example, cn=domainadmin,cn=My-Company.

  • ldap.host - The host name or IP address of the LDAP server for the DirX Identity Provisioning database; for example, localhost.

  • ldap.port - The port number of the LDAP server for the DirX Identity Provisioning database; for example, 389 or 636.

  • ldap.isSSL - Whether to connect to the LDAP server for the DirX Identity Provisioning database via SSL (true), or without SSL (false); this flag is not used by Spring authenticators.

File password.properties

This file contains the password used by the REST Services to connect to the DirX Identity Provisioning domain.

  • ldap.password.domainadmin - The password of the domain admin of the DirX Identity Provisioning domain.

Configuring LDAP Connection Pools

By default, the REST Services establish a connection to the LDAP server each time they authenticate a user or process a request. The connection is closed when user authentication or request processing is finished. Establishing a connection to the LDAP server is a costly operation. With LDAP connection pools, the connections are not created per requests but just once. Each request then takes a connection from the pool and returns it to the pool when finished. This process can significantly improve the performance of authentications and request processing.

The REST Services use up to three different LDAP connection pools:

  • For the authentication providers “dxiLdapUserNameAuthenticationProvider” and “dxiLdapDNAuthenticationProvider”.

  • For the user details service “dxiLdapUserDetailsService”.

  • For request processing.

Each LDAP connection pool supports the following configuration parameters:

  • maxSize - The maximum number of connections in the pool. The default value is 0.

  • initialSize - The initial number of connections in the pool, a number between 0 and the maximum number. The default value is 0.

  • times - The time (in milliseconds) to wait for a free connection from the pool if currently is no free connection available. The default value is 0.

  • rejectOnOverflow - How to react when no connection from the pool is available. If true, the request is rejected with HTTP status code 503 (Server unavailable). If false, an individual connection is established. The default value is true.

To disable a pool, set its maximum size to 0. In this case, an individual connection is created for each request.

Configuring the LDAP Connection Pool for Request Processing

This section describes how to configure the LDAP connection pool for request processing.

File security.properties

We recommend enabling and configuring an LDAP connection pool for request processing:

  • ldap.request.connectionPool - The LDAP connection pool configuration. The sample shows the pre-configured values and, in parentheses, the hardcoded default values:

ldap.request.connectionPool.initialSize      = 50   (0)
ldap.request.connectionPool.maxSize          = 100  (0)
ldap.request.connectionPool.timeout          = 0    (0)
ldap.request.connectionPool.rejectOnOverflow = true (true)

Configuring User Authentication

Before the REST Services start to process a request, the user sending the request is authenticated and mapped to a user in the DirX Identity database. On failure to authenticate or identify the user, the request is rejected.

The REST Services support a variety of authentication methods. These include:

  • Spring HTTP basic authentication with user name and password.

  • HTTP basic authentication with user name or DN and password via proprietary authentication providers.

  • Windows Kerberos authentication.

  • X.509 certificate-based authentication.

  • Authentication by DirX Access.

You can activate one or more authentication methods. If one method fails, the next one is tried. A request is rejected only if all methods fail.

Note that the REST Services ignore the DirX Identity login status attributes: they don’t check whether the authenticated user is locked, and they don’t update login failure attributes on failed or successful login attempts. They also don’t write authentication audit records.

Authentication Entry Point

The authentication entry point is a Java class that handles failed authentication attempts for all supported authentication mechanisms. The class sets:

  • The HTTP response code to 401 (Unauthorized).

  • The HTTP response header "WWW-Authenticate" to "FormBased" if the preferred authentication method is "x509". This prevents browsers from popping up their own HTTP basic login windows.

  • The HTTP response header "WWW-Authenticate" to "FormBased" if the preferred authentication method is "basic“, and the request has been sent by the Business User Interface. This prevents browsers from popping up their own HTTP basic login windows.

  • The HTTP response header "WWW-Authenticate" to "Negotiate" if the preferred authentication method is "kerberos". This triggers browsers to resubmit the request with Kerberos user credentials.

The "WWW-Authenticate" header is not returned if a request fails due to invalid HTTP basic credentials, or if the preferred authentication method is "basic" and the request was not sent by the Business User Interface.

The Business User Interface sets request parameter "AuthMethod" to one of "BASIC", "X509", or "KERBEROS".
File security.xml

The entry point id is assigned to the attribute entry-point-ref of the element http in the file security.xml:

<http entry-point-ref="dxiRestAuthenticationEntryPoint">
. . .
</http>
File security.properties

The preferred authentication method is defined by the property:

  • auth.method.preferred - Either "kerberos" , "x509", or "basic".

Spring HTTP Basic Authentication

HTTP basic authentication is performed by Spring. Spring extracts user name and password from the HTTP request header "Authorization", inserts the user name into an LDAP filter and performs a search in an LDAP directory to unambiguously find the user. If successful, Spring performs a bind with that user’s DN and the password against the same LDAP server to verify the password.

The pre-configured authentication provider described below performs user searches and password verifications against the DirX Identity Provisioning database. Note that Spring allows you to set up additional authentication providers; for example, to match the credentials against different LDAP servers. These providers can be configured in the same way as the pre-configured provider.

File security.xml

The child element http-basic of the element http enables Spring HTTP basic authentication:

<http . . .>
   . . .
   <http-basic/>
   . . .
</http>

The ldap-server element specifies the LDAP server to be contacted for verifying the user credentials:

<ldap-server id="ldapServer"
   url="${ldap.protocol}://${ldap.host}:${ldap.port}/"
   manager-dn="${ldap.domainadmin}"
   manager-password="#{crypt.password}"
/>

  • id - A unique identifier for the server. It is referenced in the ldap-authentication-provider element described below.

  • url - The URL used to contact the LDAP server. The URL contains some placeholders for properties defined in the file security.properties.

  • manager-dn - The DN of the bind credentials with which to perform the search operation. It’s just a placeholder for a property defined in the file security.properties.

  • manager-password - The password of the bind credentials to perform the search operation with. It references a DirX Identity REST Services class with component name crypt that will read the password with key "ldap.password.domainadmin" from the file password.properties.

The child element ldap-authentication-provider of the element authentication-manager specifies how to find a match between a user name from HTTP basic credentials and a user in the specified LDAP server:

<authentication-manager>
  . . .
  <ldap-authentication-provider
    server-ref="ldapServer"
    user-search-filter=
       "(&amp;(cn={0})(objectclass=dxrUser)(dxrState=ENABLED))"
    user-search-base="cn=Users,${ldap.domain}"
    group-search-base="cn=Groups,cn=DirXmetaRole,
                       cn=TargetSystems,${ldap.domain}"
  />
  . . .
</authentication-manager>

  • server-ref - The ID of the ldap-server element defining the LDAP server to be contacted.

  • user-search-filter - The filter for the search to find the matching user. The placeholder "{0}" is replaced with the actual user name from the HTTP basic credentials. The pre-configured filter expects that users perform authentications with their common names.

  • user-search-base - The DN of the base node for the search in the LDAP server.

  • group-search-base - The DN of the base node for the search for groups of which the matching user is a member. Note that the result of this search doesn’t affect the authentication success and request handling in any way. It is simply ignored here.

File security.properties

The additional settings for HTTP basic authentication are:

  • ldap.protocol - Either ldaps when connecting to the LDAP server via SSL or ldap when connecting to the LDAP server without SSL.

  • ldap.groupBase - The DN of the base node of the group tree to be used by Spring for searching groups of which the authenticated user is a member; for example, cn=Groups,cn=DirXmetaRole,cn=TargetSystems. This property is currently unused.

HTTP Basic DN Authentication Provider

The DN authentication provider validates HTTP basic credentials with user DN and password. It first checks whether the user with the given DN exists in the DirX Identity database, and whether the user’s state is ENABLED. Then it verifies the given password by authenticating with user DN and password against the DirX Identity database. The provider supports an LDAP connection pool.

The provider identifier is "dxiLdapDNAuthenticationProvider".

File security.xml

The child element http-basic of the element http enables HTTP basic authentication:

<http . . .>
   . . .
   <http-basic/>
   . . .
</http>

The child element authentication-provider of the element authentication-manager references the DN authentication provider:

<authentication-manager>
  <authentication-provider ref="dxiLdapDNAuthenticationProvider"/>
</authentication-manager>
File security.properties

You can configure whether the credentials are checked by authenticationg against the LDAP server, or by comparing the credential password with the user password in the database. For performance reasons, we recommend using password comparison whenever possible.

  • auth.comparePasswords - Whether to check user credentials by comparing the credential password with the user password (true) or by authenticating against the LDAP server (false). The default value is true.

    auth.comparePasswords = true

We recommend enabling and configuring an LDAP connection pool for the authentication provider:

  • ldap.auth.connectionPool - The LDAP connection pool configuration. The sample shows the pre-configured values and, in parentheses, the hardcoded default values:

ldap.auth.connectionPool.initialSize      = 25   (0)
ldap.auth.connectionPool.maxSize          = 50   (0)
ldap.auth.connectionPool.timeout          = 0    (0)
ldap.auth.connectionPool.rejectOnOverflow = true (false)
The pool is shared with the user name authentication provider.

HTTP Basic User Name Authentication Provider

The user name authentication provider validates HTTP basic credentials with user name and password. The user name is usually the value of an attribute uniquely identifying a user, like common name or email address. The provider checks whether the user with the given name exists in the DirX Identity database, and whether the user’s state is ENABLED. Then it verifies the given password by authenticating with user DN and password against the DirX Identity database. The provider supports an LDAP connection pool.

The provider identifier is "dxiLdapUserNameAuthenticationProvider".

File security.xml

The child element http-basic of the element http enables HTTP basic authentication:

<http . . .>
   . . .
    <http-basic/>
   . . .
</http>

The child element authentication-provider of the element authentication-manager references the user name authentication provider:

<authentication-manager>
 <authentication-provider ref="dxiLdapUserNameAuthenticationProvider"/>
</authentication-manager>
File security.properties

You can configure search base and filter for searching the user:

  • auth.userName.userSearchBase - The DN of the base node for the search in the LDAP server.

  • auth.userName.userFilter - The filter for the search to find the matching user. The placeholder "{0}" is replaced with the actual user name from the HTTP basic credentials. The pre-configured filter expects that users perform authentications with their common names.

    auth.userName.userSearchBase = cn=Users,cn=My-Company
auth.userName.userFilter     = (&(cn={0})(objectclass=dxrUser)(dxrState=ENABLED))

You can also configure whether the credentials are checked by authenticating against the LDAP server, or by comparing the credential password with the user password in the database. For performance reasons, we recommend using password comparison whenever possible.

  • auth.comparePasswords - Whether to check user credentials by comparing the credential password with the user password (true) or by authenticating against the LDAP server (false). The default value is true.

    auth.comparePasswords = true

We recommend enabling and configuring an LDAP connection pool for the authentication provider:

  • ldap.auth.connectionPool - The LDAP connection pool configuration. The sample shows the pre-configured values and, in parentheses, the hardcoded default values:

    ldap.auth.connectionPool.initialSize      = 25   (0)
ldap.auth.connectionPool.maxSize          = 50   (0)
ldap.auth.connectionPool.timeout          = 0    (0)
ldap.auth.connectionPool.rejectOnOverflow = true (false)
The pool is shared with the DN authentication provider.

Certificate-based Authentication

Certificate-based Authentication

Certificate-based authentication is primarily handled by the Tomcat Web application server. If Tomcat has verified the validity of the certificate presented along with a request, it forwards the certificate information to the application handling the request. In our case, Spring then extracts the subject DN from the certificate and passes it to a user details service. The user details service is implemented by a DirX Identity REST Services class. The class tries to unambiguously match the subject DN against a user in the DirX Identity Provisioning database. If successful, the user is authenticated and request handling proceeds. If not, the request is rejected as unauthorized.

Certificate-based authentication requires that the clients connect via HTTP over SSL. Configuring the authentication comprises three steps that correspond to the three components involved: Tomcat, Spring and the user details service.

Configuring Tomcat

See the HTTP connector chapter in your Tomcat documentation for information on how to enable and set up SSL with client certificates; some keywords are "clientAuth" and "SSLHostConfig” and “certificateVerification".

Configuring Spring

The child element x509 of the element http in the file security.xml enables Spring certificate-based authentication:

<http . . .>
   . . .
   <x509 subject-principal-regex="(.*)"
       user-service-ref="dxiLdapUserDetailsService"/>
   . . .
</http>

  • subject-principal-regex - A regular expression that defines which part of the subject DN Spring forwards to the user details service. The implemented user details service expects to get the complete DN, which is matched by the expression "(.*)".

  • user-service-ref - The Spring component name of the user details service. The component name of the implemented user details service is "dxiLdapUserDetailsService".

DirX Access Authentication

For detailed instructions on how to set up a DirX Access PEP for the REST Services, see the DirX Identity Business User Interface Configuration Guide.

We recommend using the user details service provided by the REST Services in connection with DirX Access.

File security.xml

Change the value of property "userDetailService" to "dxiLdapUserDetailsService":

<beans:bean id="preauthAuthProvider" class="...">
  <beans:property name="preAuthenticatedUserDetailsService">
    <beans:bean id="userDetailsServiceWrapper" class="..">
      <beans:property name="userDetailsService" ref="dxiLdapUserDetailsService"/>
    </beans:bean>
  </beans:property>
</beans:bean>
File security.properties

Disable the property with key "auth.userDetails.selectRDN":

#auth.userDetails.valueSelectRDN = cn:1

Configuring the User Details Service

The user details service maps a user who has been authenticated via an external authentication provider to a user in the DirX Identity database. Examples for external authentication providers are the Spring X.509 certificate base authenticator and DirX Access.

The external authentication provider passes an attribute value of the authenticated user to DirX Identity, for example the user’s common name, email address, or the subject DN from the user’s certificate.

The user details service inserts the attribute value into a filter template and performs a search in the DirX Identity Provisioning database to find a matching user. Instead of inserting the entire attribute value, the service may also extract a part of the attribute value and insert just the extracted part into the filter.

File security.properties

You can configure search base and filter for searching the user, and how the filter value is extracted from the provided attribute value:

  • auth.userDetails.userSearchBase - The distinguished name of the root node of the user tree in the DirX Identity Provisioning domain, like cn=Users,cn=My-Company.

  • auth.userDetails.userFilter - The LDAP filter for searching the user in the user tree, like "(cn={0})". The placeholder {0} will be replaced with the actual user filter value obtained from the certificate.

  • auth.userDetails.valueSelectRDN - Extracts the current user filter value by capturing an RDN component value from the certificate subject DN. For example, "cn:1" extracts the value of the first cn (common name), while "sid:-1" extracts the value of the last RDN with type sid. The returned value is unescaped; it will not contain any RDN escape characters.

  • auth.userDetails.valuePattern - Extracts the current user filter value from the certificate subject DN via a regular expression. For example, "^CN=(.?),"* expects the DN to start with "CN=" and returns the value between "CN=" and the next comma. Note that the returned value is not unescaped and common names containing a comma will be incompletely returned. The pattern is ignored if an RDN selector is specified.

We recommend enabling and configuring an LDAP connection pool for the user details service:

  • ldap.userDetails.connectionPool - The LDAP connection pool configuration. The sample shows the pre-configured values and, in parentheses, the hardcoded default values:

ldap.userDetails.connectionPool.initialSize      = 25   (0)
ldap.userDetails.connectionPool.maxSize          = 50   (0)
ldap.userDetails.connectionPool.timeout          = 0    (0)
ldap.userDetails.connectionPool.rejectOnOverflow = true (false)

Configuring Application Logging

This section describes how to configure application logging.

File log4j.properties

Use this file to enable and configure logging of some third-party components like Spring and Castor. The provided sample configuration file activates error logs only and sends the output to a REST Services application-specific file with the name dxiRestServices-Ext.log in Tomcat’s logs folder:

log4j.rootLogger=ERROR, FILE
log4j.appender.FILE=org.apache.log4j.DailyRollingFileAppender
log4j.appender.FILE.File=${catalina.base}/logs/dxiRestServices-Ext.log
log4j.appender.FILE.DatePattern='.'yyyy-MM-dd

The log files rotate once per day. If you deploy more than one REST Services application in the same Tomcat, choose different names for the log files.

File logging.properties

Use this file to enable and configure logging of Apache CXF, the nationalization database and DirX Identity components. The service provides three sample log configuration files:

  • logging-TEST.properties - Activates a reasonable default amount of logging; to be used when developing a REST Service client.

  • logging-DEBUG.properties - Activates extensive logging for debug purposes; to be used when analyzing an issue with a REST Service request.

  • logging-PRODUCTIVE.properties - Activates the writing of error logs only; to be used in a productive environment, or when performing load tests.

The effective log configuration file is logging.properties. To make one of the sample files effective, simply copy it to the file logging.properties.

The sample configurations cause logs to be written to a REST Services application-specific file with the name dxiRestServices.*date.log* in Tomcat’s logs folder:

handlers = 99catalina.org.apache.juli.AsyncFileHandler
99catalina.org.apache.juli.AsyncFileHandler.level = FINE
99catalina.org.apache.juli.AsyncFileHandler.directory = ${catalina.base}/logs
99catalina.org.apache.juli.AsyncFileHandler.prefix = dxiRestServices.

If you deploy more than one REST Services application in the same Tomcat, choose different names for the log files.

File applicationContext.xml

Apache CXF logs the payload (the request or response body) of each request and response. The logged payload will be truncated if it exceeds a maximum size. You can define the maximum size via property "limit" of the CXF logging feature bean:

<jaxrs:features>
    <bean class="org.apache.cxf.ext.logging.LoggingFeature">
        <property name="limit" value="4096"/>
        <property name="sender" ref="dxiCXFLogEventSender"/>
    </bean>
</jaxrs:features>

The payload is only logged if the log level for Apache CXF is set to INFO or higher in file logging.properties.

Configuring the CORS Filter

Browsers traditionally follow a same-origin policy: a web page can send HTTP requests via Javascript only to the server from which the page was loaded. HTTP protocol (http/https), server name and port must coincide.

Since this policy was considered too restrictive for some modern types of web applications, the policy was weakened in newer browsers. Now, a browser may send a request to a different server from the origin. The original server is indicated to the request target in a request header with the name “Origin”. The target server can decide whether to accept or reject the request. Some browsers like Chrome also send “Origin” headers if origin and target server are identical.

The REST Services provide a CORS (Cross-Origin Resource Sharing) filter that handles CORS-related request and response headers. It checks if an incoming cross-origin request is allowed. If not, it rejects the request.

By default, the CORS filter accepts requests with an “Origin” header only if origin and target server coincide (ignoring cases). The only exception is that the default port numbers (80 and 443) might be left out.

If the client is the Business User Interface, for example, then the origin header is comprised of the protocol, server name, and port used to access the Business User Interface. The Business User Interface accesses the REST Services via a configurable protocol, server name, and port. The following table lists some matching and some non-matching origins:

Business User Interface REST Services Match

http://alpha:8080

http://alpha:8080

yes

http://alpha

http://alpha

yes

https://alpha.beta.com

https://alpha.beta.com

yes

http://alpha

http://alpha:80

yes

https://alpha.beta.com:443

https://alpha.beta.com

yes

http://alpha:8080

http://alpha.beta.com:8080

no

https://alpha

http://alpha

no

http://alpha

https://alpha

no

http://alpha:8080

http://192.133.456.654:8080

no

http://127.0.0.1:8080

http://localhost:8080

no

http://alpha:8080

http://alpha:8082

no

Activating the CORS Filter

The CORS filter is activated by adding it as a custom filter to the Spring HTTP bean in file WEB-INF/security.xml:

<http use-expressions="true" create-session="stateless" ...>
    . . .
    <custom-filter ref="corsFilter" after="PRE_AUTH_FILTER" />
    . . .
</http>
You cannot simply remove the filter here since the filter takes care of properly returning CORS related response headers even in cases of non-cross-origin requests.

Configuring the CORS Filter

The filter allows you to configure the origins it accepts in the file WEB-INF/security.properties.

You can either list the accepted origins explicitly in the configuration parameter “cors.accessControl.acceptedCrossOrigins”:

cors.accessControl.acceptedCrossOrigins =
                http://alpha:8080, https://alpha

Or you can define one or more regular expressions matching the accepted origins:

cors.accessControl.acceptedCrossOriginPatterns =
          https?://alpha([.]beta[.]com)?(:8080|:8443)?

The above sample accepts origins with protocol “http” or “https” host name “alpha” or “alpha.beta.com” and with port “8080”, “8443”, or no port at all.

Separate the origins and expressions by commas. For the syntax of the regular expressions, see the Java API documentation of package “java.util.regex”.

You can effectively disable the CORS filter by setting the pattern list to

cors.accessControl.acceptedCrossOriginPatterns = .*

Logging

You can enable filter logging in file WEB-INF/classes/logging.properties. The filter’s package name is “com.dirxcloud.dxi.rest.filter”:

# CORS filter
com.dirxcloud.dxi.rest.filter.level = FINEST

Supported log levels are “FINEST” for detailed logging and “SEVERE” for error logging.

If the log level is set to “SEVERE”, the filter logs just rejected requests:

Cross origin request rejected
Origin header: http://alpha.beta.com:8082
Protocol, server, and port from request URI:
              http://alpha.beta.com:8080

Here, the request is rejected because the port numbers are different.

Configuring REST Services Operations

The configuration is divided into the following components:

  • General configuration - Settings that are independent of any resource type or relation.

  • Resource type configuration - Settings for specific resource types, like "User" or "Role".

  • Relation configuration - Settings for relationships between entries, like the manager of a user or the owner of a role.

  • Approval service configuration - Settings for approval service requests.

  • Change password configuration - Settings for change password operations.

  • Search configuration - Settings for search operations.

General Configuration Parameters

The general configuration parameters are contained in the Java property file domain.properties.

As usual, replace special characters in property values with their UTF-8 representation prefixed with a backslash and the letter "u", for example "\u0020" for a space.

Displaying DNs

The REST Services sometimes return display values for DNs; for example, when reading role parameter values of type HDN:

{
   "uid": "uid-7f001-6f26d110-11da5aeefcf--76db",
   "display": "A115, A11, A1, Cost Locations, Groups, SAP R3, TargetSystems",
   "value": "cn=A115,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,cn=SAP R3,
             cn=TargetSystems,cn=My-Company"
}

The following configuration parameters control the representation of the display names:

  • dn.display.delimiter - The delimiter between adjacent RDNs. The default value is a comma followed by a space: ",\u0020".

  • dn.display.domainSize - The number of RDNs of the domain root. The default value is 1.

  • dn.display.includeDomain - Whether (true) or not (false) to include the domain root in the display name. The default value is false.

  • dn.display.includeTypes - Whether (true) or not (false) to include the RDN types in the display name. The default value is false.

Size and Time Limits

The following parameters define fallback size and time limits for search and list operations. In many cases, the size limits can be overridden per operation.

  • search.timeLimit - The time limit for search operations (in seconds). Default: 300 seconds.

  • search.defaultCount - The default size limit for search operations. Default: 250.

  • search.maxCount - The maximum size limit for search operations. Default: 1000.

  • search.affectedUsers.maxCount - The maximum size limit for listing the users of a privilege via privilege property "affectedUsers". Default: 1000.

  • search.pagedMaxCount - The maximum number of entries read from LDAP via a paged search. When a paged search hits the maximum number of entries, the readable entries found so far are returned to the client together with a size limit exceeded flag. See section "Search Operations" for details. Default: 1000.

  • search.linkFilter.maxCount - The maximum size limit for searching users or privileges matching the filter value for the initiator, subject, or resource of a workflow or ticket. A value less than 1 disables the search. Default: 50.

Access Rights Handling

Access policies can restrict the rights to read or modify an entry to a specific subset of the entry’s attributes. By default, the REST Services respect these policies.

  • accessRights.ignoreReadAttributePolicies - Whether to respect (false) or ignore (true) read attribute policies when reading an entry.

  • accessRights.ignoreModifyAttributePolicies - Whether to respect (false) or ignore (true) modify attribute policies when updating an entry.

  • accessRights.alwaysReadableAttributes - The list of attributes (a comma-separated list of LDAP attribute names) that are always returned by the REST Services no matter what the attribute access policies prescribe.

  • accessRights.maskValueAttributes - The list of attributes whose values should be replaced with three asterisks (*) when being returned to a client. The parameter is evaluated when returning data from a ticket or a workflow.

Attribute access policies must be enabled in the domain configuration.
Workflow Operation Settings

After having finished a workflow task, an attempt to read the next open task might fail because the workflow engine needs some time to calculate the new workflow state. Therefore, the REST Services try to read the next open task several times.

  • workflows.getNextTask.maxNumAttempts - The maximum number ot attempts to read the next open task of a running workflow; the default value is 10.

  • workflows.getNextTask.secondsBetweenAttempts - The number of seconds to wait between two subsequent attempts; the default value is 3.

Before reading a running workflow task, the REST Services locks the workflow to prevent simultaneous changes by another request or application. If locking the workflow fails, the REST Services wait some time before trying to lock the workflow again.

  • workflows.getRunningTask.maxNumAttempts - The maximum number ot attempts to lock the workflow; the default value is 2.

  • workflows.getRunningTask.secondsBetweenAttempts - The number of seconds to wait between two subsequent attempts; the default value is 3.

Before updating a running workflow task, the REST Services locks the workflow to prevent simultaneous changes by another request or application. If locking the workflow fails, the REST Services wait some time before trying to lock the workflow again.

  • workflows.updateTask.maxNumAttempts - The maximum number ot attempts to lock the workflow; the default value is 2.

  • workflows.updatetTask.secondsBetweenAttempts - The number of seconds to wait between two subsequent attempts; the default value is 3.

When listing workflow definitions, you can prevent specific workflow definitions from being returned by defining exclude filters.

  • workflows.listDefinitions.filter.exclude - A map of combinations of subject type and operation to exclude filters. The default map is empty.

You can also define which workflow definitions are being returned as self-registration workflows:

  • workflows.listDefinitions.filter.selfRegistration - A map of subject types to include filters. The default map is empty.

The values of some request workflow and activity attributes are expressions to be replaced with nationalized texts at runtime.

  • nationalization.defaultLanguage - The default langage for nationalizing workflow and activity attributes; the default value is "en".

  • nationalization.supportedLanguages - The comma-separated list of languages supported for nationalizing workflow and activity attributes; the default value is "en,de".

LDAP Lock Settings

Before an entry in the database is modified, it is locked to prevent issues due to concurrent modifications. If the entry is already locked, the modification operation fails with a corresponding error code. By setting the flag ldapLock.interactiveMode to false, you can instruct the REST Services to repeatedly try to get the lock. For more details, see the LDAP lock manual pages.

  • ldapLock.interactiveMode - Whether the REST Services runs in interactive mode (true) or not (false); default value is true.

Resource Type Configuration

A resource type corresponds to a DirX Identity object type. Its configuration includes the information that is required to process REST Services requests for entries of the resource type.

The resource type configurations are contained in the section "ResourceTypes" in the JSON file resources.json. Each of its subsections describes a particular resource type. The name of a subsection is the name of the corresponding resource type.

"ResourceTypes" : {
 "User": {
   "odName" : "dxrUser",
   "path"   : "Users",
  "attributes": {
    "namingAttribute" : "{::sn}{ ::givenName}",
    "link.displayName": "{::givenName}{ ::sn}",
    "name.formatted"  : "{::dxrSalutation}{ ::givenName}{ ::sn}"
  },
   "read" : {
     "mandatoryAttributes": ["id", "externalId", "meta", "dn"],
     "defaultAttributes"  : ["name", "userName", "phoneNumbers", "emails", "c"],
     "defaultAccessRights": ["entry", "attributes"]
   },
   "me" : {
     "extends"            : "read",
     "defaultAccessRights": ["menus", "entry", "attributes"],
     "defaultMenuKeys"    : ["SelfService", "TeamMgt", "UserMgt", "RoleMgt",
                            "Worklist", "Delegation"]
   },
   "search" : {
     "base"               : "cn=Users",
     "filter"             : "(objectClass=dxrUser)",
     "mandatoryAttributes": ["id", "externalId" , "meta" , "dn"],
     "defaultAttributes"  : ["name", "userName", "phoneNumbers", "emails", "c"],
     "acpAttributes"      : ["manager", "dxrSponsor"],
     "additionalFilter"   : "",
     "excludedTypes"      : [],
     //"excludedTypes"      : ["dxrUserFacet", "dxrPersona", "dxrFunctionalUser"],
     "defaultCount"       : 250,
     "maxCount"           : 1000,
     "sortBy"             : ["sn", "givenName"],
     "sortOrder"          : ["ascending", "ascending"]
   },
   "managedUsers" : {
     "extends"            : "search",
     "defaultCount"       : 100
   },
   "managedTeam" : {
     "extends"            : "search",
     "additionalFilter"   : "(manager={me})",
     //"additionalFilter"   : "(|(manager={me})(l={me.l}))",
    "defaultCount"       : 100,
    "delegatorTeams" : {
      "include"          : true,
      "operations"       : [ "grant" ],
      "depth"            : 3
   },
   },
   "users" : {
    "extends"            : "search",
    "defaultCount"       : 100,
    "linkAttributes"     : ["manager", "secretary", "owner", "dxrSponsor",
                            "dxrRepresentative", "dxrContactLink"]
  },
   // closedRequests, pendingRequests
  "requests" : {
    "subjectTypes"       : ["dxrUser", "dxrUserFacet", "dxrPersona",
                            "dxrFunctionalUser"]
   }
 },
 …
}

A resource type comprises some general parameters, one or more read configurations, one or more search configurations, and optionally some configuration parameters for specific requests.

General Settings

Resource type configuration general settings include:

  • odName - The name of the relevant object description.

  • acpResourceType - The relevant access policy resource type. In most cases, the access policy resource type is identical to the object description name. Therefore, the object description name serves as the default. But some cases are different. For example, the object description name for groups is "svcGroups", while the access policy resource type is "dxrTargetSystemGroup".

  • path - The URI path for reading an entry of this resource type via a REST Services request. The paths currently supported by the REST Services are "Users" and "DomainObjects".

Attributes

The attributes section can be used to customize how values of specific attributes are returned in responses. It maps attribute names to formats that may contain fixed and variable parts. For a simple attribute, there’s just one variable part for the attribute value. For attributes composed of several sub-attributes, there’s one variable part for each sub-attribute.

A variable part is enclosed in curly brackets "{…​}". Each variable part consists of up to 4 sub-parts, delimited by colons:

  • delimiter - An optional prefix for the attribute value. The delimiter is ignored if it would become the first part of the total value.

  • prefix - Another optional prefix for the attribute value.

  • attributeName - The name of the attribute or sub-attribute. It is replaced with the attribute value.

  • suffix - An optional suffix for the attribute value.

If the attribute value is empty, the variable part is ignored.

The following configuration for resource type "User" defines specific formats for the display name of link attributes, the sub-attribute "formatted" of SCIM attribute "name", and the description:

"attributes": {
   "link.displayName": "{::givenName}{ ::sn}",
   "name.formatted"  : "{::dxrSalutation}{ ::givenName}{ ::sn}",
   "description"     : "PRE1-{:PRE2-:description:-SUF1}-SUF2",
}

For a user with surname “Taspatch”, given name “Nik”, salutation “Mr.” and description “Chief Information Technology”, this results in

    "link.displayName": "Nik Taspatch"
    "name.formatted"  : "Mr. Nik Taspatch"
   "description"     : "PRE1-PRE2-Chief Information Technology-SUF1-SUF2"

For a user with surname “Taspatch” and salutation “Mr”, but without given name and description, the result is

    "link.displayName": "Taspatch"
    "name.formatted"  : "Mr. Taspatch"
    "description"     : <no value>

You can even use artificial attribute names:

"attributes": {
   "myUserName": "{::givenName}{ ::sn}{, ::title}"
}

To include the targetsystem name in the display name of group links, use for example

"attributes": {
   "link.displayName": "{::cn}{ - ::targetsystem.cn}"
}
You cannot use these representations in any kind of input data like search filters or patch operations.
Read

A read configuration controls operations to read an entry. Each resource type has a default read configuration with the identifier "read". A resource type may also support additional read configurations. The only additional configuration currently supported is "me" for resource type "User".

  • extends - For additional read configurations only. The value must be "read".

  • defaultAttributes - The attributes to return in addition to the mandatory attributes. You can use LDAP or SCIM attribute names. The parameter applies only to requests that do not provide the corresponding request parameter "attributes".

  • mandatoryAttributes - The minimum set of attributes to return, given by their LDAP or SCIM attribute names.

  • defaultAccessRights - The types of access rights to return. The supported types are "entry" and "attributes". The read configuration "me" also supports type "menus".

  • menuAccessRights - The names of the menus to be included in the menu access rights. Supported only by the read configuration "me".

Search

A search configuration controls operations to search entries. Each resource type has a default search configuration with the identifier "search". A resource type may also support additional search configurations. The only additional configurations currently supported are "managedTeam" and "managedUsers" for resource type "User".

  • extends - For additional search configurations only. The value must be "search".

  • defaultAttributes - The attributes to return in addition to the mandatory attributes. You can use LDAP or SCIM attribute names. The parameter applies only to requests that do not provide the corresponding request parameter "attributes".

  • mandatoryAttributes - The minimum set of attributes to return, given by their LDAP or SCIM attribute names.

  • defaultAccessRights - The types of access rights to return. The supported types are "entry" and "attributes".

  • acpAttributes - Additional attributes (a comma-separated list of LDAP attribute names) to be read from the LDAP server to avoid having to read each result entry separately for access policy evaluation. This parameter may speed up the operation’s performance significantly. Good choices when searching users in the DirX Identity sample database are "manager" and "dxrSponsor".

  • base - The DN of the default search base relative to the domain root. The setting can be overridden per request by the request parameter "base". If the search base is left unspecified in a request, the REST Services will also try to derive the search base from resource type components in the search filter before taking the default search base.

  • additionalFilter - An additional search filter.The filter supports the following expressions that are evaluated at runtime:

    • {me} - The DN of the authenticated user.

    • {me.dn} - The DN of the authenticated user.

    • {me.property_name} - The first value of the property with the specified name of the authenticated user; for example, "{me.ou}" for the user’s organizational unit.

  • excludedTypes - A list of object classes to be excluded from the result.

  • defaultCount - The number of users to return. The setting can be overridden per request with the request parameter "count". The value must be a positive integer. The hard-coded default value is 250.

  • maxCount - The maximum number of users to return, which is an upper limit for the request parameter "count" and the configuration parameter "defaultCount". Requests never return more than the maximum number of entries. The value must be a positive integer. The hard-coded default value is 1000.

  • pagedMaxCount - The maximum number of entries read from LDAP via a paged search. When a paged search hits the maximum number of entries, the readable entries found so far are returned to the client together with a size limit exceeded flag. See section "Search Operations" for details. The hard-coded default value is 1000.

  • strategies - The set of search strategies that applies for searches for this resource type. Accepted values are "accessPolicies", "paged", and "singlePage". The default value is ["accessPolicies", "paged"]. The values are case-sensitive, the value order is irrelevant. See section "Search Operations" for details.

  • sortBy - The attributes by which to sort the result. The setting can be overridden per request with the request parameter "sortBy".

  • sortOrder - The sort order per sort attribute, either "ascending" or "descending". The setting can be overridden per request with the request parameter "sortOrder".

Users

The configuration extends the search configuration to set specific parameter values for the domain service operation "/DomainObjects/users".

The operation returns the list of users referencing a given entry; for example, the users whose attribute "dxrLocationLink" matches a given location. Parameter "linkAttributes" defines the list of user attributes that might contain a reference to the given entry.

  • linkAttributes - The list of user attributes to be checked for an entry reference.

Resource Type User

ManagedTeam

The configuration is a search configuration which applies to the self-service operation "/Me/managedTeam".

The managed team of the authenticated user might include the managed teams of users who have directly or indirectly delegated operations to the authenticated user.

  • delegatorTeams - The delegator teams to be included:

  • include - Whether (true) or not (false) to include delegator teams. The default value is true.

  • operations - The list of delegation operations to consider, like "grant" and "approve". The default list includes "grant" only.

  • depth - The recursion depth. A depth of 1 indicates to include only the teams of direct delegators who have delegated one or more of the operations to the authenticated user. A depth of 2 indicates to also include the managed teams of those users who are direct delegators of the direct delegators of depth 1, and so on. The default value is 3, the maximum value is 10.

ManagedUsers

The configuration is a search configuration which applies to the user service operation "/Users/{userId}/managedUsers".

Requests

User and self service provide some operations to search and read pending or closed profile and privilege change requests.

The configuration lets you restrict the subject types of the workflows and tickets for the profile and privilege changes.

  • subjectTypes - The default list of subject types (attribute "dxrObjectType") of the relevant tickets and workflows. If the list is empty, any subject type is accepted.

Resource Type FunctionalUser

AssignedFunctionalUsers

The configuration is a search configuration which applies when searching for functional users via the self-service operations "/Me/users" and "/Me/functionalUsers" and the user service operations "/Users/{userId}/users" and "/Users/{userId}/functionalUsers".

Resource Type Persona

AssignedPersonas

The configuration is a search configuration which applies when searching for personas via the self-service operations "/Me/users" and "/Me/personas" and the user service operations "/Users/{userId}/users" and "/Users/{userId}/personas".

Resource Type UserFacet

AssignedUserFacets

The configuration is a search configuration which applies when searching for user facets via the self-service operations "/Me/users" and "/Me/userFacets" and the user service operations "/Users/{userId}/users" and "/Users/{userId}/userFacets".

Resource Type Role

AssignableRoles

The configuration is a search configuration which applies when searching for assignable roles via the self-service operations "/Me/assignableRoles" and "/Me/assignablePrivileges" and the user service operations "/Users/{userId}/assignableRoles" and "/Users/{userId}/assignablePrivileges".

AssignedRoles

The configuration is a search configuration which applies when searching for assigned roles via the self-service operations "/Me/roles" and "/Me/privileges" and the user service operations "/Users/{userId}/roles" and "/Users/{userId}/privileges".

AssignedRole

The configuration is a read configuration which applies when reading roles via the self-service operations "/Me/roles/{assignmentId}" and "/Me/privileges/{assignmentId}" and the user service operations "/Users/{userId}/roles/{assignmentId}" and "/Users/{userId}/privileges/{assignmentId}".

Resource Type Permission

AssignablePermissions

The configuration is a search configuration which applies when searching for assignable permissions via the self-service operations "/Me/assignablePermissions" and "/Me/assignablePrivileges" and the user service operations "/Users/{userId}/assignablePermissions" and "/Users/{userId}/assignablePrivileges".

AssignedPermissions

The configuration is a search configuration which applies when searching for assigned permissions via the self-service operations "/Me/permissions" and "/Me/privileges" and the user service operations "/Users/{userId}/permissions" and "/Users/{userId}/privileges".

AssignedPermission

The configuration is a read configuration which applies when reading permissions via the self-service operations "/Me/permissions/{assignmentId}" and "/Me/privileges/{assignmentId}" and the user service operations "/Users/{userId}/permissions/{assignmentId}" and "/Users/{userId}/privileges/{assignmentId}".

Resource Type Group

AssignableGroups

The configuration is a search configuration which applies when searching for assignable groups via the self-service operations "/Me/assignableGroups" and "/Me/assignablePrivileges" and the user service operations "/Users/{userId}/assignableGroups" and "/Users/{userId}/assignablePrivileges".

AssignedGroups

The configuration is a search configuration which applies when searching for assigned groups via the self-service operations "/Me/groups" and "/Me/privileges" and the user service operations "/Users/{userId}/groups" and "/Users/{userId}/privileges".

AssignedGroup

The configuration is a read configuration which applies when reading groups via the self-service operations "/Me/groups/{assignmentId}" and "/Me/privileges/{assignmentId}" and the user service operations "/Users/{userId}/groups/{assignmentId}" and "/Users/{userId}/privileges/{assignmentId}".

Relation Configuration

A relation corresponds to a DN link attribute. It controls how the proposal list for the value(s) of a DN link attribute is retrieved from the database and sent to the REST Services client.

The relation configurations are contained in the section "Relations" in the JSON file resources.json. Each of its subsections describes one or more relation.

"Relations" : {
   "managers,owners" : {
       "resourceType" : "User",
       "search" : {
           "additionalFilter" :
               "(&(dxrState=enabled)(|(sn=*{value}*)(givenName=*{value}*)))"
       }
   },
   "owners_for_role" : {
       "resourceType" : "User",
       "search" : {
           "searchBase" : "o=My-Company,cn=Users,{domain}"
           "additionalFilter" :
               "(&(dxrState=enabled)(|(sn=*{value}*)(givenName=*{value}*)))"
       }
   }
}

A relation can have any name but should correspond to one of the patterns "<attribute name>_for_<resource type>" and "<attribute name>". The second pattern defines the fallback for the first one. If a client requests the proposal list for "owners_for_role" and no relation with that name is found, the relation with the name "owners" applies.

You can map more than one name to the same configuration by separating the names with commas, like "managers,owners".

A relation specifies the resource type of the proposals and the configuration parameters for searching the proposals.

  • resourceType - The name of the resource type of the proposals.

  • search - The search configuration parameters.By default, the search configuration of the resource type applies.Search configurations for relations, however, support some additional filter expressions:

    • additionalFilter - An additional search filter.The filter supports the following expressions that are evaluated at runtime:

      • {me} - The DN of the authenticated user.

      • {me.dn} - The DN of the authenticated user.

      • {me.propertyName} - The first value of the property with the specified LDAP attribute name of the authenticated user; for example, "{me.ou}" for the user’s organizational unit.

      • {target} - The DN of the target entry.The target is the entry with the DN link attribute for which the proposal list is requested.

      • {target.dn} - The DN of the target entry.

      • {target.propertyName} - The first value of the property with the specified name of the target entry; for example, "{target.o}" for the entry’s organization.

      • {value} - The search value provided by the REST Services client to restrict the proposal list.

      • {domain} - The DN of the domain root node.

Approval Service Operations

The file approval.properties includes several configuration parameters that control aspects of task list and approval operations:

  • worklist.sizelimit - The maximum number of approval requests that can be contained in one bulk approval request package. This parameter is used when a bulk approval command is executed. If a bulk command contains a large number of approval requests, the REST Services split the request into packages that each contain at a maximum the number of requests defined in this parameter. For example, if there are 3,420 approval requests and worklist.sizelimit is set to 1000, the REST Services execute this command in 4 rounds: 1,000, 1,000, 1,000 and 420 requests. The hard-coded default value is 100.

  • worklist.countSizelimit - The size limit when counting the number of open tasks for the authenticated user. The default value is 1000.

  • worklist.initiatorDetailAttributes - The attributes to be returned for initiators of tasks when requesting a task list, specified as a comma-separated list of LDAP attribute names. The hard-coded default value is an empty list.

  • worklist.resourceDetailAttributes - The attributes to be returned for resources of tasks when requesting a task list, specified as a comma-separated list of LDAP attribute names. The hard-coded default value is an empty list.

  • worklist.subjectDetailAttributes - The attributes to be returned for subjects of tasks when requesting a task list, specified as a comma-separated list of LDAP attribute names. The hard-coded default value is an empty list.

Change Password Operations

The file password.properties contains the PINs used by the REST Services for password encryption and decryption.

  • encryption.pin - The PIN used to encrypt and decrypt user passwords when encryption mode is enabled.

  • encryption.previousPin - The PIN previously used to encrypt and decrypt passwords when encryption mode is enabled.

Search Operations

As of version 8.10SP2, the REST Services implement three different strategies for searching entries in the LDAP database:

  • Access policy-based searches.

  • Paged searches.

  • Single page searches.

The Rest Service uses an access policy-based search whenever possible. If that is not possible, it will try a paged search. If paged searches are disabled or if the limit of simultaneous paged search requests is reached, the Rest Service will fall back on a single page search.

Previous versions supported only single page searches.

Access Policy-Based Searches

An access policy-based search evaluates the access policies to perform one or more LDAP searches with filters extended by access policy resource filters.

  • Pros

    • It is usually much faster than a paged or single page search.

    • The requested size limit ("count") works as expected.

  • Cons

    • It supports only searches with scope subtree.

    • It does not support sort attributes ("sortBy").

    • It ignores the default sort attributes configured in file resources.json.

    • The Rest Service must be able to determine the resource type of the requested entries, either via the request path (like "/Users") or, for path "/DomainObjects", from a single "meta.resourceType" in the search filter.

    • Works only if the requested entries are controlled by access policies.

Paged Searches

A paged search operation gets the entries from LDAP page by page (usually with page size 300). The entries in each returned page are then checked one by one if the authenticated user is allowed to read them. Non-readable entries are removed from the result. If the total number of readable entries hits the requested size limit, the paged LDAP search is cancelled, and the result list is returned to the Rest Service client.

  • Pros

    • It works for all search requests.

    • If sorting is requested, the result list contains the first entries according to the sort criteria.

  • Cons

    • Checking the access rights per entry is usually slow.

    • Since one cannot say in advance on which pages the readable entries are returned, the negative effects on performance are often significant. As a compromise, the Rest Service reads only a certain number of entries from LDAP and cancels the paged LDAP search when hitting this limit. In that case, the result returned to the Rest Service client might be incomplete.

    • The LDAP server supports only a limited number of simultaneous paged searches. If the limit is exceeded, requests will fall back on single page searches.

Single Page Searches

A search operation performs a simple (non-paged) LDAP search with the requested size limit (count). Due to the limit, the search result is often incomplete. The entries in the search result are then checked one by one if the authenticated user is allowed to read them. Non-readable entries are removed from the result. The remaining result is returned to the Rest Service client.

  • Pros

    • It works for all search requests.

  • Cons

    • The result of the Rest Service search request often contains less entries than the requested size limit, although the authenticated user might be allowed to read many more entries matching the search criteria, which just happened to be not returned by the LDAP search due to the size limit.

    • Checking the access rights per entry is often slow. But as only one LDAP search is done, the negative effects on performance are limited.

    • If sorting is requested, the result list is sorted, but the list contains an arbitrary subset of all matching entries in the database, not necessarily the first ones according to the sort criteria.

Strategy Selection Details

An access policy-based search is selected if

  • Access policies are enabled in the domain configuration.

  • The request specifies a unique resource type in its path or the search filter.

  • Search strategy "accessPolices" is enabled for the resource type in file resources.json.

  • The resource type configuration in file resources.json specifies an access policy resource type ("acpResourceType") or an object description name ("odName").

  • The corresponding objects are subject to access policies.

  • The request search scope is "subtree".

  • The request doesn’t specify any sort attributes ("sortBy").

A paged search is selected if

  • The access policy-based search is not selectable.

  • If the request specifies a unique resource type and the search strategy "paged" is enabled for that resource type in the file resources.json.

  • If the request does not specify a unique resource type and the search strategy "paged" is enabled for resource type "Any" in the file resources.json.

A single page search is selected if

  • The access policy-based search and the paged search are not selectable.

  • If a paged search failed since the LDAP server’s limit for simultaneous paged searches had been exceeded.

Configuration Parameters

Size limit parameters in the file domain.properties:

  • search.maxCount - The maximum size limit for search operations. Default: 1000.

  • search.pagedMaxCount - The maximum number of entries read from LDAP via a paged search. When a paged search hits the maximum number of entries, the readable entries found so far are returned to the client together with a size limit exceeded flag. Default: 1000.

Search parameters in resource type section "search" in the file resources.json:

  • pagedMaxCount - The maximum number of entries read from LDAP via a paged search. When a paged search hits the maximum number of entries, the readable entries found so far are returned to the client together with a size limit exceeded flag. The hard-coded default value is 1000.

  • strategies - The set of search strategies to apply for searches for this resource type. Accepted values are "accessPolicies", "paged", and "singlePage". The default value is ["accessPolicies", "paged"]. The values are case-sensitive, the value order is irrelevant. Some examples:

    • ["accessPolicies", "paged"] - Perform an access policy-based search if possible. Otherwise, try a paged search. If that fails, fall back on a single page search. This is also the default set.

    • ["accessPolicies"] - Perform an access policy-based search if possible. Otherwise, fall back on a single page search.

    • ["paged"] - Try a paged search. If that fails, fall back on a single page search.

    • ["singlePaged"] - Do a single page search.

    • [] - As ["accessPolicies", "paged"].

Affected Operations

The strategy selection affects the following operations:

  • GET /DomainObjects

  • POST /DomainObjects/search

  • POST /DomainObjects/{entryId}/search

  • GET /Me/certificationCampaigns

  • GET /Me/delegations

  • GET /Me/delegations/assignedDelegations

  • GET /Me/managedTeam

  • GET /Users

  • GET /Users/managedUsers

Objects and Attributes

The REST Services support SCIM notation and LDAP notation for accessing object attributes.

In the sample JSON requests and responses listed in this chapter, some lines are wrapped for better readability.

LDAP Attributes

LDAP attribute names in query parameters or request bodies of REST Services operations are case-insensitive, while the services always return lowercase attribute names in responses.

JSON Representations

This section describes JSON representations of objects and attributes.

Attributes of Type String

String values are represented in JSON as strings enclosed in double quotes, for example:

"description": "Chief Information Technology"

Each double quote or backslash within a value is escaped by a backslash:

"description": "Manager of \"DEV APP\""
"description": "Manager with a back\\slash"

A value may also contain special characters line new lines and tabs, which are represented by "\n", "\r", "\t" etc., like in:

"description": "Chief Information Technology\nLine\t2\r\nManager of \"DEV APP\""
Attributes of Type Boolean

Boolean values are represented in JSON as Boolean values true and false, for example

"dxrpwdreset": true
Attributes of Type Integer

Integer values are represented in JSON as Numbers without decimal point, for example

"dxrpwdfailurecount": 4

When modifying an entry, negative values must be represented in as Strings, for example

"dxrpwdfailurecount": "-4"
Attributes of Type Double

Double values are represented in JSON as Numbers with or without decimal point, for example

"dxrcompriskscore": 666.0
"dxrcompriskscore": -666.56
"dxrcompriskscore": 555
Attributes of Type GeneralizedTime

Generalized time values are UTC times, represented in JSON as Strings in the following format: "YYYY-MM-DDTHH:mm:ss[.SSS]Z".

"dxrEndDate": "2018-01-22T12:30:00Z"
"dxrEndDate": "2018-01-22T12:30:00.000Z"
"dxrEndDate": "2017-12-31T00:20:15.512Z"

The letter "T" separates date and time, while the final "Z" indicates UTC time. The milliseconds are optional.

The format conforms to ISO 8601. It is also used by the JavaScript method Date.toJSON.

Attributes of Type IDMTimeinterval

Time intervals are represented in JSON as objects with the following sub-attributes:

  • years - the number of years.

  • months - the number of months.

  • days - the number of days.

  • hours - the number of hours.

  • minutes - the number of minutes.

  • seconds - the number of seconds.

  • milliseconds - the number of milliseconds.

All numbers are integers; sub-attributes with value 0 are omitted.

"dxrreapprovalperiod": {
   "months":4,
   "days":12,
   "years":1
}

"dxrcertificationperiod": {
   "months":9
}
Link Attributes

A link attribute is an attribute referencing one or more other objects in the database. Its values in the database are the distinguished names of the referenced objects. The value representation used by the REST Services depends on the attribute’s type in the relevant object description, and on the REST Services operation.

Read and Search Operations

If the attribute is defined as String (like for example user attribute dxrRoleLink), the values are by default simply the distinguished names of the referenced objects. When requesting the attribute with extension ".link", however, the attribute is handled like StorageObject attributes.

If the attribute is defined as StorageObject, the values are represented in the same way as SCIM attribute manager. The sub-attributes correspond to LDAP attributes as follows:

  • value - dxruid

  • $ref - an HTTP link to read manager details; the link includes the link’s dxruid.

  • displayName - The displayName is determined according to the following rules in descending precedence:

    • The LDAP attribute displayName; if defined and not empty.

    • If the linked object is a persona or a user facet: the object’s cn.

    • If the linked object is a user: the user’s givenName and sn, separated by a space.

    • The DXI pseudo-attribute $displayname.

You can request additional attributes for the referenced entries like shown in the following samples.

Reading a user with requested attribute "secretary":

"secretary": {
 "displayName": "Retha Wagner",
 "value": "uid-7f001-6f26d110-11da5aeefcf--7ff8",
 "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                              Users/uid-7f001-6f26d110-11da5aeefcf--7ff8"
}

Reading a user with requested attributes "secretary.description" and "secretary.manager":

"secretary": {
 "manager":
 {
   "displayName":"Gabriela Morton",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ffd",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Users/uid-7f001-6f26d110-11da5aeefcf--7ffd"
 },
 "displayName":"Olivier Hungs",
 "description":"General Manager",
 "value":"00014281",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/Users/00014281"
}

Reading a user with requested attributes "secretary.description" and "secretary.manager.mail":

"secretary": {
 "manager":
 {
   "mail":
   [
     "Gabriela.Morton@My-Company.com"
   ],
   "displayName":"Gabriela Morton",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ffd",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Users/uid-7f001-6f26d110-11da5aeefcf--7ffd"
 },
 "displayName":"Olivier Hungs",
 "description":"General Manager",
 "value":"00014281",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/Users/00014281"
}

Reading a user with requested attribute "dxrGroupLink":

"dxrgrouplink":
[
 "cn=CertificationCampaignAdmins,cn=Groups,cn=DirXmetaRole,
   cn=TargetSystems,cn=My-Company",
 "cn=DataProviders,cn=Groups,cn=DirXmetaRole,
   cn=TargetSystems,cn=My-Company"
]

Reading a user with requested attribute "dxrGroupLink.link":

"dxrgrouplink":
[
 {
   "displayName":"CertificationCampaignAdmins",
   "value":"metacpd482d8-5dde4afb-19640-3314-9ab15-42",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
          Groups/metacpd482d8-5dde4afb-19640-3314-9ab15-42"
 },
 {
   "displayName":"DataProviders",
   "value":"uid-a5d19b0-23d9d18e-150d70f9e3b--7ff8",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
          Groups/uid-a5d19b0-23d9d18e-150d70f9e3b--7ff8"
 }
]

Reading a user with requested attributes "dxrGroupLink.link" and "dxrGroupLink.owner":

"dxrgrouplink":
[
 {
   "owner":
   [
     {
       "displayName":"Nik Taspatch",
       "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
     }
   ],
   "displayName":"CertificationCampaignAdmins",
   "value":"metacpd482d8-5dde4afb-19640-3314-9ab15-42",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
          Groups/metacpd482d8-5dde4afb-19640-3314-9ab15-42"
 },
 {
   "owner":
   [
     {
       "displayName":"Nik Taspatch",
       "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
     }
   ],
   "displayName":"DataProviders",
   "value":"uid-a5d19b0-23d9d18e-150d70f9e3b--7ff8",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
          Groups/uid-a5d19b0-23d9d18e-150d70f9e3b--7ff8"
 }
]

Modify Operations

In the request body of a modify operation, the values are represented simply by the DNs or the UIDs of the referenced objects:

"manager": "cn=Hungs Olivier,o=My-Company,cn=Users,cn=My-Company"
"dxrRepresentative": "uid-7f001-6f26d110-11da5aeefcf--7ff8"
Compound Attributes

Compound attributes store a set of DirX Identity attributes in a single LDAP attribute. Examples are "dxrOptions", "dxmSpecificAttributes" and "dxrRPValues". A compound attribute has a delimiter which is usually a space or the equal sign "=". The delimiter separates name and value of each sub-attribute.

You can configure the sub-attributes of a compound attribute in the respective object description. This way, you can have sub-attributes of any type and with multiple values. Sub-attributes not configured in the object description are assumed to be single-valued and of type String.

The REST services represent each compound attribute as a JSON object. Its members are the sub-attributes. The representation of the sub-attribute value(s) depends on their configuration.

A Sample Configuration

Let’s assume the compound attribute "dxrOptions" is configured in the object description with a space as delimiter:

<property name="dxrOptions" subsetdelimiter=" " />

And let’s assume its sub-attribute configurations are

<property name="dxrOptions(mvInteger)" type="java.lang.Integer"
         multivalue="true"/>
<property name="dxrOptions(svString)"  type="java.lang.String"/>
<property name="dxrOptions(mvString)"  type="java.lang.String"
         multivalue="true"
<property name="dxrOptions(svBoolean)" type="java.lang.Boolean"/>

It has the following sub-attributes:

  • A multi-valued Integer attribute with name "mvInteger".

  • A single-valued String attribute with name "svString".

  • A multi-valued String attribute with name "mvString".

  • A single-valued Boolean attribute with name "svBoolean".

It may have additional sub-attributes without configuration, which are (by hard-coded default configuration) single-valued and of type "String".

Reading the Compound Attribute

Let’s assume attribute "dxrOptions" of a sample database entry has the following values:

dxrOptions: mvinteger 1001
dxrOptions: mvinteger 1002
dxrOptions: svstring alpha-v1
dxrOptions: mvstring beta-v1
dxrOptions: mvstring beta-v2
dxrOptions: svboolean TRUE
dxrOptions: unconfigured v1

The REST Service represents attribute "dxrOptions" of the entry as follows provided the sample sub-attribute configurations are enabled:

"dxroptions": {
   "mvinteger":    [ 1001, 1002 ],
   "svstring":     "alpha-v1",
   "mvstring":     [ "beta-v1", "beta-v2" ],
   "svboolean":    true,
   "unconfigured": "v1"
}
The values are represented as Numbers, Booleans or Strings, and that all values of sub-attributes configured as multi-valued are returned.

If the sample sub-attribute configurations are not enabled, the representation looks like:

"dxroptions": {
   "mvinteger":    "1001",
   "svstring":     "alpha-v1",
   "mvstring":     "beta-v1",
   "svboolean":    "true",
   "unconfigured": "v1"
}
All values are represented as Strings, and you get one value per sub-attribute only.

Updating the Compound Attribute

If the sample sub-attribute configurations are enabled, a request to update attribute "dxrOptions" looks like:

{
 "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
 "Operations" : [
   {
     "op" : "replace",
     "path" : "dxrOptions",
     "value": {
         "svString":     "alpha-v1",
         "mvString":     [ "beta-v1", "beta-v2" ],
         "mvInteger":    [ 1001, 1002 ],
         "svBoolean":    true,
         "unconfigured": "v1"
     }
   }
 ]
}

This will replace any current values of the listed sub-attributes with the new values. It will not affect any sub-attributes not listed here.

You can also update the values one by one:

{
 "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
 "Operations" : [
   {
     "op" : "add",
     "path" : "dxrOptions.svBoolean",
     "value": true
   },
   {
     "op" : "replace",
     "path" : "dxrOptions.mvString",
     "value": [
     "beta-v1",
     "beta-v2"
     ]
   }
}

To remove the attribute with all its values, use:

{
 "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
 "Operations" : [
   {
     "op" : "remove",
     "path" : "dxrOptions"
   }
 ]
}

You can also clear all values and set new ones in the same request:

{
 "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
 "Operations" : [
   {
     "op" : "remove",
     "path" : "dxrOptions"
   },
   {
     "op" : "add",
     "path" : "dxrOptions",
     "value": {
         "svString":     "alpha-v1",
         "mvString":     [ "beta-v1", "beta-v2" ],
         "mvInteger":    [ 1001, 1002 ],
         "svBoolean":    true,
         "unconfigured": "v1"
     }
   }
 ]
}

If the sample sub-attribute configurations are not enabled, a request to update attribute "dxrOptions" must provide String values only, and at most one value per sub-attribute:

{
 "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
 "Operations" : [
   {
     "op" : "replace",
     "path" : "dxrOptions",
     "value": {
         "svString":     "alpha-v1",
         "mvString":     "beta-v1",
         "mvInteger":    "1001",
         "svBoolean":    "true",
         "unconfigured": "v1"
     }
   }
 ]
}

SCIM Attributes

This section provides information about SCIM attributes.

SCIM Core Schema Attributes

SCIM attribute names in query parameters or request bodies of REST Services operations are case-insensitive. The services, on the other hand, always return case-exact names in responses as specified by the SCIM specifications; for example, phoneNumbers and not phonenumbers.

Simple Attributes

Some SCIM core schema attributes are simply mapped to their corresponding LDAP attributes:

  • department - Mapped to the LDAP attribute departmentNumber.

  • displayName - Mapped to the LDAP attribute displayName; the attribute is by default defined in LDAP for auxiliary objectclass "inetOrgPerson" only; it is different from the DirX Identity pseudo-attribute $displayName.

  • employeeNumber - Mapped to the LDAP attribute employeeNumber.

  • externalId - Mapped to the LDAP attribute uid.

  • organization - Mapped to the LDAP attribute o.

  • preferredLanguage - Mapped to the LDAP attribute preferredLanguage.

  • profileUrl - Mapped to the LDAP attribute labeledURI.

  • title - Mapped to the LDAP attribute title.

  • userName - Mapped to the LDAP attribute uid.

  • userType - Mapped to the LDAP attribute employeeType.

Complex Attributes

Other SCIM core schema attributes require a more complex mapping to one or more LDAP attributes:

  • active - The boolean attribute corresponds to the LDAP attribute dxrState.

    When reading the SCIM attribute, its value is:

    • true if the value of the LDAP attribute is "ENABLED".

    • false if the value of the LDAP attribute is not "ENABLED".

    When setting the SCIM attribute to true:

    • The attribute dxrState is set to "ENABLED".

    • The attributes dxrDisableStartDate and dxrDisableEndDate are deleted.

    When setting the SCIM attribute to false:

    • The attribute dxrState is set to "DISABLED".

    • The attribute dxrDisableStartDate is set to the current time unless it is already set to a date in the past.

    • The attribute dxrDisableEndDate is deleted.

    Modifying the attribute is rejected if the current dxrState value is neither "ENABLED" nor "DISABLED". Removing the SCIM attribute is not supported.

  • addresses - Multi-valued. The sub-attributes correspond to LDAP attributes as follows:

    • type - The only supported address type is "work".

    • formatted - postalAddress; dollar characters “$” in postalAddress values correspond to new line characters “\n” in formatted values.

    • streetAddress - street

    • locality - l

    • region - st

    • postalCode - postalCode

    • country - c

    Here is a sample address:

    "addresses" : [
 {
   "type" : "work",
   "formatted" : "My-Company\n808 Howell Street\n3rd Floor\nSan Jose CA 95113",
   "streetAddress" : "808 Howell Street",
   "locality" : "My-Company San Jose",
   "region" : "CA",
   "postalCode" : "95113",
   "country" : "US"
 }
]

  • costCenter - Multi-valued as opposed to single-valued in the SCIM core schema. The attribute is mapped to the common names (cn) of dxrCostUnitLink references.

  • emails - Multi-valued. The sub-attributes correspond to LDAP attributes as follows:

    • type - The only supported email type is "work".

    • value - mail

    • display - Not supported.

    • primary - Not supported.

    Here is an example with two email addresses:

    "emails" : [
 {
   "type" : "work",
   "value" : "Nik.Taspatch@My-Company.com"
 },
 {
   "type" : "work",
   "value" : "Nik.Taspatch@Another-Company.com"
 }
]

  • groups - Multi-valued. The list of groups includes the assigned and the pending groups of a user. The sub-attributes of a single group correspond to LDAP attributes as follows:

    • value - dxruid

    • $ref - An HTTP link to read group details; the link includes the group’s dxruid.

    • display - The DXI pseudo-attribute $displayname.

    • type - One of "deleted", " direct" or " indirect".

      • deleted - If the group is not manually assigned and in state "DELETED".

      • direct - If the group is manually assigned and in state "ENABLED", "ADD", or "FUTURE".

      • indirect - If the group is not manually assigned and in state "INHERITED", or if the group is assigned via a business object, a rule or a user facet.

    • description - description; a proprietary extension.

    • assignment - A proprietary SCIM extension for group assignments.

    Here is a sample with two groups:

    "groups" : [
 {
   "value" : " metacp8add10-57fe5e43-ddec7-5d4a9-40",
   "$ref" : "http://localhost:9000/Groups/metacp8add10-57fe5e43-ddec7-5d4a9-40"
   "display" : "CertificationCampaignAdmins",
   "type" : "direct",
   "description" : "Certification campaigns administrator group",
   "assignment" : {
       "mode" : "manual",
       "state" : "ENABLED",
       "isEditable" : true,
       "hasSODViolations" : false,
       "dxrNeedsReapproval" : false
   }
 },
 {
   "value" : " uid-01-6f26d110-11da5aeefcf--7824",
   "$ref" : "http://localhost:9000/Groups/uid-01-6f26d110-11da5aeefcf--7824",
   "display" : "Administrator",
   "type" : "indirect",
   "description" : "Extranet portal administration",
   "assignment" : {
       "mode" : "inherited",
       "state" : "INHERITED",
       "isEditable" : true,
       "hasSODViolations" : false,
       "dxrNeedsReapproval" : false
   }
 }
]

  • id - The attribute is mapped to the LDAP attribute dxruid if available and to the DN otherwise.

  • manager - The sub-attributes correspond to LDAP attributes as follows:

    • value - dxruid

    • $ref - An HTTP link to read manager details; the link includes the manager’s dxruid.

    • displayName - displayName; if not available, givenName and sn, separated by a space; as a last resort, the DXI pseudo-attribute $displayname.

    Here is a sample manager:

    "manager" : {
 "value" : "uid-7f001-6f26d110-11da5aeefcf--7ff8",
 "$ref" : "http://localhost:9000/Users/uid-7f001-6f26d110-11da5aeefcf--7ff8"",
 "displayName" : "Retha Wagner"
}

  • meta - The sub-attributes correspond to LDAP attributes as follows:

    • created - createTimeStamp

    • lastModified - modifyTimeStamp

    • location - An HTTP link to read user details; the link includes the user’s dxruid.

    • resourceType - The resource type for users is "User".

    • version - Not supported.

    Here is a sample meta attribute:

    "meta" : {
 "created" : "2016-10-12T16:01:19.822Z",
 "location" : "http://localhost:9000/Users/uid-7f001-6f26d110-11da5aeefcf--7ff9",
 "lastModified" : "2017-06-19T11:02:54.529Z",
 "resourceType" : "User"
}

  • name - The sub-attributes correspond to LDAP attributes as follows:

    • formatted - displayName; if not available, dxrSalutation, givenName and sn, separated by spaces.

    • familyName - sn

    • givenName - givenName

    • middleName - Not supported.

    • honorificPrefix - dxrSalutation

    • honorificSuffix - Not supported.

    Here is a sample name:

    "name" : {
  "formatted" : "Mr. Nik Taspatch",
  "familyName" : "Taspatch",
  "givenName" : "Nik",
  "honorificPrefix" : "Mr."
}

  • phoneNumbers - Multi-valued. The sub-attributes correspond to LDAP attributes as follows:

    • type - The only supported phone number types are "work", "mobile" and "fax".

    • value - telephoneNumber for type "work", facsimileTelephoneNumber for type "fax", mobile for type "mobile".

    • display - Not supported.

    • primary - Not supported.

    Here is an example with phone numbers:

    "phoneNumbers" : [
 {
   "type" : "work",
   "value" : "+1 408 876-73623"
},
{
  "type" : "mobile",
  "value" : "0123 456 1234567"
 },
 {
   "type" : "fax",
   "value" : "+1 408 876-35267"
 }
]

  • roles - Multi-valued. The list of roles includes the assigned and the pending roles of a user. The sub-attributes of a single role correspond to LDAP attributes as follows:

    • value - dxruid

    • $ref - An HTTP link to read role details; the link includes the role’s dxruid.

    • display - The DXI pseudo-attribute $displayname.

    • type - One of "deleted", " direct" or " indirect".

      • deleted - If the role is not manually assigned and in state "DELETED".

      • direct - If the role is manually assigned and in state "ENABLED", "ADD", or "FUTURE".

      • indirect - If the role is not manually assigned and in state "INHERITED", or if the role is assigned via a business object, a rule, or a user facet.

    • description - description

    • assignment - A proprietary SCIM extension for role assignments including role parameters.

    Here is an example with two roles:

    "roles": [
 {
   "value": "uid-7f001-6f26d110-11da5aeefcf--78c0",
   "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   domainObjects/uid-7f001-6f26d110-11da5aeefcf--78c0",
   "display": "Windows Administrator",
   "type": "direct",
   "description": "Windows administration",
   "assignment": {
       "mode": "manual",
       "state": "ENABLED",
       "isEditable": true,
       "hasSODViolations": false,
       "dxrEndDate": "2018-05-30T22:00:00.000Z",
       "dxrNeedsReapproval": false
   }
 },
 {
   "value": "uid-a5d1993--687c2e99-1605985ffa0--7671",
   "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   domainObjects/uid-a5d1993--687c2e99-1605985ffa0--7671",
   "display": "Project Member",
   "type" : "deleted",
   "description" : "Member of a project",
   "assignment" : {
     "state" : "DELETED",
     "isEditable": true,
     "hasSODViolations": false,
     "dxrStartDate": "2017-12-31T23:00:00.000Z",
     "dxrEndDate":" 2018-05-30T22:00:00.000Z",
     "dxrNeedsReapproval": true,
     "roleParameters": [
       {
         "uid": "uid-7f001-cee271-fed935aa6d--7eb4",
         "values": [
           {
             "display": "OptimizeIT",
             "value": "cn=OptimizeIT,cn=Projects,cn=BusinessObjects,
                           cn=My-Company"
           }
         ],
         "name": "Project",
         "type": "DN"
       }
     ]
   }
 }
]

  • X509Certificates - Multi-valued. The sub-attributes correspond to LDAP attributes as follows:

    • type - Not supported.

    • value - userCertificate

    • display - Not supported.

    • primary - Not supported.

    Here is an example with two certificates:

    "X509Certificates": [
 {
   "value": "MIIFsjCCBJqgAwIBAgIE…value truncated…"
 },
 {
   "value": "MIICNjCCAZ8CBEem8os…value truncated…"
 }
]
Unsupported Attributes

The following SCIM core schema attributes are not supported:

  • division - No replacement.

  • entitlements - No replacement.

  • ims - No replacement.

  • locale - No replacement.

  • photos - Multi-valued. Use the LDAP attribute jpegPhoto instead. But note that jpegPhoto does not support the type/value representation of SCIM photos, and that the values are Base64-encoded photos, not just HTTP links to the photos.

  • nickname - No replacement.

  • password - No replacement.

  • timezone - No replacement.

Proprietary Extensions

The following attributes are proprietary extensions to the SCIM schema.

Permissions

The permissions attribute represents the list of a user’s assigned and pending permissions. It includes the following fields:

  • value - dxruid

  • $ref - An HTTP link to read permission details; the link includes the permission’s dxruid.

  • display - The DXI pseudo-attribute $displayname.

  • type - One of "deleted", " direct" or " indirect".

    • deleted - If the permission is not manually assigned and in state "DELETED".

    • direct - If the permission is manually assigned and in state "ENABLED", "ADD", or "FUTURE".

    • indirect - If the permission is not manually assigned and in state "INHERITED", or if the permission is assigned via a business object, a rule, or a user facet.

  • description - description

  • assignment - A proprietary SCIM extension for permission assignments.

Here is an example with two permissions:

"permissions" : [
 {
   "value": "uid-7f001-6f26d110-11da5aeefcf--7921",
   "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   domainObjects/uid-7f001-6f26d110-11da5aeefcf--7921"
   "display": "Signature Level 1",
   "type": "direct",
   "description": "Minimum level of signatures",
   "assignment": {
       "mode": "manual,rule",
       "state": "ENABLED",
       "isEditable": true,
       "hasSODViolations": false,
       "dxrNeedsReapproval": false
   }
 },
 {
   "value": "uid-7f001-6f26d110-11da5aeefcf--793f",
   "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   domainObjects/uid-7f001-6f26d110-11da5aeefcf--793f"
   "display": "DXR Policy Administrator",
   "type": "indirect",
   "description": "DirX Identity policy administration",
   "assignment": {
       "mode": "inherited",
       "state": "INHERITED",
       "isEditable": true,
       "hasSODViolations": false,
       "dxrNeedsReapproval": false
   }
 }
]
Assignments

The assignment attribute represents a privilege assignment. It includes the following fields:

  • uid - The assignment UID for an assignment of a parameterized role. It’s the common name of the corresponding assignment object below the user entry. The UID can for example be used in request URLs to change or delete the assignment, or to change role parameter values.

  • dxrEndDate - The end date of the assignment.

  • dxrStartDate - The start date of the assignment.

  • dxrNeedsReapproval - A Boolean flag indicating whether the assignment is subject to re-approval.

  • mode - The assignment mode, one of "manual", "inherited", "rule", "BO", and "UF", or a comma-separated combination thereof.

  • state - The assignment state, one of "ADD", "DELETE", "DELETED", "ENABLED", "INHERITED", and "MODIFY".

  • roleParameters - Multi-valued. Lists the role parameters for a role assignment with parameters.

  • hasSODViolations - A Boolean flag indicating whether or not the assignment constitutes an SoD violation.

  • isEditable - A Boolean flag indicating whether the assignment can be changed by the authenticated user.

  • accountState - For a group assignment, the state of the corresponding account assignment, one of "ADD", "DELETED", "ENABLED", "IMPORTED", "INACTIVE" and "IGNORE".

  • initiator - For a pending assignment, the DN of the user requesting the assignment.

Here is a sample assignment:

"assignment":
{
   "dxrStartDate": "2017-12-03T23:00:00.000Z",
   "dxrEndDate": "2018-03-03T23:00:00.000Z",
   "dxrNeedsReapproval": false,
   "mode": "manual",
   "state": "ENABLED",
   "hasSODViolations": false,
   "isEditable": true
}

Here is another assignment with role parameters:

"assignment":
{
   "uid": "uid-a5d1993-47c18b9-160260e3dd4--7f46",
   "dxrNeedsReapproval": false,
   "mode": "manual",
   "state": "ENABLED",
   "hasSODViolations": false,
   "isEditable": true,
   "roleParameters":
   [
       {
           "uid": "uid-7f001--290d5629-1183529ae71--7ffe",
           "name": "Car Number",
           "values":
           [
               {
                   "display": "PA RK 404"
               }
           ],
           "type": "Text"
       }
   ]
}

And here is a pending group assignment:

"assignment": {
   "dxrNeedsReapproval": false,
   "mode": "manual",
   "state": "ADD",
   "hasSODViolations": false,
   "isEditable": false,
   "accountState": "INACTIVE",
   "initiator": "cn=Taspatch Nik,ou=Global IT,o=My-Company,cn=Users,
                     cn=My-Company"
}
Role Parameters

The role parameters attribute represents the list of role parameters for a role assignment. It includes the following fields:

  • uid - The role parameter UID (dxrUID).

  • name - The role parameter name (cn).

  • type - The role parameter type (dxrType), one of "DN", "HDN", "String", "Text", and "Integer".

  • values - The current role parameter values:

    • uid - The parameter value UID (dxrUID); for role parameters of type HDN only.

    • display - The display value, if any; the value, otherwise.

    • value - The parameter value.

The values might be missing; for example, when reading assignable roles.

Here are some examples.

Type "DN"

The first example shows a role parameter of type "DN" without a display attribute and two values. Since no display attribute is configured, the REST Services generate a display value as described in the section "Configuring REST Services Operations", in the subsection "Displaying DNs".

"roleParameters": [
 {
   "uid": "uid-a5d19c8--5c612e07-162912e74a1--7fed",
   "name": "Project-NO-DISP",
   "type": "DN",
   "values": [
     {
       "display": "MoreCustomers, Projects, BusinessObjects",
       "value": "cn=MoreCustomers,cn=Projects,cn=BusinessObjects,cn=My-Company"
     },
     {
       "display": "OptimizeIT, Projects, BusinessObjects",
       "value": "cn=OptimizeIT,cn=Projects,cn=BusinessObjects,cn=My-Company"
     }
   ]
 }
]

The second example shows a role parameter of type "DN" with display attribute "cn" and a single value:

"roleParameters": [
 {
   "uid": "uid-7f001-cee271-fed935aa6d--7eb4",
   "name": "Project",
   "type": "DN",
   "values": [
     {
       "display": "OptimizeIT",
       "value": "cn=OptimizeIT,cn=Projects,cn=BusinessObjects,cn=My-Company"
     }
   ]
 }
]

Type "HDN"

The first example shows a role parameter of type "HDN" without a display attribute and with two values. Since no display attribute is configured, the REST Services generate a display value as described in the section "Configuring REST Services Operations", subsection "Displaying DNs".

"roleParameters": [
 {
   "uid": "uid-7f001--6c1b645f-112e5d0d91a--7ffc",
   "name": "Cost Locations",
   "type": "HDN",
   "values": [
     {
       "uid": "uid-7f001-6f26d110-11da5aeefcf--76de",
       "display": "A112, A11, A1, Cost Locations, Groups, SAP R3, TargetSystems",
       "value": "cn=A112,cn=A11,cn=A1,cn=Cost Locations,
                    cn=Groups,cn=SAP R3,cn=TargetSystems,cn=My-Company"
     },
     {
       "uid": "uid-7f001-6f26d110-11da5aeefcf--76dc",
       "display": "A114, A11, A1, Cost Locations, Groups, SAP R3, TargetSystems",
       "value": "cn=A114,cn=A11,cn=A1,cn=Cost Locations,
                    cn=Groups,cn=SAP R3,cn=TargetSystems,cn=My-Company"
     }
   ]
 }
]

The second example shows a single-valued role parameter of type "HDN" with display attribute "cn". The display attribute is configured in the database in the role parameter definition.

"roleParameters": [
 {
   "uid": "uid-a5d19c8-3ce7c21f-1626cd66a86--7fc4",
   "name": "Cost Locations-SV-DISP",
   "type": "HDN",
   "values": [
     {
       "uid": "uid-7f001-6f26d110-11da5aeefcf--76d6",
       "display": "A1191",
       "value": "cn=A1191,cn=A119,cn=A11,cn=A1,cn=Cost Locations,
                    cn=Groups,cn=SAP R3,cn=TargetSystems,cn=My-Company"
     }
   ]
 }
]

Type "String"

The first example shows two role parameters of type "String" with display attribute. Each parameter has one value.

"roleParameters": [
 {
   "uid": "uid-a5d19a6-3aed3f99-14acf1e100c--7fff",
   "name": "Organizational Unit",
   "type": "String",
   "values": [
     {
       "display": "Sales",
       "value": "ou=Sales,o=My-Company,cn=Companies,
                          cn=BusinessObjects,cn=My-Company"
     }
   ]
 },
 {
   "uid": "uid-a5d19a6--611f49d0-14a578d6e45--7fde",
   "name": "Country",
   "type": "String",
   "values": [
     {
       "display": "Denmark",
       "value": "DK"
     }
   ]
 }
]

The next example shows a role parameter of type "String" without display attribute. The parameter has two values.

"roleParameters": [
 {
   "uid": "uid-a5d19a6--611f49d0-14a578d6e45--7fdf",
   "name": "EmployeeType",
   "type": "String",
   "values": [
     {
       "display": "Contractor"
     },
     {
       "display": "Customer"
     }
   ]
 }
]

Type "Text"

The example shows a role parameter of type "Text" with two values. There’s no distinction between value and display value for text parameters.

"roleParameters": [
 {
   "uid": "uid-7f001--290d5629-1183529ae71--7ffe",
   "name": "Car Number",
   "type": "Text",
   "values": [
     {
       "display": "M HT 55"
     },
     {
       "display": "M HU 606"
     }
   ]
 }
]

Type "Integer"

The example shows two role parameters of type "Integer"; note that their values are represented as JSON strings, not JSON numbers:

"roleParameters": [
 {
   "uid": "uid-a5d1993-66410db1-15f8115f13e--7ffc",
   "name": "Integer1",
   "type": "Integer",
   "values": [
     {
       "display": "33"
     }
   ],
 },
 {
   "uid": "uid-a5d1993-66410db1-15f8115f13e--7ff8",
   "name": "Integer2",
   "type": "Integer",
   "values": [
     {
       "display": "1"
     },
     {
       "display": "2"
     }
   ]
 }
]
Role Parameter Configurations

A role parameter configuration represents the configuration of a role parameter. The configuration, especially the proposals, may depend on

  • The role to which the parameter is assigned.

  • The user who gets the role.

  • The authenticated user who assigns the role. His access rights, for example, might determine the set of proposal values, as well as the selectability of HDN nodes.

A role parameter configuration includes the following fields:

  • uid - The role parameter UID (dxrUID).

  • name - The role parameter name (cn).

  • type - The role parameter type (dxrType), one of "DN", "HDN", "String", "Text", and "Integer".

  • description - The role parameter description.

  • mandatory - Whether a parameter value must be specified when assigning the role to a user.

  • singleValued - Whether only one parameter value may be assigned per time period to the same user.

  • uniqueValues - For multi-valued role parameters: whether the same parameter value may be assigned only once per time period to the same user.

  • defaultValues - The default parameter values.

  • minimum - The minimum value for a parameter of type Integer.

  • maximum - The maximum value for a parameter of type Integer.

  • proposals - The role parameter proposals. The proposals might

    • display - The display value, if any; the value, otherwise.

    • value - The parameter value.

    • Some fields are for role parameters of type HDN only.

      • uid - The HDN node UID (dxrUID).

      • selectable - Whether the HDN node is selectable.

      • leaf - Whether the HDN node is a leaf or has children.

Here are some examples.

Type "DN"

The example shows the configuration of a DN role parameter with a default value and three proposal values:

{
   "uid": "uid-7f001-cee271-fed935aa6d--7eb4",
   "name": "Project",
   "type": "DN",
   "description": "Role parameter that lists all projects of My-Company",
   "mandatory": true,
   "singleValued": false,
   "selectLeavesOnly": false,
   "uniqueValues": false,
   "minimum": 0,
   "maximum": 0,
   "defaultValues":
   [
       { "display": "High performance" }
   ],
   "proposals":
   [
       { "display": "High performance" },
       { "display": "MoreCustomers" },
       { "display": "OptimizeIT" }
   ]
}

Type "HDN"

The example shows the configuration of a HDN role parameter without a default value and two top nodes for the HDN tree:

{
   "uid": "uid-7f001--6c1b645f-112e5d0d91a--7ffc",
   "name": "Cost Locations",
   "type": "HDN",
   "description": "Role parameter to assign cost locations",
   "mandatory": true,
   "singleValued": false,
   "selectLeavesOnly": false,
   "uniqueValues": false,
   "minimum": 0,
   "maximum": 0,
   "defaultValues":
   [
   ],
   "proposals":
   [
       {
           "display": "A111, A11, A1, Cost Locations, Groups,
                          SAP R3, TargetSystems",
           "value": "cn=A111,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                         cn=SAP R3,cn=TargetSystems,cn=My-Company",
           "uid": "uid-7f001-6f26d110-11da5aeefcf--76e1",
           "selectable": true,
           "leaf": false
       },
       {
           "display": "A119, A11, A1, Cost Locations, Groups,
                          SAP R3, TargetSystems",
           "value": "cn=A119,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                        cn=SAP R3,cn=TargetSystems,cn=My-Company",
           "uid": "uid-7f001-6f26d110-11da5aeefcf--76d7",
           "selectable": true,
           "leaf": false
       }
   ]
}

Type "Text"

The example shows the configuration of a text role parameter without a default value and without any proposals:

{
   "name": "Car Number",
   "uid": "uid-7f001--290d5629-1183529ae71--7ffe",
   "description": "The number of your car for the Parking lot",
   "type": "Text",
   "mandatory": false,
   "singleValued": false,
   "selectLeavesOnly": false,
   "uniqueValues": false,
   "minimum": 0,
   "maximum": 0,
   "defaultValues":
   [
   ],
   "proposals":
   [
   ]
}
Role Parameter HDN Layer

A role parameter HDN layer lists the child nodes of a HDN role parameter node. Each child node includes the following fields:

  • display - The node display value.

  • value - The node DN.

  • uid - The node UID (dxrUID).

  • selectable - Whether the node is selectable.

  • leaf - Whether the node is a leaf or has children.

The example shows the layer below node "cn=A119". The layer includes two child nodes. Both are leaf nodes. "A1192" is selectable, while "A1191" is not.

[
   {
       "display":"A1191",
       "value": "cn=A1191,cn=A119,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                    cn=SAP R3,cn=TargetSystems,cn=My-Company",
       "uid": "uid-7f001-6f26d110-11da5aeefcf--76d6",
       "selectable": false,
       "leaf": true
   },
   {
       "display": "A1192",
       "value": "cn=A1192,cn=A119,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                    cn=SAP R3,cn=TargetSystems,cn=My-Company",
       "uid": "uid-7f001-6f26d110-11da5aeefcf--76d5",
       "selectable": true,
       "leaf": true
   }
]
Segregation of Duties (SoD) Violations

A request to assign a privilege is usually rejected if the assignment would cause an SoD violation. In that case, a SCIM error response with status "409" and scimType "sodViolation" is returned. The response includes an additional proprietary field "sodViolations" which lists details about the violation. If the assignment violates more than one SoD policy, the result includes all violated policies.

A request to assign more than one privilege returns all SoD violations caused by the requested assignments. If the requested assignments included bulk ids, the violation details will also include the bulk ids, so that the client can find the corresponding SoD violations for each requested assignment.

Note that assignment requests can suppress SoD violation checks via a request parameter. In that case, the assignments are accepted but must be approved.

The SoD violation extension includes the following details:

  • policy - The violated SoD policy.

    • displayName - The policy’s display name.

    • description - The policy’s description.

    • value - The policy’s unique id (dxruid).

    • $ref - The REST Services request to get details about the policy.

  • conflictingPrivileges - The privileges causing the violation.

    • type - The privilege type, one of “role”, “permission”, and “group”.

    • displayName - The privilege’s display name.

    • description - The privilege’s description.

    • value - The privilege’s unique id (dxruid).

    • $ref - The REST Services request to get details about the privilege.

    • bulkIds - The bulk ids of the requested assignments for this privilege.

For the first example, let’s assume a user has already the roles “HW Developer” and “SW Developer”, and that there two SoD policies saying that role “Test Tasks” conflicts with role “HW Developer” and “SW Developer”, respectively. A request to assign role “Test Tasks” to the user results in two SoD violations:

"sodViolations":[
 {
   "policy": {
     "displayName":"Tester <> HW Developer",
     "description":"Testers cannot be HW developers",
     "value":"uid-7f001-6f26d110-11da5aeefcf--78df",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78df"
   },
   "conflictingPrivileges":[
     {
       "type":"role",
       "displayName":"Test Tasks",
       "description":"Tasks for the product test department",
       "value":"uid-7f001-6f26d110-11da5aeefcf--78b7"
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78b7"
     },
     {
       "type":"role",
       "name":"HW Developer",
       "description":"Employee working for HW product development",
       "value":"uid-7f001-6f26d110-11da5aeefcf--78bc"
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78bc"
     }
   ]
 },
 {
   "policy": {
     "displayName":"Tester <> SW Developer",
     "description":"Testers cannot be SW developers",
     "value":"uid-7f001-6f26d110-11da5aeefcf--78de",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78de"
   },
   "conflictingPrivileges":[
     {
       "type":"role",
       "displayName":"Test Tasks",
       "description":"Tasks for the product test department",
       "value":"uid-7f001-6f26d110-11da5aeefcf--78b7"
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78b7"
     },
     {
       "type":"role",
       "name":"SW Developer",
       "description":"Employee working for SW product development",
       "value":"uid-7f001-6f26d110-11da5aeefcf--78b8"
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78b8"
     }
   ]
 }
]

For the next example, let’s assume a user has already the role “Test Tasks”, and that there is an SoD policy saying that role “Test Tasks” conflicts with the two parameterized roles “Project Manager” and “Project Member”. A request to assign role “Project Manager” once (with bulk id “Project Manager Assignment”) and role “Project Member” twice (with bulk ids “Project Member Assignment #1” and “Project Member Assignment #2”, respectively) to the user results in the following SoD violations:

"sodViolations":[
 {
   "policy": {
     "displayName":"Tester <> Project Manager and Member",
     "description":"Testers cannot be project managers or members",
     "uid":"uid-c0a82a1--35b586bc-171f2df4165--7f5",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             DomainObjects/uid-c0a82a1--35b586bc-171f2df4165--7f5"
   },
   "conflictingPrivileges":[
     {
       "type":"role",
       "displayName":"Test Tasks",
       "description":"Tasks for the product test department",
       "value":"uid-7f001-6f26d110-11da5aeefcf--78b7"
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78b7"
     },
     {
       "type":"role",
       "name":"Project Manager",
       "description":"Manager of a project",
       "value":"uid-7f001-6f26d110-11da5aeefcf--78ac"
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78ac",
       "bulkIds": [
         "Project Manager Assignment"
       ]
     },
     {
       "type":"role",
       "name":"Project Member",
       "description":"Member of a project",
       "value":"uid-7f001-6f26d110-11da5aeefcf--78abc"
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78ab",
       "bulkIds": [
         "Project Member Assignment #1",
         "Project Member Assignment #2"
       ]
     }
   ]
 }
]
Access Rights

The virtual attribute "dxrvAccessRights" represents access rights of the authenticated user:

  • menus - The menus and menu items the authenticated user is allowed to see and select.

  • entry - The operations the authenticated user is allowed to perform on a requested resource.

  • attributes - The attributes of a requested resource the authenticated user is allowed to read or modify.

Menu access rights depend only on the authenticated user, but not on a requested resource. Therefore, they are returned by Self Service / Profile requests only. Menu access rights are based on menu access policies. They are shared with Web Center.

Entry and attribute access rights depend on a requested resource. The resource can be the target of a read operation, or an entry in a search result. Entry and attribute access rights are based on read and modify access policies.

Access rights are read-only. They cannot be modified via the REST Services. Note that access policies and menu access policies can be disabled in the domain configuration.

By default, requests to read a user or to search users will not return any access rights. You need to request access rights explicitly in the request parameter "attributes" by combining one or more of the following virtual attribute names:

  • dxrvAccessRights - Returns the default access rights. The default access right types can be configured in the configuration file domain.properties.

  • dxrvAccessRights.entry - Returns the entry access rights.

  • dxrvAccessRights.attributes - Returns the attribute access rights.

  • dxrvAccessRights.menus - Returns the menu access rights for the default menu keys. The default menu keys can be configured in the configuration file domain.properties.

  • *dxrvAccessRights.menus.*menuKey - Returns the menu access rights for the specified menu key; for example, "dxrvAccessRights.menus.GroupMgt". Menu keys are case sensitive.

The result will include the sum of all requested access rights.

Here are some sample access rights objects where the authenticated user is granted the Self Service, Worklist and GroupMgt menu, but no other menu.

Requesting the default access rights:

GET /Me?attributes=dxrvAccessRights

"dxrvAccessRights": {
  "entry": [
      "delegate",
      "setPassword",
      "modify",
      "read",
      "readPassword",
      "showTasksOf"
  ],
  "menus": {
      "Worklist": [
          "taskList",
          "initiatedWorkflows",
          "certificationCampaignList"
      ],
      "SelfService":[
          "summary",
          "modify",
          "addChallengeResponse",
          "showSubscriptionStatus",
          "showSODViolations",
          "subscribePrivileges",
          "changePassword"
      ]
  }
}

Requesting the default menu access rights plus the GroupMgt access right:

GET /Me?attributes=dxrvAccessRights.menus,dxrvAccessRights.menus.GroupMgt

"dxrvAccessRights": {
  "menus": {
      "Worklist": [
          "taskList",
          "initiatedWorkflows",
          "certificationCampaignList"
      ],
      "SelfService":[
          "summary",
          "modify",
          "addChallengeResponse",
          "showSubscriptionStatus",
          "showSODViolations",
          "subscribePrivileges",
          "changePassword"
      ],
      "GroupMgt":[
          "assignUsers",
          "summary",
          "select",
          "delete",
          "showMembers",
          "unassignUsers",
          "modify",
          "lastSelection",
          "assignMembers",
          "create",
          "showSubscriptionStatus",
          "export",
          "runReport"
      ]
  }
}

Requesting the default menu access rights when menu access policies are disabled; the list of menu items contains just the virtual menu item "all":

GET /Me?attributes=dxrvAccessRights.menus

"dxrvAccessRights": {
  "menus": {
      "Worklist": [
          "all"
      ],
      "SelfService":[
          "all"
      ],
      "UserMgt":[
          "all"
      ],
      "RoleMgt":[
          "all"
      ]
  }
}

Requesting the default entry access rights when access policies are disabled; the list of entry operations contains just the virtual item "all":

GET /Me?attributes=dxrvAccessRights.entry

"dxrvAccessRights": {
  "entry": [
      "all"
  ]
}
Pending Modifications

The virtual attribute "dxrvPendingModifications" represents modifications of an entry awaiting approval or to be performed on a future due date (tickets).

The attribute contains the following fields:

  • modifications - The list of requested attribute modifications. Each modification includes the following fields:

    • path - The LDAP name of the modified attribute.

    • scimPath - The SCIM name(s) of the modified attribute. Usually, there’s just one corresponding SCIM attribute. LDAP attribute displayname, however, is mapped to SCIM attributes displayName and name.formatted. For brevity, typed SCIM attributes are returned in hash notation, like emails#work instead of emails[type eq \"work\"].

    • affectedScimPaths - The names of SCIM attributes that may be affected by the modification since their value depends on the modified attribute. Changing attribute *dxrDisableStartDate, for example, affects the value of the active flag. The affected attributes do not include those which depend on the modified attribute via the "dependsOn" flag in the corresponding object description.

    • oldValue - Returns the old attribute value(s).

    • newValue - Returns the new attribute value(s).

  • dueDate - The date on which to perform the modification; only tickets have a due date.

  • state - The modification state, like "InApproval" or "Input.Completed".

  • mode - Either "manual" or "rule".

Pending modifications are not returned by default. They must be explicitly requested in the parameter "attributes"; for example:

GET /Me?attributes=dxrvPendingModifications,…

The response includes all modifications pending for the requested entry provided the authenticated user is allowed to read the modified attribute.

The first example includes modifications of the email address and the fax number:

"dxrvPendingModifications": [
   {
       "mode":"manual",
       "state":"InApproval",
       "modifications":
       [
           {
               "path":"mail",
               "oldValue":
               [
                   "Marc.Abele@My-Company.com"
               ],
               "newValue":
               [
                   "Marco.Abel@My-Company.com",
                   "Marc.Abele@My-Company.com"
               ],
               "scimPaths":
               [
                   "emails#work"
               ]
           }
       ]
   },
   {
       "mode":"manual",
       "state":"InApproval",
       "modifications":
       [
           {
               "path":"facsimiletelephonenumber",
               "oldValue":"+49 89 323-58564",
               "newValue":"0001 2930 48765",
               "scimPaths":
               [
                   "phoneNumbers#fax"
               ]
           }
       ]
   }
]

The next example shows a modification ticket for last name, country, and cost center:

"dxrvPendingModifications": [
   {
       "dueDate":"2018-12-31T22:00:00.000Z",
       "mode":"manual",
       "state":"Input.Completed",
       "modifications":
       [
           {
               "path":"sn",
               "oldValue":"Abele",
               "newValue":"Wagner",
               "scimPaths":
               [
                   "name.familyName"
               ],
               "affectedScimPaths":
               [
                   "name.formatted"
               ]
           },
           {
               "path":"c",
               "oldValue:"GR",
               "newValue":"GB",
               "scimPaths":
               [
                   "addresses#work.country"
               ]
           },
           {
               "path":"dxrcostunitlink",
               "newValue": {
                   "displayName":"CC 200",
                   "value":"uid-a5d19b4-779da99d-15d78bc95a1--7fe4",
                   "$ref":"http://localhost:8080/
                           DirXIdentityRestService-My-Company/DomainObjects/
                           uid-a5d19b4-779da99d-15d78bc95a1--7fe4"
               },
               "scimPaths":
               [
                   "costCenter"
               ]
           }
       ]
   }
]
Target System Link

The virtual attribute "dxrvTargetSystem" represents the target system for groups and accounts. The attribute is represented like link attributes and can be used in the same way when reading or searching groups and accounts.

Reading a group or account with requested attribute "dxrvTargetSystem":

"dxrvtargetsystem":
{
   "displayName":"Extranet Portal",
   "value":"metacpeb82d8-5dde4af6-ccd57-310c-c1910-369",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/DomainObjects/
           metacpeb82d8-5dde4af6-ccd57-310c-c1910-369"
}

Reading a group or account with requested attribute "dxrvTargetSystem.dxrType":

"dxrvtargetsystem":
{
   "displayName":"Extranet Portal",
   "dxrtype":"LDAP",
   "value":"metacpeb82d8-5dde4af6-ccd57-310c-c1910-369",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/DomainObjects/
           metacpeb82d8-5dde4af6-ccd57-310c-c1910-369"
}
Certification Campaign

A certification campaign object represents, as usual, the attributes of a certification campaign, but also includes the list of certification entries to be certified by a particular approver. The object includes

  • Attributes of the certification campaign, like its display name, common name, start and expiration date, UID and meta data.

  • The certification entries with open certification tasks for the approver. For each certification entry, this includes

    • The certification entry details.

    • The certification subject, which is a user in case of a user certification, and a privilege in case of a privilege certification.

    • The certification progress, that is the total number of assignments to be certified by the approver, and how many of them are already completed.

The overall structure of the representation for a user certification campaign is

{
 . . . certification campaign attributes . . .,
 "certifications": {
   "users":
   [
     {
       . . . certification entry attributes . . .,
       "dxrvprogress":
       {
         "total":6,
         "completed":3
       },
       "subject": {. . . user details . . .}
     },
     . . .
   ]
 }
}

The overall structure of the representation for a privilege certification campaign is

{
 . . . certification campaign attributes . . .,
 "certifications": {
   "roles":
   [
     {
       . . . certification entry attributes . . .,
       "dxrvprogress": {. . . certification progress . . .},
       "subject": {. . . role details . . .}
     },
     . . .
   ],
   "permissions":
   [
     {
       . . . certification entry attributes . . .,
       "dxrvprogress": {. . . certification progress . . .},
       "subject": {. . . permission details . .}
     },
     . . .
   ]
   "groups":
   [
     {
       . . . certification entry attributes . . .,
       "dxrvprogress": {. . . certification progress . . .},
       "subject": {. . . group details . . .}
     },
     . . .
   ]
 }
}

Certifications

The list of certification entries.

For a user certification, the object includes

  • users - The list of certification entries with user subjects.

For a privilege certification, the object includes

  • roles - The list of certification entries with role subjects.

  • permissions - The list of certification entries with permission subjects.

  • groups - The list of certification entries with group subjects.

Each certification entry includes

  • subject - Details of the certification entry subject, which is a privilege in case of a user certification, and a user in case of a privilege certification.

  • dxrvprogress - The progress of the certification for this subject.

dxrvProgress

The certification progress includes:

  • total - The total number of privilege assignments to be certified.

  • completed - The number of privilege assignments already certified.

A sample progress object is:

"dxrvprogress": {
 "total":6,
 "completed":3
}
Certification Entry

A certification entry represents the privilege assignments a user must certify for a particular subject of a campaign. The entry includes

  • The campaign the certification entry is a part of.

  • Attributes of the certification entry, like its display name, common name, UID and meta data.

  • Details of the subject, which is a user in case of a user certification, and a privilege in case of a privilege certification.

  • The manual assignments the approver should approve or reject. For each assignment, this includes

    • The assignment details.

    • The assignment resource, which is a privilege in case of a user certification, and a user in case of a privilege certification.

    • The changes to the assignment requested by the current or a previous approver during the certification process. The changes may affect the assignment start date, its end date or its role parameters.

    • The current certification result, that is whether the assignment has been accepted or rejected by the current or a previous approver, and any related comment.

  • The automatic non-manual assignments the approver may reject. For each assignment, this includes

    • The assignment details.

    • The assignment resource, which is a privilege in case of a user certification, and a user in case of a privilege certification.

    • The current certification result, that is whether the assignment has been rejected by the current or a previous approver, and any related comment.

The overall structure of the representation for a user certification is

{
 . . . certification entry attributes . . .,
 "campaign": {. . . campaign details. . .},
 "subject": {. . . user subject details . . .},
 "assignments": {
   "roles":
   [
     {
       "resource": {. . . role details . . .},
       "assignment": {. . . assignment details . . .},
       "assignmentChanges": {. . . requested assignment changes . . .},
       "certificationResult": {. . . current certification result . . .}
     },
     . . .
   ],
   "permissions":
   [
     {
       "resource": {. . . permission details . . .},
       "assignment": {. . . assignment details . . .},
       "assignmentChanges": {. . . requested assignment changes . . .},
       "certificationResult": {. . . current certification result . . .}
     },
     . . .
   ]
   "groups":
   [
     {
       "resource": {. . . group details . . .},
       "assignment": {. . . assignment details . . .},
       "assignmentChanges": {. . . requested assignment changes . . .},
       "certificationResult": {. . . current certification result . . .}
     },
     . . .
   ]
 },
 "automaticAssignments": {
   "roles":
   [
     {
       "resource": {. . . role details . . .},
       "assignment": {. . . assignment details . . .},
       "certificationResult": {. . . current certification result . . .}
     },
     . . .
   ],
   "permissions":
   [
     {
       "resource": {. . . permission details . . .},
       "assignment": {. . . assignment details . . .},
       "certificationResult": {. . . current certification result . . .}
     },
     . . .
   ],
   "groups":
   [
     {
       "resource": {. . . group details . . .},
       "assignment": {. . . assignment details . . .},
       "certificationResult": {. . . current certification result. . .}
     },
     . . .
   ]
 }
}

The overall structure of the representation for a privilege certification is

{
 . . . certification entry attributes . . .,
 "campaign": {. . . campaign details. . .},
 "subject": {. . . privilege subject details . . .},
 "assignments": {
   "users":
   [
     {
       "resource": {. . . user details . . .},
       "assignment": {. . . assignment details . . .},
       "assignmentChanges": {. . . requested assignment changes . . .},
       "certificationResult": {. . . current certification result  . . .}
     },
     . . .
   ]
 },
 "automaticAssignments": {
   "users":
   [
     {
       "resource": {. . . user details . . .},
       "assignment": {. . . assignment details . . .},
       "certificationResult": {. . . current certification result . . .}
     },
     . . .
   ]
 }
}

Assignments

The manual assignments the approver should approve or reject.

For a user certification, the object includes

  • roles - The list of manual role assignments to the user. Note that a role with parameters might be assigned to the user more than once.

  • permissions - The list of manual permission assignments to the user.

  • groups - The list of manual group assignments to the user.

For a privilege certification, the object includes

  • users - The list of manual assignments of the privilege to users. For a role with parameters, the list might contain more than one assignment to the same user.

Each assignment in one of the above the lists includes

  • resource - Details of the assigned privilege in case of a user certification; details of the user in case of a privilege certification.

  • assignment - Details of the assignment; see the description of proprietary extension "Assignments".

  • assignmentChanges - Requested changes to the assignment.

  • certificationResult - The current certification decision.

AutomaticAssignments

The non-manual assignments the approver might reject or comment on. The object includes the same fields as the manual assignments above, with the one exception of assignmentChanges.

AssignmentChanges

The changes to the assignment requested by the current or a previous approver during the certification process. The changes include:

  • dxrStartDate - The new start date of the assignment.

  • dxrEndDate - The new end date of the assignment.

  • deletedRoleParameters - The role parameter values to be deleted from the assignment.

If all fields are empty, the assignment changes object will be omitted. A sample assignment change is:

"assignmentChanges": {
 "dxrStartDate":"2020-02-27T23:00:00.000Z",
 "dxrEndDate":"2021-02-27T23:00:00.000Z",
 "deletedRoleParameters":
 [
   {
     "uid":"uid-7f001-cee271-fed935aa6d--7eb4",
     "values":
     [
       {
         "display":"OptimizeIT",
         "value":"cn=OptimizeIT,cn=Projects,cn=BusinessObjects,cn=My-Company"
       }
     ],
     "name":"Project",
     "type":"DN"
   }
 ]
}

CertificationResult

The current certification result includes

  • state - The decision taken by the current or previous approver on an assignment; either "approved" or "rejected". The field is missing if no decision has been taken yet.

  • reason - The optional reason for the decision, or for taking no decision.

If both fields are empty, the entire certification result will be omitted. A sample certification result is:

"certificationResult": {
 "state":"rejected",
 "reason":"user is not an administrator"
}

Attribute Modifications

A modification request specifies the attribute changes in a list of operations. Each operation comprises the following sub-attributes:

  • op - The operation type, one of "replace", "add", or "remove".

  • path - The SCIM or LDAP attribute name. Attribute names are case-insensitive.

  • value - The new attribute value or values. For single-valued attributes, at most one value must be specified. Values are ignored for remove operations. The value syntax is as defined by SCIM for SCIM attributes, and as defined by LDAP for LDAP attributes.

A replace operation deletes the current attribute values, if any, and adds the new ones. If no new values are specified, the attribute will not have any value afterwards. Note that replace operations do not support replacing just a specific subset of the current values of a multi-valued attribute with new ones while leaving all other values untouched.

An add operation adds the specified values if the attribute is multi-valued. For single-valued attributes, however, the add operation acts like a replace operation.

A remove operation deletes all the current values, if any. Remove operations ignore any specified value.

LDAP Attributes

Here we show with some examples how to modify attributes using LDAP notation. The attribute manager is a single-valued attribute, while the attribute mail is multi-valued.

Single-Valued Attributes

For single-valued attributes, there’s no difference between add and replace operations.

Adding or replacing a string attribute via operation type "replace":

{
   "op": "replace",
   "path": "employeeType",
   "value": "INTERNAL"
}

Adding or replacing string attribute via operation type "add":

{
   "op": "add",
   "path": "employeeType",
   "value": "INTERNAL"
}

Adding or replacing a date attribute:

{
   "op": "add",
   "path": "dxrEndDate",
   "value": "2028-12-31T00:00:00.000Z"
}

Adding or replacing a Boolean attribute:

{
   "op": "replace",
   "path": "dxrPwdReset",
   "value": true
}

Adding or replacing an integer attribute:

{
   "op": "add",
   "path": "dxrPwdFailureCount",
   "value": 4
}

Adding or replacing a double attribute:

{
   "op": "replace",
   "path": "dxrCompRiskScore",
   "value": 555.0
}

Adding or replacing a link attribute via DN:

{
    "op": "add",
    "path": "manager",
    "value": "cn=Hungs Olivier,o=My-Company,cn=Users,cn=My-Company"
}

Adding or replacing a link attribute via UID:

{
    "op": "replace",
    "path": "manager",
    "value": "uid-7f001-6f26d110-11da5aeefcf--7ffa"
}

Removing an attribute:

{
    "op": "remove",
    "path": "telephoneNumber"
}

You can also combine changes to multiple attributes in a single operation:

{
   "op": "replace",
   "value": {
       "telephoneNumber": "+49 05489 200101020",
       "mobile": "0184 200101020-700",
       "manager": "uid-7f001-6f26d110-11da5aeefcf--7ffa"
   }
}
Multi-Valued Attributes

Replacing the values of a string attribute with a single value:

{
   "op": "replace",
   "path": "mail",
   "value": "Pitton.Lavina@alpha.com"
}

The attribute now has just one value.

Adding another value:

{
   "op": "add",
   "path": "mail",
   "value": "Pitton.Lavina@beta.com "
}

The attribute now has two values.

Adding another two values:

{
   "op": "add",
   "path": "mail",
   "value": [
      "Pitton.Lavina@gamma.com",
      "Pitton.Lavina@delta.com"
   ]
}

The attribute now has four values.

Replacing the values with two new ones:

{
   "op": "replace",
   "path": "mail",
   "value": [
      "Pitton.Lavina@eta.com",
      "Pitton.Lavina@zeta.com"
   ]
}

The attribute has now two values.

The same result can be achieved with a couple of variants:

{
   "op": "replace",
   "path": "mail",
   "value": [
       { "value": "Pitton.Lavina@eta.com" },
       { "value": "Pitton.Lavina@zeta.com" }
   ]
}

{
   "op": "replace",
   "value": {
      "mail": [
          "Pitton.Lavina@eta.com",
          "Pitton.Lavina@zeta.com"
       ]
   }
}

{
   "op": "replace",
   "value": {
      "mail": [
          { "value": "Pitton.Lavina@eta.com" },
          { "value": "Pitton.Lavina@zeta.com" }
       ]
   }
}

Removing a specific value:

{
  "op": "remove",
  "path": "mail",
  "value": "Pitton.Lavina@eta.com"
}

The attribute now has just one value.

Removing all attribute values:

{
   "op": "remove",
   "path": "mail"
}

The attribute now has no value.

Adding a value:

{
   "op": "add",
   "path": "mail",
   "value": "Pitton.Lavina@theta.com"
}

The attribute now has just one value again.

You can also combine changes to multiple attributes in a single operation:

{
   "op": "replace",
   "value": {
      "mail": [
           "Pitton.Lavina@eta.com",
          "Pitton.Lavina@zeta.com"
       ],
      "dxrSecOULink": [
           "uid-7f001-6f26d110-11da5aeefcf--797a",
          "uid-7f001-6f26d110-11da5aeefcf--7ff8"
       ],
       "phoneNumbers": [
           { "value" : "+41 506 77987" }
       ]
   }
}

SCIM Attributes

Here we show how to modify attributes using their SCIM notation by providing some examples. Phone number and fax number are single-valued attributes, while the email address is multi-valued.

Single-Valued Attributes

Replacing phone and fax number:

{
   "op": "replace",
   "path": "phoneNumbers[type eq \"work\"]",
   "value": "+44 20 234-2837201"
},
{
   "op": "replace",
   "path": "phoneNumbers[type eq \"fax\"]",
   "value": "+49 89 323-5856401"
}

Each attribute now has just one value.

Replacing phone and fax number via operation type "add", overriding the previous values:

{
   "op": "add",
   "path": "phoneNumbers[type eq \"work\"]",
   "value": "+44 20 234-2837202"
},
{
   "op": "add",
   "path": "phoneNumbers[type eq \"fax\"]",
   "value": "+49 89 323-5856402"
}

Again, each attribute now has just one value.

Removing the fax number:

{
   "op": "remove",
   "path": "phoneNumbers[type eq \"fax\"]"
}

The fax number no longer has a value, while the value of the phone number is left untouched.

Removing the phone number:

{
   "op": "remove",
   "path": "phoneNumbers[type eq \"work\"]"
}

Now both attributes have no value.

Adding new values to both attributes:

{
    "op": "add",
    "path": "phoneNumbers",
   "value": [
       {
           "type":"work",
           "value":"+44 20 234-2837203"
       },
       {
           "type":"fax",
           "value":"+49 89 323-5856403"
       }
   ]
}

Each attribute now has one value.

Replacing the attribute values:

{
    "op": "replace",
    "path": "phoneNumbers",
    "value": [
       {
           "type":"work",
           "value":"+44 20 234-2837204"
       },
       {
           "type":"fax",
           "value":"+49 89 323-5856404"
       }
   ]
}

Each attribute now has just one value again.

Removing both attributes:

{
   "op": "remove",
   "path": "phoneNumbers"
}

The attributes no longer have values.

Multi-Valued Attributes

Replacing the values of a string attribute with a single value:

{
   "op": "replace",
   "path": "emails[type eq \"work\"]",
   "value": "Pitton.Lavina@alpha.com"
}

The attribute now has just one value.

Adding another value:

{
   "op": "add",
   "path": "emails[type eq \"work\"]",
   "value": [
       {
           "value": "Pitton.Lavina@beta.com"
       }
   ]
}

The attribute now has two values.

Adding another two values; we can omit the type, since "work" is the default type:

{    "op": "add",
   "path": "emails",
   "value": [
      {
          "value": "Pitton.Lavina@gamma.com"
      },
      {
          "value": "Pitton.Lavina@delta.com"
      }
   ]
}

The attribute now has four values.

Replacing the values with two new ones:

{
   "op": "replace",
   "path": "emails",
   "value": [
      {
          "value": "Pitton.Lavina@eta.com",
           "type": "work"
      },
      {
          "value": "Pitton.Lavina@zeta.com",
           "type": "work"
      }
   ]
}

The attribute now has two values.

Removing a specific value:

{
  "op": "remove",
  "path": "emails[type eq \"work\"]",
  "value": "Pitton.Lavina@eta.com"
}

The attribute now has just one value.

Removing all attribute values:

{
   "op": "remove",
   "path": "emails[type eq \"work\"]"
}

Now the attribute has no value at all.

Adding a value:

{
   "op": "add",
   "path": "emails",
   "value": [
      {
          "value": "Pitton.Lavina@theta.com",
           "type": "work"
      }
   ]
}

Now the attribute has just one value again.

REST Services Operations

Note that in the sample JSON requests and responses listed in this section, some lines are wrapped for better readability.

Many operations expect one or more entry IDs as input.An entry ID is usually the value of the entry’s "dxrUID" attribute.In almost all cases, however, the operations will also accept the DN instead.

The operations respect attribute access policies.Returned results do not include any attributes which are not readable for the authenticated user and attempts to modify an attribute which the authenticated user is not allowed to modify are rejected.You can change the default behavior with some general REST Services configuration parameters.

Response data to REST Services requests is always UTF-8 encoded.We recommend using UTF-8 for request data, too and to set the HTTP request header Content-Type to "application/json; charset=UTF-8".You can, however, use any other character set you like as long as it fits your data.The default character set is ISO-8859-1.

Error Handling

This section describes the error handling as implemented by domain, user and self service operations.

Operation failures are indicated by returning a corresponding HTTP error code. The relevant error codes are:

  • BAD_REQUEST (400) - An input value is invalid, or the input data is incorrectly formatted.

  • UNAUTHORIZED (401) - User authentication failed.

  • FORBIDDEN (403) - The authenticated user is not allowed to perform the operation due to missing access rights.

  • NOT_FOUND (404) - An entry to be read, modified, or deleted was not found in the database, or connecting to the service failed (Tomcat not running, URL or an HTTP header value is incorrect).

  • CONFLICT (409) - An operation could not be performed due to a conflict:

    • An assignment request was rejected since a conflicting assignment already exists.

    • An assignment request would result in an SoD violation.

    • The assignment ID for a privilege operation does not uniquely identify an assignment.

    • A delegation request was rejected since it would cause a circular delegation.

    • A request affecting a user failed temporarily since the user is locked by another request.

    • A request to delete an entry was rejected since a corresponding approval workflow is already running.

    • A request to create an entry was rejected since the new entry’s name is already assigned to another entry.

    • A request to rename an entry was rejected since the entry’s new name is already assigned to another entry.

  • INTERNAL_SERVER_ERROR (500) - The request could not be mapped to a handler in the service, usually due to an incorrect URI path or incorrect HTTP headers.

In some error cases, the operation also returns a SCIM error response giving details about the issue, for example:

{
   "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ],
   "status":"400",
   "scimType":"invalidValue",
   "detail":"Illegal value for attribute 'telephonenumber' found"
}

The status field repeats the HTTP status code, the scimType is a more fine-grained error classification, and the detail is a textual representation of the error details. Values for scimType include:

  • circularDelegation - A new delegation or updates to an existing delegation would lead to a circular delegation.

  • incorrectDateOrder - The start date of an assignment or delegation occurs after its end date.

  • deletionPending - A deletion approval workflow is already running for an entry deletion request.

  • invalidFilter - The filter for a search operation is invalid.

  • invalidPassword - The old password for a password change operation is invalid.

  • invalidPath - The path for an operation within a PATCH request is missing or invalid.

  • invalidSyntax - The syntax of a JSON object in the request body is invalid.

  • invalidValue - The value of a JSON object in the request body is invalid.

  • locked - The target user of an operation is temporarily locked by another request.

  • missingConfiguration - A search configuration for a resource type is missing.

  • mutability - An attempt to change a read-only attribute or a mastered attribute was rejected.

  • noTarget - One of the following errors has occurred:

    • The path for a remove operation within a PATCH request is missing.

    • The path within a PATCH request operation denotes an attribute that is not configured in an object description.

  • sodViolation - A request to assign a privilege was rejected since it would result in an SoD violation.

  • temporary - Indicates a temporary error:

    • A request to change or reset a password failed since sending the password change event to the message broker failed.

  • uniqueness - One of the following errors has occurred:

    • A request to assign a privilege was rejected since it conflicts with an existing assignment.

    • A request to read a privilege assignment failed since the assignment ID is the ID of a privilege that is assigned more than once.

    • A request to create an entry failed since the DN of the new entry is already assigned to another entry.

    • A request to rename an entry failed since the DN of the renamed entry is already assigned to another entry.

Domain Service Operations

The domain service provides generic operations on arbitrary entries. The domain service does not support SCIM attributes.

Overview

This section provides an overview of domain service operations.

List of Operations

  • POST /DomainObjects - Creates an entry.

  • GET /DomainObjects/{entryId} - Reads an entry.

  • PATCH /DomainObjects/{entryId} - Updates an entry.

  • DELETE /DomainObjects/{entryId} - Deletes an entry.

  • GET /DomainObjects - Searches a list of entries.

  • GET /DomainObjects/{entryId}/users - Lists users of the entry with the given UID.

  • POST /DomainObjects/search - Searches proposals for a relation (a DN link attribute).

  • POST /DomainObjects/{entryId}/search - Searches proposals for a relation of the entry with the given UID.

  • GET /DomainObjects/{entryId}/attributesToBeApproved - Checks which attributes of the entry with the given UID require modification approval.

Creating an Entry

This operation creates an entry.

Request

HTTP Method and Path

POST /DomainObjects

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • ignoreWarnings - When warnings occur, whether to create the entry anyway (true) or reject the request (false). The default is false.

Request Body

The request body is a JSON object with the attributes and metadata of the entry to create. The first example creates a location:

{
   "resourceType"   : "Location",
   "parentId"           : "uid-7f001-6f26d110-11da5aeefcf--796e",
   "l"                       : "My-Company München Pasing",
   "description"       : "Created by Nik Taspatch",
   "postaladdress"   : "My-Company$Landsberger Str. 201$80157 München$Germany",
   "postalCode"      : "80157",
   "street"               : "Landsberger Str.",
   "st"                     : "Bavaria",
   "manager"           : "uid-7f001-6f26d110-11da5aeefcf--7ff9"
}

The next example creates a password policy:

{
   "odName"                                : "dxrPwdPolicy",
   "parentId"                                 : "uid-a5d19c8--3ef2bf8e-165ae4bfee2--7fdc",
   "cn"                                          : "Test Policy Alpha",
   "description"                             : "Created by Nik Taspatch",
   "dxrPwdMinLength"                 : 4,
   "dxrPwdMaxLength"                : 20,
   "dxrPwdProhibitedSubstrings"  : [ "Anton", "Hugo", "Erna" ],
   "dxrPwdWindowsCompatible"  : true
}

The supported metadata are:

  • parentId - The UID or DN of the new entry’s parent. The parent id is required and must identify an existing entry.

  • resourceType - The resource type name of the new entry.

  • odName - The name of the object description that applies to the new entry. It’s taken from the specified resource type if missing. It is required if no resource type is specified, or the resource type configuration does not include an object description name.

  • reason - The optional reason for requesting to create the entry. It is relevant only if the creation is subject to approval.

  • dueDate - The optional creation due date, that is the date the object should be created. Setting a due date will start a ticket.

Response

HTTP Success Codes

  • CREATED (201) - The entry was created, and the created entry is returned.

  • ACCEPTED (202) - If a creation workflow or ticket has been started.

Response Content

On success with the code OK (201), the operation returns a JSON object with the created entry. The object is formatted in the same way as when reading the entry.

Reading an Entry

The operation retrieves an entry’s data.

The operation can be configured in resource type-specific read sections. The resource type is determined by the entry. The default resource type is "Any".

Request

HTTP Method and Path

GET /DomainObjects/{entryId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • entryId - The entry’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of LDAP attribute names that specify the attributes to be returned in the result. By default, all attributes are returned.

Response

HTTP Success Codes

  • OK (200) - The entry is returned.

Response Content

On success, the operation returns a JSON object that lists the entry’s properties:

{
   "dxrworkflowlink":"cn=Manager Nomination,cn=Approval,
       cn=My-Company,cn=Definitions,cn=wfRoot,cn=My-Company",
   "dxrreference":"Word Document: Projects.doc",
   "dxrversion":"1.0",
   "numsubordinates":0,
   "dxruid":"uid-7f001-6f26d110-11da5aeefcf--78ac",
   "description":"Manager of a project",
   "dxrroleid":"0500",
   "dn":"cn=Project Manager,cn=Project Specific,
             cn=Corporate Roles,cn=RoleCatalogue,cn=My-Company",
   "dxrneedsapproval":true,
   "dxrroleengineer":
   [
       "cn=Pitton Lavina,ou=Global IT,o=My-Company,cn=Users,cn=My-Company"
   ],
   "dxrsubtasks":"Project management, project reports",
   "modifiersname":"cn=SystemAdmin,cn=DirXmetaRole-SystemDomain",
   "creatorsname":"cn=SystemAdmin,cn=DirXmetaRole-SystemDomain",
   "objectclass":
   [
       "dxrRole",
       "top"
   ],
   "dxruserassignmentpossible":true,
   "path":"RoleCatalogue/Corporate Roles/Project Specific/Project Manager",
   "dxrroleadmin":
   [
       "cn=Taspatch Nik,ou=Global IT,o=My-Company,cn=Users,cn=My-Company"
   ],
   "dxrreapprovalperiod":"P0Y0M0DT0H0M0S",
   "createtimestamp":"2016-10-12T16:01:12.914Z",
   "id":"cn=Project Manager,cn=Project Specific,
         cn=Corporate Roles,cn=RoleCatalogue,cn=My-Company",
   "modifytimestamp":"2017-10-27T08:02:57.619Z",
   "dxrroleparamlink":
   [
       "cn=Project,cn=My-Company,cn=RoleParams,
            cn=Customer Extensions,cn=Configuration,cn=My-Company"
   ],
   "dxrresponsibilities":"Management and controlling of a project",
   "owner":
   [
       "cn=Hungs Olivier,o=My-Company,cn=Users,cn=My-Company"
   ],
   "dxrtba":false,
   "numallsubordinates":0,
   "namingattr":"Project Manager",
   "dxrreappworkflowlink":"cn=Manager Nomination,cn=Approval,
        cn=My-Company,cn=Definitions,cn=wfRoot,cn=My-Company",
   "dxrpermissionlink":
   [
       "cn=Project Manager,cn=Project Specific,
            cn=Corporate Permissions,cn=Permissions,cn=My-Company"
   ],
   "dxrtype":"Basic",
   "dxrsodworkflowlink":"cn=Manager Nomination,cn=Approval,
        cn=My-Company,cn=Definitions,cn=wfRoot,cn=My-Company",
   "cn":"Project Manager",
   "dxrrpmatchrule":
   [
       {
           "uid":"uid-7f001-cee271-fed935aa6d--7eb4",
           "attribute":"dxrproject",
           "type":"Group",
           "operator":"="
       }
   ],
   "folder":"RoleCatalogue/Corporate Roles/Project Specific",
   "displayname":"Project Manager",
   "dxrlanguage":"En",
   "parentpath":"RoleCatalogue/Corporate Roles/Project Specific",
   "dxrmodworkflowlink":"cn=Manager Nomination,cn=Approval,
        cn=My-Company,cn=Definitions,cn=wfRoot,cn=My-Company",
   "dxrdelworkflowlink":"cn=Manager Nomination,cn=Approval,
        cn=My-Company,cn=Definitions,cn=wfRoot,cn=My-Company",
   "odname":"dxrRole"
}

Updating an Entry

This operation updates an entry. The request path must include the ID of the entry to be changed.

To rename an entry, change its naming attribute.

Request

HTTP Method and Path

PATCH /DomainObjects/{entryId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support PATCH requests, you can send a POST request instead including this additional header set to PATCH.

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • entryId - The entry’s UID (dxruid).

Query Parameters

  • ignoreWarnings - When warnings occur, whether to update the entry anyway (true) or reject the request (false). The default is false.

  • attributes - A comma-separated list of SCIM or LDAP attribute names. If specified, the operation returns the updated entry including the attributes defined here as well as the mandatory ones. If not specified, the operation will not return any data except on errors.

Request Body

The request body is a JSON object with the changes to be made. The example requests some updates for a role:

{
 "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
 "Operations" : [
   {
     "op" : "replace",
     "path" : "description",
     "value" : "Request your corporate credit card for travelling"
   },
   {
     "op" : "replace",
     "path" : "dxrRoleAdmin",
     "value" : "uid-7f001-6f26d110-11da5aeefcf--7ff9"
   },
   {
     "op" : "replace",
     "path" : "dxrRoleEngineer",
     "value" : "cn=Pitton Lavina,ou=Global IT,o=My-Company,
                                 cn=Users,cn=My-Company"
   },
   {
     "op" : "add",
     "path" : "dxrNeedsReapproval",
     "value" : true
   },
   {
     "op" : "add",
     "path" : "dxrReapprovalDate",
     "value" : "2020-01-01T12:00:00.000Z"
   },
   {
     "op" : "add",
     "path" : "dxrReapprovalPeriod",
     "value" : {
     "years" : 2,
     "months" : 4,
     "days" : 10
     }
   }
 ]
}

  • Operations - The list of modify operations.

  • reason - The optional reason for requesting to update the entry. It is relevant only if the modifications are subject to approval.

  • dueDate - The optional modification due date, that is the date the object should be modified. Setting a due date will start a ticket.

Response

HTTP Success Codes

  • OK (200) - The entry was updated and the updated entry is returned if requested.

  • ACCEPTED (202) - A modification workflow or ticket has been started. The updated entry is returned if requested but will not reflect ticketed changes or changes awaiting approval.

  • NO_CONTENT (204) - The entry was updated but no content is returned.

Response Content

On success with OK (200) or ACCEPTED (202), and if request parameter "attributes" is not empty, the operation returns a JSON object with the updated entry. The object is formatted in the same way as when reading the entry.

Deleting an Entry

This operation deletes an entry. The request path must include the ID of the entry to be deleted.

If the deletion of the entry is subject to approval, the operation will just start the respective approval workflow. If not, the entry’s state will be set to "DELETED". The entry will not be physically deleted.

Request

HTTP Method and Path

DELETE /DomainObjects/{entryId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • entryId - The entry’s UID (dxruid).

Query Parameters

  • ignoreWarnings - When warnings occur, whether to delete the entry anyway (true), or reject the request (false). The default is false.

  • recursive - Whether to delete all objects below the entry, provided the entry is a container (true), or whether to delete just the entry (false). The default is false.

Request Body

The request body is a JSON object that specifies the reason and the due date for the deletion:

{
  "reason": "We don’t need the entry anymore.",
 "dueDate": "2021-02-25T00:00:00.000Z"
}

  • reason - The optional reason for requesting to delete the entry. It is relevant only if the deletion is subject to approval.

  • dueDate - The optional deletion due date, that is the date the object should be deleted. Setting a due date will start a ticket.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The entry was deleted, or an approval workflow was started.

  • ACCEPTED (202) - If a deletion workflow or ticket has been started.

Searching Entries

The operation retrieves a set of entries matching some search criteria.

The operation can be configured in resource type specific "search" sections. The resource type is determined by query parameter "filter". If the filter includes no resource type or more than one resource type, the default resource type "Any" applies.

The size limit is defined by

  • Request parameter "count".

  • Parameter "defaultCount" of resource type section "search".

  • Configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Parameter "maxCount" of resource type section "search".

  • Configuration parameter "search.maxCount".

in descending priority.

Request

HTTP Method and Path

GET /DomainObjects

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. If just "none" is requested, only the number of entries is returned. Otherwise, the result includes, for each entry:

    • The mandatory attributes.

    • The requested attributes, if any requested.

    • The default attributes, if no attributes are requested.

  • base - The search base.

  • scope - The search scope, one of "base", "oneLevel" or "subtree". The default scope is "subtree".

  • filter - The search filter. To get entries of a specific resource type only, include a resource type filter. Note that the first filter sets the configuration resource type to "Role", while the configuration resource type for the second filter is ”Any”.

    filter=(meta.resourceType eq "Role") and (cn sw "co")

filter=(meta.resourceType eq "Role") or (meta.resourceType eq "Permission")

  • sortBy - The attributes by which the search result is sorted. You can specify one or more LDAP attributes, separated by commas. Sorting is performed by the underlying directory service, so the LDAP attributes must have a proper ordering match rule in the directory schema.

  • sortOrder - The sort order, either "ascending" or "descending". You can specify the order per sort attribute, separated by commas.

  • count - The maximum number of entries to return.

Response

HTTP Success Codes

  • OK (200) - The list of entries is returned.

Response Content

On success, the operation returns a JSON object with the list of entries:

{
   "startIndex":1,
   "totalResults":7,
   "itemsPerPage":7,
   "schemas":
   [
       "urn:ietf:params:scim:api:messages:2.0:ListResponse"
   ],
   "Resources":[
     {
       "meta":
       {
         "created":"2016-10-12T16:01:12.789Z",
         "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                     DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78b5",
         "lastModified":"2018-01-11T08:59:21.040Z",
         "resourceType":"Role"
       },
       "dn":"cn=Contractor,cn=General,cn=Corporate Roles,
             cn=RoleCatalogue,cn=My-Company",
       "cn":"Contractor",
       "id":"uid-7f001-6f26d110-11da5aeefcf--78b5"
       "dxrpermissionlink":
       [
         "cn=Contractor,cn=General,cn=Corporate Permissions,
                        cn=Permissions,cn=My-Company",
         "cn=Restricted File Share,cn=General,cn=Corporate Permissions,
                        cn=Permissions,cn=My-Company"
       ],
       "dxrroleengineer":
       [
         {
           "displayName":"Lavina Pitton",
           "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
         }
       ],
     },
     (OTHER ENTRIES ELIMINATED)…
   ]
}

Response Data

  • totalResults - The number of entries returned.

  • itemsPerPage - For future use. Currently its value is identical to totalResults.

  • startIndex - For future use. Currently it’s always 1.

  • Resources - The list of entries.

Listing Users of an Entry

The operation list the users of an entry, that is the users who reference the entry in one of their attributes. Examples are the users a given privilege is assigned to, or the users in a specific location or organizational unit.

The operation can be configured in resource type specific "users" sections. The resource type is determined by the given entry.

The size limit is defined by

  • Request parameter "count".

  • Parameter "defaultCount" of resource type section "users".

  • Configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Parameter "maxCount" of resource type section "users".

  • Configuration parameter "search.maxCount".

in descending priority.

Request

HTTP Method and Path

GET /DomainObjects/{entryId}/users

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • entryId - The entry’s UID (dxruid).

Query Parameters

  • linkAttributes - The comma-separated list of user attributes. A user is returned if at least one of the attributes references the entry.

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the user attributes to be returned in the result. If just "none" is requested, only the number of users is returned. Otherwise, the result includes, for each user:

    • The mandatory attributes.

    • The requested attributes, if any requested.

    • The default attributes, if no attributes are requested.

  • base - The search base.

  • scope - The search scope, one of "base", "oneLevel" or "subtree". The default scope is "subtree".

  • filter - An additional search filter for the users.

  • sortBy - The attributes by which the search result is sorted. You can specify one or more LDAP attributes, separated by commas. Sorting is performed by the underlying directory service, so the LDAP attributes must have a proper ordering match rule in the directory schema.

  • sortOrder - The sort order, either "ascending" or "descending". You can specify the order per sort attribute, separated by commas.

  • count - The maximum number of users to return.

Response

HTTP Success Codes

  • OK (200) - The list of users is returned.

Response Content

On success, the operation returns a JSON object with the list of users:

{
  "startIndex":1,
  "totalResults":7,
  "itemsPerPage":7,
  "schemas":
  [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources":[
   {
     "emails":
     [
       {
         "type":"work",
         "value":"Roman.Gebhart@My-Company.com"
       }
     ],
     "c":"DE",
     "meta":
     {
       "created":"2021-08-18T15:28:53.346Z",
       "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7fea",
       "lastModified":"2021-11-16T06:56:20.497Z",
       "resourceType":"User"
     },
     "name":
     {
       "formatted":"Hr. Roman Gebhart",
       "givenName":"Roman",
       "familyName":"Gebhart",
       "honorificPrefix":"Hr."
     },
     "externalId":"gebhart",
     "dn":"cn=Gebhart Roman,ou=Product Testing,o=My-Company,
           cn=Users,cn=My-Company",
     "id":"uid-7f001-6f26d110-11da5aeefcf--7fea",
     "userName":"gebhart",
     "phoneNumbers":
     [
       {
         "type":"work",
         "value":"+49 30 6574-8042"
       },
       {
         "type":"fax",
         "value":"+49 30 6574-2256"
       }
     ]
   },
   (OTHER ENTRIES ELIMINATED)…
  ]
}

Response Data

  • totalResults - The number of users returned.

  • itemsPerPage - For future use. Currently its value is identical to totalResults.

  • startIndex - For future use. Currently it’s always 1.

  • Resources - The list of users.

Searching Proposals for a Relation

The operation retrieves the proposal list for a relation or DN link attribute of an entry, like the manager of a user or the owner of a privilege. The request comes in two variants.

In the first variant, the proposal list depends on the resource type of the target entry but not on the target entry itself. The proposal list for owner, for example, might be different for roles than for permissions, but will be the same for all roles.

In the second variant, the proposal list might vary with the target object. The manager proposal list for one user, for example, might be different from that of another user.

Each relation is identified by a name. The name is mapped to a sub-section of section"Relations" in file resources.json. The search configuration defines the details of how to find the corresponding proposal list, like the search filter and the maximum number of entries to return. The search filter might depend on the specific target entry.

The size limit is defined by

  • Parameter "defaultCount" of relation section "search".

  • Parameter "defaultCount" of relation resource type section "search".

  • Global configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Global configuration parameter "search.maxCount".

Request

HTTP Method and Path

POST /DomainObjects/search

POST /DomainObjects/{entryId}/search

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • entryId - The target entry’s UID (dxruid).

Request Body

The request body is a JSON object with the relation name, search value, and the attributes to return for each proposal:

{
   "action": "managers_for_user",
   "value": "hun",
   "attributes": ["name", "ou"]
}

Asterisks (*) within the search value serve as wildcards.

Response

HTTP Success Codes

  • OK (200) - The proposal list is returned.

Response Content

On success, the operation returns a JSON object with the proposal list:

{
 "startIndex":1,
 "totalResults":3,
 "itemsPerPage":3,
 "schemas":
 [
   "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 ],
 "Resources":[
   {
     "name":
     {
       "formatted":"Hr. Olivier Hungs",
       "givenName":"Olivier",
       "familyName":"Hungs",
       "honorificPrefix":"Hr."
     },
     "externalId":"hungs",
     "dn":"cn=Hungs Olivier,o=My-Company,cn=Users,cn=My-Company",
     "id":"00014281",
     "ou":"General Management",
     "meta":
     {
       "created":"2016-10-12T16:01:19.510Z",
       "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/00014281",
       "lastModified":"2018-08-28T08:15:13.336Z",
       "resourceType":"User"
     }
   },
   (OTHER ENTRIES ELIMINATED)…
 ]
}

Response Data

  • totalResults - The number of entries returned.

  • itemsPerPage - For future use. Currently its value is identical to totalResults.

  • startIndex - For future use. Currently it’s always 1.

  • Resources - The proposal list.

Listing Attributes to be Approved

The operation checks which attributes of an entry require modification approval. This can be used to decide whether to ask for a reason when a user modifies an entry.

Request

HTTP Method and Path

GET /DomainObjects/{entryId}/attributesToBeApproved

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • entryId - The entry’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of the attributes to be checked. The list may include LDAP and SCIM attribute names. If the list is empty, all attributes are checked, but the result will include only LDAP names.

Response

HTTP Success Codes

  • OK (200) - The list of attributes requiring modification approval is returned.

Response Content

On success, the operation returns a JSON object that lists the entry’s properties.

Let’s assume attributes "telephoneNumber", "street" and "userCertificate" require modification approval.

Here are the responses for some sample attribute lists:

  • attributes - "phoneNumbers"

    {
[ "phoneNumbers" ]
}

    You cannot see which of the different phone numbers require approval.

  • attributes - "phoneNumbers#work,phoneNumbers#mobile"

    {
[ "phoneNumbers#work" ]
}

  • attributes - "addresses#work"

    {
[ "addresses#work" ]
}

    You cannot see whether the approval is due to attribute "street" or to another one like "postalCode".

  • attributes - "x509Certificates"

    {
[ "x509Certificates" ]
}

  • attributes - "telephoneNumber,street,userCertificate"

    {
[ "telephoneNumber,"userCertificate","street" ]
}

  • attributes - ""

    {
[ "telephonenumber","usercertificate","street" ]
}
Attribute names are used in lower-case here.

User Service Operations

The user service provides operations on a given user’s profile data and on his privilege assignments.

Overview

This section provides an overview of user service operations.

List of Operations

  • Profile Data

    • GET /Users/{userId} - Reads a user’s profile data.

    • PATCH /Users/{userId} - Updates a user’s profile data.

  • User Data

    • GET /Users - Searches a list of users.

    • GET /Users/managedUsers - Lists the users managed by the authenticated user.

    • GET /Users/{userId}/accounts - Lists a user’s accounts.

  • Privilege Assignments

    • GET /Users/{userId}/roles
      GET /Users/{userId}/permissions
      GET /Users/{userId}/groups
      GET /Users/{userId}/privileges - Lists a user’s privilege assignments (not including the ones still awaiting approval).

    • GET /Users/{userId}/roles/count
      GET /Users/{userId}/permissions/count
      GET /Users/{userId}/groups/count
      GET /Users/{userId}/privileges/count - Returns the number of privileges assigned to a user (not including the pending assignments).

    • GET /Users/{userId}/assignableRoles
      GET /Users/{userId}/assignablePermissions
      GET /Users/{userId}/assignableGroups
      GET /Users/{userId}/assignablePrivileges - Lists the privileges that the authenticated user can assign to a user.

    • POST /Users/{userId}/roles
      POST /Users/{userId}/permissions
      POST /Users/{userId}/groups - Assigns a privilege to a user.

    • POST /Users/{userId}/privileges - Assigns one or more privileges to a user.

    • GET /Users/{userId}/roles/{assignmentId}
      GET /Users/{userId}/permissions/{assignmentId}
      GET /Users/{userId}/groups/{assignmentId}       - Reads a user’s privilege assignment with the given ID.

    • PATCH /Users/{userId}/roles/{assignmentId}
      PATCH /Users/{userId}/permissions/{assignmentId}
      PATCH /Users/{userId}/groups/{assignmentId}       - Changes a user’s privilege assignment with the given ID.

    • DELETE /Users/{userId}/roles/{assignmentId}
      DELETE /Users/{userId}/permissions/{assignmentId}
      DELETE /Users/{userId}/groups/{assignmentId}       - Deletes a user’s privilege assignment(s) with the given ID.

    • GET /Users/{userId}/roles/{roleId}/roleParams
      GET /Users/{userId}/assignableRoles/{roleId}/roleParams       - Reads the role parameter configuration for the assigned and assignable role, respectively, with the given ID.

    • GET /Users/{userId}/roles/{roleId}/roleParams/{roleParamId}/
      proposal/{roleParamNodeId}
      GET /Users/{userId}/assignableRoles/{roleId}/roleParams/{roleParamId}/
      proposal/{roleParamNodeId}       - Reads the next level of proposals below the specified role parameter node for a role parameter of type HDN for the assigned and assignable role, respectively, with the given ID.

  • Pending Privilege Assignments - A pending privilege assignment is a privilege assignment to a user which is still awaiting approval, or which is scheduled to be performed on some future day (a ticket). It doesn’t matter whether the assignment was requested by the user himself, or by another user.

    • GET /Users/{userId}/pendingRoles
      GET /Users/{userId}/pendingPermissions
      GET /Users/{userId}/pendingGroups
      GET /Users/{userId}/pendingPrivileges - Lists a user’s privilege assignments that still await approval.

    • GET /Users/{userId}/pendingRoles/count
      GET /Users/{userId}/pendingPermissions/count
      GET /Users/{userId}/pendingGroups/count
      GET /Users/{userId}/pendingPrivileges/count - Returns the number of privilege assignments still awaiting approval.

    • GET /Users/{userId}/pendingRoles/{requestId}
      GET /Users/{userId}/pendingRoles/{requestId}/{orderId}
      GET /Users/{userId}/pendingPermissions/{requestId}
      GET /Users/{userId}/pendingPermissions/{requestId}/{orderId}
      GET /Users/{userId}/pendingGroups/{requestId}
      GET /Users/{userId}/pendingGroups/{requestId}/{orderId}
      GET /Users/{userId}/pendingPrivileges/{requestId}
      GET /Users/{userId}/pendingPrivileges/{requestId}/{orderId}       - Reads the pending privilege assignment with the given request ID and order ID.

  • Pending Profile Changes - A pending profile change is a modification to a user’s profile data which is still awaiting approval, or which is scheduled to be performed on some future day (a ticket). It doesn’t matter whether the change was requested by the user himself, or by another user.

    • GET /Users/{userId}/pendingProfileChanges - Lists the pending profile changes.

    • GET /Users/{userId}/pendingProfileChanges/count - Returns the number of pending profile changes.

    • GET /Users/{userId}/pendingProfileChanges/{requestId} - Reads the pending profile change with the given request ID.

  • Pending Initiated Requests - An initiated request is a privilege assignment or a profile change requested by a user. It doesn’t matter whether he assigned the privilege to himself or to another user or whether he changed his own profile or another user’s profile. An initiated request is pending if it is awaiting approval, or if it is scheduled to be performed on some future day (a ticket).

    • GET /Users/{userId}/pendingRequests - Lists the pending initiated requests.

    • GET /Users/{userId}/pendingRequests/count - Returns the number of pending initiated requests.

    • GET /Users/{userId}/pendingRequests/{requestId}
      GET /Users/{userId}/pendingRequests/{requestId}/{orderId}       - Reads the pending initiated request with the given request ID and order ID.

      • DELETE /Users/{userId}/pendingRequests/{requestId} - Cancels the workflow or deletes the ticket which is the source of the pending initiated request with the given request ID.

  • Closed Requests - A closed request is a finished workflow or a processed ticket for a privilege assignment or a profile change.

    • GET /Users/{userId}/closedRequests - Lists the closed requests with the user as initiator or subject.

    • GET /Users/{userId}/closedRequests/{requestId} - Reads the closed request with the given ID. The user must be either the initiator or the subject of the request.

  • Personas, User Facets and Functional Users - Requests to list or count a user’s personas, user facets and functional users.

    • GET /Users/{userId}/personas - Lists the personas of a user.

    • GET /Users/{userId}/personas/count - Returns the number of personas of a user.

    • GET /Users/{userId}/userFacets - Lists the user facets of a user.

    • GET /Users/{userId}/userFacets/count - Returns the number of user facets of a user.

    • GET /Users/{userId}/functionalUsers - Lists the functional users of a user.

    • GET /Users/{userId}/functionalUsers/count - Returns the number of functional users of a user.

    • GET /Users/{userId}/users - List the personas, user facets and functional users of a user.

    • GET /Users/{userId}/users/count - Returns the numbers of personas, user facets and functional users of a user.

    • GET /Users/{userId}/owners - Lists the owners of a user.

    • GET /Users/{userId}/sponsors - Lists the sponsors of a user.

Reading the Profile

This operation retrieves a user’s profile data.

The operation can be configured in section "read" of resource type "User".

Request

HTTP Method and Path

GET /Users/{userId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the user attributes to be returned in the result. If not specified, the default attributes apply. In any case, the result will also include the mandatory attributes in addition to the attributes defined here.

Response

HTTP Success Codes

  • OK (200) - The entry is returned.

Response Content

On success, the operation returns a JSON object with the requested profile data:

{
   "emails":
   [
      {
         "type":"work",
         "value":Nik.Taspatch@My-Company.com
      }
   ],
   "c":"US",
   "meta":
   {
      "created":"2016-10-12T16:01:19.822Z",
      "location":"http://localhost:8080/DirXIdentityRestService-My-
Company/Users/uid-7f001-6f26d110-11da5aeefcf--7ff9",
      "lastModified":"2017-12-13T12:08:41.361Z",
      "resourceType":"User"
   },
   "schemas":
   [
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
   ],
   "name":
   {
      "formatted":"Mr. Nik Taspatch",
      "givenName":"Nik",
      "familyName":"Taspatch",
      "honorificPrefix":"Mr."
   },
   "externalId":"taspatch",
   "dn":"cn=Taspatch Nik,ou=Global IT,o=My-Company,cn=Users,cn=My-Company",
   "id":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "userName":"taspatch",
   "phoneNumbers":
   [
      {
         "type":"work",
         "value":"+1 408 876-73623"
      },
      {
         "type":"fax",
         "value":"+1 408 876-4405978121255"
      }
   ]
}

Updating the Profile

This operation updates the profile data of a user.

Request

HTTP Method and Path

PATCH /Users/{userId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support PATCH requests, you can send a POST request instead including this additional header set to PATCH.

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • ignoreWarnings - When warnings occur, whether to update the entry anyway (true) or reject the request (false). The default is false.

  • attributes - A comma-separated list of SCIM or LDAP attribute names. If specified, the operation returns the updated profile data including the attributes defined here as well as the mandatory ones. If not specified, the operation will not return any data except when errors occur.

Request Body

The request body is a JSON object with the changes to be made:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
     {
        "op" : "replace",
        "path" : "employeeType"
        "value" : "Internal"
     }
  ]
}

  • Operations - The list of modify operations.

  • dueDate - The optional modification due date, that is the date the object should be modified. Setting a due date will start a ticket.

  • reason - The reason for requesting to modify the profile. Only relevant if one or more attributes are subject to approval.

Response

HTTP Success Codes

  • OK (200) - The entry was updated, and the updated entry is returned if requested.

  • ACCEPTED (202) - A modification workflow or ticket has been started; the updated entry is returned if requested but will not reflect ticketed changes or changes awaiting approval.

  • NO_CONTENT (204) - The entry was updated but no content is returned.

Response Content

On success with OK (200) or ACCEPTED (202) and if request parameter “attributes” is not empty, the operation returns a JSON object with the updated profile. The object is formatted in the same way as when reading the profile.

Searching Users

The operation retrieves a set of users matching some search criteria.

The operation can be configured in section "search" of resource type "User".

The size limit for assignable roles is defined by

  • Request parameter "count".

  • Parameter "defaultCount" of resource type "User" section "search".

  • Configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Parameter "maxCount" of resource type "User" section "search".

  • Configuration parameter "search.maxCount".

in descending priority.

Request

HTTP Method and Path

GET /Users

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. If just "none" is requested, only the number of managed users is returned. Otherwise, the result includes, for each user:

    • The mandatory attributes.

    • The requested attributes if any are requested.

    • The default attributes if no attributes are requested.

  • base - The search base.

  • scope - The search scope, one of "base", "oneLevel" or "subtree". The default scope is "subtree".

  • filter - The search filter.

  • sortBy - The attributes by which the search result is sorted. You can specify one or more LDAP attributes, separated by commas. Sorting is performed by the underlying directory service, so the LDAP attributes must have a proper ordering match rule in the directory schema.

  • sortOrder - The sort order, either "ascending" or "descending". You can specify the order per sort attribute, separated by commas.

  • count - The maximum number of entries to return.

Response

HTTP Success Codes

  • OK (200) - The list of users is returned.

Response Content

On success, the operation returns a JSON object with the list of users:

{
    "startIndex":1,
    "totalResults":12,
    "itemsPerPage":12,
    "schemas":
    [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources":[
      {
        "emails":
        [
            {
                "type":"work",
                "value":"Boris.Tinker@My-Company"
            }
        ],
        "c":"DE",
        "meta":
        {
            "created":"2016-10-12T16:01:19.775Z",
            "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        Users/uid-7f001-6f26d110-11da5aeefcf--7ffb",
            "lastModified":"2018-04-03T07:52:30.426Z",
            "resourceType":"User"
        },
        "schemas":
        [
            "urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
        ],
        "name":
        {
            "formatted":"Hr. Boris Tinker",
            "givenName":"Boris",
            "familyName":"Tinker",
            "honorificPrefix":"Hr."
        },
        "externalId":"tinker",
        "dn":"cn=Tinker Boris,ou=Finances,o=My-Company,cn=Users,cn=My-Company",
        "id":"uid-7f001-6f26d110-11da5aeefcf--7ffb",
        "userName":"tinker",
        "phoneNumbers":
        [
            {
                "type":"work",
                "value":"+49 89 323-48371"
            },
            {
                "type":"fax",
                "value":"+49 89 323-58564"
            }
        ]
      },
      (OTHER USERS ELIMINATED)…
    ]
}

Response Data

  • totalResults - The number of users returned.

  • itemsPerPage - For future use. Currently its value is identical to totalResults.

  • startIndex - For future use. Currently it’s always 1.

  • Resources - The list of users.

Listing Managed Users

This operation retrieves the users managed by the authenticated user.

The operation can be configured in the section "managedUsers" of resource type "User".

The size limit for assignable roles is defined by

  • Request parameter "count".

  • Parameter "defaultCount" of resource type "User" section "managedUsers".

  • Parameter "defaultCount" of resource type "User" section "search".

  • Configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Parameter "maxCount" of resource type "User" section "managedUsers".

  • Parameter "maxCount" of resource type "User" section "search".

  • Configuration parameter "search.maxCount".

in descending priority.

Request

HTTP Method and Path

GET /Users/managedUsers

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. If just "none" is requested, only the number of managed users is returned. Otherwise, the result includes for each user:

    • The mandatory attributes.

    • The requested attributes if any are requested.

    • The default attributes if no attributes are requested.

  • base - The search base.

  • scope - The search scope, one of "base", "oneLevel", or "subtree", The default scope is "subtree".

  • filter - The search filter.

  • filterValue - The value to replace the placeholder in configuration parameter "valueFilter" (in section “managedUsers” of resource type “User”) with. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

  • sortBy - The attributes by which the search result is sorted. You can specify one or more LDAP attributes, separated by commas. Sorting is performed by the underlying directory service, so the LDAP attributes must have a proper ordering match rule in the directory schema.

  • sortOrder - The sort order, either "ascending" or "descending". You can specify the order per sort attribute, separated by commas.

  • count - The maximum number of entries to return.

Response

HTTP Success Codes

  • OK (200) - The list of managed users is returned.

Response Content

On success, the operation returns a JSON object with the list of managed users:

{
   "startIndex":1,
   "totalResults":36,
   "itemsPerPage":36,
   "schemas":
   [
       "urn:ietf:params:scim:api:messages:2.0:ListResponse"
   ],
   "Resources":
   [
       {
           "emails":
           [
               {
                   "type":"work",
                   "value":"Stephen.Green@My-Company.com"
               }
           ],
           "c":"US",
           "name":
           {
               "formatted":"Mr. Stephen Green",
               "givenName":"Stephen",
               "familyName":"Green",
               "honorificPrefix":"Mr."
           },
           "userName":"green",
           "phoneNumbers":
           [
               {
                   "type":"work",
                   "value":"+1 408 876-49912"
               },
               {
                   "type":"fax",
                   "value":"+1 408 876-35267"
               }
           ]
       },
       …
       {
           "emails":
           [
               {
                   "type":"work",
                   "value":"Retha.Wagner@My-Company.com"
               }
           ],
           "name":
           {
               "formatted":"Retha Wagner",
               "givenName":"Retha",
               "familyName":"Wagner"
           },
           "phoneNumbers":
           [
               {
                   "type":"work",
                   "value":"+49 89 323"
               }
           ]
       }
   ]

Response Data

  • totalResults - The number of users returned.

  • itemsPerPage - For future use. Currently its value is identical to totalResults.

  • startIndex - For future use. Currently it’s always 1.

  • Resources - The list of managed users.

Listing Accounts

This operation retrieves the accounts of a user.

No size or time limits applies to this operation.

Request

HTTP Method and Path

GET /Users/{userId}/accounts

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the account attributes to be returned in the result. The default attributes are "display", "$ref", "value", and "description". The value is the account’s unique ID.

Response

HTTP Success Codes

  • OK (200) - The account list is returned.

Response Content

On success, the operation returns a JSON object with the list of accounts:

{
  "totalResults":2,
  "Resources":
  [
    {
      "display":"Marc Abele 2623",
      "description":"Account for Marc Abele",
      "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
              /DomainObjects/uid-7f001-6f26d110-11da5aeefcf--7791",
      "value":"uid-7f001-6f26d110-11da5aeefcf--7791"
    },
    {
      "display":"Privileged Physicist",
      "description":"Account",
      "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
              /DomainObjects/uid-a5d19b4-4f8427cf-15ca5349858--7ffe",
      "value":"uid-a5d19b4-4f8427cf-15ca5349858--7ffe"
    }
  ]
}

Response Data

  • totalResults - The number of accounts returned.

  • Resources - The list of accounts.

Listing Assigned Privileges

This operation retrieves the privileges assigned to a user. New assignments that still await approval are not included, while assignments that await modification or deletion approval are included. The state of each returned assignment is one of "ENABLED", "INHERITED", "MODIFY", "DELETE", "IMPORTED" or "DELETED".

The operation can be configured in sections "assignedRoles" of resource type "Role", "assignedPermissions" of resource type "Permission", and "assignedGroups" of resource type "Group". The applied configuration parameters are "base", "additionalFilter", "defaultAttributes" and "mandatoryAttributes". All other configuration parameters are ignored.

No size or time limits apply to this operation.

Request

HTTP Method and Path

GET /Users/{userId}/roles

GET /Users/{userId}/permissions

GET /Users/{userId}/groups

GET /Users/{userId}/privileges

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. The result includes for each privilege:

    • The mandatory attributes.

    • The requested attributes, if any requested.

    • The default attributes, if no attributes are requested.

  • The default and mandatory attributes can be configured. The value is the privilege’s unique ID.

  • base - The search base.

  • filter - The search filter. To get entries of a specific resource type only, include a resource type filter, for example

    filter=(meta.resourceType eq "Role") and (cn sw "co")

filter=(meta.resourceType eq "Role") or (meta.resourceType eq "Permission")

  • filterValue - The value to replace the placeholder in configuration parameter "valueFilter" (in section “assignedRoles” of resource type “Role” for roles, likewise for groups and permissions) with. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

  • count - The maximum number of entries to return.

Response

HTTP Success Codes

  • OK (200) - The assignment list is returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with a single list of respective privilege assignments:

{
   "totalResults":21,
   "Resources":
   [
      {
         "assignment":
         {
            "hasSODViolations":false,
            "isEditable":true,
            "mode":"manual",
            "dxrEndDate":"2018-03-03T23:00:00.000Z",
            "state":"ENABLED",
            "dxrNeedsReapproval":false,
            "dxrStartDate":"2017-12-03T23:00:00.000Z"
         },
         "display":"Restaurant Card",
         "description":"Request your restaurant card for selected locations",
         "type":"direct",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        domainObjects/uid-7f001-6f26d110-11da5aeefcf--78a5",
         "value":"uid-7f001-6f26d110-11da5aeefcf--78a5"
      },
      {
         "assignment":
         {
            "uid":"uid-a5d1993-47c18b9-160260e3dd4--7f46",
            "hasSODViolations":false,
            "isEditable":true,
            "mode":"manual",
            "roleParameters":
            [
               {
                  "uid":"uid-7f001--290d5629-1183529ae71--7ffe",
                  "name":"Car Number",
                  "type":"Text"
               }
            ],
            "state":"ENABLED",
            "dxrNeedsReapproval":false
         },
         "display":"Parking Place Munich",
         "description":"Request your slot in the parking place in Munich",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        domainObjects/uid-7f001-6f26d110-11da5aeefcf--78a6"
      },
      (OTHER ASSIGNMENTS ELIMINATED)…
   ]
}

The operation "Users/{userId}/privileges", on the other hand, returns a JSON object with three lists, one for each type of privilege:

{
 "roles":{
   "totalResults":21,
   "Resources":[…]
 },
 "permissions":{
   "totalResults":28,
   "Resources":[…]
 },
 "groups":{
   "totalResults":47,
   "Resources":[…]
 }
}

Response Data

  • totalResults - The number of privilege assignments returned.

  • Resources - The list of privilege assignments.

Counting Assigned Privileges

This operation counts the privileges assigned to a user. New assignments still awaiting approval are not included, while assignments awaiting modification or deletion approval are included.

No size or time limits applies to this operation.

Request

HTTP Method and Path

GET /Users/{userId}/roles/count

GET /Users/{userId}/permissions/count

GET /Users/{userId}/groups/count

GET /Users/{userId}/privileges/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Response

HTTP Success Codes

  • OK (200) - The numbers of assignments are returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with a single counter:

{
 "totalResults":21,
 "sizeLimitExceeded":false
}

The operation "Users/{userId}/privileges/count", on the other hand, returns a JSON object with three counters, one or each type of privilege:

{
 "roles":{
   "totalResults":21,
   "sizeLimitExceeded":false
 },
 "permissions":{
   "totalResults":28,
   "sizeLimitExceeded":false
 },
 "groups":{
   "totalResults":47,
   "sizeLimitExceeded":false
 }
}

Response Data

  • totalResults - The number of privilege assignments.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached the size limit. The size limit for counting parameterized roles is 1000. There is no size limit for counting non-parameterized roles, permissions, and groups.

Listing Assignable Privileges

This operation retrieves the privileges the authenticated user can assign to a user. Privileges that can be assigned only once and are already assigned to the user, will not be included in the result.

For each privilege in the result, the flag "assignableOnlyOnce" indicates whether the privilege can be assigned just once (true) or more than once (false).

The operation can be configured in sections "assignableRoles" of resource type "Role", "assignablePermissions" of resource type "Permission", and "assignableGroups" of resource type "Group". The applied configuration parameters are "base", "additionalFilter", "defaultAttributes" and "mandatoryAttributes". All other configuration parameters are ignored.

The size limit for assignable roles is defined by

  • Request parameter "count".

  • Parameter "defaultCount" of resource type "Role" section "assignableRoles".

  • Parameter "defaultCount" of resource type "Role" section "search".

  • Configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Parameter "maxCount" of resource type "Role" section "assignableRoles".

  • Parameter "maxCount" of resource type "Role" section "search".

  • Configuration parameter "search.maxCount".

in descending priority.

The maximum size limit is restricted by the global LDAP search size limit configured at the domain object. Similar for permissions and groups.

Request

HTTP Method and Path

GET /Users/{userId}/assignableRoles

GET /Users/{userId}/assignablePermissions

GET /Users/{userId}/assignableGroups

GET /Users/{userId}/assignablePrivileges

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

userId -The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. The result includes for each privilege:

    • The mandatory attributes.

    • The requested attributes, if any requested.

    • The default attributes, if no attributes are requested.

  • base - The search base.

  • filter - The search filter. To get entries of a specific resource type only, include a resource type filter, for example

filter=(meta.resourceType eq "Role") and (cn sw "co")

filter=(meta.resourceType eq "Role") or (meta.resourceType eq "Permission")

  • filterValue - The value to replace the placeholder in configuration parameter "valueFilter" (in section “assignableRoles” of resource type “Role” for roles, likewise for groups and permissions) with. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

  • count - The maximum number of entries to return.

Response

HTTP Success Codes

  • OK (200) - The privilege list is returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with the list of privileges:

{
   "totalResults":54,
   "Resources":
   [
      {
         "value":"uid-7f001-6f26d110-11da5aeefcf--78b5",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        domainObjects/uid-7f001-6f26d110-11da5aeefcf--78b5",
         "display":"Contractor",
         "description":"Standard role for all contractors",
        "assignableOnlyOnce":true
      },
      {
         "value":"uid-7f001-6f26d110-11da5aeefcf--78ab",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        domainObjects/uid-7f001-6f26d110-11da5aeefcf--78ab",
         "display":"Project Member",
         "description":"Member of a project",
         "roleParameters": [
            {
               "uid":"uid-7f001-cee271-fed935aa6d--7eb4",
               "name":"Project",
               "type":"DN"
            }
         ],
        "assignableOnlyOnce":false
      },
      (OTHER ROLES ELIMINATED)…
   ]
}

The operation "Users/{userId}/assignablePrivileges", on the other hand, returns a JSON object with three lists, one for each type of privilege:

{
 "roles":{
   "totalResults":240,
   "Resources":[…]
 },
 "permissions":{
   "totalResults":259,
   "Resources":[…]
 },
 "groups":{
   "totalResults":47,
   "Resources":[…]
 }
}

Response Data

  • totalResults - The number of privileges returned.

  • Resources - The list of privileges.

Assigning a Privilege

This operation assigns a privilege to a user.

Request

HTTP Method and Path

POST /Users/{userId}/roles

POST /Users/{userId}/permissions

POST /Users/{userId}/groups

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • ignoreWarnings - Whether to assign the privilege even if the assignment results in a warning for example due to SoD violations (true) or reject the request (false). If a request is rejected, the response body contains details about the SoD violation. The default is false.

Request Body

The request body is a JSON object with details of the new assignment:

{
  "resourceId": "uid-7f001-6f26d110-11da5aeefcf--78b5",
  "assignment": {
        "dxrStartDate":"2017-12-13T00:00:00.000Z",
        "dxrEndDate":"2018-12-13T00:00:00.000Z",
        "dxrNeedsReapproval": false
   },
  "reason":"I need the role for doing my work."
}

For parameterized roles, the assignment also includes the role parameters:

{
  "resourceId": "uid-7f001-6f26d110-11da5aeefcf--78a6",
  "assignment": {
     "dxrEndDate":"2018-12-20T00:00:00.000Z",
     "roleParameters":[
        {
           "uid":"uid-7f001--290d5629-1183529ae71--7ffe",
           "values" : [
              { "value" : "HB-RT 102" },
              { "value" : "HL-KI 716" }
           ]
        }
     ]
  }
}

  • resourceId - The UID of the privilege to assign.

  • assignment - The optional assignment details:

  • dxrStartDate - The start date for the assignment. By default, the assignment is valid immediately (after creation or approval).

    • dxrEndDate - The start date for the assignment. By default, the assignment is valid forever.

    • dxrNeedsReapproval - Whether (true) or not (false) the assignment must be re-approved. The default is false.

    • roleParameters - The array of role parameters, if applicable. Each role parameter is given by its UID (dxruid) and its values.

  • dueDate - The optional assignment due date, that is the date the privileges should be assigned. Setting a due date will start a ticket.

  • reason - The optional reason for the assignment.

Response

HTTP Success Codes

  • CREATED (201) - The assignment has been created.

  • ACCEPTED (202) - The assignment has been created but is awaiting approval.

Assigning Multiple Privileges

This operation assigns multiple privileges to a user. The privileges can be a mix of roles, permissions and groups.

If an assignment fails, the operation stops with a corresponding error response, and will not assign any privilege at all. The client can attach a bulk id to each assignment. The bulk id of the assignment which caused the error is returned in the error response.

SoD violations are collected over all assignments and sent back in a condensed form which also includes the bulk ids of the conflicting assignments.

Request

HTTP Method and Path

POST /Users/{userId}/privileges

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • ignoreWarnings - Whether to assign the privileges even if one or more assignments result in warnings like SoD violations (true), or whether to reject the request in such a case (false). If a request is rejected due to SoD violations, the response body contains details about the SoD violations. The default is false.

Request Body

The request body is a JSON object with details of the new assignments:

{
 "assignments": [
   {
     "bulkId": "Parking Place Munich assignment",
     "resourceId": "uid-7f001-6f26d110-11da5aeefcf--78a6",
     "assignment": {
       "roleParameters":[
         {
           "uid":"uid-7f001--290d5629-1183529ae71--7ffe",
           "values" : [
             { "value" : "HL-KI 716" }
           ]
         }
       ]
     }
   },
   {
     "bulkId": "BusinessObjectAdmin assignment",
     "resourceId": "metacpd482d8-5dde4afb-1388-3314-ab4f8-38",
     "assignment": {
       "dxrStartDate":"2020-12-20T00:00:00.000Z"
     }
   },
   {
     "bulkId": "Silver Customer assignment",
     "resourceId": "uid-7f001-6f26d110-11da5aeefcf--794a",
   }
 ],
 "reason":"A very simple assignnment of permission Silver Customer."
}

  • assignments - The list of privilege assignments.

    • bulkId - An optional client generated bulk identifier for the assignment.

    • resourceId - The UID of the privilege to assign.

    • assignment - The optional assignment details:

      • dxrStartDate - The start date for the assignment. By default, the assignment is valid immediately (after creation or approval).

      • dxrEndDate - The start date for the assignment. By default, the assignment is valid forever.

      • dxrNeedsReapproval - Whether (true) or not (false) the assignment must be re-approved. The default is false.

      • roleParameters - The array of role parameters, if applicable. Each role parameter is given by its UID (dxruid) and its values.

  • reason - The optional reason for the assignments.

  • dueDate - The optional ticket due date for the assignments.

Response

HTTP Success Codes

  • CREATED (201) - The assignments have been created. No assignment must be approved.

  • ACCEPTED (202) - The assignments have been created but one or more of them are awaiting approval.

Reading a Privilege Assignment

This operation retrieves details of a privilege assignment for a user. The request path must include the ID of the assignment. If the ID is the UID of a specific assignment, that assignment is returned. If the ID is the UID of a privilege and the privilege is assigned exactly once to the user, the corresponding privilege assignment is returned. If no assignment or more than one assignment exists, the operation fails.

Request

HTTP Method and Path

GET /Users/{userId}/roles/{assignmentId}

GET /Users/{userId}/permissions/{assignmentId}

GET /Users/{userId}/groups/{assignmentId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

  • assignmentId - The UID of an assignment (cn) or the UID of a privilege (dxruid). The privilege UID can only be used when the privilege is assigned just once.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. The default attributes are "display", "$ref", "value", "type", "description", and "assignment".

Response

HTTP Success Codes

  • OK (200) - The privilege assignment is returned.

Response Content

On success, the operation returns a SCIM privilege object with assignment details:

{
 "value":"uid-7f001-6f26d110-11da5aeefcf--78a6",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                domainObjects/uid-7f001-6f26d110-11da5aeefcf--78a6",
 "display":"Parking Place Munich",
 "description":"Request your slot in the parking place in Munich",
 "type":"direct",
 "assignment":
 {
   "mode":"manual",
   "uid":"uid-a5d1993-6ebccb13-160598706a8--7d29",
   "hasSODViolations":false,
   "isEditable":true,
   "roleParameters":[
     {
       "uid":"uid-7f001--290d5629-1183529ae71--7ffe",
       "values":[
         {
           "display":"M HT 55"
         },
         {
           "display":"M HU 606"
         }
       ],
       "name":"Car Number",
       "type":"Text"
     }
   ],
   "state":"ENABLED",
   "dxrNeedsReapproval":false
 }
}

Here is a second example, this time with role parameters of type HDN:

{
    "assignment":
    {
        "mode":"manual",
        "uid":"uid-a5d19c8-1ae7304f-16262fbf209--7fe5",
        "hasSODViolations":false,
        "isEditable":true,
        "roleParameters":
        [
            {
                "uid":"uid-7f001--6c1b645f-112e5d0d91a--7ffc",
                "values":
                [
                    {
                        "uid":"uid-7f001-6f26d110-11da5aeefcf--76d7",
                        "display":"A119, A11, A1, Cost Locations, Groups,
                                   SAP R3, TargetSystems",
                        "value":"cn=A119,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                                 cn=SAP R3,cn=TargetSystems,cn=My-Company"
                    },
                    {
                        "uid":"uid-7f001-6f26d110-11da5aeefcf--76d3",
                        "display":"A121, A12, A1, Cost Locations, Groups,
                                   SAP R3, TargetSystems",
                        "value":"cn=A121,cn=A12,cn=A1,cn=Cost Locations,cn=Groups,
                                 cn=SAP R3,cn=TargetSystems,cn=My-Company"
                    }
                ],
                "name":"Cost Locations",
                "type":"HDN"
            }
        ],
        "state":"ENABLED",
        "dxrNeedsReapproval":false
    },
    "display":"Cost Location Manager",
    "description":"Assigns the right to manage a cost location.\n
                   Allows additionally assigning other managers to this\n
                   or a lower level cost location.",
    "type":"direct",
    "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78b4",
    "value":"uid-7f001-6f26d110-11da5aeefcf--78b4"
}

Changing a Privilege Assignment

This operation changes a privilege assignment for a user. The request path must include the ID of the assignment to be changed. If the ID is the UID of a specific assignment, that assignment is changed. If the ID is the UID of a privilege, the assignment for that privilege is changed. If multiple assignments match the specified assignment ID, the operation fails with HTTP status code "CONFLICT". Multiple assignments of the same privilege are possible only for roles with parameters.

If an assignment change is subject to approval, the operation does not change the assignment immediately and starts an approval workflow instead.

Request

HTTP Method and Path

PATCH /Users/{userId}/roles/{assignmentId}

PATCH /Users/{userId}/permissions/{assignmentId}

PATCH /Users/{userId}/groups/{assignmentId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support PATCH requests, you can send a POST request instead including this additional header set to PATCH.

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

  • assignmentId - The UID of an assignment (cn) or the UID of a privilege (dxruid). The privilege UID can only be used when the privilege is assigned just once.

Query Parameters

  • ignoreWarnings - When an assignment change will result in a warning, whether to change the assignment anyway (true) or reject the request (false). The default is false.

Request Body

The request body is a JSON object with the changes to be made:

{
   "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
   "Operations" : [
      {
         "op" : "add",
         "path" : "dxrStartDate"
         "value" : "2018-01-01T00:00:00.000Z"
      },
      {
         "op" : "replace",
         "path" : "dxrEndDate",
         "value" : "2030-01-06T00:00:00.000Z"
      },
      {
         "op" : "replace",
         "path" : "dxrNeedsReapproval",
         "value" : true
      }
   ],
   "reason" : "I need these changes now."
}

For parameterized roles, the assignment also includes the role parameters:

{
   "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
   "Operations" : [
      {
         "op" : "remove",
         "path" : "dxrStartDate"
      },
      {
         "op" : "replace",
         "path" : "dxrEndDate",
         "value" : "2030-01-06T00:00:00.000Z"
      },
      {
         "op" : "replace",
         "path" : "roleParameters",
         "value" : [
            {
               "uid" : "uid-7f001-cee271-fed935aa6d--7eb4",
               "values" : [
                  {
                     "value" : "High performance"
                  },
                  {
                     "value" : "MoreCustomers"
                  }
               ]
            }
         ]
      }
   ],
   "reason" : "I need these changes now."
}

  • Operations - The modify operations to be performed. Relevant assignment attributes are:

    • dxrStartDate - The start date for the assignment.

    • dxrEndDate - The end date for the assignment.

    • dxrNeedsReapproval - Whether (true) or not (false) the assignment must be re-approved.

    • roleParameters - The array of role parameters, if applicable. Each role parameter is given by its UID (dxruid) and its values.

  • dueDate - The optional modification due date, that is the date the assignment should be modified. Setting a due date will start a ticket.

  • reason - The optional reason for requesting the changes.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The assignment has been changed.

  • ACCEPTED (202) - The assignment has been changed but the changes are awaiting approval.

Deleting a Privilege Assignment

This operation deletes a privilege assignment for a user. The request path must include the ID of the assignment(s) to be deleted. If the ID is the UID of a specific assignment, that assignment is deleted. If multiple assignments match the specified assignment ID, the operation fails with HTTP status code "CONFLICT". Multiple assignments of the same privilege are possible only for roles with parameters.

If an assignment deletion is subject to approval, the operation does not delete the assignment immediately and starts an approval workflow instead.

Request

HTTP Method and Path

DELETE /Users/{userId}/roles/{assignmentId}

DELETE /Users/{userId}/permissions/{assignmentId}

DELETE /Users/{userId}/groups/{assignmentId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support DELETE requests with request bodies, you can send a POST request instead including this additional header set to DELETE.

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

  • assignmentId - The UID of an assignment (cn) or the UID of a privilege (dxruid). The privilege UID can only be used when the privilege is assigned just once.

Request Body

The request body is a JSON object that specifies the reason for the deletion:

{
  "reason":"I don’t need the role anymore."
}

  • dueDate - The optional deletion due date, that is the date the assignment should be deleted. Setting a due date will start a ticket.

  • reason - The optional reason for requesting to delete the assignment.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The assignment has been deleted, or deletion is awaiting approval.

  • ACCEPTED (202) - The assignment has been marked for deletion but the deletion is subject to approval.

Reading a Role Parameter Configuration

This operation retrieves the configuration of the parameters of a role that is or can be assigned to a user.

The request path must include the ID of the role assignment, the assigned role, or the role to be assigned. It doesn’t matter whether the role is assigned just once or more than once since the parameter configuration depends only on the role but not on any specific assignment.

Note that the configuration may vary with the role, the user and the authenticated user.

See the section “Assigning Roles with Parameters” for details on when and how to use this request.

Request

HTTP Method and Path

GET /Users/{userId}/roles/{roleId}/roleParams

GET /Users/{userId}/assignableRoles/{roleId}/roleParams

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

  • roleId - The UID of a role assignment (cn) or the UID of a role (dxruid).

Response

HTTP Success Codes

  • OK (200) - The role parameter configuration is returned.

Response Content

On success, the operation returns a JSON array of role parameter configurations:

[
   {
       "name":"Cost Locations",
       "uid":"uid-7f001--6c1b645f-112e5d0d91a--7ffc",
       "description":"Role parameter to assign cost locations",
       "type":"HDN",
       "mandatory":true,
       "singleValued":false,
       "selectLeavesOnly":false,
       "uniqueValues":false,
       "minimum":0,
       "maximum":0,
       "defaultValues":
       [
       ],
       "proposals":
       [
           {
               "display":"A111, A11, A1, Cost Locations, Groups,
                          SAP R3, TargetSystems",
               "uid":"uid-7f001-6f26d110-11da5aeefcf--76e1",
               "value":"cn=A111,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                        cn=SAP R3,cn=TargetSystems,cn=My-Company",
               "selectable":true,
               "leaf":false
           },
           {
               "display":"A119, A11, A1, Cost Locations, Groups,
                          SAP R3, TargetSystems",
               "uid":"uid-7f001-6f26d110-11da5aeefcf--76d7",
               "value":"cn=A119,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                        cn=SAP R3,cn=TargetSystems,cn=My-Company",
               "selectable":true,
               "leaf":false
           }
       ]
   }
]

Here is a second example, this time with role parameters of type DN and Text:

[
   {
       "name":"Project",
       "uid":"uid-7f001-cee271-fed935aa6d--7eb4",
       "description":"Role parameter that lists all projects of My-Company",
       "type":"DN",
       "mandatory":true,
       "singleValued":false,
       "selectLeavesOnly":false,
       "uniqueValues":false,
       "minimum":0,
       "maximum":0,
       "defaultValues":
       [
       ],
       "proposals":
       [
           { "display":"High performance" },
           { "display":"MoreCustomers" },
           { "display":"OptimizeIT" },
           { "display":"Testproject" }
       ]
   },
   {
       "name":"Car Number",
       "uid":"uid-7f001--290d5629-1183529ae71--7ffe",
       "description":"The number of your car for the Parking lot",
       "type":"Text",
       "mandatory":false,
       "singleValued":false,
       "selectLeavesOnly":false,
       "uniqueValues":false,
       "minimum":0,
       "maximum":0,
       "defaultValues":
       [
       ],
       "proposals":
       [
       ]
   }
]

Reading the Next Level of HDN Role Parameter Nodes

This operation retrieves the children of a given role parameter node for a role parameter of type HDN.

The request path must include the ID of the role assignment, the assigned role, or the role to be assigned. It doesn’t matter whether the role is assigned just once or more than once since the parameter configuration depends only on the role but not on any specific assignment. The path must also include the ID of the HDN role parameter and of the parent node whose children are requested.

Note that the configuration may vary with the role, the user and the authenticated user.

See the section “Assigning Roles with Parameters” for details on when and how to use this request.

Request

HTTP Method and Path

GET /Users/{userId}/roles/{roleId}/roleParams/{roleParamId}
/proposal/{roleParamNodeId}

GET /Users/{userId}/assignableRoles/{roleId}/roleParams/
{roleParamId}/proposal/{roleParamNodeId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

  • roleId - The UID of an assignment (cn), or the UID of a role (dxruid).

  • roleParamId - The UID of HDN role parameter (dxruid).

  • roleParamNodeId - The UID of a role parameter node (dxruid).

Response

HTTP Success Codes

  • OK (200) - The children of the role parameter node are returned.

Response Content

On success, the operation returns a JSON array with the children of the specified role parameter node; in the following example, node "cn=A111,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,cn=SAP R3,cn=TargetSystems,cn=My-Company":

[
   {
       "display":"A1111",
       "uid":"uid-7f001-6f26d110-11da5aeefcf--76e0",
       "value":"cn=A1111,cn=A111,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                cn=SAP R3,cn=TargetSystems,cn=My-Company",
       "selectable":true,
       "leaf":true
   },
   {
       "display":"A1112",
       "uid":"uid-7f001-6f26d110-11da5aeefcf--76df",
       "value":"cn=A1112,cn=A111,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                cn=SAP R3,cn=TargetSystems,cn=My-Company",
       "selectable":true,
       "leaf":true
   }
]

Listing Pending Privilege Assignments

This operation retrieves the privileges that have been assigned to a user but are still awaiting approval; that is, the privileges with assignment state "ADD".

The list of subject types for the tickets and workflows can be configured in section ”requests” of resource type "User".

The search base for the tickets can be configured in section "search" of resource type "Ticket". The search base for the workflows can be configured in section "search" of resource type "WorkflowInstance".

The size limit is defined by

  • Parameter "defaultCount" in section "search" of resource type "Ticket" or "WorkflowInstance".

  • Configuration parameter "search.defaultCount".

in descending priority.

Request

HTTP Method and Path

GET /Users/{userId}/pendingRoles

GET /Users/{userId}/pendingPermissions

GET /Users/{userId}/pendingGroups

GET /Users/{userId}/pendingPrivileges

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests that are scheduled to be performed on some future day. The default is true.

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. The default attributes are "display", "$ref", "value", "type", "description", and "assignment". The value is the privilege’s unique ID.

  • filterValue - A filter for the privilege assignment requests. A request matches if one of its resources or its initiator match. For resources, the value replaces the placeholder in configuration parameter "valueFilter" in section “search” of resource type “Role” for roles, likewise for groups and permissions. For initiators, the value replaces the placeholder in configuration parameter "valueFilter" in section “search” of resource type “User”. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

Response

HTTP Success Codes

  • OK (200) - The assignment list is returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with a single list of respective privilege assignments:

{
  "totalResults":3,
  "Resources":
  [
     {
        "assignment":
        {
           "hasSODViolations":false,
           "isEditable":false,
           "mode":"manual",
           "state":"ADD",
           "dxrNeedsReapproval":false,
           "dxrStartDate":"2017-12-03T23:00:00.000Z"
        },
        "display":"Corporate Credit Card",
        "description":"Request your corporate credit card for travelling",
        "type":"direct",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                      Users/uid-7f001-6f26d110-11da5aeefcf--7ff9/
                      pendingRoles/uid-a5dcb1--350b007-17d2e0908a0--7fd2/3",
       "value":"uid-a5dcb1--350b007-17d2e0908a0--7fd2/3"
    },
    (OTHER ASSIGNMENTS ELIMINATED)…
 ]
}

The attributes "value" and "$ref" return the request ID, which is the UID of the ticket or workflow (here "uid-a5dcb1—​350b007-17d2e0908a0—​7fd2".) If the request is a ticket with more than one assignment, the attributes also include the order ID, which is the index of the assignment within the ticket (here "3".)

The operation "Users/{userId}/pendingPrivileges", on the other hand, returns a JSON object with three lists, one for each type of privileges:

{
 "roles":{
   "totalResults":3,
   "Resources":[…]
 },
 "permissions":{
   "totalResults":3,
   "Resources":[…]
 },
 "groups":{
   "totalResults":2,
   "Resources":[…]
 }
}

Response Data

  • totalResults - The number of privilege assignments returned.

  • Resources - The list of privilege assignments.

Counting Pending Privilege Assignments

This operation counts the pending privilege assignments for a user.

The size limit for ticket searches can be configured in section "search" of resource type "Ticket". The size limit for workflow searches can be configured in section "search" of resource type "WorkflowInstance".

The size limit for counting the assignments is defined by

  • Parameter "maxCount" of resource type "User" section "search".

  • Configuration parameter "search.maxCount".

in descending priority.

Request

HTTP Method and Path

GET /Users/{userId}/pendingRoles/count

GET /Users/{userId}/pendingPermissions/count

GET /Users/{userId}/pendingGroups/count

GET /Users/{userId}/pendingPrivileges/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

Response

HTTP Success Codes

  • OK (200) - The numbers of assignments are returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with a single counter:

{
 "totalResults":3,
 "sizeLimitExceeded":false
}

The operation "Users/{userId}/pendingPrivileges/count", on the other hand, returns a JSON object with three counters, one for each type of privilege:

{
 "roles":{
   "totalResults":3,
   "sizeLimitExceeded":false
 },
 "permissions":{
   "totalResults":1,
   "sizeLimitExceeded":false
 },
 "groups":{
   "totalResults":0,
   "sizeLimitExceeded":false
 }
}

Response Data

  • totalResults - The number of privilege assignments.

  • sizeLimitExceeded -Whether (true) or not (false) the operation reached a size limit. The size limit is 1000 for searching the relevant approval workflows and 1000 for searching the relevant tickets.

Reading a Pending Privilege Assignment

This operation retrieves details of a pending privilege assignment for a user. The request path must include the request ID and optionally the order ID of the pending assignment.

Request

HTTP Method and Path

GET /Users/{userId}/pendingRoles/{requestId}

GET /Users/{userId}/pendingPermissions/{requestId}/{orderId}

GET /Users/{userId}/pendingPermissions/{requestId}

GET /Users/{userId}/pendingPrivileges/{requestId}/{orderId}

GET /Users/{userId}/pendingGroups/{requestId}

GET /Users/{userId}/pendingGroups/{requestId}/{orderId}

GET /Users/{userId}/pendingPrivileges/{requestId}

GET /Users/{userId}/pendingRoles/{requestId}/{orderId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow and activity attributes.

Path Parameters

  • userId - The user’s UID (dxruid).

  • requestId - The UID of a pending privilege assignment.

  • orderId - If the source oif the pending privilege is a ticket with multiple assignments:the index of the assignment within the ticket, as returned by the list operation.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specifies the privilege attributes to be returned in the result. The default attributes are "display", "$ref", "value", "description", "assignment", "initiator", "subject", "currentParticipants", "nextApprovalDate", "requestReason", "dueDate", and "targetSystem.cn" (for groups only).

Response

HTTP Success Codes

  • OK (200) - The privilege assignment is returned.

Response Content

On success, the operation returns a SCIM privilege assignment object with details:

{
"nextApprovalDate":"2019-05-03T13:59:01.000Z",
"subject":
{
  "displayName":"Nik Taspatch",
  "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
  "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                /users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
},
"assignment":
{
  "mode":"manual",
  "hasSODViolations":false,
  "isEditable":false,
  "operation":"ADD"
},
"display":"Signature Level 3",
"initiator":
{
  "displayName":"Lavina Pitton",
  "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
  "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                /users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
},
"currentParticipants":
[
  {
    "displayName":"Olivier Hungs",
    "value":"00014281",
    "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                  /users/00014281"
  },
  {
    "displayName":"Christopher Dalmar",
    "value":"10052505",
    "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                  /users/10052505"
  }
],
"description":"Highest level of signatures for top management",
"$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
              /Users/uid-7f001-6f26d110-11da5aeefcf--7ff9
              /pendingRoles/16a77c7d134%24-6874/16a77c7d134%24-6874",
"value":"16a77c7d134$-6874"
}

Listing Pending Profile Changes

This operation retrieves the pending changes to a user’s profile. A change may be pending because it is awaiting approval or because it has been scheduled to be performed on some future day.

The list of subject types for the tickets and workflows can be configured in section ”requests” of resource type "User".

The search base for the tickets can be configured in section "search" of resource type "Ticket". The search base for the workflows can be configured in section "search" of resource type "WorkflowInstance".

The size limit is defined by

  • Parameter "defaultCount" in section "search" of resource type "Ticket" or "WorkflowInstance".

  • Configuration parameter "search.defaultCount".

in descending priority.

Request

HTTP Method and Path

GET /Users/{userId}/pendingProfileChanges

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

  • filterValue - A filter for the profile change initiator. The value will replace the placeholder in configuration parameter "valueFilter" in section “search” of resource type “User”. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no filter is applied.

Response

HTTP Success Codes

  • OK (200) - The assignment list is returned.

Response Content

On success, the operation returns a JSON object with the list of profile changes:

{
"totalResults":2,
"Resources":
[
  {
    "nextApprovalDate":"2019-07-03T14:01:02.000Z",
    "subject":
    {
      "displayName":"Marc Abele",
      "value":"uid-7f001-6f26d110-11da5aeefcf--7ffc",
      "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                     Users/uid-7f001-6f26d110-11da5aeefcf--7ffc"
    },
    "display":"Abele Marc",
    "initiator":
    {
      "displayName":"Nik Taspatch",
      "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
      "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                     Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
    },
    "currentParticipants":
    [
      {
        "displayName":"Administrator",
        "value":"metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Users/metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4"
      },
      {
        "displayName":"Lavina Pitton",
        "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
      },
      {
        "displayName":"Nik Taspatch",
        "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
      }
    ],
    "id":"16b1c3bf967$-753a",
    "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ffc/
                   pendingProfileChanges/16b1c3bf967%24-753a",
    "mode":"manual",
    "state":"InApproval",
    "modifications":
    [
      {
        "path":"mail",
        "oldValue":
        [
          "Marc.Abele@My-Company.com"
        ],
        "newValue":
        [
          "Marcello.Abele@My-Company.com"
        ],
        "scimPaths":
        [
          "emails#work"
        ]
      }
    ]
  },
  {
    "subject":
    {
      "displayName":"Marc Abele",
      "value":"uid-7f001-6f26d110-11da5aeefcf--7ffc",
      "$ref":http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/uid-7f001-6f26d110-11da5aeefcf--7ffc
    },
    "display":"Abele Marc 12:18:17",
    "initiator":
    {
      "displayName":"Nik Taspatch",
      "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
      "$ref":http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/uid-7f001-6f26d110-11da5aeefcf--7ff9
    },
    "id":"uid-a5d19dc--625fc563-169c92aafe6--7fad",
    "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ffc/
                   pendingProfileChanges/uid-a5d19dc--169c92aafe6--7fad",
    "dueDate":"2020-03-30T22:00:00.000Z",
    "mode":"manual",
    "state":"Input.Completed",
    "modifications":
    [
      {
        "path":"telephonenumber",
        "oldValue":"+49 89 6263-4096",
        "newValue":"+49 89 6263-4096 1000",
        "scimPaths":
        [
          "phoneNumbers#work"
        ]
      }
    ]
  }
]
}

Response Data

  • totalResults - The number of pending profile changes returned.

  • Resources - The list of pending profile changes.

Counting Pending Profile Changes

This operation counts the pending changes to a user’s profile.

The size limit for ticket searches can be configured in section "search" of resource type "Ticket". The size limit for workflow searches can be configured in section "search" of resource type "WorkflowInstance".

The size limit is given by "search" section parameter "maxCount" or general configuration parameter "search.maxCount" in descending priority.

Request

HTTP Method and Path

GET /Users/{userId}/pendingProfileChanges/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

Response

HTTP Success Codes

  • OK (200) - The number of pending profile changes is returned.

Response Content

On success, the operation returns a JSON object with number of pending profile changes:

{
 "totalResults":4,
 "sizeLimitExceeded":false
}

Response Data

  • totalResults - The number of pending profile changes.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached a size limit. The size limits are 1000 for profile changes awaiting approval and 1000 for ticketed profile changes.

Reading a Pending Profile Change

This operation retrieves details of a pending profile change request for a user. The request path must include the request ID.

Request

HTTP Method and Path

GET /Users/{userId}/pendingProfileChange/{requestId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow and activity attributes.

Path Parameters

  • userId - The user’s UID (dxruid).

  • requestId - The UID of a pending profile change.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specifies the profile change attributes to be returned in the result.

Response

HTTP Success Codes

  • OK (200) - The profile change is returned.

Response Content

On success, the operation returns a profile change object with details:

{
 "subject":
 {
   "displayName":"Marc Abele",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ffc",
   "$ref":http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ffc
 },
 "display":"Abele Marc 12:18:17",
 "initiator":
 {
   "displayName":"Nik Taspatch",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "$ref":http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff9
 },
 "id":"uid-a5d19dc--625fc563-169c92aafe6--7fad",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                Users/uid-7f001-6f26d110-11da5aeefcf--7ffc/
                pendingProfileChanges/uid-a5d19dc--625fc563-169c92aafe6--7fad",
 "dueDate":"2020-03-30T22:00:00.000Z",
 "mode":"manual",
 "state":"Input.Completed",
 "modifications":
 [
   {
     "path":"telephonenumber",
     "oldValue":"+49 89 6263-4096",
     "newValue":"+49 89 6263-4096 1000",
     "scimPaths":
     [
       "phoneNumbers#work"
     ]
   }
 ]
}

Listing Initiated Requests

This operation retrieves the privileges that have been assigned by a user but are still awaiting approval and the profile changes requested by the user that are still awaiting approval.

The list of subject types for the tickets and workflows can be configured in section ”requests” of resource type "User".

The search base for the tickets can be configured in section "search" of resource type "Ticket". The search base for the workflows can be configured in section "search" of resource type "WorkflowInstance".

The size limit is defined by

  • Parameter "defaultCount" in section "search" of resource type "Ticket" or "WorkflowInstance".

  • Configuration parameter "search.defaultCount".

in descending priority.

Request

HTTP Method and Path

GET /Users/{userId}/pendingRequests

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • includeProfileChanges - Whether (true) or not (false) to include profile change requests. The default is true.

  • includePrivilegeAssignmentChanges - Whether (true) or not (false) to include privilege assignment requests. The default is true.

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

  • filter - The SCIM filter to be applied when searching for initiated profile changes and privilege assignments. The default is no filter.

  • workflowFilter - The SCIM filter to be applied when searching for privilege assignments. The default is no filter.

  • ticketFilter - The SCIM filter to be applied when searching for ticketed requests. The default is no filter.

  • filterValue - A filter for the privilege assignment requests. A request matches if one of its resources or its subject match. For resources, the value replaces the placeholder in configuration parameter "valueFilter" in section “search” of resource type “Role” for roles, likewise for groups and permissions. For subject, the value replaces the placeholder in configuration parameter "valueFilter" in section “search” of resource type “User”. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

Response

HTTP Success Codes

  • OK (200) - The initiated requests are returned.

Response Content

On success, the operation returns a JSON object with the list of initiated requests for each privilege type and another list with profile changes:

{
"profileChanges":
{
  "totalResults":1,
  "Resources":
  [
    {
      "nextApprovalDate":"2019-07-03T15:15:43.000Z",
      "subject":
      {
        "displayName":"Christopher Dalmar",
        "value":"10052505",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Users/10052505"
      },
      "display":"Dalmar Christopher",
      "initiator":
      {
        "displayName":"Olivier Hungs",
        "value":"00014281",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Users/00014281"
      },
      "currentParticipants":
      [
        {
          "displayName":"Administrator",
          "value":"metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4",
          "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                         Users/metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4"
        },
        {
          "displayName":"Lavina Pitton",
          "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
          "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                         Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
        },
        {
          "displayName":"Nik Taspatch",
          "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
          "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                         Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
        }
      ],
      "id":"16b1c3bf967$-740d",
      "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                     Users/uid-7f001/pendingRequests/16b1c3bf967%24-740d",
      "mode":"manual",
      "state":"InApproval",
      "modifications":
      [
        {
          "path":"mail",
          "oldValue":
          [
            "Christopher.Dalmar@My-Company"
          ],
          "newValue":
          [
            "Chris.Dalmar@My-Company.com",
            "Christopher.Dalmar@My-Company"
          ],
          "scimPaths":
          [
            "emails#work"
          ]
        }
      ]
    }
  ]
},
"permissions":
{
  "totalResults":1,
  "Resources":
  [
    {
      "nextApprovalDate":"2019-04-16T13:02:29.000Z",
      "subject":
      {
        "displayName":"Gabriela Morton",
        "value":"uid-7f001-6f26d110-11da5aeefcf--7ffd",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Users/uid-7f001-6f26d110-11da5aeefcf--7ffd"
      },
      "assignment":
      {
        "mode":"manual",
        "hasSODViolations":false,
        "isEditable":false,
        "operation":"ADD"
      },
      "display":"Manager",
      "initiator":
      {
        "displayName":"Olivier Hungs",
        "value":"00014281",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Users/00014281"
      },
      "currentParticipants":
      [
        {
          "displayName":"Olivier Hungs",
          "value":"00014281",
          "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                         Users/00014281"
        },
        {
          "displayName":"Christopher Dalmar",
          "value":"10052505",
          "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                         Users/10052505"
        }
      ],
      "description":"Standard permission for managers",
      "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                     Users/uid-7f001/pendingRequests/16a20df4e51%24-69b8",
      "value":"16a20df4e51$-69b8"
    }
  ]
},
"roles":
{
  "totalResults":0,
  "Resources":
  [
  ]
},
"groups":
{
  "totalResults":0,
  "Resources":
  [
  ]
}
}

The attributes "value" and "$ref" return the request ID, which is the UID of the ticket or workflow If the request is a ticket with more than one assignment, the attributes also include the order ID, which is the index of the assignment within the ticket.

Response Data

  • totalResults - The number of initiated requests returned.

  • Resources - The list of initiated requests.

Counting Initiated Requests

This operation counts the pending requests initiated by a user.

The size limit for ticket searches can be configured in section "search" of resource type "Ticket". The size limit for workflow searches can be configured in section "search" of resource type "WorkflowInstance".

The size limit is given by "search" section parameter "maxCount" or general configuration parameter "search.maxCount" in descending priority.

Request

HTTP Method and Path

GET /Users/{userId}/pendingRequests/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • includeProfileChanges - Whether (true) or not (false) to include profile change requests. The default is true.

  • includePrivilegeAssignmentChanges - Whether (true) or not (false) to include privilege assignment requests. The default is true.

  • includeWorkflowRequests -Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

  • filter - The SCIM filter to be applied when searching for initiated profile changes and privilege assignments. The default is no filter.

  • workflowFilter - The SCIM filter to be applied when searching for privilege assignments. The default is no filter.

  • ticketFilter - The SCIM filter to be applied when searching for ticketed requests. The default is no filter.

Response

HTTP Success Codes

  • OK (200) - The numbers of pending initiated requests are returned.

Response Content

On success, the operation returns counters for each privilege type, and another counter for profile changes.

{
 "profileChanges":{
   "totalResults":2,
   "sizeLimitExceeded":false
 },
 "roles":{
   "totalResults":4,
   "sizeLimitExceeded":false
 },
 "permissions":{
   "totalResults":1,
   "sizeLimitExceeded":false
 },
 "groups":{
   "totalResults":0,
   "sizeLimitExceeded":false
 }
}

Response Data

  • totalResults - The number of pending initiated privilege assignments or profile changes.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached the size limit. The size limit for counting profile change workflows, profile change tickets, privilege assignment workflows and privilege assignment tickets is 1000 each.

Reading an Initiated Request

This operation retrieves details of a pending request initiated by a user.

Request

HTTP Method and Path

GET /Users/{userId}/pendingRequests/{requestId}

GET /Users/{userId}/pendingRequests/{requestId}/{orderId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

  • requestId - The UID of a pending request initiated by the user.

  • orderId - The index of the assignment within a privilege assignment ticket, as returned by the list operation.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specifies the attributes to be returned in the result. By default, the request returns all attributes. The parameter is ignored for profile changes.

Response

HTTP Success Codes

  • OK (200) - The initiated request is returned.

Response Content

On success, the operation returns a JSON object with details of the initiated request:

{
 "nextApprovalDate":"2019-07-03T15:15:43.000Z",
 "subject":
 {
   "displayName":"Christopher Dalmar",
   "value":"10052505",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                  Users/10052505"
 },
 "display":"Dalmar Christopher",
 "initiator":
 {
   "displayName":"Olivier Hungs",
   "value":"00014281",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                  Users/00014281"
 },
 "currentParticipants":
 [
   {
     "displayName":"Administrator",
     "value":"metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4"
   },
   {
     "displayName":"Lavina Pitton",
     "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
   },
   {
     "displayName":"Nik Taspatch",
     "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
   }
 ],
 "id":"16b1c3bf967$-740d",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                Me/pendingRequests/16b1c3bf967%24-740d",
"mode":"manual",
"state":"InApproval",
"modifications":
[
  {
    "path":"mail",
    "oldValue":
    [
      "Christopher.Dalmar@My-Company"
    ],
    "newValue":
    [
      "Chris.Dalmar@My-Company.com",
      "Christopher.Dalmar@My-Company"
    ],
    "scimPaths":
    [
      "emails#work"
    ]
  }
]
}

Deleting an Initiated Request

This operation cancels the workflow or deletes the ticket which is the source of a pending request initiated by a user.

Request

HTTP Method and Path

DELETE /Users/{userId}/pendingRequests/{requestId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

  • requestId - The UID of a pending request initiated by the user.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The initiated request has been deleted.

Listing Closed Requests

This operation lists the finished requests with a given user as initiator or subject. The list includes privilege assignment changes as well as profile changes, workflow requests as well as ticket requests.

The list of subject types for the tickets and workflows can be configured in section ”requests” of resource type "User".

The search base for the tickets can be configured in section "search" of resource type "Ticket". The search base for the workflows can be configured in section "search" of resource type "WorkflowInstance".

The size limit is defined by

  • Parameter "defaultCount" in section "search" of resource type "Ticket" or "WorkflowInstance".

  • Configuration parameter "search.defaultCount".

in descending priority.

The list of attributes returned for each closed request is fixed.

Request

HTTP Method and Path

GET /Users/{userId}/closedRequests

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • includeProfileChanges - Whether (true) or not (false) to include profile change requests. The default is true.

  • includePrivilegeAssignmentChanges - Whether (true) or not (false) to include privilege assignment requests. The default is true.

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow was started. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which were scheduled to be performed on a specific day. The default is true.

  • filter - The SCIM filter to be applied when searching for profile changes and privilege assignments. The default is no filter.

  • workflowFilter - The SCIM filter to be applied when searching for requests for which an approval workflow was started. The default is no filter.

  • ticketFilter - A SCIM filter to be applied when searching for ticketed requests. The default is no filter.

  • filterValue - A filter value for the request’s subject, initiator, and resource. The value is to replace the placeholder in configuration parameter "valueFilter" in section "search” of the resource type configurations for "User" (subject and initiator) and, depending on the workflow resource’s type, for "Role", "Permission" or "Group” (resource). Asterisks (*) within the filter value serve as wildcards. If left unspecified, no filter is applied.

  • from - The earliest end date (for example "2021-03-10T00:00:00.000Z"). By default, there’s no lower bound for the end date.

  • to - The latest end date (for example "2021-06-10T00:00:00.000Z"). By default, there’s no upper bound for the end date.

Response

HTTP Success Codes

  • OK (200) - The closed requests are returned.

Response Content

On success, the operation returns a JSON object with the list of closed requests for each privilege type, and another list with profile changes:

{
 "profileChanges":
 {
   "totalResults":1,
   "Resources":
   [
     {
       "mode":"manual",
       "applicationState":"CHANGES_APPLIED",
       "endDate":"2021-03-16T12:06:44.000Z",
       "subject":
       {
         "displayName":"Nik Taspatch",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
       },
       "display":"Taspatch Nik",
       "initiator":
       {
         "displayName":"Olivier Hungs",
         "value":"00014281
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/00014281"
       },
       "state":"SUCCEEDED",
       "value":"17839d3a27d$-6f7b",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               Me/closedRequests/17839d3a27d%24-6f7b",
       "startDate":"2021-03-16T12:05:14.000Z",
       "expirationDate":"2021-03-20T12:05:14.000Z
       "modifications":
       [
         {
           "path":"dxroulink",
           "newValue":
           {
             "displayName":"Sales",
             "value":"uid-7f001-6f26d110-11da5aeefcf--7970",
             "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                     DomainObjects/uid-7f001-6f26d110-11da5aeefcf--7970"
           }
         },
         {
           "path":"dxrlocationlink",
           "newValue":
           {
             "displayName":"My-Company Rome",
             "value":"uid-7f001-6f26d110-11da5aeefcf--795f",
             "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                     DomainObjects/uid-7f001-6f26d110-11da5aeefcf--795f"
           }
         }
       ]
     }
   ]
 },
 "permissions":
 {
   "totalResults":0,
   "Resources":
   [
   ]
 },
 "roles":
 {
   "totalResults":0,
   "Resources":
   [
   ]
 },
 "groups":
 {
   "totalResults":1,
   "Resources":
   [
 {
   "workflow":
   {
     "displayName":"Dalmar Christopher -> Software Beta Programs",
     "value":"1762760dce7$-63ea",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             DomainObjects/1762760dce7%24-63ea"
   },
   "endDate":"2021-03-15T15:15:44.997Z",
   "subject":
   {
     "displayName":"Christopher Dalmar",
     "value":"10052505",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/10052505"
   },
   "assignment":
   {
     "mode":"manual",
     "hasSODViolations":false,
     "isEditable":false,
     "operation":"ADD"
   },
   "display":"Software Beta Programs",
   "initiator":
   {
     "displayName":"Nik Taspatch",
     "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
   },
   "dueDate":"2021-11-30T23:00:00.000Z",
   "description":"Service to access software beta programs of My-Company",
   "targetsystem.cn":"Extranet Portal",
   "state":"Approval.Error",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Me/closedRequests/uid-a5dcb1-4eea9959-176280034f5--7dfe",
   "value":"uid-a5dcb1-4eea9959-176280034f5--7dfe",
   "startDate":"2020-12-03T10:02:40.960Z"
 }
}

Response Data

  • totalResults - The number of closed requests returned.

  • Resources - The list of closed requests.

Reading a Closed Request

This operation retrieves details of a closed request with a given user as initiator or subject.

If the request was processed by a workflow, the result includes the list of finished people activities.

The list of attributes returned for the closed request is fixed.

Request

HTTP Method and Path

GET /Users/{userId}/closedRequests/{requestId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow and activity attributes.

Path Parameters

  • userId - The user’s UID (dxruid).

  • requestId - The UID of a closed request which the user is the initiator of subject of.

Response

HTTP Success Codes

  • OK (200) - The closed request is returned.

Response Content

On success, the operation returns a JSON object with details of the closed request. For examples, see the corresponding Self Service operation.

Listing Personas

This operation returns the list of personas of a user.

No size or time limits apply to this operation.

If you also also need the list of user facets or functional users, use request "Listing Users" for performance reasons.

When reading the profile of the user (request "Reading the Profile"), you can get the list of personas via the virtual user attribute "personasForUser".

Request

HTTP Method and Path

GET /Users/{userId}/personas

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the persona attributes to be returned in the result. The default and mandatory attributes can be configured in section "search" of resource type "Persona".

Response

HTTP Success Codes

  • OK (200) - The personas are returned.

Response Content

On success, the operation returns a JSON object with the list of personas; attribute “value” is the persona’s unique ID:

{
 "startIndex":1,
 "totalResults":1,
 "itemsPerPage":1,
 "schemas":
 [
   "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 ],
 "Resources":
 [
   {
     "owner":
     {
       "displayName":"Bruno Klarmann",
       "value":"10052504",
       "$ref":"http://localhost:8080/
               DirXIdentityRestService-My-Company/Users/10052504"
     },
     "dxruseruid":"10052504",
     "c":"US",
     "displayName":"Klarmann Bruno Psn",
     "dn":"cn=Klarmann Bruno Psn,ou=Sales Europe,ou=Sales,
           o=My-Company,cn=Users,cn=My-Company",
     "id":"cn=Klarmann Bruno Psn,ou=Sales Europe,ou=Sales,
           o=My-Company,cn=Users,cn=My-Company",
     "value":"uid-c0a8c84--7e9b4cc4-13caacc7369--7f71",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-c0a8c84--7e9b4cc4-13caacc7369--7f71"
   }
 }
}

Response Data

  • totalResults - The number of personas returned.

  • Resources - The list of personas.

Counting Personas

This operation returns the number of personas of a user.

No size or time limits apply to this operation.

If you also also need the number of user facets or functional users, use request "Counting Users" for performance reasons.

Request

HTTP Method and Path

GET /Users/{userId}/personas/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Response

HTTP Success Codes

  • OK (200) - The number of personas is returned.

Response Content

On success, the operation returns a JSON object with the number of personas:

{
 "totalResults":1
}

Response Data

  • totalResults - The number of personas.

Listing User Facets

This operation returns the list of user facets of a user.

No size or time limits apply to this operation.

If you also also need the list of personas or functional users, use request "Listing Users" for performance reasons.

When reading the profile of the user (request "Reading the Profile"), you can get the list of user facets via the virtual user attribute "userFacetsForUser".

Request

HTTP Method and Path

GET /Users/{userId}/userFacets

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the user facet attributes to be returned in the result. The default and mandatory attributes can be configured in section "search" of resource type "UserFacet".

Response

HTTP Success Codes

  • OK (200) - The user facets are returned.

Response Content

On success, the operation returns a JSON object with the list of user facets; attribute “value” is the user facet’s unique ID:

{ "startIndex":1, "totalResults":1, "itemsPerPage":1, "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "Resources": [ { "owner": { "displayName":"Bruno Klarmann", "value":"10052504", "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/ Users/10052504" }, "dxruseruid":"10052504", "displayName":"Klarmann Bruno UFt", "dn":"cn=Klarmann Bruno UFt,ou=Sales Europe,ou=Sales, o=My-Company,cn=Users,cn=My-Company", "id":"cn=Klarmann Bruno UFt,ou=Sales Europe,ou=Sales, o=My-Company,cn=Users,cn=My-Company", "value":"uid-a5dcb1-526441a-175b10b4afb—​7d25", "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/ Users/uid-a5dcb1-526441a-175b10b4afb—​7d25" } ] }

Response Data

  • totalResults - The number of user facets returned.

  • Resources - The list of user facets.

Counting User Facets

This operation returns the number of user facets of a user.

No size or time limits apply to this operation.

If you also also need the number of personas or functional users, use request "Counting Users" for performance reasons.

Request

HTTP Method and Path

GET /Users/{userId}/userFacets/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Response

HTTP Success Codes

  • OK (200) - The number of user facets is returned.

Response Content

On success, the operation returns a JSON object with the number of user facets:

{
 "totalResults":1
}

Response Data

  • totalResults - The number of user facets.

Listing Functional Users

This operation returns the list of functional users of a user.

No size or time limits apply to this operation.

If you also also need the list of personas or user facets, use request "Listing Users" for performance reasons.

When reading the profile of the user (request "Reading the Profile"), you can get the list of functional users via the virtual user attribute "functionalUsersForUser".

Request

HTTP Method and Path

GET /Users/{userId}/functionalUsers

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the functional user attributes to be returned in the result. The default and mandatory attributes can be configured in section "search" of resource type "FunctionalUser".

Response

HTTP Success Codes

  • OK (200) - The functional users are returned.

Response Content

On success, the operation returns a JSON object with the list of functional users; attribute “value” is the functional users’s unique ID:

{
 "startIndex":1,
 "totalResults":1,
 "itemsPerPage":1,
 "schemas":
 [
   "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 ],
 "Resources":
 [
   {
     "dxruseruid":"uid-7f001-6f26d110-11da5aeefcf--7fe6",
     "c":"DE",
     "displayName":"Meeting Room Berlin",
     "dxrsponsor":
     {
       "displayName":"Klaus Reichel",
       "value":"uid-7f001-6f26d110-11da5aeefcf--7fe6",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               Users/uid-7f001-6f26d110-11da5aeefcf--7fe6"
     },
     "dn":"cn=Meeting Room Berlin,ou=Resources,o=My-Company,
           cn=Users,cn=My-Company",
     "id":"cn=Meeting Room Berlin,ou=Resources,o=My-Company,
           cn=Users,cn=My-Company",
     "value":"uid-c0a8c84--4ae2f0b6-13ca509f9e6--7e87",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-c0a8c84--4ae2f0b6-13ca509f9e6--7e87"
   }
 ]
}

Response Data

  • totalResults - The number of functional users returned.

  • Resources - The list of functional users.

Counting Functional Users

This operation returns the number of functional users of a user.

No size or time limits apply to this operation.

If you also also need the number of personas or user facets, use request "Counting Users" for performance reasons.

Request

HTTP Method and Path

GET /Users/{userId}/functionalUsers/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Response

HTTP Success Codes

  • OK (200) - The number of functional users is returned.

Response Content

On success, the operation returns a JSON object with the number of functional users:

{
 "totalResults":2
}

Response Data

  • totalResults - The number of functional users.

Listing Users

This operation returns the lists of personas, user facets and functional users of a user.

No size or time limits apply to this operation.

Request

HTTP Method and Path

GET /Users/{userId}/users

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the attributes to be returned in the result for each persona, user facet or functional user. The default and mandatory attributes can be configured in section "search" of resource types "Persona", "UserFacet" and "FunctionalUser".

Response

HTTP Success Codes

  • OK (200) - The personas, user facets and functional users are returned.

Response Content

On success, the operation returns a JSON object with the lists of personas, user facets and functional users; attribute “value” is the unique ID of the persona, user facet or functional user:

{
 "personas":
 {
   "startIndex":1,
   "totalResults":1,
   "itemsPerPage":1,
   "schemas":
   [
     "urn:ietf:params:scim:api:messages:2.0:ListResponse"
   ,
   "Resources":
   [
   ... 1 persona ...
   ]
 },
 "userFacets":
 {
   "startIndex":1,
   "totalResults":0,
   "itemsPerPage":1,
   "schemas":
   [
     "urn:ietf:params:scim:api:messages:2.0:ListResponse"
   ,
   "Resources":
   [
   ]
 },
 "functionalUsers":
 {
   "startIndex":1,
   "totalResults":2,
   "itemsPerPage":1,
   "schemas":
   [
     "urn:ietf:params:scim:api:messages:2.0:ListResponse"
   ,
   "Resources":
   [
   ... 2 functional users ...
   ]
 }
}

Response Data

  • totalResults - The numbers of personas, user facets and functional users returned.

  • Resources - The lists of personas, user facets and functional users.

Counting Users

This operation returns the numbers of personas, user facets and functional users of a user.

No size or time limits apply to this operation.

Request

HTTP Method and Path

GET /Users/{userId}/users/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Response

HTTP Success Codes

  • OK (200) - The numbers of personas, user facets and functional users are returned.

Response Content

On success, the operation returns a JSON object with the numbers of personas, user facets and functional users:

{
 "userFacets":
 {
   "totalResults":0
 },
 "functionalUsers":
 {
   "totalResults":2
 },
 "personas":
 {
   "totalResults":0
 }
}

Response Data

  • totalResults - The numbers of personas, user facets and functional users.

Listing Owners

This operation returns the owners of a user. Usually, there’s at most one owner.

No size or time limits apply to this operation.

When reading the profile of the user (request "Reading the Profile"), you can get the owners via user attribute "owner".

Request

HTTP Method and Path

GET /Users/{userId}/owners

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the owner attributes to be returned in the result. The default and mandatory attributes can be configured in section "search" of resource type "User" and "Persona".

Response

HTTP Success Codes

  • OK (200) - The owners are returned.

Response Content

On success, the operation returns a JSON object with the list of owners; attribute “value” is the owner’s unique ID:

{
 "startIndex":1,
 "totalResults":1,
 "itemsPerPage":1,
 "schemas":
 [
   "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 ],
 "Resources":
 [
   {
     "c":"DE",
     "displayName":"Bruno Klarmann",
     "dn":"cn=Klarmann Bruno,ou=Sales Europe,ou=Sales,o=My-Company,
           cn=Users,cn=My-Company",
     "id":"cn=Klarmann Bruno,ou=Sales Europe,ou=Sales,o=My-Company,
           cn=Users,cn=My-Company",
     "value":"10052504",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/10052504"
   }
 ]
}

Response Data

  • totalResults - The number of owners returned.

  • Resources - The list of owners.

Listing Sponsors

This operation returns the sponsors of a user. Usually, there’s at most one sponsor.

No size or time limits apply to this operation.

When reading the profile of the user (request "Reading the Profile"), you can get the sponsors via user attribute "dxrSponsor".

Request

HTTP Method and Path

GET /Users/{userId}/sponsor

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the sponsor attributes to be returned in the result. The default and mandatory attributes can be configured in section "search" of resource type "User" and "Persona".

Response

HTTP Success Codes

  • OK (200) - The sponsors are returned.

Response Content

On success, the operation returns a JSON object with the list of sponsors; attribute “value” is the sponsor’s unique ID:

{
 "startIndex":1,
 "totalResults":1,
 "itemsPerPage":1,
 "schemas":
 [
   "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 ],
 "Resources":
 [
   {
     "c":"DE",
     "displayName":"Klaus Reichel",
     "dn":"cn=Reichel Klaus,ou=Product Testing,o=My-Company,
           cn=Users,cn=My-Company",
     "id":"cn=Reichel Klaus,ou=Product Testing,o=My-Company,
           cn=Users,cn=My-Company",
     "value":"uid-7f001-6f26d110-11da5aeefcf--7fe6",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-7f001-6f26d110-11da5aeefcf--7fe6"
   }
 ]
}

Response Data

  • totalResults - The number of sponsors returned.

  • Resources - The list of sponsors.

User Password Service Operations

The user password service provides operations to read a user’s password policy and to reset a user’s password.

Overview

This section provides an overview of user password service operations.

List of Operations

  • GET /Users/{userId}/passwordPolicy - Reads a user’s password policy.

  • POST /Users/{userId}/password - Resets a user’s password.

Reading a Password Policy

This operation reads a user’s password policy.

The authenticated user must have the access rights to set the user’s password.

Request

HTTP Method and Path

GET /Users/{userId}/passwordPolicy

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Response

HTTP Success Codes

  • OK (200) - The password policy is returned. The policy is empty if no password policy is assigned to the user and no default password policy exists.

Response Content

On success, the operation returns a JSON object representing the password policy:

{
 "dxrPwdMinLength":10,
 "dxrPwdMinNumeric":1,
 "dxrPwdExpireWarning":14,
 "dxrPwdMaxAge":120,
 "dxrPwdMaxLength":30,
 "dxrPwdMinLowerChar":1,
 "dxrPwdMinNonAlphaNum":2,
 "dxrPwdMinUpperChar":1,
 "dxrPwdProhibitedSubstrings":
 [
   "dirx",
   "test"
 ],
 "dxrPwdProhibitedChars":"#-{+}",
 "dxrPwdMinSpecialChar":4,
 "dxrPwdInHistory":10,
 "prohibitedWindowsPasswordTokens":
 [
   "nik",
   "taspatch",
   "5326",
   "ntaspa32"
 ],
"dxrPwdWindowsCompatible":true,
"customCheckers":{
  "PasswordDiffChecker":{
    "allowReverse":false,
    "maxSharedSubstringLength":3
  },
  "SyntaxChecker":{
  }
}
}

Resetting a Password

This operation resets a user’s password. The old user password is not needed. After reset, the user is usually forced to change his password on the next login.

Note that the REST Service doesn’t change the password directly in the database. It just sends a password change event. The event is then usually processed by a Java-based server. The operation returns after it sends the event; it does not wait until the event is processed. This means that the operation usually returns before the password is changed.

The authenticated user must have the access rights to set the user’s password.

Request

HTTP Method and Path

POST /Users/{userId}/password

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Request Body

The request body is a JSON object with the new password:

{
 "password":"?XcarlB?210=!"
}
Response

HTTP Success Codes

  • NO_CONTENT (204) - The password change event has been sent.

User Certification Service Operations

The user certification service provides operations to view certification tasks for a given user. A certification task for a user is a privilege assignment that the user must certify.

There are two types of certification campaigns, privilege certification and user certification campaigns:

  • Privilege Certification Campaign

    • The value of campaign attribute dxrType is "RoleToUser".

    • The subject of a certification is a privilege: role, permission, or group.

    • The resources of a certification are users.

  • User Certification Campaign

    • The value of campaign attribute dxrType is "UserToRole".

    • The subject of a certification is a user.

    • The resources of a certification are privileges: roles, permissions and / or groups.

Overview

This section provides general information about certification service operations.

List of Operations

  • GET /Users/{userId}/certifications - Lists the running certification campaigns with open tasks for the specified user.

  • GET /Users/{userId}/certifications/count - Counts the certification campaigns with open tasks for the specified user.

  • GET /Users/{userId}/certifications/{campaignId} - Returns details of a certification campaign, including the list of subjects with open certification tasks for the specified user.

  • GET /Users/{userId}/certifications/{campaignId}/{certificationId} - Returns details of a certification entry, including the list of privilege assignments to be certified by the specified user.

Listing Certification Campaigns

This operation retrieves the running certification campaigns with open certification tasks for a given user.

The operation can be configured in section "search" of resource type "RunningCertificationCampaign".

Request

HTTP Method and Path

GET /Users/{userId}/certifications

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the certification campaign attributes to be returned in the result. The list may include the virtual attribute "dxrvNumberOfCertifications". If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

Response

HTTP Success Codes

  • OK (200) - The certification campaign list is returned.

Response Content

On success, the operation returns a JSON object with the list of certification campaigns:

{
 "totalResults":3,
 "schemas":
 [
   "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 ],
 "Resources":
 [
   {
     "owner":
     {
       "displayName":"Nik Taspatch",
       "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                  Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
     },
     "meta":
     {
       "created":"2019-11-27T15:17:18.366Z",
       "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                     Me/certifications/uid-c0a82a1--7bf0ab25-16ead58d54a--7ff4",
       "lastModified":"2019-11-27T15:43:38.862Z",
       "resourceType":"RunningCertificationCampaign"
     },
     "dxrstate":"RUNNING",
     "description":"Certification of Corporate Roles",
     "dxrtype":"RoleToUser",
     "dxrexpirationdate":"2020-11-26T23:00:00.000Z",
     "cn":"Corporate Roles",
     "dxrstartdate":"2019-11-26T23:00:00.000Z",
     "id":"uid-c0a82a1--7bf0ab25-16ead58d54a--7ff4",
     "dxrvnumberofcertifications":16,
     "$displayname":"Corporate Roles"
   },
   (OTHER CAMPAIGNS ELIMINATED)…
 ]
}

Response Data

  • totalResults - The number of certification campaigns returned.

  • Resources - The list of certification campaigns. For each certification campaign, the virtual attribute "dxrvNumberOfCertifications" returns the number of subjects with open tasks for the specified user.

Counting Certification Campaigns

This operation counts the certification campaigns with open tasks for a given user.

Request

HTTP Method and Path

GET /Users/{userId}/certifications/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • userId - The user’s UID (dxruid).

Response

HTTP Success Codes

  • OK (200) - The number of certification campaigns is returned.

Response Content

On success, the operation returns a JSON object with number of certification campaigns:

{
 "totalResults":3,
 "sizeLimitExceeded":false
}

Response Data

  • totalResults - The number of certification campaigns.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached a size limit. The value is always false since the operation doesn’t specify a size limit.

Reading a Certification Campaign

This operation returns details of a certification campaign with open tasks for a given user. The result includes the list of subjects with open certification tasks.

The operation can be configured in section "read" of resource type "RunningCertificationCampaign".

Request

HTTP Method and Path

GET /Users/{userId}/certifications/{campaignId}

Path Parameters

  • userId - The user’s UID (dxruid).

  • campaignId - The certification campaign’s UID (dxruid). If the UID is not assigned to a certification campaign with open tasks for the specified user, the operation fails.

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • campaignAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the certification campaign attributes to be returned in the result. The virtual attribute “dxrvNumberOfCertifications” is not supported. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • certificationAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the certification attributes to be returned in the result. The list may include the virtual attribute "dxrvProgress". If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • subjectAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the subject attributes to be returned in the result. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

Response

HTTP Success Codes

  • OK (200) - The certification campaign details are returned.

Response Content

On success, the operation returns a JSON object with the requested certification campaign data. For details, see the description of proprietary extension "Certification Campaign" in section “Objects and Attributes”.

{
 "owner":
 {
   "displayName":"Nik Taspatch",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/Users/
           uid-7f001-6f26d110-11da5aeefcf--7ff9"
 },
 "meta":
 {
   "created":"2019-12-18T10:35:25.646Z",
   "location":"http://localhost:8080/DirXIdentityRestService-My-Company/Users/
               00014281/certifications/uid-c0a82a1--3b1928d9-16f188374f8--7fdc",
   "lastModified":"2019-12-18T10:37:52.043Z",
   "resourceType":"RunningCertificationCampaign"
 },
 "dxrstate":"RUNNING",
 "description":"All privileges for Financiers",
 "dxrtype":"UserToRole",
 "dxrexpirationdate":"2020-08-18T10:29:00.000Z",
 "dxrstartdate":"2019-12-18T10:29:00.000Z",
 "id":"uid-c0a82a1--3b1928d9-16f188374f8--7fdc",
 "cn":"All privileges",
 "certifications":
 {
   "users":
   [
     {
       "meta":
       {
         "created":"2019-12-18T10:37:52.022Z",
         "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Users/00014281/certifications/uid-c0a82a1--3b1928d9-16f188374f8--7fdc/
           uid-c0a82a1--4b487c9f-16f1880d9df--7fcc",
         "resourceType":"CertificationEntryUser"
       },
       "subject":
       {
         "telephonenumber":"+49 89 323-45301",
         "meta":
         {
           "created":"2019-11-27T10:08:06.761Z",
           "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Users/10052505",
           "lastModified":"2020-01-02T09:31:50.297Z",
           "resourceType":"User"
         },
         "description":"General Manager",
         "externalId":"dalmar",
         "dn":"cn=Dalmar Christopher,ou=Finances,o=My-Company,
               cn=Users,cn=My-Company",
         "id":"10052505",
         "$displayname":"Dalmar Christopher",
         "$parentfolder":"ou=Finances,o=My-Company,cn=Users,cn=My-Company"
       },
       "dxrvprogress":
       {
         "total":6,
         "completed":0
       },
       "id":"uid-c0a82a1--4b487c9f-16f1880d9df--7fcc",
       "cn":"Dalmar Christopher",
       "$displayname":"Dalmar Christopher",
       "$parentfolder":"cn=User Certification,cn=All privileges,
                        cn=Certification Campaigns,cn=My-Company"
     },
     (OTHER USERS ELIMINATED)…
   ]
 }
}

Reading a Certification Entry

This operation returns details of a certification entry. The result includes the list of privilege assignments to be certified by the specified user, as well as the changes to the assignments requested so far during the campaign.

The operation can be configured in section "read" of the resource type matching the certification entry (one of "CertificationEntryUser", "CertificationEntryRole", "CertificationEntryPermission", and "CertificationEntryGroup").

Request

HTTP Method and Path

GET /Users/{userId}/certifications/{campaignId}/{certificationId}

Path Parameters

  • userId - The user’s UID (dxruid).

  • campaignId - The certification campaign’s UID (dxruid). If the UID is not assigned to a certification campaign with open tasks for the specified user, the operation fails.

  • certificationId - The certification entry’s UID (dxruid). If the UID is not assigned to a certification entry belonging to the specified campaign, the operation fails.

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • campaignAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the certification campaign attributes to be returned in the result. The virtual attribute “dxrvNumberOfCertifications” is not supported. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • certificationAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the certification attributes to be returned in the result. The list may include the virtual attribute "dxrvProgress". If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • subjectAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the subject attributes to be returned in the result. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • resourceAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the resource attributes to be returned in the result. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • includeManualAssignments - Whether to include the manually assigned privileges (true) or not (false). Default is true.

  • includeNonManualAssignments - Whether to include the non-manually assigned privileges (true) or not (false). Default is false.

Response

HTTP Success Codes

  • OK (200) - The certification entry details are returned.

Response Content

On success, the operation returns a JSON object with the requested certification entry data. For details, see the description of proprietary extension "Certification Entry" in section “Objects and Attributes”.

{
 "meta":
 {
   "created":"2020-01-21T12:18:43.322Z",
   "location":"http://localhost:8080/DirXIdentityRestService-My-Company/Users
               /00014281/certifications/uid-c0a82a1-5c4abaa9-16fc7c7eca5--7f72/
               uid-c0a82a1-742b6634-16fc7920e26--7fa5",
   "lastModified":"2020-01-21T12:29:42.107Z",
   "resourceType":"CertificationEntryUser"
 },
 "id":"uid-c0a82a1-742b6634-16fc7920e26--7fa5",
 "cn":"Abele Marc",
 "$displayname":"Abele Marc",
 "$parentfolder":"cn=User Certification,cn=All privileges of Abele,
                  cn=Certification Campaigns,cn=My-Company",
 "subject":
 {…
 },
 "campaign":
 {…
 },
 "assignments":
 {
   "permissions": [...],
   "groups": [...],
   "roles":
   [
     {
       "resource":
       {
         "owner":
         [
           {
             "displayName":"Christopher Dalmar",
             "value":"10052505",
             "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                     /Users/10052505"
           }
         ],
         "meta":
         {
           "created":"2019-11-27T10:08:00.203Z",
           "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78b5",
           "resourceType":"Role"
         },
         "description":"Standard role for all contractors",
         "dn":"cn=Contractor,cn=General,cn=Corporate Roles,
               cn=RoleCatalogue,cn=My-Company",
         "id":"uid-7f001-6f26d110-11da5aeefcf--78b5",
         "$displayname":"Contractor",
         "$parentfolder":"cn=General,cn=Corporate Roles,
                          cn=RoleCatalogue,cn=My-Company"
       },
       "assignment":
       {
         "mode":"manual",
         "uid":"uid-c0a82a1-6d2f5fcb-16f8fc11151--7fb0",
         "hasSODViolations":false,
         "displayState":"FUTURE",
         "isEditable":true,
         "dxrEndDate":"2021-01-09T23:00:00.000Z",
         "state":"FUTURE",
         "type":"direct",
         "dxrNeedsReapproval":false,
         "dxrStartDate":"2020-02-09T23:00:00.000Z"
       },
       "assignmentChanges":
       {
         "dxrEndDate":"2020-12-31T23:00:00.000Z",
         "dxrStartDate":"2020-02-15T23:00:00.000Z"
       },
       "certificationResult":
       {
         "state":"accepted"
       }
     },
     ...
   ]
 },
 "automaticAssignments":
 {
   "permissions": [...],
   "groups": [...],
   "roles": [...]
 }
}

Self Service Operations

Self service provides operations on the authenticated user’s data (his profile), on his privilege assignments, and on requests that he initiates.

Overview

This section provides general information about self service operations.

List of Operations

  • Profile Data

    • GET /Me - Reads the profile data.

    • PATCH /Me - Updates the profile data.

  • User Data

    • GET /Me/managedTeam - Lists the users in the team managed by the authenticated user.

    • GET /Me/managedTeam/count - Returns the number of users in the team managed by the authenticated user.

    • GET /Me/accounts - Lists the accounts of the authenticated user.

  • Privilege Assignments

    • GET /Me/roles
      GET /Me/permissions
      GET /Me/groups
      GET /Me/privileges - Lists the privileges assigned to the authenticated user (not including the pending assignments).

    • GET /Me/roles/count
      GET /Me/permissions/count
      GET /Me/groups/count
      GET /Me/privileges/count       - Returns the number of privileges assigned to the authenticated user (not including the pending assignments).

    • GET /Me/assignableRoles
      GET /Me/assignablePermissions
      GET /Me/assignableGroups
      GET /Me/assignablePrivileges - Lists the privileges that the authenticated user can assign to himself.

    • POST /Me/roles
      POST /Me/permissions
      POST /Me/groups       - Creates a new privilege assignment.

    • GET /Me/roles/{assignmentId}
      GET /Me/permissions/{assignmentId}
      GET /Me/groups/{assignmentId}       - Reads the privilege assignment with the given ID.

    • PATCH /Me/roles/{assignmentId}
      PATCH /Me/permissions/{assignmentId}
      PATCH /Me/groups/{assignmentId}       - Changes the privilege assignment with the given ID.

    • DELETE /Me/roles/{assignmentId}
      DELETE /Me/permissions/{assignmentId}
      DELETE /Me/groups/{assignmentId}       - Deletes the privilege assignment(s) with the given ID.

    • GET /Me/roles/{roleId}/roleParams
      GET /Me/assignableRoles/{roleId}/roleParams       - Reads the role parameter configuration for the assigned and assignable role, respectively, with the given ID.

    • GET /Me/roles/{roleId}/roleParams/{roleParamId}/proposal/{roleParamNodeId}
      GET /Me/assignableRoles/{roleId}/roleParams/{roleParamId}/
      proposal/{roleParamNodeId}       - Reads the next level of proposals below the specified role parameter node for a role parameter of type HDN for the assigned and assignable role, respectively, with the given ID.

  • Pending Privilege Assignments - A pending privilege assignment is a privilege assignment to the authenticated user which is still awaiting approval, or which is scheduled to be performed on some future day (a ticket). It doesn’t matter whether the assignment was requested by the authenticated user himself, or by another user.

    • GET /Me/pendingRoles
      GET /Me/pendingPermissions
      GET /Me/pendingGroups
      GET /Me/pendingPrivileges       - Lists the privilege assignments still awaiting approval.

    • GET /Me/pendingRoles/count
      GET /Me/pendingPermissions/count
      GET /Me/pendingGroups/count
      GET /Me/pendingPrivileges/count       - Returns the number of privilege assignments still awaiting approval.

    • GET /Me/pendingRoles/{requestId}
      GET /Me/pendingRoles/{requestId}/{orderId}
      GET /Me/pendingPermissions/{requestId}
      GET /Me/pendingPermissions/{requestId}/{orderId}
      GET /Me/pendingGroups/{requestId}
      GET /Me/pendingGroups/{requestId}/{orderId}
      GET /Me/pendingPrivileges/{requestId}
      GET /Me/pendingPrivileges/{requestId}/{orderId} - Reads the pending privilege assignment with the given request ID and order ID.

  • Pending Profile Changes - a pending profile change is a modification to the authenticated user’s profile data which is still awaiting approval or which is scheduled to be performed on some future day (a ticket). It doesn’t matter whether the change was requested by the authenticated user himself or by another user.

    • GET /Me/pendingProfileChanges - Lists the pending profile changes.

    • GET /Me/pendingProfileChanges/{requestId} - Reads the pending profile change with the given request ID.

    • GET /Me/pendingProfileChanges/count - Returns the number of pending profile changes.

  • Pending Initiated Requests - An initiated request is a privilege assignment or a profile change requested by the authenticated user. It doesn’t matter whether he assigned the privilege to himself or to another user, or whether he changed his own profile, or another user’s profile. An initiated request is pending if it is awaiting approval, or if it is scheduled to be performed on some future day (a ticket).

    • GET /Me/pendingRequests - Lists the pending initiated requests.

    • GET /Me/pendingRequests/count - Returns the number of pending initiated requests.

    • GET /Me/pendingRequests/{requestId}
      GET /Me/pendingRequests/{requestId}/{orderId} - Reads the pending initiated request with the given request ID and orderID.

    • DELETE /Me/pendingRequests/{requestId} - Cancels the workflow or deletes the ticket which is the source of the pending initiated request with the given request ID.

  • Closed Requests - A closed request is a finished workflow or a processed ticket for a privilege assignment or a profile change.

    • GET /Me/closedRequests - Lists the closed requests with the authenticated user as initiator or subject.

    • GET /Me/closedRequests/{requestId} - Reads the closed request with the given ID. The authenticated user must be either the initiator or the subject of the request.

  • Personas, User Facets and Functional Users - Requests to list or count the authenticated user’s personas, user facets and functional users.

    • GET /Me/personas - Lists the personas of the authenticated user.

    • GET /Me/personas/count - Returns the number of personas of the authenticated user.

    • GET /Me/userFacets - Lists the user facets of the authenticated user.

    • GET /Me/userFacets/count - Returns the number of user facets of the authenticated user.

    • GET /Me/functionalUsers - Lists the functional users of the authenticated user.

    • GET /Me/functionalUsers/count - Returns the number of functional users of the authenticated user.

    • GET /Me/users - Lists the personas, user facets and functional users of the authenticated user.

    • GET /Me/users/count - Returns the numbers of personas, user facets and functional users of the authenticated user.

Reading the Profile

This operation retrieves profile data of the authenticated user.

The operation can be configured in section "me" of resource type "User".

Request

HTTP Method and Path

GET /Me

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the user attributes to be returned in the result. If not specified, the default attributes apply. In any case, the result will also include the mandatory attributes in addition to the attributes defined here.

Response

HTTP Success Codes

  • OK (200) - The entry is returned.

Response Content

On success, the operation returns a JSON object with the requested profile data:

{
  "emails":
  [
     {
        "type":"work",
        "value":Nik.Taspatch@My-Company.com
     }
  ],
  "c":"US",
  "meta":
  {
     "created":"2016-10-12T16:01:19.822Z",
     "location":"http://localhost:8080/DirXIdentityRestService-My-company/
Users/uid-7f001-6f26d110-11da5aeefcf--7ff9",
     "lastModified":"2017-12-13T12:08:41.361Z",
     "resourceType":"User"
  },
  "schemas":
  [
     "urn:ietf:params:scim:schemas:core:2.0:User",
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "name":
  {
     "formatted":"Mr. Nik Taspatch",
     "givenName":"Nik",
     "familyName":"Taspatch",
     "honorificPrefix":"Mr."
  },
  "externalId":"taspatch",
  "dn":"cn=Taspatch Nik,ou=Global IT,o=My-Company,cn=Users,cn=My-Company",
  "id":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
  "userName":"taspatch",
  "phoneNumbers":
  [
     {
        "type":"work",
        "value":"+1 408 876-73623"
     },
     {
        "type":"fax",
        "value":"+1 408 876-4405978121255"
     }
  ]
}

Updating the Profile

This operation updates the profile data of the authenticated user.

Request

HTTP Method and Path

PATCH /Me

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support PATCH requests, you can send a POST request instead including this additional header set to PATCH.

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • ignoreWarnings - When warnings occur, whether to update the entry anyway (true), or reject the request (false). The default is false.

  • attributes - A comma-separated list of SCIM or LDAP attribute names. If specified, the operation returns the updated profile data including the attributes defined here as well as the mandatory ones. If not specified, the operation does not return any data unless an error occurs.

Request Body

The request body is a JSON object with the changes to be made:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
     {
        "op" : "replace",
        "path" : "employeeType"
        "value" : "Internal"
     }
  ]
}

  • Operations - The list of modify operations.

  • dueDate - The optional modification due date, that is the date the object should be modified. Setting a due date will start a ticket.

  • reason - The reason for requesting to modify the profile. Only relevant if one or more attributes are subject to approval.

Response

HTTP Success Codes

  • OK (200) - The entry was updated and the updated entry is returned.

  • ACCEPTED (202) - A modification workflow or ticket has been started; the updated entry is returned if requested but will not reflect ticketed changes or changes awaiting approval.

  • NO_CONTENT (204) - The entry was updated but no content is returned.

Response Content

On success with OK (200) or ACCEPTED (202) and if request parameter “attributes” is not empty, the operation returns a JSON object with the updated profile. The object is formatted in the same way as when reading the profile.

Listing the Users in the Managed Team

This operation retrieves the users in the team managed by the authenticated user. The team may include teams of other users who have delegated tasks to the authenticated user.

The operation can be configured in section "managedTeam" of resource type "User".

The size limit for assignable roles is defined by

  • Request parameter "count".

  • Parameter "defaultCount" of resource type "User" section "managedTeam".

  • Parameter "defaultCount" of resource type "User" section "search".

  • Configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Parameter "maxCount" of resource type "User" section "managedTeam".

  • Parameter "maxCount" of resource type "User" section "search".

  • Configuration parameter "search.maxCount".

in descending priority.

Request

HTTP Method and Path

GET /Me/managedTeam

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. If just "none" is requested, only the number of managed users is returned. Otherwise, the result includes, for each user:

    • The mandatory attributes.

    • The requested attributes, if any requested.

    • The default attributes if no attributes are requested.

  • base - The search base.

  • scope - The search scope, one of "base", "oneLevel", or "subtree", The default scope is "subtree".

  • filter - The search filter.

  • filterValue - The value to replace the placeholder in configuration parameter "valueFilter" (in section “managedTeam” of resource type “User”) with. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

  • sortBy - The attributes by which the search result is sorted. You can specify one or more LDAP attributes, separated by commas. Sorting is performed by the underlying directory service, so the LDAP attributes must have a proper ordering match rule in the directory schema.

  • sortOrder - The sort order, either "ascending" or "descending". You can specify the order per sort attribute, separated by commas.

  • count - The maximum number of entries to return.

Response

HTTP Success Codes

  • OK (200) - The list of users in the managed team is returned.

Response Content

On success, the operation returns a JSON object with the list of managed team users:

{
   "startIndex":1,
   "totalResults":36,
   "itemsPerPage":36,
   "schemas":
   [
       "urn:ietf:params:scim:api:messages:2.0:ListResponse"
   ],
   "Resources":
   [
       {
           "emails":
           [
               {
                   "type":"work",
                   "value":"Stephen.Green@My-Company.com"
               }
           ],
           "c":"US",
           "name":
           {
               "formatted":"Mr. Stephen Green",
               "givenName":"Stephen",
               "familyName":"Green",
               "honorificPrefix":"Mr."
           },
           "userName":"green",
           "phoneNumbers":
           [
               {
                   "type":"work",
                   "value":"+1 408 876-49912"
               },
               {
                   "type":"fax",
                   "value":"+1 408 876-35267"
               }
           ]
       },
       …
       {
           "emails":
           [
               {
                   "type":"work",
                   "value":"Retha.Wagner@My-Company.com"
               }
           ],
           "name":
           {
               "formatted":"Retha Wagner",
               "givenName":"Retha",
               "familyName":"Wagner"
           },
           "phoneNumbers":
           [
               {
                   "type":"work",
                   "value":"+49 89 323"
               }
           ]
       }
   ]

Response Data

  • totalResults - The number of users returned.

  • itemsPerPage - For future use. Currently its value is identical to totalResults.

  • startIndex - For future use. Currently it’s always 1.

  • Resources - The list of managed users.

Counting the Users in the Managed Team

This operation counts the users in the team managed by the authenticated user. The team might include teams of other users who have delegated tasks to the authenticated user.

The operation can be configured in section "managedTeam" of resource type "User".

The default and maximum size limits are the same as for the request to list the users in the managed team.

Request

HTTP Method and Path

GET /Me/managedTeam/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • base - The search base.

  • scope - The search scope, one of "base", "oneLevel", or "subtree", The default scope is "subtree".

  • filter - The search filter.

  • count - The search size limit. The default size limit is specified by parameter "defaultCount" of the managed team configuration, the maximum size limit by parameter "maxCount".

Response

HTTP Success Codes

  • OK (200) - The number of team members is returned.

Response Content

On success, the operation returns a JSON object with the number of team members:

{
  "totalResults":36,
  "sizeLimitExceeded":false
}

Response Data

  • totalResults - The number of team members.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached the size limit.

Listing Accounts

This operation retrieves the accounts of the authenticated user.

No size or time limits apply to this operation.

Request

HTTP Method and Path

GET /Me/accounts

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the account attributes to be returned in the result. The default attributes are "display", "$ref", "value", and "description". The value is the account’s unique ID.

Response

HTTP Success Codes

  • OK (200) - The account list is returned.

Response Content

On success, the operation returns a JSON object with the list of accounts:

{
 "totalResults":2,
 "Resources":
 [
   {
     "display":"Marc Abele 2623",
     "description":"Account for Marc Abele",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
             /DomainObjects/uid-7f001-6f26d110-11da5aeefcf--7791",
     "value":"uid-7f001-6f26d110-11da5aeefcf--7791"
   },
   {
     "display":"Privileged Physicist",
     "description":"Account",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
             /DomainObjects/uid-a5d19b4-4f8427cf-15ca5349858--7ffe",
     "value":"uid-a5d19b4-4f8427cf-15ca5349858--7ffe"
   }
 ]
}

Response Data

  • totalResults - The number of accounts returned.

  • Resources - The list of accounts.

Listing Assigned Privileges

This operation retrieves the privileges assigned to the authenticated user. New assignments still awaiting approval are not included, while assignments awaiting modification or deletion approval are included. The state of each returned assignment is one of "ENABLED", "INHERITED", "MODIFY", "DELETE", "IMPORTED", and "DELETED".

No size or time limits apply to this operation.

Request

HTTP Method and Path

GET /Me/roles

GET /Me/permissions

GET /Me/groups

GET /Me/privileges

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. The default attributes are "display", "$ref", "value", "type", "description", "assignment", and “targetsystem.cn” (for groups only). The value is the privilege’s unique ID.

  • base - The search base.

  • filter - The search filter. To get entries of a specific resource type only, include a resource type filter, for example

    filter=(meta.resourceType eq "Role") and (cn sw "co")

filter=(meta.resourceType eq "Role") or (meta.resourceType eq "Permission")

  • filterValue - The value to replace the placeholder in configuration parameter "valueFilter" (in section “assignedRoles” of resource type “Role” for roles, likewise for groups and permissions) with. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

  • count - The maximum number of entries to return.

Response

HTTP Success Codes

  • OK (200) - The requested assignments are returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with a single list of respective privilege assignments:

{
  "totalResults":21,
  "Resources":
  [
     {
        "assignment":
        {
           "hasSODViolations":false,
           "isEditable":true,
           "mode":"manual",
           "dxrEndDate":"2018-03-03T23:00:00.000Z",
           "state":"ENABLED",
           "dxrNeedsReapproval":false,
           "dxrStartDate":"2017-12-03T23:00:00.000Z"
        },
        "display":"Restaurant Card",
        "description":"Request your restaurant card for selected locations",
        "type":"direct",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       domainObjects/uid-7f001-6f26d110-11da5aeefcf--78a5",
        "value":"uid-7f001-6f26d110-11da5aeefcf--78a5"
     },
     {
        "assignment":
        {
           "uid":"uid-a5d1993-47c18b9-160260e3dd4--7f46",
           "hasSODViolations":false,
           "isEditable":true,
           "mode":"manual",
           "roleParameters":
           [
              {
                 "uid":"uid-7f001--290d5629-1183529ae71--7ffe",
                 "name":"Car Number",
                 "type":"Text"
              }
           ],
           "state":"ENABLED",
           "dxrNeedsReapproval":false
        },
        "display":"Parking Place Munich",
        "description":"Request your slot in the parking place in Munich",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       domainObjects/uid-7f001-6f26d110-11da5aeefcf--78a6"
     },
     (OTHER ASSIGNMENTS ELIMINATED)…
  ]
}

The operation "Me/privileges", on the other hand, returns a JSON object with three lists, one for each type of privilege:

{
 "roles":{
   "totalResults":21,
   "Resources":[…]
 },
 "permissions":{
   "totalResults":28,
   "Resources":[…]
 },
 "groups":{
   "totalResults":47,
   "Resources":[…]
 }
}

Response Data

  • totalResults - The number of privilege assignments returned.

  • Resources - The list of privilege assignments.

Counting Assigned Privileges

This operation counts the privileges assigned to the authenticated user. New assignments still awaiting approval are not included, while assignments awaiting modification or deletion approval are included.

No size or time limits applies to this operation.

Request

HTTP Method and Path

GET /Me/roles/count

GET /Me/permissions/count

GET /Me/groups/count

GET /Me/privileges/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Response

HTTP Success Codes

  • OK (200) - The numbers of assignments are returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with a single counter:

{
 "totalResults":21,
 "sizeLimitExceeded":false
}

The operation "Me/privileges/count", on the other hand, returns a JSON object with three counters, one or each type of privilege:

{
 "roles":{
   "totalResults":21,
   "sizeLimitExceeded":false
 },
 "permissions":{
   "totalResults":28,
   "sizeLimitExceeded":false
 },
 "groups":{
   "totalResults":47,
   "sizeLimitExceeded":false
 }
}

Response Data

  • totalResults - The number of privilege assignments.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached the size limit. The size limit for counting parameterized roles is 1000. There’s no size limit for counting non-parameterized roles, permissions and groups.

Listing Assignable Privileges

This operation retrieves the privileges the authenticated user can assign to himself. Privileges that can be assigned only once and are already assigned to the authenticated user, will not be included in the result.

For each privilege in the result, the flag "assignableOnlyOnce" indicates whether the privilege can be assigned just once (true) or more than once (false).

The time limit for this operation is the global LDAP search time limit configured at the domain object.

The size limit for assignable roles is defined by

  • Request parameter "count".

  • Parameter "defaultCount" of resource type "Role" section "assignableRoles".

  • Parameter "defaultCount" of resource type "Role" section "search".

  • Configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Parameter "maxCount" of resource type "Role" section "assignableRoles".

  • Parameter "maxCount" of resource type "Role" section "search".

  • Configuration parameter "search.maxCount".

in descending priority.

The maximum size limit is restricted by the global LDAP search size limit configured at the domain object. Similar for permissions and groups.

Request

HTTP Method and Path

GET /Me/assignableRoles

GET /Me/assignablePermissions

GET /Me/assignableGroups

GET /Me/assignablePrivileges

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. The default attributes are "display", "$ref", "value", "description", "roleParameters" (for roles only), and “targetsystem.cn” (for groups only). The value is the privilege’s unique ID.

  • base - The search base.

  • filter - The search filter. To get entries of a specific resource type only, include a resource type filter, for example

    filter=(meta.resourceType eq "Role") and (cn sw "co")

filter=(meta.resourceType eq "Role") or (meta.resourceType eq "Permission")

  • filterValue - The value to replace the placeholder in configuration parameter "valueFilter" (in section “assignableRoles” of resource type “Role” for roles, likewise for groups and permissions) with. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

  • count - The maximum number of entries to return.

Response

HTTP Success Codes

  • OK (200) - The requested privileges are returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with a single list of respective privileges:

{
   "totalResults":54,
   "Resources":
   [
      {
         "value":"uid-7f001-6f26d110-11da5aeefcf--78b5",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        domainObjects/uid-7f001-6f26d110-11da5aeefcf--78b5",
         "display":"Contractor",
         "description":"Standard role for all contractors",
        "assignableOnlyOnce":true
      },
      {
         "value":"uid-7f001-6f26d110-11da5aeefcf--78ab",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        domainObjects/uid-7f001-6f26d110-11da5aeefcf--78ab",
        "display":"Project Member",
         "description":"Member of a project",
         "roleParameters": [
            {
               "uid":"uid-7f001-cee271-fed935aa6d--7eb4",
               "name":"Project",
               "type":"DN"
            }
         ] ,
        "assignableOnlyOnce":false
      },
      (OTHER ROLES ELIMINATED)…
   ]
}

The operation "Me/assignablePrivileges", on the other hand, returns a JSON object with three lists, one for each type of privileges:

{
 "roles":{
   "totalResults":54,
   "Resources":[…]
 },
 "permissions":{
   "totalResults":62,
   "Resources":[…]
 },
 "groups":{
   "totalResults":130,
   "Resources":[…]
 }
}

Response Data

  • totalResults - The number of privileges returned.

  • Resources - The list of privileges.

Assigning a Privilege

This operation assigns a privilege to the authenticated user.

Request

HTTP Method and Path

POST /Me/roles

POST /Me/permissions

POST /Me/groups

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • ignoreWarnings - Whether to assign the privilege even if it results in a warning for example due to SoD violations (true) or to reject the request (false). If a request is rejected, the response body contains details about the SoD violation. The default is false.

Request Body

The request body is a JSON object with details of the new assignment:

{
  "resourceId": "uid-7f001-6f26d110-11da5aeefcf--78b5",
  "assignment": {
        "dxrStartDate":"2017-12-13T00:00:00.000Z",
        "dxrEndDate":"2018-12-13T00:00:00.000Z",
        "dxrNeedsReapproval": false
   },
  "reason":"I need the role for doing my work."
}

For parameterized roles, the assignment also includes the role parameters:

{
   "resourceId":"uid-7f001-6f26d110-11da5aeefcf--78b4",
   "assignment": {
       "dxrEndDate":"2020-12-20T00:00:00.000Z",
       "roleParameters":[
         {
            "uid":"uid-7f001--6c1b645f-112e5d0d91a--7ffc",
            "values" : [
                { "value":"cn=A119,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                           cn=SAP R3,cn=TargetSystems,cn=My-Company" },
                { "value":"cn=A12,cn=A1,cn=Cost Locations,cn=Groups,
                           cn=SAP R3,cn=TargetSystems,cn=My-Company" }
            ]
         }
       ]
   }
}

  • resourceId - The UID of the privilege to assign.

  • assignment - The assignment details are optional:

    • dxrStartDate - The start date for the assignment. By default, the assignment is valid immediately (after creation or approval).

    • dxrEndDate - The start date for the assignment. By default, the assignment is valid forever.

    • dxrNeedsReapproval - Whether (true) or not (false) the assignment must be re-approved. The default is false.

    • roleParameters - The array of role parameters, if applicable. Each role parameter is given by its UID (dxruid) and its values.

  • dueDate - The optional assignment due date, that is the date the privileges should be assigned. Setting a due date will start a ticket.

  • reason - The optional reason for requesting the assignment.

Response

HTTP Success Codes

  • CREATED (201) - The assignment has been created.

  • ACCEPTED (202) - The assignment has been created but is awaiting approval.

Reading a Privilege Assignment

This operation retrieves details of a privilege assignment for the authenticated user. The request path must include the ID of the assignment. If the ID is the UID of a specific assignment, that assignment is returned. If the ID is the UID of a privilege and the privilege is assigned exactly once to the authenticated user, the corresponding privilege assignment is returned. If no assignment or more than one assignment exists, the operation fails.

Request

HTTP Method and Path

GET /Me/roles/{assignmentId}

GET /Me/permissions/{assignmentId}

GET /Me/groups/{assignmentId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • assignmentId- The UID of an assignment (cn) or the UID of a privilege (dxruid). The privilege UID can only be used when the privilege is assigned just once.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specifies the privilege attributes to be returned in the result. The default attributes are "display", "$ref", "value", "type", "description", and "assignment".

Response

HTTP Success Codes

  • OK (200) - The privilege assignment is returned.

Response Content

On success, the operation returns a SCIM privilege object with assignment details:

{
   "value":"uid-7f001-6f26d110-11da5aeefcf--78a6",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                  domainObjects/uid-7f001-6f26d110-11da5aeefcf--78a6",
   "display":"Parking Place Munich",
   "description":"Request your slot in the parking place in Munich",
   "type":"direct",
   "assignment":
   {
      "mode":"manual",
      "uid":"uid-a5d1993-6ebccb13-160598706a8--7d29",
      "hasSODViolations":false,
      "isEditable":true,
      "roleParameters":[
         {
            "uid":"uid-7f001--290d5629-1183529ae71--7ffe",
            "values":[
               {
                  "display":"M HT 55"
               },
               {
                  "display":"M HU 606"
               }
            ],
            "name":"Car Number",
            "type":"Text"
         }
      ],
      "state":"ENABLED",
      "dxrNeedsReapproval":false
   }
}

Here is a second example, this time with role parameters of type HDN:

{
    "assignment":
    {
        "mode":"manual",
        "uid":"uid-a5d19c8-1ae7304f-16262fbf209--7fe5",
        "hasSODViolations":false,
        "isEditable":true,
        "roleParameters":
        [
            {
                "uid":"uid-7f001--6c1b645f-112e5d0d91a--7ffc",
                "values":
                [
                    {
                        "uid":"uid-7f001-6f26d110-11da5aeefcf--76d7",
                        "display":"A119, A11, A1, Cost Locations, Groups,
                                   SAP R3, TargetSystems",
                        "value":"cn=A119,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                                 cn=SAP R3,cn=TargetSystems,cn=My-Company"
                    },
                    {
                        "uid":"uid-7f001-6f26d110-11da5aeefcf--76d3",
                        "display":"A121, A12, A1, Cost Locations, Groups,
                                   SAP R3, TargetSystems",
                        "value":"cn=A121,cn=A12,cn=A1,cn=Cost Locations,cn=Groups,
                                 cn=SAP R3,cn=TargetSystems,cn=My-Company"
                    }
                ],
                "name":"Cost Locations",
                "type":"HDN"
            }
        ],
        "state":"ENABLED",
        "dxrNeedsReapproval":false
    },
    "display":"Cost Location Manager",
    "description":"Assigns the right to manage a cost location.\n
                   Allows additionally assigning other managers to this\n
                   or a lower level cost location.",
    "type":"direct",
    "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78b4",
    "value":"uid-7f001-6f26d110-11da5aeefcf--78b4"
}

Changing a Privilege Assignment

This operation changes a privilege assignment for the authenticated user. The request path must include the ID of the assignment to be changed. If the ID is the UID of a specific assignment, that assignment is changed. If the ID is the UID of a privilege, the assignment for that privilege is changed. If multiple assignments match the specified assignment ID, the operation fails with HTTP status code "CONFLICT". Multiple assignments of the same privilege are possible only for roles with parameters.

If an assignment change is subject to approval, the operation does not change the assignment immediately and starts an approval workflow instead.

Request

HTTP Method and Path

PATCH /Me/roles/{assignmentId}

PATCH /Me/permissions/{assignmentId}

PATCH /Me/groups/{assignmentId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support PATCH requests, you can send a POST request instead including this additional header set to PATCH.

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • assignmentId- The UID of an assignment (cn) or the UID of a privilege (dxruid). The privilege UID can only be used when the privilege is assigned just once.

Query Parameters

  • ignoreWarnings - When an assignment change will result in a warning for example due to SoD violations, whether to change the assignment anyway (true) or reject the request (false). The default is false.

Request Body

The request body is a JSON object with the changes to be made:

{
   "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
   "Operations" : [
      {
         "op" : "add",
         "path" : "dxrStartDate"
         "value" : "2018-01-01T00:00:00.000Z"
      },
      {
         "op" : "replace",
         "path" : "dxrEndDate",
         "value" : "2030-01-06T00:00:00.000Z"
      },
      {
         "op" : "replace",
         "path" : "dxrNeedsReapproval",
         "value" : true
      }
   ],
   "reason" : "I need these changes now."
}

For parameterized roles, the assignment includes also the role parameters:

{
   "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
   "Operations" : [
      {
         "op" : "remove",
         "path" : "dxrStartDate"
      },
      {
         "op" : "replace",
         "path" : "dxrEndDate",
         "value" : "2030-01-06T00:00:00.000Z"
      },
      {
         "op" : "replace",
         "path" : "roleParameters",
         "value" : [
            {
               "uid" : "uid-7f001-cee271-fed935aa6d--7eb4",
               "values" : [
                  {
                     "value" : "High performance"
                  },
                  {
                     "value" : "MoreCustomers"
                  }
               ]
            }
         ]
      }
   ],
   "reason" : "I need these changes now."
}

  • Operations - The modify operations to be performed. Relevant assignment attributes are:

    • dxrStartDate - The start date for the assignment.

    • dxrEndDate - The end date for the assignment.

    • dxrNeedsReapproval - Whether (true) or not (false) the assignment must be re-approved.

    • roleParameters - The array of role parameters, if applicable. Each role parameter is given by its UID (dxruid) and its values.

  • dueDate - The optional modification due date, that is the date the assignment should be modified. Setting a due date will start a ticket.

  • reason - The optional reason for requesting the changes.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The assignment has been changed.

  • ACCEPTED (202) - The assignment has been changed but the changes are awaiting approval.

Deleting a Privilege Assignment

This operation deletes a privilege assignment for the authenticated user. The request path must include the ID of the assignment(s) to be deleted. If the ID is the UID of a specific assignment, that assignment is deleted. If multiple assignments match the specified assignment ID, the operation fails with HTTP status code "CONFLICT". Multiple assignments of the same privilege are possible only for roles with parameters.

If an assignment deletion is subject to approval, the operation does not delete the assignment immediately and starts an approval workflow instead.

Request

HTTP Method and Path

DELETE /Me/roles/{assignmentId}

DELETE /Me/permissions/{assignmentId}

DELETE /Me/groups/{assignmentId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support DELETE requests with request bodies, you can send a POST request instead including this additional header set to DELETE.

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • assignmentId- The UID of an assignment (cn) or the UID of a privilege (dxruid). The privilege UID can only be used when the privilege is assigned just once.

Request Body

The request body is a JSON object that specifies the reason for the deletion:

{
   "reason":"I don’t need the role anymore."
}

  • dueDate - The optional deletion due date, that is the date the assignment should be deleted. Setting a due date will start a ticket.

  • reason - The optional reason for requesting to delete the assignment.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The assignment has been deleted or deletion is awaiting approval.

  • ACCEPTED (202) - The assignment has been marked for deletion, but the deletion is subject to approval.

Reading a Role Parameter Configuration

This operation retrieves the configuration of the parameters of a role that is or can be assigned to the authenticated user.

The request path must include the ID of the role assignment, the assigned role, or the role to be assigned. It doesn’t matter whether the role is assigned just once or more than once since the parameter configuration depends only on the role and not on any specific assignment,

Note that the configuration may vary with the role and the authenticated user.

See the section “Assigning Roles with Parameters” for details on when and how to use this request.

Request

HTTP Method and Path

GET /Me/roles/{roleId}/roleParams

GET /Me/assignableRoles/{roleId}/roleParams

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • roleId - The UID of a role assignment (cn) or the UID of a role (dxruid).

Response

HTTP Success Codes

  • OK (200) - The role parameter configuration is returned.

Response Content

On success, the operation returns a JSON array of role parameter configurations:

[
    {
        "name":"Cost Locations",
        "uid":"uid-7f001--6c1b645f-112e5d0d91a--7ffc",
        "description":"Role parameter to assign cost locations",
        "type":"HDN",
        "mandatory":true,
        "singleValued":false,
        "selectLeavesOnly":false,
        "uniqueValues":false,
        "minimum":0,
        "maximum":0,
        "defaultValues":
        [
        ],
        "proposals":
        [
            {
                "display":"A111, A11, A1, Cost Locations, Groups,
                           SAP R3, TargetSystems",
                "uid":"uid-7f001-6f26d110-11da5aeefcf--76e1",
                "value":"cn=A111,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                         cn=SAP R3,cn=TargetSystems,cn=My-Company",
                "selectable":true,
                "leaf":false
            },
            {
                "display":"A119, A11, A1, Cost Locations, Groups,
                           SAP R3, TargetSystems",
                "uid":"uid-7f001-6f26d110-11da5aeefcf--76d7",
                "value":"cn=A119,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                         cn=SAP R3,cn=TargetSystems,cn=My-Company",
                "selectable":true,
                "leaf":false
            }
        ]
    }
]

Here is a second example, this time with role parameters of type DN and Text:

[
    {
        "name":"Project",
        "uid":"uid-7f001-cee271-fed935aa6d--7eb4",
        "description":"Role parameter that lists all projects of My-Company",
        "type":"DN",
        "mandatory":true,
        "singleValued":false,
        "selectLeavesOnly":false,
        "uniqueValues":false,
        "minimum":0,
        "maximum":0,
        "defaultValues":
        [
        ],
        "proposals":
        [
            { "display":"High performance" },
            { "display":"MoreCustomers" },
            { "display":"OptimizeIT" },
            { "display":"Testproject" }
        ]
    },
    {
        "name":"Car Number",
        "uid":"uid-7f001--290d5629-1183529ae71--7ffe",
        "description":"The number of your car for the Parking lot",
        "type":"Text",
        "mandatory":false,
        "singleValued":false,
        "selectLeavesOnly":false,
        "uniqueValues":false,
        "minimum":0,
        "maximum":0,
        "defaultValues":
        [
        ],
        "proposals":
        [
        ]
    }
]

Reading the Next Level of HDN Role Parameter Nodes

This operation retrieves the children of a given role parameter node for a role parameter of type HDN.

The request path must include the ID of the role assignment, the assigned role, or the role to be assigned. It doesn’t matter whether the role is assigned just once or more than once since the parameter configuration depends only on the role and not on any specific assignment. The path must also include the ID of the HDN role parameter and of the parent node whose children are requested.

The configuration may vary with the role and the authenticated user.

See the section “Assigning Roles with Parameters” for details on when and how to use this request.

Request

HTTP Method and Path

GET /Me/roles/{roleId}/roleParams/{roleParamId}/proposal/{roleParamNodeId}

GET /Me/assignableRoles/{roleId}/roleParams/{roleParamId}/proposal/{roleParamNodeId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • roleId - The UID of a role assignment (cn) or the UID of a role (dxruid).

  • roleParamId - The UID of HDN role parameter (dxruid).

  • roleParamNodeId - The UID of a role parameter node (dxruid).

Response

HTTP Success Codes

  • OK (200) - The children of the role parameter node are returned.

Response Content

On success, the operation returns a JSON array with the children of the specified role parameter node; in the following example, node "cn=A111,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,cn=SAP R3,cn=TargetSystems,cn=My-Company":

[
    {
        "display":"A1111",
        "uid":"uid-7f001-6f26d110-11da5aeefcf--76e0",
        "value":"cn=A1111,cn=A111,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                 cn=SAP R3,cn=TargetSystems,cn=My-Company",
        "selectable":true,
        "leaf":true
    },
    {
        "display":"A1112",
        "uid":"uid-7f001-6f26d110-11da5aeefcf--76df",
        "value":"cn=A1112,cn=A111,cn=A11,cn=A1,cn=Cost Locations,cn=Groups,
                 cn=SAP R3,cn=TargetSystems,cn=My-Company",
        "selectable":true,
        "leaf":true
    }
]

Listing Pending Privilege Assignments

This operation retrieves the privilege assignments to the authenticated user which are still awaiting approval, and the ones which are scheduled to be performed on some future day (tickets).

The search for tickets can be configured in section "search" of resource type "Ticket". The search for workflows can be configured in section "search" of resource type "WorkflowInstance".

The size limit is defined by

  • Parameter "defaultCount" in section "search" of resource type "Ticket" or "WorkflowInstance".

  • Configuration parameter "search.defaultCount".

in descending priority.

Request

HTTP Method and Path

GET /Me/pendingRoles

GET /Me/pendingPermissions

GET /Me/pendingGroups

GET /Me/pendingPrivileges

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. The default attributes are "display", "$ref", "value", "description", "assignment", "initiator", "subject", "currentParticipants", "nextApprovalDate", "requestReason", "dueDate", and "targetSystem.cn" (for groups only). The value is the privilege’s unique ID.

  • filterValue - A filter for the privilege assignment requests. A request matches if one of its resources or its initiator match. For resources, the value replaces the placeholder in configuration parameter "valueFilter" in section “search” of resource type “Role” for roles, likewise for groups and permissions. For initiators, the value replaces the placeholder in configuration parameter "valueFilter" in section “search” of resource type “User”. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

Response

HTTP Success Codes

  • OK (200) - The assignment list is returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with a single list of respective privilege assignments:

{
  "totalResults":3,
  "Resources":
  [
     {
       "requestReason":"Requested for Taspatch by Pitton",
       "nextApprovalDate":"2019-05-03T12:18:57.000Z",
       "subject":
       {
         "displayName":"Nik Taspatch",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
         "$ref":http://localhost:8080/DirXIdentityRestService-My-Company
                      /Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
       },
       "assignment":
       {
         "mode":"manual",
         "hasSODViolations":false,
         "isEditable":false,
         "operation":"ADD"
       },
       "display":"Berlin - Data Center",
       "initiator":
       {
         "displayName":"Lavina Pitton",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                       /Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
       },
       "currentParticipants":
       [
         {
           "displayName":"Olivier Hungs",
           "value":"00014281",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                         /Users/00014281"
         },
         {
           "displayName":"Retha Wagner",
           "value":"uid-7f001-6f26d110-11da5aeefcf--7ff8",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                         /Users/uid-7f001-6f26d110-11da5aeefcf--7ff8"
         },
         {
           "displayName":"Nik Taspatch",
           "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                         /Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
         },
         {
           "displayName":"Christopher Dalmar",
           "value":"10052505",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                         /Users/10052505"
         }
       ],
       "description":"Protected room for server hardware",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                     /Me/pendingRoles/16a77c7d134%24-71c4",
       "value":"16a77c7d134$-71c4"
     },
     {
       "subject":
       {
         "displayName":"Nik Taspatch",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                       /Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
       },
       "assignment":
       {
         "mode":"manual",
         "hasSODViolations":false,
         "isEditable":false,
         "operation":"ADD"
       },
       "display":"Contractor",
       "initiator":
       {
         "displayName":"Lavina Pitton",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                       /Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
       },
       "dueDate":"2020-04-30T22:00:00.000Z",
       "description":"Standard role for all contractors",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                     /Me/pendingRoles/uid-a5d19dc-4a0faa41-16a77c9d758--7eeb",
       "value":"uid-a5d19dc-4a0faa41-16a77c9d758--7eeb"
     },
     (OTHER ASSIGNMENTS ELIMINATED)…
  ]
}
The first assignment comes from an approval workflow, the second one from a ticket.

The operation "Me/pendingPrivileges", on the other hand, returns a JSON object with three lists, one for each type of privileges:

{
 "roles":{
   "totalResults":3,
   "Resources":[…]
 },
 "permissions":{
   "totalResults":3,
   "Resources":[…]
 },
 "groups":{
   "totalResults":2,
   "Resources":[…]
 }
}

Response Data

  • totalResults - The number of privilege assignments returned.

  • Resources - The list of privilege assignments. The list might be incomplete due to a size limit of 1000 for searching the relevant approval workflows and a size limit of 1000 for searching the relevant tickets.

Counting Pending Privilege Assignments

This operation counts the pending privilege assignments for the authenticated user.

The size limit for ticket searches can be configured in section "search" of resource type "Ticket". The size limit for workflow searches can be configured in section "search" of resource type "WorkflowInstance".

The size limit is given by "search" section parameter "maxCount" or general configuration parameter "search.maxCount" in descending priority.

Request

HTTP Method and Path

GET /Me/pendingRoles/count

GET /Me/pendingPermissions/count

GET /Me/pendingGroups/count

GET /Me/pendingPrivileges/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

Response

HTTP Success Codes

  • OK (200) - The numbers of assignments are returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with a single counter:

{
 "totalResults":3,
 "sizeLimitExceeded":false
}

The operation "Me/pendingPrivileges/count", on the other hand, returns a JSON object with three counters, one or each type of privileges:

{
 "roles":{
   "totalResults":3,
   "sizeLimitExceeded":false
 },
 "permissions":{
   "totalResults":1,
   "sizeLimitExceeded":false
 },
 "groups":{
   "totalResults":0,
   "sizeLimitExceeded":false
 }
}

Response Data

  • totalResults - The number of privilege assignments.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached a size limit. The size limit is 1000 for searching the relevant approval workflows and 1000 for searching the relevant tickets.

Reading a Pending Privilege Assignment

This operation retrieves details of a pending privilege assignment for the authenticated user. The request path must include the request ID and optionally the order ID of the pending privilege assignment.

Request

HTTP Method and Path

GET /Me/pendingRoles/{requestId}

GET /Me/pendingRoles/{requestId}/{orderId}

GET /Me/pendingPermissions/{requestId}

GET /Me/pendingPermissions/{requestId}/{orderId}

GET /Me/pendingGroups/{requestId}

GET /Me/pendingGroups/{requestId}/{orderId}

GET /Me/pendingPrivileges/{requestId}

GET /Me/pendingPrivileges/{requestId}/{orderId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow and activity attributes.

Path Parameters

  • requestId- The UID of a pending privilege assignment.

  • orderId - If the source of the pending privilege is a ticket with multiple assignments, the index of the assignment within the ticket, as returned by the list operation.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specifies the privilege attributes to be returned in the result. The default attributes are "display", "$ref", "value", "type", "description", "assignment", "initiator", "subject", "currentParticipants", "nextApprovalDate", "requestReason", and "dueDate".

Response

HTTP Success Codes

  • OK (200) - The privilege assignment is returned.

Response Content

On success, the operation returns a SCIM privilege assignment object with details:

{
 "nextApprovalDate":"2019-05-03T13:59:01.000Z",
 "subject":
 {
   "displayName":"Nik Taspatch",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                 /users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
 },
 "assignment":
 {
   "mode":"manual",
   "hasSODViolations":false,
   "isEditable":false,
   "operation":"ADD"
 },
 "display":"Signature Level 3",
 "initiator":
 {
   "displayName":"Lavina Pitton",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                 /users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
 },
 "currentParticipants":
 [
   {
     "displayName":"Olivier Hungs",
     "value":"00014281",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                   /users/00014281"
   },
   {
     "displayName":"Christopher Dalmar",
     "value":"10052505",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                   /users/10052505"
   }
 ],
 "description":"Highest level of signatures for top management",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
               /Me/pendingRoles/16a77c7d134%24-6874",
 "value":"16a77c7d134$-6874"
}

Listing Pending Profile Changes

This operation retrieves the pending changes to the authenticated user’s profile. A change might be pending since it is awaiting approval, or since it has been scheduled to be performed on some future day.

The search for tickets can be configured in section "search" of resource type "Ticket". The search for workflows can be configured in section "search" of resource type "WorkflowInstance".

The size limit is defined by

  • Parameter "defaultCount" in section "search" of resource type "Ticket" or "WorkflowInstance".

  • Configuration parameter "search.defaultCount".

in descending priority.

Request

HTTP Method and Path

GET /Me/pendingProfileChanges

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

  • filterValue - A filter for the profile change initiator. The value will replace the placeholder in configuration parameter "valueFilter" in section “search” of resource type “User”. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no filter is applied.

Response

HTTP Success Codes

  • OK (200) - The assignment list is returned.

Response Content

On success, the operation returns a JSON object with the list of profile changes:

{
 "totalResults":2,
 "Resources":
 [
   {
     "nextApprovalDate":"2019-07-03T14:01:02.000Z",
     "subject":
     {
       "displayName":"Marc Abele",
       "value":"uid-7f001-6f26d110-11da5aeefcf--7ffc",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                      Users/uid-7f001-6f26d110-11da5aeefcf--7ffc"
     },
     "display":"Abele Marc",
     "initiator":
     {
       "displayName":"Nik Taspatch",
       "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                      Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
     },
     "currentParticipants":
     [
       {
         "displayName":"Administrator",
         "value":"metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        Users/metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4"
       },
       {
         "displayName":"Lavina Pitton",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
       },
       {
         "displayName":"Nik Taspatch",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
       }
     ],
     "id":"16b1c3bf967$-753a",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                    Me/pendingProfileChanges/16b1c3bf967%24-753a",
    "mode":"manual",
    "state":"InApproval",
    "modifications":
    [
      {
        "path":"mail",
        "oldValue":
        [
          "Marc.Abele@My-Company.com"
        ],
        "newValue":
        [
          "Marcello.Abele@My-Company.com"
        ],
        "scimPaths":
        [
          "emails#work"
        ]
      }
    ]
  },
  {
    "subject":
    {
      "displayName":"Marc Abele",
      "value":"uid-7f001-6f26d110-11da5aeefcf--7ffc",
      "$ref":http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/uid-7f001-6f26d110-11da5aeefcf--7ffc
    },
    "display":"Abele Marc 12:18:17",
    "initiator":
    {
      "displayName":"Nik Taspatch",
      "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
      "$ref":http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/uid-7f001-6f26d110-11da5aeefcf--7ff9
    },
    "id":"uid-a5d19dc--625fc563-169c92aafe6--7fad",
    "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Me/pendingProfileChanges/
                   uid-a5d19dc--625fc563-169c92aafe6--7fad",
    "dueDate":"2020-03-30T22:00:00.000Z",
    "mode":"manual",
    "state":"Input.Completed",
    "modifications":
    [
      {
        "path":"telephonenumber",
        "oldValue":"+49 89 6263-4096",
        "newValue":"+49 89 6263-4096 1000",
        "scimPaths":
        [
          "phoneNumbers#work"
        ]
      }
    ]
  }
]
}

Response Data

  • totalResults - The number of pending profile changes returned.

  • Resources - The list of pending profile changes.

Counting Pending Profile Changes

This operation counts the pending changes to the authenticated user’s profile.

The size limit for ticket searches can be configured in section "search" of resource type "Ticket". The size limit for workflow searches can be configured in section "search" of resource type "WorkflowInstance".

The size limit is given by "search" section parameter "maxCount" or general configuration parameter "search.maxCount" in descending priority.

Request

HTTP Method and Path

GET /Me/pendingProfileChanges/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

Response

HTTP Success Codes

  • OK (200) - The number of pending profile changes is returned.

Response Content

On success, the operation returns a JSON object with number of pending profile changes:

{
 "totalResults":4,
 "sizeLimitExceeded":false
}

Response Data

  • totalResults - The number of pending profile changes.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached a size limit. The size limits are 1000 for profile changes awaiting approval and 1000 for ticketed profile changes.

Reading a Pending Profile Change

This operation retrieves details of a pending profile change request for the authenticated user. The request path must include the request ID.

Request

HTTP Method and Path

GET /Me/pendingProfileChange/{requestId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow and activity attributes.

Path Parameters

  • requestId - The UID of a pending profile change.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specifies the profile change attributes to be returned in the result.

Response

HTTP Success Codes

  • OK (200) - The profile change is returned.

Response Content

On success, the operation returns the profile change object with details:

{
 "nextApprovalDate":"2019-07-03T14:01:02.000Z",
 "subject":
 {
   "displayName":"Marc Abele",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ffc",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                  Users/uid-7f001-6f26d110-11da5aeefcf--7ffc"
 },
 "display":"Abele Marc",
 "initiator":
 {
   "displayName":"Nik Taspatch",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                  Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
 },
 "currentParticipants":
 [
   {
     "displayName":"Lavina Pitton",
     "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
   }
 ],
 "id":"16b1c3bf967$-753a",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                Me/pendingProfileChanges/16b1c3bf967%24-753a",
 "mode":"manual",
 "state":"InApproval",
 "modifications":
 [
   {
     "path":"mail",
     "oldValue":
     [
       "Marc.Abele@My-Company.com"
     ],
     "newValue":
     [
       "Marcello.Abele@My-Company.com"
     ],
     "scimPaths":
     [
       "emails#work"
     ]
   }
 ]
}

Listing Initiated Requests

This operation retrieves the privileges that have been assigned by the authenticated user but are still awaiting approval, and the profile changes requested by the authenticated user still awaiting approval.

The list of subject types for the tickets and workflows can be configured in section ”requests” of resource type "User".

The search base for the tickets can be configured in section "search" of resource type "Ticket". The search base for the workflows can be configured in section "search" of resource type "WorkflowInstance".

The size limit is defined by

  • Parameter "defaultCount" in section "search" of resource type "Ticket" or "WorkflowInstance".

  • Configuration parameter "search.defaultCount".

in descending priority.

Request

HTTP Method and Path

GET /Me/pendingRequests

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • includeProfileChanges - Whether (true) or not (false) to include profile change requests. The default is true.

  • includePrivilegeAssignmentChanges - Whether (true) or not (false) to include privilege assignment requests. The default is true.

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

  • filter - The SCIM filter to be applied when searching for initiated profile changes and privilege assignments. The default is no filter.

  • workflowFilter - The SCIM filter to be applied when searching for requests for which an approval workflow is running. The default is no filter.

  • ticketFilter - A SCIM filter to be applied when searching for ticketed requests. The default is no filter.

  • filterValue - A filter for the privilege assignment requests. A request matches if one of its resources or its subject match. For resources, the value replaces the placeholder in configuration parameter "valueFilter" in section “search” of resource type “Role” for roles, likewise for groups and permissions. For subject, the value replaces the placeholder in configuration parameter "valueFilter" in section “search” of resource type “User”. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

Response

HTTP Success Codes

  • OK (200) - The initiated requests are returned.

Response Content

On success, the operation returns a JSON object with the list of initiated requests for each privilege type, and another list with profile changes:

{
 "profileChanges":
 {
   "totalResults":1,
   "Resources":
   [
     {
       "nextApprovalDate":"2019-07-03T15:15:43.000Z",
       "subject":
       {
         "displayName":"Christopher Dalmar",
         "value":"10052505",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        Users/10052505"
       },
       "display":"Dalmar Christopher",
       "initiator":
       {
         "displayName":"Olivier Hungs",
         "value":"00014281",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        Users/00014281"
       },
       "currentParticipants":
       [
         {
           "displayName":"Administrator",
           "value":"metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                          Users/metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4"
         },
         {
           "displayName":"Lavina Pitton",
           "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                          Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
         },
         {
           "displayName":"Nik Taspatch",
           "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                          Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
         }
       ],
       "id":"16b1c3bf967$-740d",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                      Me/pendingRequests/16b1c3bf967%24-740d",
      "mode":"manual",
      "state":"InApproval",
      "modifications":
      [
        {
          "path":"mail",
          "oldValue":
          [
            "Christopher.Dalmar@My-Company"
          ],
          "newValue":
          [
            "Chris.Dalmar@My-Company.com",
            "Christopher.Dalmar@My-Company"
          ],
          "scimPaths":
          [
            "emails#work"
          ]
        }
      ]
     }
   ]
 },
 "permissions":
 {
   "totalResults":1,
   "Resources":
   [
     {
       "nextApprovalDate":"2019-04-16T13:02:29.000Z",
       "subject":
       {
         "displayName":"Gabriela Morton",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ffd",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        Users/uid-7f001-6f26d110-11da5aeefcf--7ffd"
       },
       "assignment":
       {
         "mode":"manual",
         "hasSODViolations":false,
         "isEditable":false,
         "operation":"ADD"
       },
       "display":"Manager",
       "initiator":
       {
         "displayName":"Olivier Hungs",
         "value":"00014281",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        Users/00014281"
       },
       "currentParticipants":
       [
         {
           "displayName":"Olivier Hungs",
           "value":"00014281",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                          Users/00014281"
         },
         {
           "displayName":"Christopher Dalmar",
           "value":"10052505",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                          Users/10052505"
         }
       ],
       "description":"Standard permission for managers",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                      Me/pendingRequests/16a20df4e51%24-69b8",
       "value":"16a20df4e51$-69b8"
     }
   ]
 },
 "roles":
 {
   "totalResults":0,
   "Resources":
   [
   ]
 },
 "groups":
 {
   "totalResults":0,
   "Resources":
   [
   ]
 }
}

Response Data

  • totalResults - The number of initiated requests returned.

  • Resources - The list of initiated requests.

Counting Initiated Requests

This operation counts the pending requests initiated by the authenticated user.

The size limit for ticket searches can be configured in section "search" of resource type "Ticket". The size limit for workflow searches can be configured in section "search" of resource type "WorkflowInstance".

The size limit is given by "search" section parameter "maxCount" or general configuration parameter "search.maxCount" in descending priority.

Request

HTTP Method and Path

GET /Me/pendingRequests/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • includeProfileChanges - Whether (true) or not (false) to include profile change requests. The default is true.

  • includePrivilegeAssignmentChanges - Whether (true) or not (false) to include privilege assignment requests. The default is true.

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow is running (true) or not (false). The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which are scheduled to be performed on some future day. The default is true.

  • filter - The SCIM filter to be applied when searching for initiated profile changes and privilege assignments. The default is no filter.

  • workflowFilter - The SCIM filter to be applied when searching for privilege assignments. The default is no filter.

  • ticketFilter - The SCIM filter to be applied when searching for ticketed requests. The default is no filter.

Response

HTTP Success Codes

  • OK (200) - The numbers of pending initiated requests are returned.

Response Content

On success, the operation returns counters for each privilege type and another counter for profile changes.

{
 "profileChanges":{
   "totalResults":2,
   "sizeLimitExceeded":false
 },
 "roles":{
   "totalResults":4,
   "sizeLimitExceeded":false
 },
 "permissions":{
   "totalResults":1,
   "sizeLimitExceeded":false
 },
 "groups":{
   "totalResults":0,
   "sizeLimitExceeded":false
 }
}

Response Data

  • totalResults - The number of pending initiated privilege assignments or profile changes.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached the size limit. The size limit for counting profile change workflows, profile change tickets, privilege assignment workflows and privilege assignment tickets is 1000 each.

Reading an Initiated Request

This operation retrieves details of a pending request initiated by the authenticated user.

Request

HTTP Method and Path

GET /Me/pendingRequests/{requestId}

GET /Me/pendingRequests/{requestId}/{orderId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • requestId - The UID of a pending request initiated by the authenticated user.

  • orderId - The index of the assignment within a privilege assignment ticket, as returned by the list operation.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specifies the attributes to be returned in the result. By default, the request returns all attributes. The parameter is ignored for profile changes.

Response

HTTP Success Codes

  • OK (200) - The initiated request is returned.

Response Content

On success, the operation returns a JSON object with details of the initiated request:

{
 "nextApprovalDate":"2019-07-03T15:15:43.000Z",
 "subject":
 {
   "displayName":"Christopher Dalmar",
   "value":"10052505",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                  Users/10052505"
 },
 "display":"Dalmar Christopher",
 "initiator":
 {
   "displayName":"Olivier Hungs",
   "value":"00014281",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                  Users/00014281"
 },
 "currentParticipants":
 [
   {
     "displayName":"Administrator",
     "value":"metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/metacp-80b7dc0e-4d15-77cc-659b-2c37de08efe4"
   },
   {
     "displayName":"Lavina Pitton",
     "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
   },
   {
     "displayName":"Nik Taspatch",
     "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
   }
 ],
 "id":"16b1c3bf967$-740d",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                Me/pendingRequests/16b1c3bf967%24-740d",
"mode":"manual",
"state":"InApproval",
"modifications":
[
  {
    "path":"mail",
    "oldValue":
    [
      "Christopher.Dalmar@My-Company"
    ],
    "newValue":
    [
      "Chris.Dalmar@My-Company.com",
      "Christopher.Dalmar@My-Company"
    ],
    "scimPaths":
    [
      "emails#work"
    ]
  }
]
}

Deleting an Initiated Request

This operation cancels the workflow or deletes the ticket which is the source of a pending request initiated by the authenticated user.

Request

HTTP Method and Path

DELETE /Me/pendingRequests/{requestId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • requestId - The UID of a pending request initiated by the user.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The initiated request has been deleted.

Listing Closed Requests

This operation lists the finished requests with the authenticated user as initiator or subject. The list includes privilege assignment changes as well as profile changes, workflow requests as well as ticket requests.

The list of subject types for the tickets and workflows can be configured in section ”requests” of resource type "User".

The search base for the tickets can be configured in section "search" of resource type "Ticket". The search base for the workflows can be configured in section "search" of resource type "WorkflowInstance".

The size limit is defined by

  • Parameter "defaultCount" in section "search" of resource type "Ticket" or "WorkflowInstance".

  • Configuration parameter "search.defaultCount".

in descending priority.

The list of attributes returned for each closed request is fixed.

Request

HTTP Method and Path

GET /Me/closedRequests

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • includeProfileChanges - Whether (true) or not (false) to include profile change requests. The default is true.

  • includePrivilegeAssignmentChanges - Whether (true) or not (false) to include privilege assignment requests. The default is true.

  • includeWorkflowRequests - Whether (true) or not (false) to include requests for which an approval workflow was started. The default is true.

  • includeTicketRequests - Whether (true) or not (false) to include ticketed requests which were scheduled to be performed on a specific day. The default is true.

  • filter - The SCIM filter to be applied when searching for profile changes and privilege assignments. The default is no filter.

  • workflowFilter - The SCIM filter to be applied when searching for requests for which an approval workflow was started. The default is no filter.

  • ticketFilter - A SCIM filter to be applied when searching for ticketed requests. The default is no filter.

  • filterValue - A filter value for the workflow or ticket subject, initiator, and resource. The value is to replace the placeholder in configuration parameter "valueFilter" in section "search” of the resource type configurations for "User" (subject and initiator) and, depending on the workflow resource’s type, for "Role", "Permission" or "Group” (resource). Asterisks (*) within the filter value serve as wildcards. If left unspecified, no filter is applied.

  • from - The earliest end date (for example "2021-03-10T00:00:00.000Z"). By default, there’s no lower bound for the end date.

  • to - The latest end date (for example "2021-06-10T00:00:00.000Z"). By default, there’s no upper bound for the end date.

Response

HTTP Success Codes

  • OK (200) - The closed requests are returned.

Response Content

On success, the operation returns a JSON object with the list of closed requests for each privilege type, and another list with profile changes:

{
 "profileChanges":
 {
   "totalResults":1,
   "Resources":
   [
     {
       "mode":"manual",
       "applicationState":"CHANGES_APPLIED",
       "endDate":"2021-03-16T12:06:44.000Z",
       "subject":
       {
         "displayName":"Nik Taspatch",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
       },
       "display":"Taspatch Nik",
       "initiator":
       {
         "displayName":"Olivier Hungs",
         "value":"00014281
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/00014281"
       },
       "state":"SUCCEEDED",
       "value":"17839d3a27d$-6f7b",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               Me/closedRequests/17839d3a27d%24-6f7b",
       "startDate":"2021-03-16T12:05:14.000Z",
       "expirationDate":"2021-03-20T12:05:14.000Z
       "modifications":
       [
         {
           "path":"dxroulink",
           "newValue":
           {
             "displayName":"Sales",
             "value":"uid-7f001-6f26d110-11da5aeefcf--7970",
             "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                     DomainObjects/uid-7f001-6f26d110-11da5aeefcf--7970"
           }
         },
         {
           "path":"dxrlocationlink",
           "newValue":
           {
             "displayName":"My-Company Rome",
             "value":"uid-7f001-6f26d110-11da5aeefcf--795f",
             "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                     DomainObjects/uid-7f001-6f26d110-11da5aeefcf--795f"
           }
         }
       ]
     }
   ]
 },
 "permissions":
 {
   "totalResults":0,
   "Resources":
   [
   ]
 },
 "roles":
 {
   "totalResults":0,
   "Resources":
   [
   ]
 },
 "groups":
 {
   "totalResults":1,
   "Resources":
   [
 {
   "workflow":
   {
     "displayName":"Dalmar Christopher -> Software Beta Programs",
     "value":"1762760dce7$-63ea",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             DomainObjects/1762760dce7%24-63ea"
   },
   "endDate":"2021-03-15T15:15:44.997Z",
   "subject":
   {
     "displayName":"Christopher Dalmar",
     "value":"10052505",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/10052505"
   },
   "assignment":
   {
     "mode":"manual",
     "hasSODViolations":false,
     "isEditable":false,
     "operation":"ADD"
   },
   "display":"Software Beta Programs",
   "initiator":
   {
     "displayName":"Nik Taspatch",
     "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
   },
   "dueDate":"2021-11-30T23:00:00.000Z",
   "description":"Service to access software beta programs of My-Company",
   "targetsystem.cn":"Extranet Portal",
   "state":"Approval.Error",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Me/closedRequests/uid-a5dcb1-4eea9959-176280034f5--7dfe",
   "value":"uid-a5dcb1-4eea9959-176280034f5--7dfe",
   "startDate":"2020-12-03T10:02:40.960Z"
 }
}

Response Data

  • totalResults - The number of closed requests returned.

  • Resources - The list of closed requests.

Reading a Closed Request

This operation retrieves details of a closed request with the authenticated user as initiator or subject.

If the request was processed by a workflow, the result includes the list of finished people activities.

The list of attributes returned for the closed request is fixed.

Request

HTTP Method and Path

GET /Me/closedRequests/{requestId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow and activity attributes.

Path Parameters

  • requestId - The UID of a closed request which the authenticated user is the initiator or subject of.

Response

HTTP Success Codes

  • OK (200) - The closed request is returned.

Response Content

On success, the operation returns a JSON object with details of the closed request. The first example response shows a profile change ticket:

{
 "mode":"manual",
 "endDate":"2021-03-15T15:15:52.217Z",
 "subject":
 {
   "displayName":"Nik Taspatch",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
 },
 "display":"Taspatch Nik 14:10:25",
 "initiator":
 {
   "displayName":"Nik Taspatch",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
 },
 "dueDate":"2021-01-30T23:00:00.000Z",
 "state":"ApplyChange.Completed",
 "value":"uid-c0a82a1--6bfdfab4-17067d3b25f--7f26",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
         Me/closedRequests/uid-c0a82a1--6bfdfab4-17067d3b25f--7f26",
 "operation":"MODIFY",
 "startDate":"2020-02-21T13:10:25.159Z",
 "modifications":
 [
   {
     "path":"preferredlanguage",
     "newValue":"fr",
     "scimPaths":
     [
       "preferredLanguage"
     ]
   }
 ]
}

The next example response shows a privilege assignment ticket:

{
 "subject":
 {
   "displayName":"Christopher Dalmar",
   "value":"10052505",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Users/10052505"
 },
 "assignment":
 {
   "mode":"manual",
   "hasSODViolations":false,
   "isEditable":false,
   "operation":"ADD"
 },
 "display":"Software Beta Programs",
 "dueDate":"2021-11-30T23:00:00.000Z",
 "description":"Service to access software beta programs of My-Company",
 "state":"Approval.Error",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
         Me/closedRequests/uid-a5dcb1-4eea9959-176280034f5--7dfe",
 "value":"uid-a5dcb1-4eea9959-176280034f5--7dfe",
 "startDate":"2021-11-30T23:00:00.000Z",
 "resourceType":"Group"
}

The following example response shows a profile change workflow:

{
 "mode":"manual",
 "endDate":"2021-04-06T05:44:14.000Z",
 "subject":
 {
   "displayName":"Nik Taspatch",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
 },
 "activities":
 [
   {
     "contentReadOnly":false,
     "displayName":"Approval of Attribute Modifications-0",
     "retryCount":2,
     "description":"Please approve the following attribute modification
         request for the listed user.\n
         Check it carefully, adapt some values if necessary and accept
         or reject it.\n
         It is good style to enter a reason (especially when rejecting).",
     "dn":"cn=Approval of Attribute Modifications-0,cn=17881d69036$-7450,
           cn=2021-03-30,cn=Modify Location and Organization,cn=Users,
           cn=My-Company,cn=Monitor,cn=wfRoot,cn=My-Company",
     "title":"Approval of Attribute Modifications",
     "type":"people",
     "escalationLevel":0,
     "retryLimit":3,
     "master":"Approval of Attribute Modifications",
     "dueDateEnabled":false,
     "meta":
     {
       "created":"2021-03-30T08:35:56.048Z",
       "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   DomainObjects/uid-a5dcb1-13278e64-17881d662bd--7ecf",
       "lastModified":"2021-04-06T05:44:14.646Z",
       "resourceType":"ActivityInstance"
     },
     "subType":"approveModification",
     "id":"uid-a5dcb1-13278e64-17881d662bd--7ecf",
     "state":"CANCELLED",
     "startDate":"2021-04-01T13:42:08.000Z",
     "expirationDate":"2021-04-02T13:42:08.000Z",
     "participants":
     [
       {
         "displayName":"Hans Berner",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff7",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff7"
       },
       {
         "displayName":"Laura Telfer",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff2",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff2"
       },
       {
         "displayName":"Santiago Strober",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff3",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff3"
       },
       {
         "displayName":"Rita Straub",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff4",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff4"
       },
       {
         "displayName":"Aurilia Poole",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff5",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff5"
       },
       {
         "displayName":"Mary-Jane Ormsby",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff6",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff6"
       }
     ]
   }
 ],
 "display":"Taspatch Nik",
 "initiator":
 {
   "displayName":"Nik Taspatch",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
 },
 "state":"FAILED.EXPIRED",
 "value":"17881d69036$-7450",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
         Me/closedRequests/17881d69036%24-7450",
 "startDate":"2021-03-30T08:35:55.000Z",
 "expirationDate":"2021-04-03T08:35:55.000Z",
 "modifications":
 [
   {
     "path":"description",
     "newValue":"Chief Information Technology IT"
   }
 ]
}

The last example response shows a privilege assignment workflow:

{
 "endDate":"2021-03-09T13:05:06.000Z",
 "subject":
 {
   "displayName":"Nik Taspatch",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
 },
 "assignment":
 {
   "mode":"manual",
   "hasSODViolations":false,
   "isEditable":false,
   "operation":"ADD"
 },
 "activities":
 [
   {
     "contentReadOnly":false,
     "displayName":"Approval by Privilege Managers-0",
     "retryCount":1,
     "description":"Please approve the following privilege request.\n
          Check it carefully and accept or reject it.\n
          It is good style to enter a reason (especially when rejecting).",
     "dn":"cn=Approval by Privilege Managers-0,cn=178026dc151$-7c90,
           cn=2021-03-05,cn=4-Eye Approval,cn=Approval,cn=My-Company,
           cn=Monitor,cn=wfRoot,cn=My-Company",
     "title":"Approval by Privilege Managers",
     "type":"people",
     "escalationLevel":0,
     "retryLimit":2,
     "master":"Approval by Privilege Managers",
     "dueDateEnabled":false,
     "meta":
     {
       "created":"2021-03-05T12:49:18.770Z",
       "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   DomainObjects/uid-a5dcb1--1c5c7547-178026d932c--7f94",
       "lastModified":"2021-03-09T13:05:06.977Z",
       "resourceType":"ActivityInstance"
     },
     "subType":"approveAssignment",
     "id":"uid-a5dcb1--1c5c7547-178026d932c--7f94",
     "state":"CANCELLED",
     "startDate":"2021-03-09T10:05:14.000Z",
     "expirationDate":"2021-03-10T10:05:15.000Z",
     "participants":
     [
       {
         "displayName":"Retha Wagner",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff8",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff8"
       },
       {
         "displayName":"Nik Taspatch",
         "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
       }
     ]
   },
   {
     "contentReadOnly":false,
     "displayName":"Approval by User Manager-0",
     "retryCount":1,
     "description":"Please approve the following privilege request.\n
          Check it carefully and accept or reject it.\n
          It is good style to enter a reason (especially when rejecting).",
     "dn":"cn=Approval by User Manager-0,cn=178026dc151$-7c90,cn=2021-03-05,
           cn=4-Eye Approval,cn=Approval,cn=My-Company,cn=Monitor,
           cn=wfRoot,cn=My-Company",
     "title":"Approval by User Manager",
     "type":"people",
     "escalationLevel":0,
     "retryLimit":2,
     "master":"Approval by User Manager",
     "dueDateEnabled":false,
     "meta":
     {
       "created":"2021-03-05T12:49:18.775Z",
       "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   DomainObjects/uid-a5dcb1--1c5c7547-178026d932c--7f93",
       "lastModified":"2021-03-09T13:05:06.981Z",
       "resourceType":"ActivityInstance"
     },
     "subType":"approveAssignment",
     "id":"uid-a5dcb1--1c5c7547-178026d932c--7f93",
     "state":"CANCELLED",
     "startDate":"2021-03-09T10:05:14.000Z",
     "expirationDate":"2021-03-10T10:05:15.000Z",
     "participants":
     [
       {
         "displayName":"Olivier Hungs",
         "value":"00014281",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/00014281"
       },
       {
         "displayName":"Christopher Dalmar",
         "value":"10052505",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                 Users/10052505"
       }
     ]
   }
 ],
 "display":"DXR Informational Users",
 "initiator":
 {
   "displayName":"Nik Taspatch",
   "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
   "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
           Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
 },
 "description":"DirX Identity informational users",
 "state":"FAILED.EXPIRED",
 "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
         Me/closedRequests/178026dc151%24-7c90",
 "value":"178026dc151$-7c90",
 "startDate":"2021-03-05T12:49:18.000Z",
 "resourceType":"Role"
}

Listing Personas

This operation returns the list of personas of the authenticated user.

No size or time limits apply to this operation.

If you also also need the list of user facets or functional users, use request "Listing Users" for performance reasons.

When reading the profile of the authenticated user (request "Reading the Profile"), you can get the list of personas via the virtual user attribute "personasForUser".

Request

HTTP Method and Path

GET /Me/personas

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the persona attributes to be returned in the result. The default and mandatory attributes can be configured in section "search" of resource type "Persona".

Response

HTTP Success Codes

  • OK (200) - The personas are returned.

Response Content

On success, the operation returns a JSON object with the list of personas; attribute “value” is the persona’s unique ID:

{
 "startIndex":1,
 "totalResults":1,
 "itemsPerPage":1,
 "schemas":
 [
   "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 ],
 "Resources":
 [
   {
     "owner":
     {
       "displayName":"Bruno Klarmann",
       "value":"10052504",
       "$ref":"http://localhost:8080/
               DirXIdentityRestService-My-Company/Users/10052504"
     },
     "dxruseruid":"10052504",
     "c":"US",
     "displayName":"Klarmann Bruno Psn",
     "dn":"cn=Klarmann Bruno Psn,ou=Sales Europe,ou=Sales,
           o=My-Company,cn=Users,cn=My-Company",
     "id":"cn=Klarmann Bruno Psn,ou=Sales Europe,ou=Sales,
           o=My-Company,cn=Users,cn=My-Company",
     "value":"uid-c0a8c84--7e9b4cc4-13caacc7369--7f71",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-c0a8c84--7e9b4cc4-13caacc7369--7f71"
   }
 }
}

Response Data

  • totalResults - The number of personas returned.

  • Resources - The list of personas.

Counting Personas

This operation returns the number of personas of the authenticated user.

No size or time limits apply to this operation.

If you also also need the number of user facets or functional users, use request "Counting Users" for performance reasons.

Request

HTTP Method and Path

GET /Me/personas/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Response

HTTP Success Codes

  • OK (200) - The number of personas is returned.

Response Content

On success, the operation returns a JSON object with the number of personas:

{
 "totalResults":1
}

Response Data

  • totalResults - The number of personas.

Listing User Facets

This operation returns the list of user facets of the authenticated user.

No size or time limits apply to this operation.

If you also also need the list of personas or functional users, use request "Listing Users" for performance reasons.

When reading the profile of the authenticated user (request "Reading the Profile"), you can get the list of user facets via the virtual user attribute "userFacetsForUser".

Request

HTTP Method and Path

GET /Me/userFacets

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the user facet attributes to be returned in the result. The default and mandatory attributes can be configured in section "search" of resource type "UserFacet".

Response

HTTP Success Codes

  • OK (200) - The user facets are returned.

Response Content

On success, the operation returns a JSON object with the list of user facets; attribute “value” is the user facet’s unique ID:

{
 "startIndex":1,
 "totalResults":1,
 "itemsPerPage":1,
 "schemas":
 [
   "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 ],
 "Resources":
 [
   {
     "owner":
     {
       "displayName":"Bruno Klarmann",
       "value":"10052504",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               Users/10052504"
     },
     "dxruseruid":"10052504",
     "displayName":"Klarmann Bruno UFt",
     "dn":"cn=Klarmann Bruno UFt,ou=Sales Europe,ou=Sales,
           o=My-Company,cn=Users,cn=My-Company",
     "id":"cn=Klarmann Bruno UFt,ou=Sales Europe,ou=Sales,
           o=My-Company,cn=Users,cn=My-Company",
     "value":"uid-a5dcb1-526441a-175b10b4afb--7d25",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-a5dcb1-526441a-175b10b4afb--7d25"
   }
 ]
}

Response Data

  • totalResults - The number of user facets returned.

  • Resources - The list of user facets.

Counting User Facets

This operation returns the number of user facets of the authenticated user.

No size or time limits apply to this operation.

If you also also need the number of personas or functional users, use request "Counting Users" for performance reasons.

Request

HTTP Method and Path

GET /Me/userFacets/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Response

HTTP Success Codes

  • OK (200) - The number of user facets is returned.

Response Content

On success, the operation returns a JSON object with the number of user facets:

{
 "totalResults":1
}

Response Data

  • totalResults - The number of user facets.

Listing Functional Users

This operation returns the list of functional users of the authenticated user.

No size or time limits apply to this operation.

If you also also need the list of personas or user facets, use request "Listing Users" for performance reasons.

When reading the profile of the authenticated user (request "Reading the Profile"), you can get the list of functional users via the virtual user attribute "functionalUsersForUser".

Request

HTTP Method and Path

GET /Me/functionalUsers

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the functional user attributes to be returned in the result. The default and mandatory attributes can be configured in section "search" of resource type "FunctionalUser".

Response

HTTP Success Codes

  • OK (200) - The functional users are returned.

Response Content

On success, the operation returns a JSON object with the list of functional users; attribute “value” is the functional users’s unique ID:

{
 "startIndex":1,
 "totalResults":1,
 "itemsPerPage":1,
 "schemas":
 [
   "urn:ietf:params:scim:api:messages:2.0:ListResponse"
 ],
 "Resources":
 [
   {
     "dxruseruid":"uid-7f001-6f26d110-11da5aeefcf--7fe6",
     "c":"DE",
     "displayName":"Meeting Room Berlin",
     "dxrsponsor":
     {
       "displayName":"Klaus Reichel",
       "value":"uid-7f001-6f26d110-11da5aeefcf--7fe6",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               Users/uid-7f001-6f26d110-11da5aeefcf--7fe6"
     },
     "dn":"cn=Meeting Room Berlin,ou=Resources,o=My-Company,
           cn=Users,cn=My-Company",
     "id":"cn=Meeting Room Berlin,ou=Resources,o=My-Company,
           cn=Users,cn=My-Company",
     "value":"uid-c0a8c84--4ae2f0b6-13ca509f9e6--7e87",
     "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-c0a8c84--4ae2f0b6-13ca509f9e6--7e87"
   }
 ]
}

Response Data

  • totalResults - The number of functional users returned.

  • Resources - The list of functional users.

Counting Functional Users

This operation returns the number of functional users of the authenticated user.

No size or time limits apply to this operation.

If you also also need the number of personas or user facets, use request "Counting Users" for performance reasons.

Request

HTTP Method and Path

GET /Me/functionalUsers/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Response

HTTP Success Codes

  • OK (200) - The number of functional users is returned.

Response Content

On success, the operation returns a JSON object with the number of functional users:

{
 "totalResults":2
}

Response Data

  • totalResults - The number of functional users.

Listing Users

This operation returns the lists of personas, user facets and functional users of the authenticated user.

No size or time limits apply to this operation.

Request

HTTP Method and Path

GET /Me/users

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the attributes to be returned in the result for each persona, user facet or functional user. The default and mandatory attributes can be configured in section "search" of resource types "Persona", "UserFacet" and "FunctionalUser".

Response

HTTP Success Codes

  • OK (200) - The personas, user facets and functional users are returned.

Response Content

On success, the operation returns a JSON object with the lists of personas, user facets and functional users; attribute “value” is the unique ID of the persona, user facet or functional user:

{
 "personas":
 {
   "startIndex":1,
   "totalResults":1,
   "itemsPerPage":1,
   "schemas":
   [
     "urn:ietf:params:scim:api:messages:2.0:ListResponse"
   ,
   "Resources":
   [
   ... 1 persona ...
   ]
 },
 "userFacets":
 {
   "startIndex":1,
   "totalResults":0,
   "itemsPerPage":1,
   "schemas":
   [
     "urn:ietf:params:scim:api:messages:2.0:ListResponse"
   ,
   "Resources":
   [
   ]
 },
 "functionalUsers":
 {
   "startIndex":1,
   "totalResults":2,
   "itemsPerPage":1,
   "schemas":
   [
     "urn:ietf:params:scim:api:messages:2.0:ListResponse"
   ,
   "Resources":
   [
   ... 2 functional users ...
   ]
 }
}

Response Data

  • totalResults - The numbers of personas, user facets and functional users returned.

  • Resources - The lists of personas, user facets and functional users.

Counting Users

This operation returns the numbers of personas, user facets and functional users of the authenticated user.

No size or time limits apply to this operation.

Request

HTTP Method and Path

GET /Me/users/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Response

HTTP Success Codes

  • OK (200) - The numbers of personas, user facets and functional users are returned.

Response Content

On success, the operation returns a JSON object with the numbers of personas, user facets and functional users:

{
 "userFacets":
 {
   "totalResults":0
 },
 "functionalUsers":
 {
   "totalResults":2
 },
 "personas":
 {
   "totalResults":0
 }
}

Response Data

  • totalResults - The numbers of personas, user facets or functional users.

Password Service Operations

The password service provides operations to read the authenticated user’s password policy and to change his password.

Overview

This section provides an overview of password service operations.

List of Operations

  • GET /Me/passwordPolicy - Reads the authenticated user’s password policy.

  • POST /Me/password - Changes the authenticated user’s password.

Reading the Password Policy

This operation reads the authenticated user’s password policy.

The authenticated user must have the access rights to set his password.

Request

HTTP Method and Path

GET /Me/passwordPolicy

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Response

HTTP Success Codes

  • OK (200) - The password policy is returned. The policy is empty if no password policy is assigned to the user and no default password policy exists.

Response Content

On success, the operation returns a JSON object representing the password policy:

{
 "dxrPwdMinLength":6,
 "dxrPwdMinNumeric":2,
 "dxrPwdExpireWarning":0,
 "dxrPwdMaxAge":0,
 "dxrPwdMaxLength":8,
 "dxrPwdMinLowerChar":0,
 "dxrPwdMinNonAlphaNum":2,
 "dxrPwdMinUpperChar":1,
 "dxrPwdMinSpecialChar":1,
 "dxrPwdInHistory":10,
"dxrPwdWindowsCompatible":true,
"customCheckers":{
  "PasswordDiffChecker":{
    "allowReverse":false,
    "maxSharedSubstringLength":3
  },
  "SyntaxChecker":{
  }
}
}

Changing the Password

This operation changes the authenticated user’s password. The old user password must be provided with the request and is verified. If verification fails, the request is rejected.

Note that the REST Service doesn’t change the password directly in the database. It just sends a password change event. The event is then usually processed by a Java-based server. The operation returns after sending the event; it does not wait until the event is processed. This means that the operation usually returns before the password is changed.

The authenticated user must have the access rights to set his password.

Request

HTTP Method and Path

POST /Me/password

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Request Body

The request body for a simple password change is a JSON object with the old and new password:

{
 "oldPassword":"<old password>",
 "password":"<new password>"
}

Optionally the request supports the change of account passwords comparable to the corresponding Web Center ChangePassword JSP tag. In this case the request body contains the following optional attributes:

  • omitUser - Whether both user and account passwords are to be changed, or account passwords only. (Default value: false).

  • masterAccounts - The user’s master accounts for password synchronization:

    • account - The DN or UID of the account for password synchronization.

  • syncAccounts - The user’s accounts for password synchronization:

    • account - The DN or UID of the account for password synchronization.

    • synchronize - The password synchronization flag.

The following example shows a request, which sets the attribute “dxrOption(preventPwdSync)” to true for all given accounts before changing the password, thus preventing a password change for these accounts.

{
 "oldPassword":"<old password>",
 "password":"<new password>",
 "omitUser": true,
 "masterAccounts": [
  {
   "account": "uid-7f001-6f26d110-11da5aeefcf--7657"
  }
 ],
 "syncAccounts": [
  {
   "account": "uid-7f001-6f26d110-11da5aeefcf--777c",
   "synchronize": false
  },
  {
   "account": "uid-7f001-6f26d110-11da5aeefcf--7852",
   "synchronize": false
  }
 ]
}
Response

HTTP Success Codes

  • NO_CONTENT (204) - The password change event has been sent.

Delegation Service Operations

The delegation service provides operations on the delegations where the authenticated user is the delegator, as well as listing and reading the delegations where he is the substitute.

The service handles only the new type of delegations introduced with DirX Identity 8.7 SP3. The new delegations have a non-empty operation (attribute dxrOperationImp). The legacy delegations (with empty operation) are ignored.

If the new delegations are not enabled, the requests return an error response with HTTP status code 501 (Not Implemented).

Overview

This section provides general information about delegation service operations.

List of Operations

  • Delegations Delegated by the Authenticated User

    • GET /Me/delegations - Lists the delegations with the authenticated user as delegator.

    • GET /Me/delegations/count - Counts the delegations with the authenticated user as delegator.

    • GET /Me/delegations/{delegationId} - Reads the delegation with the given ID.

    • POST /Me/delegations - Creates a new delegation.

    • GET /Me/delegations/check - Checks if creating a new delegation will lead to a circular delegation.

    • PATCH /Me/delegations/{delegationId} - Changes the delegation with the given ID.

    • GET /Me/delegations/{delegationId}/check - Checks if changing the delegation with the given ID will lead to a circular delegation.

    • DELETE /Me/delegations/{delegationId} - Deletes the delegation with the given ID.

  • Delegations Delegated to the Authenticated User

    • GET /Me/delegations/assignedDelegations - Lists the delegations with the authenticated user as the substitute.

    • GET /Me/delegations/assignedDelegations/count - Counts the delegations with the authenticated user as the substitute.

    • GET /Me/delegations/{delegationId} - Reads the delegation with the given ID.

Listing Delegations

This operation retrieves the delegations where the authenticated user is the delegator.

The operation can be configured in section "search" of resource type "Delegation".

Request

HTTP Method and Path

GET /Me/delegations

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the delegation attributes to be returned in the result. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

Response

HTTP Success Codes

  • OK (200) - The delegation list is returned.

Response Content

On success, the operation returns a JSON object with the list of delegations:

{
   "totalResults":3,
   "Resources":
   [
     {
       "dxrassignfrom":
       {
           "displayName":"Olivier Hungs",
           "value":"00014281",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/00014281"
       },
       "meta":
       {
           "created":"2018-08-27T11:15:15.267Z",
           "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Me/delegations/uid-a5d19c8--24d12c54-1657b17fba5--7fe8",
           "lastModified":"2018-08-27T11:15:17.701Z",
           "resourceType":"Delegation"
       },
       "dxrname":"Hungs Grant -> Tinker",
       "dxrassignto":
       {
           "displayName":"Boris Tinker",
           "value":"uid-7f001-6f26d110-11da5aeefcf--7ffb",
           "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Users/uid-7f001-6f26d110-11da5aeefcf--7ffb"
       },
       "description":"Hungs delegates grants to Tinker",
       "dxrstartdate":"2018-08-02T22:00:00.000Z",
       "id":"uid-a5d19c8--24d12c54-1657b17fba5--7fe8",
       "dxroperationimp":"grant",
       "dxrenddate":"2020-09-02T22:00:00.000Z"
     },
     (OTHER DELEGATIONS ELIMINATED)…
   ]
}

Response Data

  • totalResults - The number of delegations returned.

  • Resources - The list of delegations.

Counting Delegations

This operation counts the delegations where the authenticated user is the delegator.

The operation can be configured in section "search" of resource type "Delegation".

Request

HTTP Method and Path

GET /Me/delegations/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Response

HTTP Success Codes

  • OK (200) - The number of delegations is returned.

Response Content

On success, the operation returns a JSON object with number of delegations:

{
  "totalResults":3,
  "sizeLimitExceeded":false
}

Response Data

  • totalResults - The number of delegations.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached a size limit. The size limit is specified by the parameter "defaultCount" of the delegation search configuration.

Listing Assigned Delegations

This operation retrieves the delegations where the authenticated user is the substitute.

The operation can be configured in section "search" of resource type "Delegation".

Request

HTTP Method and Path

GET /Me/delegations/assignedDelegations

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the delegation attributes to be returned in the result. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

Response

HTTP Success Codes

  • OK (200) - The delegation list is returned.

Response Content

On success, the operation returns a JSON object with the list of delegations:

{
   "totalResults":4,
   "Resources":
   [
     {
       "dxrassignfrom":
       {
           "displayName":"Boris Tinker",
           "value":"uid-7f001-6f26d110-11da5aeefcf--7ffb",
           "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Users/uid-7f001-6f26d110-11da5aeefcf--7ffb"
       },
       "meta":
       {
           "created":"2018-08-27T11:15:15.267Z",
           "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                       Me/delegations/uid-a5d19c8--24d12c54-1657b17fba5--7fc8",
           "lastModified":"2018-08-27T11:15:17.701Z",
           "resourceType":"Delegation"
       },
       "dxrname":"Tinker Approve -> Hungs",
       "dxrassignto":
       {
           "displayName":"Olivier Hungs",
           "value":"00014281",
           "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/00014281"
       },
       "description":"Tinker delegates approvals to Hungs",
       "dxrstartdate":"2018-08-02T22:00:00.000Z",
       "id":"uid-a5d19c8--24d12c54-1657b17fba5--7fc8",
       "dxroperationimp":"approve",
       "dxrenddate":"2020-09-02T22:00:00.000Z"
     },
     (OTHER DELEGATIONS ELIMINATED)…
   ]
}

Response Data

  • totalResults - The number of delegations returned.

  • Resources - The list of delegations.

Counting Assigned Delegations

This operation counts the delegations where the authenticated user is the substitute.

The operation can be configured in section "search" of resource type "Delegation".

Request

HTTP Method and Path

GET /Me/assignedDelegations/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Response

HTTP Success Codes

  • OK (200) - The number of delegations is returned.

Response Content

On success, the operation returns a JSON object with the number of delegations:

{
  "totalResults":6,
  "sizeLimitExceeded":false
}

Response Data

  • totalResults - The number of delegations.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached a size limit. The size limit is specified by the parameter "defaultCount" of the delegation search configuration.

Reading a Delegation

The operation retrieves a delegation provided the authenticated user is its delegator or substitute.

The operation can be configured in section "read" of resource type "Delegation".

Request

HTTP Method and Path

GET /Me/delegations/{delegationId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • delegationId - The delegation’s UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the user attributes to be returned in the result. If not specified, the default attributes apply. In any case, the result will also include the mandatory attributes in addition to the attributes defined here.

Response

HTTP Success Codes

  • OK (200) - The delegation is returned.

Response Content

On success, the operation returns a JSON object with the requested delegation data:

{
   "dxrassignfrom":
   {
        "displayName":"Olivier Hungs",
       "value":"00014281",
       "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
               Users/00014281"
   },
   "meta":
   {
       "created":"2018-08-27T13:15:49.690Z",
       "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Me/delegations/uid-a5d19c8--1fc413e3-1657b764518--7fea",
       "lastModified":"2018-08-28T11:15:17.701Z",
       "resourceType":"Delegation"
   },
   "dxrname":"Hungs Approve -> Pitton",
   "dxrassignto":
   {
       "displayName":"Lavina Pitton",
       "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
       "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
   },
   "description":"Hungs delegates approvals to Pitton",
   "dxrstartdate":"2019-08-01T22:00:00.000Z",
   "id":"uid-a5d19c8--1fc413e3-1657b764518--7fea",
   "dxroperationimp":"approve",
   "dxrenddate":"2020-09-01T22:00:00.000Z"
}

Creating a New Delegation

This operation creates a new delegation with the authenticated user as delegator.

Request

HTTP Method and Path

POST /Me/delegations

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • ignoreWarnings - Whether to create the new delegation even if it results in a circular delegation (true) or reject the request (false). The default is false.

Request Body

The request body is a JSON object with details of the new delegation:

  • Name (dxrName), operation (dxrOperationImp) and substitute (dxrAssignTo) are required.

  • The substitute must be a user other than the authenticated user.

  • The authenticated user will become the delegator. Any other delegator (dxrAssignFrom) found in the request data is ignored.

  • Start and end date must be in the proper order.

{
    "dxrName"        : "Hungs Approve -> Pitton",
    "description"    : "Hungs delegates approvals to Pitton",
    "dxrOperationImp": "approve",
    "dxrStartDate"   : "2019-08-01T22:00:00.000Z",
    "dxrEndDate"     : "2030-09-01T22:00:00.000Z",
    "dxrAssignTo"    : "uid-7f001-6f26d110-11da5aeefcf--7ffa"
}
Response

HTTP Success Codes

  • CREATED (201) - The assignment has been created. The new delegation is returned in the response body.

Response Content

On success, the operation returns a JSON object with the created delegation:

{
    "dxrassignfrom":
    {
        "displayName":"Olivier Hungs",
        "value":"00014281",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                Users/00014281"
    },
    "meta":
    {
        "created":"2018-08-27T13:15:49.690Z",
        "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                    Me/delegations/uid-a5d19c8--1fc413e3-1657b764518--7fea",
        "lastModified":"2018-08-28T11:15:17.701Z",
        "resourceType":"Delegation"
    },
    "dxrname":"Hungs Approve -> Pitton",
    "dxrassignto":
    {
        "displayName":"Lavina Pitton",
        "value":"uid-7f001-6f26d110-11da5aeefcf--7ffa",
        "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                    Users/uid-7f001-6f26d110-11da5aeefcf--7ffa"
    },
    "description":"Hungs delegates approvals to Pitton",
    "dxrstartdate":"2019-08-01T22:00:00.000Z",
    "id":"uid-a5d19c8--1fc413e3-1657b764518--7fea",
    "dxroperationimp":"approve",
    "dxrenddate":"2020-09-01T22:00:00.000Z"
}

Checking a Delegation to Be Created

This operation checks if a new delegation with the authenticated user as delegator will lead to a circular delegation.

Request

HTTP Method and Path

GET /Me/delegations/check

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Request Body

The request body is a JSON object with details of the new delegation.

  • Operation (dxrOperationImp) and substitute (dxrAssignTo) are required.

  • The substitute must be a user other than the authenticated user.

  • The authenticated user will become the delegator. Any other delegator (dxrAssignFrom) found in the request data is ignored.

  • Start and end date must be in the proper order.

{
    "dxrOperationImp": "approve",
    "dxrStartDate"   : "2019-08-01T22:00:00.000Z",
    "dxrEndDate"     : "2020-09-01T22:00:00.000Z",
    "dxrAssignTo"    : "uid-7f001-6f26d110-11da5aeefcf--7ffa"
}
Response

HTTP Success Codes

  • NO_CONTENT (204) - The new delegation doesn’t introduce a circular delegation.

  • CONFLICT (409) - The new delegation introduces a circular delegation.

Updating a Delegation

This operation updates a delegation which has been delegated by the authenticated user. The request path must include the ID of the delegation to be changed.

Request

HTTP Method and Path

PATCH /Me/delegations/{delegationId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support PATCH requests, you can send a POST request instead including this additional header set to PATCH.

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • delegationId - The delegation’s UID (dxruid).

Query Parameters

  • ignoreWarnings - Whether to update the delegation even if it results in a circular delegation (true), or whether to reject the request in that case (false). The default is false.

  • attributes - A comma-separated list of SCIM or LDAP attribute names. If specified, the operation returns the updated delegation data including the attributes defined here as well as the mandatory ones. If not specified, the operation will not return any data except in case of errors.

Request Body

The request body is a JSON object with the changes to be made:

  • Name (dxrName), operation (dxrOperationImp) and substitute (dxrAssignTo) can be changed but not be removed.

  • The substitute must be a user other than the authenticated user.

  • The delegator (dxrAssignFrom) must not be changed.

  • Start and end date must be in the proper order.

{
   "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
   "Operations" : [
      {
         "op"    : "replace",
         "path"  : "dxrName",
         "value" : "Hungs Approve -> Pitton Updated Grant -> Tinker"
      },
      {
         "op"    : "replace",
         "path"  : "description",
         "value" : "Hungs delegates grants to Tinker"
      },
      {
         "op"    : "replace",
         "path"  : "dxrOperationImp",
         "value" : "grant"
      },
      {
         "op"    : "replace",
         "path"  : "dxrAssignTo",
         "value" : "uid-7f001-6f26d110-11da5aeefcf--7ffb"
      },
      {
         "op"    : "replace",
         "path"  : "dxrStartDate",
         "value" : "2018-11-02T22:00:00.000Z"
      },
      {
         "op"    : "replace",
         "path"  : "dxrEndDate",
         "value" : "2018-12-02T22:00:00.000Z"
      }
   ]
}
Response

HTTP Success Codes

  • OK (200) - The delegation was updated, and the updated delegation is returned.

  • NO_CONTENT (204) - The delegation was updated but no content is returned.

Response Content

On success with the code OK (200), the operation returns a JSON object with the updated delegation. The object is formatted in the same way as when reading the delegation.

Checking a Delegation to Be Updated

This operation checks if updates to an existing delegation with the authenticated user as delegator would lead to a circular delegation.

Request

HTTP Method and Path

GET /Me/delegations/{delegationId}/check

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • delegationId - The delegation’s UID (dxruid).

Request Body

The request body is a JSON object with the prospective changes.

  • Name (dxrName), operation (dxrOperationImp) and substitute (dxrAssignTo) can be changed but not be removed.

  • The substitute must be a user other than the authenticated user.

  • The delegator (dxrAssignFrom) must not be changed.

  • Start and end date must be in the proper order.

{
   "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
   "Operations" : [
      {
         "op"    : "replace",
         "path"  : "dxrOperationImp",
         "value" : "grant"
      },
      {
         "op"    : "replace",
         "path"  : "dxrAssignTo",
         "value" : "uid-7f001-6f26d110-11da5aeefcf--7ffb"
      },
      {
         "op"    : "replace",
         "path"  : "dxrStartDate",
         "value" : "2018-11-02T22:00:00.000Z"
      },
      {
         "op"    : "replace",
         "path"  : "dxrEndDate",
         "value" : "2018-12-02T22:00:00.000Z"
      }
   ]
}
Response

HTTP Success Codes

  • NO_CONTENT (204) - The delegation updates don’t introduce a circular delegation.

  • CONFLICT (409) - The delegation updates introduce a circular delegation.

Deleting a Delegation

This operation deletes a delegation which has been delegated by the authenticated user. The request path must include the ID of the delegation to be deleted.

Request

HTTP Method and Path

DELETE /Me/delegations/{delegationId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • delegationId - The delegation’s UID (dxruid).

Response

HTTP Success Codes

  • NO_CONTENT (204) - The delegation has been deleted.

Certification Service Operations

The certification service provides operations to view and perform certification tasks for the authenticated user. A certification task for the authenticated user is a privilege assignment that the authenticated user must certify.

There are two types of certification campaigns, privilege certification and user certification campaigns:

  • Privilege Certification Campaign

    • The value of campaign attribute dxrType is "RoleToUser".

    • The subject of a certification is a privilege: role, permission, or group.

    • The resources of a certification are users.

  • User Certification Campaign

    • The value of campaign attribute dxrType is "UserToRole".

    • The subject of a certification is a user.

    • The resources of a certification are privileges: roles, permissions and / or groups.

Overview

This section provides general information about certification service operations.

List of Operations

  • GET /Me/certifications - Lists the running certification campaigns with open tasks for the authenticated user.

  • GET /Me/certifications/count - Counts the certification campaigns with open tasks for the authenticated user.

  • GET /Me/certifications/{campaignId} - Returns details of a certification campaign, including the list of subjects with open certification tasks for the authenticated user.

  • GET /Me/certifications/{campaignId}/{certificationId} - Returns details of a certification entry, including the list of privilege assignments to be certified by the authenticated user.

  • PATCH /Me/certifications/{campaignId}/{certificationId} - Updates a certification entry to be certified by the authenticated user.

Listing Certification Campaigns

This operation retrieves the running certification campaigns with open certification tasks for the authenticated user.

The operation can be configured in section "search" of resource type "RunningCertificationCampaign".

Request

HTTP Method and Path

GET /Me/certifications

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the certification campaign attributes to be returned in the result. The list may include the virtual attribute "dxrvNumberOfCertifications". If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

Response

HTTP Success Codes

  • OK (200) - The certification campaign list is returned.

Response Content

On success, the operation returns a JSON object with the list of certification campaigns:

{
  "totalResults":3,
  "schemas":
  [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources":
  [
    {
      "owner":
      {
        "displayName":"Nik Taspatch",
        "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
      },
      "meta":
      {
        "created":"2019-11-27T15:17:18.366Z",
        "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                      Me/certifications/uid-c0a82a1--7bf0ab25-16ead58d54a--7ff4",
        "lastModified":"2019-11-27T15:43:38.862Z",
        "resourceType":"RunningCertificationCampaign"
      },
      "dxrstate":"RUNNING",
      "description":"Certification of Corporate Roles",
      "dxrtype":"RoleToUser",
      "dxrexpirationdate":"2020-11-26T23:00:00.000Z",
      "cn":"Corporate Roles",
      "dxrstartdate":"2019-11-26T23:00:00.000Z",
      "id":"uid-c0a82a1--7bf0ab25-16ead58d54a--7ff4",
      "dxrvnumberofcertifications":16,
      "$displayname":"Corporate Roles"
    },
    (OTHER CAMPAIGNS ELIMINATED)…
  ]
}

Response Data

  • totalResults - The number of certification campaigns returned.

  • Resources - The list of certification campaigns. For each certification campaign, the virtual attribute "dxrvNumberOfCertifications" returns the number of subjects with open tasks for the authenticated user.

Counting Certification Campaigns

This operation counts the certification campaigns with open tasks for the authenticated user.

Request

HTTP Method and Path

GET /Me/certifications/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Response

HTTP Success Codes

  • OK (200) - The number of certification campaigns is returned.

Response Content

On success, the operation returns a JSON object with number of certification campaigns:

{
  "totalResults":3,
  "sizeLimitExceeded":false
}

Response Data

  • totalResults - The number of certification campaigns.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached a size limit. The value is always false since the operation doesn’t specify a size limit.

Reading a Certification Campaign

This operation returns details of a certification campaign with open tasks for the authenticated user. The result includes the list of subjects with open certification tasks.

The operation can be configured in section "read" of resource type "RunningCertificationCampaign".

Request

HTTP Method and Path

GET /Me/certifications/{campaignId}

Path Parameters

  • campaignId - The certification campaign’s UID (dxruid). If the UID is not assigned to a certification campaign with open tasks for the authenticated user, the operation fails.

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • campaignAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the certification campaign attributes to be returned in the result. The virtual attribute “dxrvNumberOfCertifications” is not supported. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • certificationAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the certification attributes to be returned in the result. The list may include the virtual attribute "dxrvProgress". If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • subjectAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the subject attributes to be returned in the result. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

Response

HTTP Success Codes

  • OK (200) - The certification campaign details are returned.

Response Content

On success, the operation returns a JSON object with the requested certification campaign data. For details, see the description of proprietary extension "Certification Campaign" in section “Objects and Attributes”.

{
  "owner":
  {
    "displayName":"Nik Taspatch",
    "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
    "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/Users/
                   uid-7f001-6f26d110-11da5aeefcf--7ff9"
  },
  "meta":
  {
    "created":"2019-11-27T15:17:18.366Z",
    "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                Me/certifications/uid-c0a82a1--7bf0ab25-16ead58d54a--7ff4",
    "lastModified":"2019-11-27T15:43:38.862Z",
    "resourceType":"RunningCertificationCampaign"
  },
  "dxrstate":"RUNNING",
  "description":"Certification of Corporate Roles",
  "dxrtype":"RoleToUser",
  "dxrexpirationdate":"2020-11-26T23:00:00.000Z",
  "dxrstartdate":"2019-11-26T23:00:00.000Z",
  "id":"uid-c0a82a1--7bf0ab25-16ead58d54a--7ff4",
  "cn":"Corporate Roles",
  "certifications":
  {
    "roles":
    [
      {
        "meta":
        {
          "created":"2019-11-27T15:43:38.635Z",
          "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                      Me/certifications/uid-c0a82a1--7bf0ab25-16ead58d54a--7ff4/
                      uid-c0a82a1-77a24059-16ead87932b--7fcc",
          "resourceType":"CertificationEntryRole"
        },
        "subject":
        {
          "meta":
          {
            "created":"2019-11-27T10:07:59.971Z",
            "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78cd",
            "resourceType":"Role"
          },
          "description":"DirX Identity delegation administration",
          "dn":"cn=DXR Delegation Administrator,cn=Administration,
                cn=Corporate Roles,cn=RoleCatalogue,cn=My-Company",
          "id":"uid-7f001-6f26d110-11da5aeefcf--78cd",
          "$displayname":"DXR Delegation Administrator",
          "$parentfolder":"cn=Administration,cn=Corporate Roles,
                           cn=RoleCatalogue,cn=My-Company"
        },
        "dxrvprogress":
        {
          "total":1,
          "completed":0
        },
        "id":"uid-c0a82a1-77a24059-16ead87932b--7fcc",
        "cn":"DXR Delegation Administrator",
        "$displayname":"DXR Delegation Administrator",
        "$parentfolder":"cn=Privilege Certification,cn=Corporate Roles,
                         cn=Certification Campaigns,cn=My-Company"
      },
      {
        "meta":
        {
          "created":"2019-11-27T15:43:38.616Z",
          "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                      Me/certifications/uid-c0a82a1--7bf0ab25-16ead58d54a--7ff4/
                      uid-c0a82a1-77a24059-16ead87932b--7fcf",
          "resourceType":"CertificationEntryRole"
        },
        "subject":
        {
          "meta":
          {
            "created":"2019-11-27T10:08:00.097Z",
            "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78c0",
            "resourceType":"Role"
          },
          "description":"Windows administration",
          "dn":"cn=Windows Administrator,cn=Administration,cn=Corporate Roles,
                cn=RoleCatalogue,cn=My-Company",
          "id":"uid-7f001-6f26d110-11da5aeefcf--78c0",
          "$displayname":"Windows Administrator",
          "$parentfolder":"cn=Administration,cn=Corporate Roles,
                           cn=RoleCatalogue,cn=My-Company"
        },
        "dxrvprogress":
        {
          "total":2,
          "completed":0
        },
        "id":"uid-c0a82a1-77a24059-16ead87932b--7fcf",
        "cn":"Windows Administrator",
        "$displayname":"Windows Administrator",
        "$parentfolder":"cn=Privilege Certification,cn=Corporate Roles,
                         cn=Certification Campaigns,cn=My-Company"
      },
      (OTHER PRIVILEGES ELIMINATED)…
    ]
  }
}

Reading a Certification Entry

This operation returns details of a certification entry. The result includes the list of privilege assignments to be certified by the authenticated user, as well as the changes to the assignments requested so far in the course of the campaign.

The operation can be configured in section "read" of the resource type matching the certification entry (one of "CertificationEntryUser", "CertificationEntryRole", "CertificationEntryPermission", and "CertificationEntryGroup").

Request

HTTP Method and Path

GET /Me/certifications/{campaignId}/{certificationId}

Path Parameters

  • campaignId - The certification campaign’s UID (dxruid). If the UID is not assigned to a certification campaign with open tasks for the authenticated user, the operation fails.

  • certificationId - The certification entry’s UID (dxruid). If the UID is not assigned to a certification entry belonging to the specified campaign, the operation fails.

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • campaignAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the certification campaign attributes to be returned in the result. The virtual attribute “dxrvNumberOfCertifications” is not supported. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • certificationAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the certification attributes to be returned in the result. The list may include the virtual attribute "dxrvProgress". If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • subjectAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the subject attributes to be returned in the result. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • resourceAttributes - A comma-separated list of SCIM or LDAP attribute names that specify the resource attributes to be returned in the result. If left unspecified, the list of default attributes is returned. In any case, the result also includes the mandatory attributes.

  • includeManualAssignments - Whether to include the manually assigned privileges (true) or not (false). Default is true.

  • includeNonManualAssignments - Whether to include the non-manually assigned privileges (true) or not (false). Default is false.

Response

HTTP Success Codes

  • OK (200) - The certification entry details are returned.

Response Content

On success, the operation returns a JSON object with the requested certification entry data. For details, see the description of proprietary extension "Certification Entry" in section “Objects and Attributes”.

{
  "meta":
  {
    "created":"2020-01-21T12:18:43.322Z",
    "location":"http://localhost:8080/DirXIdentityRestService-My-Company
                /Me/certifications/uid-c0a82a1-5c4abaa9-16fc7c7eca5--7f72/
                uid-c0a82a1-742b6634-16fc7920e26--7fa5",
    "lastModified":"2020-01-21T12:29:42.107Z",
    "resourceType":"CertificationEntryUser"
  },
  "id":"uid-c0a82a1-742b6634-16fc7920e26--7fa5",
  "cn":"Abele Marc",
  "$displayname":"Abele Marc",
  "$parentfolder":"cn=User Certification,cn=All privileges of Abele,
                   cn=Certification Campaigns,cn=My-Company",
  "subject":
  {…
  },
  "campaign":
  {…
  },
  "assignments":
  {
    "permissions": [...],
    "groups": [...],
    "roles":
    [
      {
        "resource":
        {
          "owner":
          [
            {
              "displayName":"Christopher Dalmar",
              "value":"10052505",
              "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company
                      /Users/10052505"
            }
          ],
          "meta":
          {
            "created":"2019-11-27T10:08:00.203Z",
            "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        DomainObjects/uid-7f001-6f26d110-11da5aeefcf--78b5",
            "resourceType":"Role"
          },
          "description":"Standard role for all contractors",
          "dn":"cn=Contractor,cn=General,cn=Corporate Roles,
                cn=RoleCatalogue,cn=My-Company",
          "id":"uid-7f001-6f26d110-11da5aeefcf--78b5",
          "$displayname":"Contractor",
          "$parentfolder":"cn=General,cn=Corporate Roles,
                           cn=RoleCatalogue,cn=My-Company"
        },
        "assignment":
        {
          "mode":"manual",
          "uid":"uid-c0a82a1-6d2f5fcb-16f8fc11151--7fb0",
          "hasSODViolations":false,
          "displayState":"FUTURE",
          "isEditable":true,
          "dxrEndDate":"2021-01-09T23:00:00.000Z",
          "state":"FUTURE",
          "type":"direct",
          "dxrNeedsReapproval":false,
          "dxrStartDate":"2020-02-09T23:00:00.000Z"
        },
        "assignmentChanges":
        {
          "dxrEndDate":"2020-12-31T23:00:00.000Z",
          "dxrStartDate":"2020-02-15T23:00:00.000Z"
        },
        "certificationResult":
        {
          "state":"accepted"
        },
        "id":"uid-c0a82a1-6d2f5fcb-16f8fc11151--7fb0"
      },
      ...
    ]
  },
  "automaticAssignments":
  {
    "permissions": [...],
    "groups": [...],
    "roles": [...]
  }
}

Updating a Certification Entry

This operation returns details of a certification entry. The result includes the list of privilege assignments to be certified by the authenticated user, as well as the changes to the assignments requested so far in the course of the campaign.

The operation can be configured in section "read" of the resource type matching the certification entry (one of "CertificationEntryUser", "CertificationEntryRole", "CertificationEntryPermission", and "CertificationEntryGroup").

Request

HTTP Method and Path

PATCH /Me/certifications/{campaignId}/{certificationId}

Path Parameters

  • campaignId - The certification campaign’s UID (dxruid). If the UID is not assigned to a certification campaign with open tasks for the authenticated user, the operation fails.

  • certificationId - The certification entry’s UID (dxruid). If the UID is not assigned to a certification entry belonging to the specified campaign, the operation fails.

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support PATCH requests, you can send a POST request instead including this additional header set to PATCH.

  • Accept - The header is optional but is recommended to be set to application/json.

Request Body

The request body is a JSON object with the new state of each assignment to be changed:

{
  "close": false,
  "assignments": [
    {
      "id": "uid-c0a82a1-6d2f5fcb-16f8fc11151--7fb0",
      "certificationResult": {
        "reason": "Role parameter value High performance deleted",
        "state": "approved"
      },
      "assignmentChanges": {
        "dxrEndDate":"2021-01-30T23:00:00.000Z",
        "deletedRoleParameters": [
          {
            "uid":"uid-7f001--6c1b645f-112e5d0d91a--7ffc",
            "values": [
              {
                "display":"High performance",
                "value":"cn=High performance,cn=Projects,
                         cn=BusinessObjects,cn=My-Company"
              }
            ],
            "name":"Project",
            "type":"DN"
           }
        ]
      }
    }
  ],
  "automaticAssignments": [
    {
      "id": "uid-c0a82a1-6d2f5fcb-16f8fc11151--7fb2",
      "certificationResult": {
        "reason": "role accepted",
        "state": "approved"
    }
  ]
}

  • close - Whether to close the certification after the assignment updates (true), or whether to leave it open (false). Closing the certification will work only if a decision (”approved” or ”rejected”) has been taken on each assignment.

  • assignments - The list of manual assignments to be updated. For each assignment:

    • id - The assignment ID, as obtained from a request to read the certification entry.

    • certificationResult - The result of the certification:

      • state - The decision taken on this assignment. Either ”approved”, ”rejected”, or ”undecided”. Default: ”undecided”.

      • reason - The optional reason for the decision.

      • notifyRejected - Whether to notify the certified user when the assignment is deleted.

  • assignmentChanges - The assignment attributes:

    • dxrStartDate - The assignment start date; if left unspecified, any existing start date will be removed.

    • dxrEndDate - The assignment end date; if left unspecified, any existing end date will be removed.

    • deletedRoleParameters - For assignments of parameterized roles, the role parameter values to be deleted. If left unspecified, no parameter values will be deleted:

      • uid - The role parameter UID.

      • values - The role parameter values to be deleted.

      • name - The role parameter name; optional.

      • type - The role parameter type; optional.

  • automaticAssignments - The list of non-manual assignments to be updated. For each assignment:

    • id - The assignment ID, as obtained from a request to read the certification entry.

    • certificationResult - The result of the certification:

    • state - The decision taken on this assignment. Either “rejected” or ”undecided”. Default: ”undecided”.

    • reason - The optional reason for the decision.

Assignments to be certified but not included in the list will be left unchanged.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The certification entry has been updated.

Workflow Service Operations

The worklfow service provides management operations to cancel a workflow or to change the participants of a workflow activity, and operations to create objects via workflows.

Overview

This section provides information about workflow service operations.

List of Operations

  • Workflow Management

    • GET /Workflows - List worfklow instances.

    • GET /Workflows/{workflowId} - Reads the workflow with the given ID.

    • DELETE /Workflows/{workflowId} - Cancels the workflow with the given ID.

    • PATCH /Workflows/{workflowId} - Changes current participants of the workflow with the given ID.

  • Workflow Definitions

    • GET /Workflows/definitions - Lists the active workflow definitions for a specific subject type and operation.

  • Create Workflows

    • POST /Workflows - Creates a workflow instance for a given workflow definition.

    • GET /Workflows/{workflowId}/task - Returns the next open workflow task for the authenticated user.

    • GET /Workflows/{workflowId}/assignableRoles
      GET /Workflows/{workflowId}/assignablePermissions
      GET /Workflows/{workflowId}/assignableGroups
      GET /Workflows/{workflowId}/assignablePrivileges       - Lists the privileges that can be assigned to the workflow subject as part of a request assignment task.

    • POST /Workflows/{workflowId}/{taskId} - Updates an open workflow task for the authenticated user.

Listing Workflows

The operation list workflow instances matching some search criteria.

The operation can be configured in section "search" or resource type “WorkflowInstance”.

The size limit is defined by

  • Request parameter "count".

  • Parameter "defaultCount" of resource type section "search".

  • Configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Parameter "maxCount" of resource type section "search".

  • Configuration parameter "search.maxCount".

in descending priority.

Request

HTTP Method and Path

GET /Workflows

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • includeProfileChanges - Whether (true) or not (false) to include workflows for profile changes. The default is true.

  • includePrivilegeAssignmentChanges - Whether (true) or not (false) to include workflows for privilege assignment changes. The default is true.

  • initiatorId - The optional DN or UID of the workflow initiator.

  • subjectId - The optional DN or UID of the workflow subject.

  • subjectTypes - The optional comma-separated list of workflow subject types, like "dxrUser". Supports wildcards (*).

  • states - The optional comma-separated list of workflow states, like "running” and “succeeded”. Supports wildcards (*).

  • maxAge - The maximum number of days elapsed since the workflow has been created. 0 for no maximum.

  • filter - An optional SCIM filter for the workflows.

  • sortBy - A comma-separated list of attributes used to order the search result.

  • sortOrder - The sort order per sort attribute, separated by commas. Allowed values are "ascending" and "descending". Default value is "ascending".

  • count - The maximum number of entries to return.

HTTP Success Codes

  • OK (200) - The workflow list is returned.

Response Content

On success, the operation returns a JSON object with the workflow list. The basic structure is:

{
  "profileChanges": {
    ...
  },
  "permissions": {
    ...
  },
  "roles": {
    ...
  },
  "groups": {
    ...
  },
}

A specific examle is:

{
  "profileChanges": {
    "startIndex": 1,
    "totalResults": 1,
    "itemsPerPage": 1,
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
      {
        "subject": {
          "displayName": "Boris Tinker",
          "value": "uid-7f001-6f26d110-11da5aeefcf--7ffb",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ffb"
        },
        "display": "Tinker Boris",
        "initiator": {
          "displayName": "Christopher Dalmar",
          "value": "10052505",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/10052505"
        },
        "dueDate": "2021-12-30T23:00:00.000Z",
        "currentParticipants": [
          {
            "displayName": "Hans Berner",
            "value": "uid-7f001-6f26d110-11da5aeefcf--7ff7",
            "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                     Users/uid-7f001-6f26d110-11da5aeefcf--7ff7"
          },
          {
            "displayName": "Aurilia Poole",
            "value": "uid-7f001-6f26d110-11da5aeefcf--7ff5",
            "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                     Users/uid-7f001-6f26d110-11da5aeefcf--7ff5"
        ],
        "description": "Modification of location and organizational unit
                        attributes of a user.",
        "source": "workflow",
        "mode": "manual",
        "nextApprovalDate": "2022-04-30T08:06:15.000Z",
        "state": "RUNNING",
        "value": "17c736795ff$-7c6b",
        "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                 Workflows/17c736795ff%24-7c6b",
        "startDate": "2021-10-12T08:06:14.000Z",
        "expirationDate": "2022-11-16T08:06:14.000Z",
        "modifications": [
          {
            "path": "dxrlocationlink",
            "oldValue": {
              "displayName": "My-Company Munich",
              "value": "uid-7f001-6f26d110-11da5aeefcf--796a",
              "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                       DomainObjects/uid-7f001-6f26d110-11da5aeefcf--796a"
            },
            "newValue": {
              "displayName": "My-Company Barcelona",
              "value": "uid-7f001-6f26d110-11da5aeefcf--7967",
              "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                       DomainObjects/uid-7f001-6f26d110-11da5aeefcf--7967"
            }
          }
        ]
      }
    ]
  },
  "permissions": {
    "startIndex": 1,
    "totalResults": 0,
    "itemsPerPage": 0,
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
    ],
  },
  "roles": {
    "startIndex": 1,
    "totalResults": 1,
    "itemsPerPage": 1,
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
      {
        "requestReason": "Need the role for baretti and bellanger",
        "subject": {
          "displayName": "Lionel Bellanger",
          "value": "00006981",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/00006981"
        },
        "assignment": {
          "mode": "manual",
          "hasSODViolations": false,
          "isEditable": false,
          "operation": "ADD"
        },
        "display": "Corporate Credit Card",
        "initiator": {
          "displayName": "Nik Taspatch",
          "value": "uid-7f001-6f26d110-11da5aeefcf--7ff9",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
        },
        "currentParticipants": [
          {
            "displayName": "Olivier Hungs",
            "value": "00014281",
            "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                     Users/00014281"
          },
          {
            "displayName": "Ruben Briner",
            "value": "uid-7f001-6f26d110-11da5aeefcf--7fe2",
            "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                     Users/uid-7f001-6f26d110-11da5aeefcf--7fe2"
          },
          {
            "displayName": "Christopher Dalmar",
            "value": "10052505",
            "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                     Users/10052505"
          }
        ],
        "description": "Approval of a privilege assignment in parallel by
                        - Manager of the user - Owner of the privilege",
        "source": "workflow",
        "nextApprovalDate": "2021-11-23T12:35:01.000Z",
        "state": "RUNNING",
        "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                 Workflows/17d4789143e%24-7b87",
        "value": "17d4789143e$-7b87",
        "startDate": "2021-11-22T12:35:01.000Z",
        "expirationDate": "2021-11-26T12:35:01.000Z",
        "resourceType": "Role"
      }
    ]
  },
  "groups": {
    "startIndex": 1,
    "totalResults": 0,
    "itemsPerPage": 0,
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
    ],
  }
}

Reading a Workflow

The operation reads a workflow with its activities.

Request

HTTP Method and Path

GET /Workflows/{workflowId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow and activity attributes.

Path Parameters

  • workflowId - The workflow UID (dxruid).

Query Parameters

  • peopleTasksOnly - Whether to return only tasks with operation type "people" (true), or tasks with any operation type (false). Default: true.

  • finishedTasksOnly - Whether to return only tasks that have a state other than "RUNNING" (true), or tasks in any state (false). Default: true.

  • masteredTasksOnly - Whether to return only tasks that have a master task (a non-empty attribute "dxmSpecifiAttributes(master)") (true), or tasks with and without master (false). Default: true.

Response

HTTP Success Codes

  • OK (200) - The entry is returned.

Response Content

On success, the operation returns a JSON object that lists the entry’s properties:

{
  "requestReason": "Need the role for baretti and bellanger",
  "subject": {
    "displayName": "Lionel Bellanger",
    "value": "00006981",
    "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/00006981"
  },
  "assignment": {
    "mode": "manual",
    "hasSODViolations": false,
    "isEditable": false,
    "operation": "ADD"
  },
  "display": "Corporate Credit Card",
  "initiator": {
    "displayName": "Nik Taspatch",
    "value": "uid-7f001-6f26d110-11da5aeefcf--7ff9",
    "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
  },
  "currentParticipants": [
    {
      "displayName": "Olivier Hungs",
      "value": "00014281",
      "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
               Users/00014281"
    },
    {
      "displayName": "Ruben Briner",
      "value": "uid-7f001-6f26d110-11da5aeefcf--7fe2",
      "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
               Users/uid-7f001-6f26d110-11da5aeefcf--7fe2"
    },
    {
      "displayName": "Christopher Dalmar",
      "value": "10052505",
      "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
               Users/10052505"
    }
  ],
  "description": "Approval of a privilege assignment in parallel by -
                  Manager of the user - Owner of the privilege",
  "source": "workflow",
  "nextApprovalDate": "2021-11-23T12:35:01.000Z",
  "activities": [
    {
      "contentReadOnly": false,
      "displayName": "Approval by Privilege Managers-0",
      "retryCount": 0,
      "description": "Please approve the following privilege request.",
      "dn": "cn=Approval by Privilege Managers-0,cn=17d4789143e$-7b87,
             cn=2021-11-22,cn=4-Eye Approval,
             cn=Approval,cn=My-Company,cn=Monitor,cn=wfRoot,cn=My-Company",
      "title": "Approval by Privilege Managers",
      "type": "people",
      "escalationLevel": 0,
      "retryLimit": 2,
      "master": "Approval by Privilege Managers",
      "dueDateEnabled": false,
      "meta": {
        "created": "2021-11-22T12:35:01.796Z",
        "location": "http://localhost:8080/DirXIdentityRestService-My-Company/
                     DomainObjects/uid-a5dcb1--6d7f8427-17d4788fb59--7f00",
        "resourceType": "ActivityInstance"
      },
      "subType": "approveAssignment",
      "id": "uid-a5dcb1--6d7f8427-17d4788fb59--7f00",
      "state": "RUNNING",
      "startDate": "2021-11-22T12:35:01.000Z",
      "expirationDate": "2021-11-23T12:35:01.000Z",
      "participants": [
        {
          "displayName": "Ruben Briner",
          "value": "uid-7f001-6f26d110-11da5aeefcf--7fe2",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7fe2"
        }
      ]
    },
    {
      "contentReadOnly": false,
      "displayName": "Approval by User Manager-0",
      "retryCount": 0,
      "description": "Please approve the following privilege request.",
      "dn": "cn=Approval by User Manager-0,cn=17d4789143e$-7b87,
             cn=2021-11-22,cn=4-Eye Approval,
             cn=Approval,cn=My-Company,cn=Monitor,cn=wfRoot,cn=My-Company",
      "title": "Approval by User Manager",
      "type": "people",
      "escalationLevel": 0,
      "retryLimit": 2,
      "master": "Approval by User Manager",
      "dueDateEnabled": false,
      "meta": {
        "created": "2021-11-22T12:35:01.822Z",
        "location": "http://localhost:8080/DirXIdentityRestService-My-Company/
                     DomainObjects/uid-a5dcb1--6d7f8427-17d4788fb59--7eff",
        "resourceType": "ActivityInstance"
      },
      "subType": "approveAssignment",
      "id": "uid-a5dcb1--6d7f8427-17d4788fb59--7eff",
      "state": "RUNNING",
      "startDate": "2021-11-22T12:35:01.000Z",
      "expirationDate": "2021-11-23T12:35:01.000Z",
      "participants": [
        {
          "displayName": "Olivier Hungs",
          "value": "00014281",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/00014281"
        },
        {
          "displayName": "Christopher Dalmar",
          "value": "10052505",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/10052505"
        }
      ]
    }
  ],
  "state": "RUNNING",
  "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
           Workflows/17d4789143e%24-7b87",
  "value": "17d4789143e$-7b87",
  "startDate": "2021-11-22T12:35:01.000Z",
  "expirationDate": "2021-11-26T12:35:01.000Z",
  "resourceType": "Role"
}

Canceling a Workflow

This operation cancels a workflow given by its workflow ID.

Request

HTTP Method and Path

DELETE /Workflows/{workflowId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • workflowId - The workflow UID (dxruid).

Response

HTTP Success Codes

  • NO_CONTENT (204) - The workflow has been canceled.

Changing a Workflow Participant

This operation replaces one or more current participants of a workflow with other ones. The participants are replaced in each running activity.

Request

HTTP Method and Path

PATCH /Workflows/{workflowId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support PATCH requests, you can send a POST request instead including this additional header set to PATCH.

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • workflowId - The workflow UID (dxruid).

Request Body

The request body is a JSON object that specifies a list of participant replacements. Each replacement consists of a pair of an add and a remove operation, or a single replace operation.

{
 "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
 "Operations": [
   {
     "op"   : "add",
     "path" : "participants",
     "value": [
       "cn=Pitton Lavina,ou=Global IT,o=My-Company,cn=Users,cn=My-Company"
     ]
   },
   {
     "op"   : "remove",
     "path" : "participants",
     "value": [
       "cn=Dalmar Christopher,ou=Finances,o=My-Company,cn=Users,cn=My-Company"
     ]
   },
   {
     "op"   : "add",
     "path" : "participants",
     "value": [
       "cn=Poole Aurilia,ou=Human Resources,o=My-Company,cn=Users,cn=My-Compan"
     ]
   },
   {
     "op"   : "remove",
     "path" : "participants",
     "value": [
       "cn=Wagner Retha,ou=Global IT,o=My-Company,cn=Users,cn=My-Company"
     ]
   }
 ]
}

A shorter equivalent notation is

{
 "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
 "Operations": [
   {
     "op"   : "replace",
     "path" : "participants[value eq \"cn=Wagner Retha,ou=Global IT,
                            o=My-Company,cn=Users,cn=My-Company\"]",
     "value": [
       "cn=Poole Aurilia,ou=Human Resources,o=My-Company,cn=Users,cn=My-Company"
     ]
   },
   {
     "op"   : "replace",
     "path" : "participants[value eq \"cn= Dalmar Christopher,ou=Finances,
                            o=My-Company,cn=Users,cn=My-Company\"]",
     "value": [
       "cn=Pitton Lavina,ou=Global IT,o=My-Company,cn=Users,cn=My-Company"
     ]
   }
 ]
}
Response

HTTP Success Codes

  • NO_CONTENT (204) - The participants have been changed.

Updating Participants in an Workflow Activity

This operation adds/removes one or more participants of a workflow activity

Request

HTTP Method and Path

PATCH /Workflows/{workflowId}/activities/{activityId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • X-HTTP-Method-Override - If your client doesn’t support PATCH requests, you can send a POST request instead including this additional header set to PATCH.

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • workflowId - The workflow UID (dxrUID).

  • activityId – The activity UID (dxrUID).

Request Body

The request body is a JSON object that specifies a list of participant replacements. Each replacement consists of a pair of an add and a remove operation, or a single replace operation.

{
    "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op"   : "add",
            "path" : "participants",
            "value": [
                "cn=Pitton Lavina,ou=Global IT,o=My-Company,cn=Users,cn=My-Company"
            ]
        },
        {
            "op"   : "remove",
            "path" : "participants",
            "value": [
                "cn=Dalmar Christopher,ou=Finances,o=My-Company,cn=Users,cn=My-Company"
            ]
        },
        {
            "op"   : "add",
            "path" : "participants",
            "value": [
                "cn=Poole Aurilia,ou=Human Resources,o=My-Company,cn=Users,cn=My-Company"
            ]
        },
        {
            "op"   : "remove",
            "path" : "participants",
            "value": [
                "cn=Wagner Retha,ou=Global IT,o=My-Company,cn=Users,cn=My-Company"
            ]
        }
    ]
}
Response

HTTP Success Codes

  • NO_CONTENT (204) - The participants have been changed.

Listing Workflow Definitions

This operation lists the workflow definitions for a specific subject type and operation.

You can exclude specific definitons from a list via configuration parameter workflows.listDefinitions.filter.exclude in file domain.properties.

Usually, one wants to separate regular create user workflows from self-registration workflows. Therefore, self-registration workflows are excluded from the create user workflow definition list via the above exclude filter. To request the list of self-registration workflow definitions, set the operation to "selfRegistration" instead of "create". The list will then include the definitions filtered by parameter workflows.listDefinitions.filter.selfRegistration in file domain.properties.

Request

HTTP Method and Path

GET /Workflows/definitions

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow definition attributes.

Query Parameters

  • subjectType - The workflow definition subject type. Default: "dxrUser".

  • operation - The workflow definition operation, or "selfRegistration". Default: "create".

  • executablesOnly - If operation is one of "create" and "selfRegistration": return only definitions which the authenticated user is allowed to start workflow instances for; default: true. Definitions for other operations are always returned whether executable or not.

  • filter - An optional SCIM filter to restrict the search result.

Response

HTTP Success Codes

  • OK (200) - The workflow definition list is returned.

Response Content

On success, the operation returns a JSON object with the workflow definition list:

{
  "startIndex":1,
  "totalResults":2,
  "itemsPerPage":2,
  "schemas":
  [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources":
  [
    {
      "displayName":"Create User With Approval",
      "description":"Create a user stepwise including approval",
      "id":"uid-c0a8e480--4b5b380c-121222f6f42--7fed",
      "priority":50
    },
    {
      "displayName":"Create User Without Approval",
      "description":"Create a user stepwise without approval",
      "id":"uid-c0a8e480--4debacf0-12273e6ff48--7fff",
      "priority":50
    },
  ]
}

Creating Workflow Instances

This operation creates a workflow instance for a given workflow definition.

Request

HTTP Method and Path

POST /Workflows

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Request Body

The request body is a JSON object that specifies the workflow definition ID and some optional workflow context attributes.

The first example shows the request body for a "Create User With Approval" workflow:

{
  "workflowDefinitionId":"uid-c0a8e480--4b5b380c-121222f6f42--7fed"
}

The next example shows the request body for a "Create Persona With Approval" workflow:

{
  "workflowDefinitionId":"uid-c0a8c84--4bca3938-13a44fb1989--7fff",
  "workflowContext": {
    "associatedEntry":"uid-7f001-6f26d110-11da5aeefcf--7fdd",
    "destinationType":"dxrPersona"
  }
}

The destination type is not required here since it can be obtained from the workflow definition:

{
  "workflowDefinitionId":"uid-c0a8c84--4bca3938-13a44fb1989--7fff",
  "workflowContext": {
    "associatedEntry":"uid-7f001-6f26d110-11da5aeefcf--7fdd"
  }
}

  • workflowDefinitionId - The workflow definition UID (dxruid) is required.

  • workflowContext - Workflow context attributes to be stored in workflow property "dxmSpecificAttributes" with name "ctx.lowerCase_attributeName". For example

    • associatedEntry - The UID of the associated entry, for example of the owner of a new persona or user facet, or the sponsor of a new functional user. Required for the relevant create workflows.

    • destinationType - The destination type of the new object. Is by default set to the value of the workflow definition property "dxrObjectType".

    • correlationId - The workflow correlation id. A correlation id will be generated if left unspecified.

    • requestReason - The optional reason for starting the workflow.

Response

HTTP Success Codes

  • OK (200) - The UID of the created workflow is returned.

Response Content

On success, the operation returns the UID of the created workflow:

{
  "workflowId":"178cf4bc351$-725e"
}

Reading the Next Open Task

This operation returns the next open workflow task for the authenticated user.

The maximum number ot attempts to read the next open task can be configured via parameter workflows.getNextTask.maxNumAttempts in file domain.properties.

The number of seconds to wait between two subsequent attempts can be configured via parameter workflows.getNextTask.secondsBetweenAttempts in file domain.properties.

Request

HTTP Method and Path

GET /Workflows/{workflowId}/task

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow attributes.

Path Parameters

  • workflowId - The workflow UID (dxruid).

Response

HTTP Success Codes

  • OK (200) - The next task is returned.

  • NO_CONTENT (204) - There’s no next task, or timeout reached.

Response Content

On success, the operation returns a JSON object with details of the next task. Note that some parts like labels and descriptions are localized whenever possible. The example shows a task to enter attributes for a create persona workflow:

{
  "activity":
  {
    "contentReadOnly":false,
    "configuration":
    {
      "attributes":
      [
        {
          "path":"title",
          "multivalued":false,
          "label":"Title",
          "type":"string",
          "mandatory":false
        },
        {
          "path":"sn",
          "multivalued":false,
          "label":"Last name",
          "type":"string",
          "mandatory":true
        },
        {
          "path":"givenname",
          "multivalued":false,
          "label":"First name",
          "type":"string",
          "mandatory":true
        },
        {
          "path":"description",
          "default":"Add description here!",
          "multivalued":false,
          "label":"Description",
          "type":"string",
          "mandatory":false
        },
        {
          "path":"dxrstartdate",
          "multivalued":false,
          "label":"Start Date",
          "type":"date",
          "mandatory":false
        },
        {
          "path":"dxrenddate",
          "multivalued":false,
          "label":"End Date",
          "type":"date",
          "mandatory":false
        },
        {
          "path":"employeetype",
          "multivalued":false,
          "options":
          [
            {
              "value":"Contractor"
            },
            {
              "value":"Customer"
            },
            {
              "value":"Internal"
            },
            {
              "value":"Supplier"
            }
          ],
          "label":"Employee Type",
          "type":"string",
          "mandatory":true
        },
        {
          "path":"employeenumber",
          "multivalued":false,
          "label":"Employee Number",
          "type":"string",
          "mandatory":true
        },
        {
          "proposalSearchAction":"dxrlocationlinks_for_persona",
          "path":"dxrlocationlink",
          "multivalued":false,
          "label":"Locality",
          "type":"link",
          "mandatory":false,
          "resourceType":"Location"
        },
        {
          "proposalSearchAction":"owners_for_persona",
          "path":"owner",
          "multivalued":false,
          "label":"rqwfs/gen/attribute descriptions/en/owner",
          "type":"link",
          "mandatory":true,
          "resourceType":"User"
        },
        {
          "proposalSearchAction":"managers_for_persona",
          "path":"manager",
          "multivalued":false,
          "label":"Manager",
          "type":"link",
          "mandatory":true,
          "resourceType":"User"
        },
        {
          "proposalSearchAction":"dxrorganizationlinks_for_persona",
          "path":"dxrorganizationlink",
          "multivalued":false,
          "label":"Organisational Unit",
          "type":"link",
          "mandatory":false,
          "resourceType":"Organization"
        },
        {
          "proposalSearchAction":"dxroulinks_for_persona",
          "path":"dxroulink",
          "multivalued":false,
          "label":"Organisational Unit",
          "type":"link",
          "mandatory":false,
          "resourceType":"OrganizationalUnit"
        },
        {
          "path":"telephonenumber",
          "multivalued":false,
          "label":"Phone",
          "type":"string",
          "mandatory":false
        },
        {
          "path":"mobile",
          "multivalued":false,
          "label":"Mobile",
          "type":"string",
          "mandatory":false
        },
        {
          "path":"mail",
          "multivalued":true,
          "label":"Mail",
          "type":"string",
          "mandatory":true
        }
      ],
      "parents":
      [
        {
          "displayName":"Users",
          "dn":"cn=Users,cn=My-Company",
          "value":"metacpeb82d8-5dde4ae2-318f8-310c-ba5ca-17d",
          "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                  DomainObjects/metacpeb82d8-5dde4ae2-318f8-310c-ba5ca-17d"
        }
      ]
    },
    "displayName":"Enter Attributes-0",
    "retryCount":0,
    "description":"Enter the required and optional attributes below.",
    "dn":"cn=Enter Attributes-0,cn=178cf4bc351$-6d3b,cn=2021-04-14,
          cn=Create Persona With Approval,cn=Personas,cn=My-Company,
          cn=Monitor,cn=wfRoot,cn=My-Company",
    "title":"Enter Attributes",
    "type":"people",
    "escalationLevel":0,
    "retryLimit":0,
    "master":"Enter Attributes",
    "dueDateEnabled":false,
    "meta":
    {
      "created":"2021-04-14T11:56:20.977Z",
      "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                  DomainObjects/uid-a5dcb1--5aae8595-178cf4b9490--7e2e",
      "lastModified":"2021-04-14T11:56:21.118Z",
      "resourceType":"ActivityInstance"
    },
    "subType":"enterAttributes",
    "id":"uid-a5dcb1--5aae8595-178cf4b9490--7e2e",
    "state":"RUNNING",
    "startDate":"2021-04-14T11:56:20.000Z",
    "expirationDate":"2021-04-14T12:56:21.000Z",
    "participants":
    [
      {
        "displayName":"Nik Taspatch",
        "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
        "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
      }
    ]
  },
  "displayName":"Majd Base Psn",
  "subject":
  {
    "owner":
    {
      "displayName":"Base Majd",
      "value":"uid-7f001-6f26d110-11da5aeefcf--7fdc",
      "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
              Users/uid-7f001-6f26d110-11da5aeefcf--7fdc"
    },
    "employeetype":"Internal",
    "mail":
    [
      "Base.Majd@My-Company.com"
    ],
    "telephonenumber":"+1 214 324-4122",
    "manager":
    {
      "displayName":"Guo-Qiang Brailey",
      "value":"uid-7f001-6f26d110-11da5aeefcf--7fde",
      "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
              Users/uid-7f001-6f26d110-11da5aeefcf--7fde"
    },
    "gender":"W",
    "employeenumber":"7839",
    "displayName":"Majd Base Psn",
    "dxruid":"uid-a5dcb1--5aae8595-178cf4b9490--7e32",
    "dxrstate":"NEW",
    "dayofbirth":"1972-01-06T23:00:00.000Z",
    "cn":"Majd Base Psn",
    "objectclass":
    [
      "inetOrgPerson",
      "organizationalPerson",
      "dxrUser",
      "dxrPersona",
      "top",
      "person"
    ],
    "givenname":"Base",
    "preferredlanguage":"en",
    "sn":"Majd",
    "value":"uid-a5dcb1--5aae8595-178cf4b9490--7e32",
    "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
            Users/uid-a5dcb1--5aae8595-178cf4b9490--7e32"
  },
  "initiator":
  {
    "displayName":"Nik Taspatch",
    "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
    "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
            Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
  },
  "currentParticipants":
  [
    {
      "displayName":"Nik Taspatch",
      "value":"uid-7f001-6f26d110-11da5aeefcf--7ff9",
      "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
              Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
    }
  ],
  "description":"Create a persona stepwise including approval",
  "dn":"cn=178cf4bc351$-6d3b,cn=2021-04-14,cn=Create Persona With Approval,
        cn=Personas,cn=My-Company,cn=Monitor,cn=wfRoot,cn=My-Company",
  "readOnly":false,
  "subjectType":"dxrPersona",
  "meta":
  {
    "created":"2021-04-14T11:56:20.439Z",
    "location":"http://localhost:8080/DirXIdentityRestService-My-Company/
                Workflows/178cf4bc351%24-6d3b",
    "lastModified":"2021-04-14T11:56:21.025Z",
    "resourceType":"WorkflowInstance"
  },
  "id":"178cf4bc351$-6d3b",
  "state":"RUNNING",
  "operation":"create",
  "startDate":"2021-04-14T11:56:20.000Z",
  "expirationDate":"2021-04-19T11:56:20.000Z"
}

Listing the Assignable Privileges for the Subject

This operation retrieves the privileges the authenticated user can assign to the workflow subject. Note that the subject of a create workflow doesn’t yet exist in the database while the workflow is running.

For each privilege in the result, the flag "assignableOnlyOnce" indicates whether the privilege can be assigned just once (true) or more than once (false).

The operation can be configured in sections "assignableRoles" of resource type "Role", "assignablePermissions" of resource type "Permission", and "assignableGroups" of resource type "Group". The applied configuration parameters are "base", "additionalFilter", "defaultAttributes" and "mandatoryAttributes". All other configuration parameters are ignored.

The size limit for assignable roles is defined by

  • Request parameter "count".

  • Parameter "defaultCount" of resource type "Role" section "assignableRoles".

  • Parameter "defaultCount" of resource type "Role" section "search".

  • Configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Parameter "maxCount" of resource type "Role" section "assignableRoles".

  • Parameter "maxCount" of resource type "Role" section "search".

  • Configuration parameter "search.maxCount".

in descending priority.

The maximum size limit is restricted by the global LDAP search size limit configured at the domain object. Similar for permissions and groups.

Request

HTTP Method and Path

GET /Workflows/{workflowId}/assignableRoles

GET /Workflows/{workflowId}/assignablePermissions

GET /Workflows/{workflowId}/assignableGroups

GET /Workflows/{workflowId}/assignablePrivileges

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • workflowId - The workflow UID (dxruid).

Query Parameters

  • attributes - A comma-separated list of SCIM or LDAP attribute names that specify the privilege attributes to be returned in the result. The result includes for each privilege:

    • The mandatory attributes.

    • The requested attributes, if any requested.

    • The default attributes, if no attributes are requested.

  • base - The search base.

  • filter - The search filter. To get entries of a specific resource type only, include a resource type filter, for example

    filter=(meta.resourceType eq "Role") and (cn sw "co")

filter=(meta.resourceType eq "Role") or (meta.resourceType eq "Permission")

  • filterValue - The value to replace the placeholder in configuration parameter "valueFilter" (in section “assignableRoles” of resource type “Role” for roles, likewise for groups and permissions) with. Asterisks (*) within the filter value serve as wildcards. If left unspecified, no additional filter is applied.

  • count - The maximum number of entries to return.

Response

HTTP Success Codes

  • OK (200) - The privilege list is returned.

Response Content

On success, the operations referring to a specific privilege type return a JSON object with the list of privileges:

{
   "totalResults":54,
   "Resources":
   [
      {
         "value":"uid-7f001-6f26d110-11da5aeefcf--78b5",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        domainObjects/uid-7f001-6f26d110-11da5aeefcf--78b5",
         "display":"Contractor",
         "description":"Standard role for all contractors",
         "assignableOnlyOnce":true
      },
      {
         "value":"uid-7f001-6f26d110-11da5aeefcf--78ab",
         "$ref":"http://localhost:8080/DirXIdentityRestService-My-Company/
                        domainObjects/uid-7f001-6f26d110-11da5aeefcf--78ab",
         "display":"Project Member",
         "description":"Member of a project",
         "roleParameters": [
            {
               "uid":"uid-7f001-cee271-fed935aa6d--7eb4",
               "name":"Project",
               "type":"DN"
            }
         ],
         "assignableOnlyOnce":false
      },
      (OTHER ROLES ELIMINATED)…
   ]
}

The operation "Workflows/{workflowId}/assignablePrivileges", on the other hand, returns a JSON object with three lists, one for each type of privilege:

{
 "roles":{
   "totalResults":240,
   "Resources":[…]
 },
 "permissions":{
   "totalResults":259,
   "Resources":[…]
 },
 "groups":{
   "totalResults":47,
   "Resources":[…]
 }
}

Response Data

  • totalResults - The number of privileges returned.

  • Resources - The list of privileges.

Updating a Workflow Task

This operation updates an open workflow task for the authenticated user.

Request

HTTP Method and Path

POST /Workflows/{workflowId}/{taskId}

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • workflowId - The workflow UID (dxruid).

  • taskId - The task UID (dxruid).

Request Body

The request body is a JSON object with the modifications to the subject.

The first example shows the request body for an enter attributes task:

{
  "subject": {
    "attributes": {
      "description": "Persona for cn=Majd Base,ou=Sales US,ou=Sales,
                      o=My-Company,cn=Users,cn=My-Company",
      "dxrEndDate": "2025-04-30T12:00:00Z",
      "mobile": "0171 66616661234",
      "title": "Sir"
    },
    "dueDate": "2023-09-09T12:15:00.000Z"
  },
  "taskContext": {
    "reason": "Majd Base needs a new persona"
  }
}

  • subject - New or modifed attribute values for the workflow subject:

    • parentDN - The DN of the parent of the subject. The parent DN is used when the subject is created via the workflow.

    • attributes - The new or modfied values for the subject’s attributes. Attributes not listed here are left unmodified. Attributes with value null are removed from the subject.

    • dueDate - The date when the workflow subject should be created. The workflow will then create a ticket for the creation of the new entry. If the task is not due date enabled, the due date will be ignored.

  • workflowContext - Workflow context attributes to be stored in workflow property "dxmSpecificAttributes" with name "ctx.lowerCase_attributeName". For example

    • requestReason - The optional reason for requesting the modifications to or the creation of the subject.

  • taskContext - Task context attributesto to be stored in activity property "dxmSpecificAttributes" with name "lowerCase_attributeName". For example

    • reason - The optional reason for this task.

The next example shows the request body for a request privileges task with a group and a parameterized role:

{
  "assignments": [
    {
      "resourceId": "uid-7f001-6f26d110-11da5aeefcf--78bc"
    },
    {
      "resourceId": "uid-7f001-6f26d110-11da5aeefcf--78b8"
    },
    {
      "resourceId": "uid-7f001-6f26d110-11da5aeefcf--78ab",
      "dxrEndDate": "2025-04-30T12:00:00Z",
      "roleParameters": [
        {
          "uid":"uid-7f001-cee271-fed935aa6d--7eb4",
          "values" : [
            { "value" : "High performance" },
            { "value" : "MoreCustomers" }
          ]
        }
      ]
  ],
  "taskContext": {
    "reason": "Majd Base needs some privileges”
  }
}

  • assignments - The list of modified or additional privilege assignments. Assignments not listed here are left unmodified.

  • workflowContext - Workflow context attributes to be stored in workflow property "dxmSpecificAttributes" with name "ctx.lowerCase_attributeName".

  • taskContext - Task context attributesto to be stored in activity property "dxmSpecificAttributes" with name "lowerCase_attributeName". For example

    • reason - The optional reason for this task.

The last example shows the request body for an approve create task:

{
  "subject": {
    "attributes": {
      "mobile": "0171 77716661234",
      "title": null
    },
    "dueDate": "2023-09-15T12:15:00.000Z"
  },
  "assignments": [
    {
      "resourceId": "uid-7f001-6f26d110-11da5aeefcf--791e",
      "assignment": {
        "dxrStartDate":"2020-12-31T00:00:00.000Z",
        "dxrEndDate":"2026-08-31T00:00:00.000Z",
        "dxrNeedsReapproval": false
      }
    },
    {
      "resourceId": "uid-7f001-6f26d110-11da5aeefcf--78ab",
      "dxrEndDate": "2025-04-30T12:00:00Z",
      "roleParameters": [
        {
          "uid":"uid-7f001-cee271-fed935aa6d--7eb4",
          "values" : [
            { "value" : "High performance" },
            { "value" : "OptimizeIT" }
          ]
        }
      ]
    }
  ],
  "taskContext": {
    "approvalResult": "ACCEPTED",
    "reason": "Majd Base needs a new persona for project OptimizeIT"
  }
}

  • subject - Modifed or additional attribute values for the workflow subject:

    • attributes - The new values for the subject’s attributes. Attributes not listed here are left unmodified. Attributes with value null are removed from the subject.

    • dueDate - The date when the workflow subject should be created. The workflow will then create a ticket for the creation of the new entry. If the task is not due date enabled, the due date will be ignored.

  • assignments - The list of modified or additional privilege assignments. Assignments not listed here are left unmodified.

  • workflowContext - Workflow context attributes to be stored in workflow property "dxmSpecificAttributes" with name "ctx.lowerCase_attributeName".

  • taskContext - Task context attributesto to be stored in activity property "dxmSpecificAttributes" with name "lowerCase_attributeName". For example

    • approvalResult - Whether the request is accepted ("ACCEPTED") or rejected ("REJECTED").

    • reason - The optional reason for this task.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The task has been updated.

Ticket Service Operations

The ticket service provides operations to list. read and delete tickets.

Overview

This section provides information about ticket service operations.

List of Operations

  • GET /Tickets - Lists tickets.

  • GET /Tickets/{ticketId}}
    GET /Tickets/{ticketId}/{orderId}     - Reads the ticket with the given ID.

  • DELETE /Tickets/{ticketId}
    DELETE /Tickets/{ticketId}/{orderId}     - Cancels the ticket with the given ID.

Listing Tickets

The operation list tickets matching some search criteria.

The operation can be configured in section "search" or resource type “Ticket”.

The size limit is defined by

  • Request parameter "count".

  • Parameter "defaultCount" of resource type section "search".

  • Configuration parameter "search.defaultCount".

in descending priority.

The maximum size limit is defined by

  • Parameter "maxCount" of resource type section "search".

  • Configuration parameter "search.maxCount".

in descending priority.

Request

HTTP Method and Path

GET /Tickets

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Query Parameters

  • initiatorId - The optional DN or UID of the workflow initiator.

  • subjectId - The optional DN or UID of the workflow subject.

  • entryOperations - The optional comma-separated list entry operations, like "add", "modify", "delete", and "info". Supports wildcards (*).

  • assignmentOperations - The optional comma-separated list of assignment operations, like "add", "modify", "delete", and "info". Supports wildcards (*).

  • subjectTypes - The optional comma-separated list of ticket subject types, like "dxrUser". Supports wildcards (*).

  • states - The optional comma-separated list of ticket states, like "Input.Completed” and “Approval.Accepted”. Supports wildcards (*).

  • maxAge - The maximum number of days elapsed since the ticket has been created. 0 for no maximum.

  • filter - An optional SCIM filter for the ticket.

  • sortBy - A comma-separated list of attributes used to order the search result.

  • sortOrder - The sort order per sort attribute, separated by commas. Allowed values are "ascending" and "descending". Default value is "ascending".

  • count - The maximum number of entries to return.

HTTP Success Codes

  • OK (200) - The ticket list is returned.

Response Content

On success, the operation returns a JSON object with the ticket list. The basic structure is:

{
  "profileChanges": {
    ...
  },
  "permissions": {
    ...
  },
  "roles": {
    ...
  },
  "groups": {
    ...
  },
}

The example below shows two entries for the ticket with ID "uid-a5dcb1—​350b007-17d2e0908a0—​7fd2". The first entry with order ID "0" is for the assignment of role "Sales Task”, the second entry with order ID "1" for the assignment of role "Silver Customer":

{
  "profileChanges": {
    "startIndex": 1,
    "totalResults": 4,
    "itemsPerPage": 4,
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
  ...
    ]
  },
  "permissions": {
    "startIndex": 1,
    "totalResults": 1,
    "itemsPerPage": 1,
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
  ...
    ]
  },
  "roles": {
    "startIndex": 1,
    "totalResults": 2,
    "itemsPerPage": 2,
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
      {
        "subject": {
          "displayName": "Nik Taspatch",
          "value": "uid-7f001-6f26d110-11da5aeefcf--7ff9",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
        },
        "assignment": {
          "mode": "manual",
          "hasSODViolations": false,
          "isEditable": false,
          "operation": "ADD"
        },
        "display": "Sales Tasks",
        "initiator": {
          "displayName": "Retha Wagner",
          "value": "uid-7f001-6f26d110-11da5aeefcf--7ff8",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ff8"
        },
        "dueDate": "2023-11-30T23:00:00.000Z",
        "state": "Input.Completed",
        "source": "ticket",
        "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                 Tickets/uid-a5dcb1--350b007-17d2e0908a0--7fd2/0",
        "value": "uid-a5dcb1--350b007-17d2e0908a0--7fd2/0",
        "startDate": "2021-11-17T14:36:47.182Z",
        "resourceType": "Role"
      },
      {
        "subject": {
          "displayName": "Nik Taspatch",
          "value": "uid-7f001-6f26d110-11da5aeefcf--7ff9",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
        },
        "assignment": {
          "mode": "manual",
          "hasSODViolations": false,
          "isEditable": false,
          "operation": "ADD"
        },
        "display": "Silver Customer",
        "initiator": {
          "displayName": "Retha Wagner",
          "value": "uid-7f001-6f26d110-11da5aeefcf--7ff8",
          "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                   Users/uid-7f001-6f26d110-11da5aeefcf--7ff8"
        },
        "dueDate": "2023-11-30T23:00:00.000Z",
        "state": "Input.Completed",
        "source": "ticket",
        "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
                 Tickets/uid-a5dcb1--350b007-17d2e0908a0--7fd2/1",
        "value": "uid-a5dcb1--350b007-17d2e0908a0--7fd2/1",
        "startDate": "2021-11-17T14:36:47.182Z",
        "resourceType": "Role"
      }
    ]
  },
  "groups": {
    "startIndex": 1,
    "totalResults": 1,
    "itemsPerPage": 1,
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
  ...
    ]
  }
}

Reading a Ticket

The operation reads a ticket.

Request

HTTP Method and Path

GET /Tickets/{ticketId}

GET /Tickets/{ticketId}/{orderId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • ticketId - The ticket UID (dxruid).

  • orderId - The index of the assignment within a privilege assignment ticket, as returned by the list operation.

Response

HTTP Success Codes

  • OK (200) - The entry is returned.

Response Content

On success, the operation returns a JSON object that lists the entry’s properties:

{
  "subject": {
    "displayName": "Nik Taspatch",
    "value": "uid-7f001-6f26d110-11da5aeefcf--7ff9",
    "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-7f001-6f26d110-11da5aeefcf--7ff9"
  },
  "assignment": {
    "mode": "manual",
    "hasSODViolations": false,
    "isEditable": false,
    "operation": "ADD"
  },
  "display": "Silver Customer",
  "initiator": {
    "displayName": "Retha Wagner",
    "value": "uid-7f001-6f26d110-11da5aeefcf--7ff8",
    "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
             Users/uid-7f001-6f26d110-11da5aeefcf--7ff8"
  },
  "dueDate": "2023-11-30T23:00:00.000Z",
  "state": "Input.Completed",
  "source": "ticket",
  "$ref": "http://localhost:8080/DirXIdentityRestService-My-Company/
           Tickets/uid-a5dcb1--350b007-17d2e0908a0--7fd2/1",
  "value": "uid-a5dcb1--350b007-17d2e0908a0--7fd2/1",
  "startDate": "2021-11-17T14:36:47.182Z",
  "resourceType": "Role"
}

Deleting a Ticket

This operation deletes a ticket given by its UID.

Request

HTTP Method and Path

DELETE /Tickets/{ticketId}

DELETE /Tickets/{ticketId}/{orderId}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • ticketId - The ticket UID (dxruid).

  • orderId - The index of the assignment within a privilege assignment ticket, as returned by the list operation. Is ignored.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The ticket has been deleted.

Approval Service Operations

The approval service provides operations to retrieve and perform the authenticated user’s approval tasks. These operations are not based on SCIM for legacy reasons

Overview

This section provides information about approval service operations.

List of Operations

  • GET /Approvals - Lists the approval tasks for the authenticated user.

  • GET /Approvals/count - Returns the number of open approval tasks for the authenticated user.

  • GET /Approvals/{workflowUID} - Reads the open approval task for the authenticated user for the workflow with the given UID.

  • POST /Approvals/{workflowUID}/approve - Approves the approval task for the workflow with the given UID.

  • POST /Approvals/{workflowUID}/reject - Rejects the approval task for the workflow with the given UID.

  • POST /Approvals/bulk - Accepts or rejects several approval tasks in one chunk.

  • GET /Approvals/closedTasks - Lists the workflows with one or more approval tasks that have been completed by the authenticated user.

Listing the Workflows with Approval Tasks

This operation retrieves the list of running workflows with approval tasks for the authenticated user.

The size limit is defined by

  • Request parameter "$top"

  • Configuration parameter "workklist.sizelimit" in file approval.properties.

  • The hard-coded default value 1000.

in descending priority.

The maximum size limit is defined by

  • Configuration parameter "workklist.sizelimit" in file approval.properties.

  • The hard-coded default value 1000.

in descending priority.

Request

HTTP Method and Path

GET /Approvals

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow and task attributes.

Query Parameters

  • $top - The number of workflows to return.

  • $sort - A comma-separated list of workflow attribute names that specify the sort order of the workflow list when searching the list in LDAP. If the search hits the size limit, the list returned from the LDAP server contains the first entries according to the sort order. The list returned to the HTTP client contains the same entries but possibly in a different order. Reasonable sort criteria are for example "dxrExpirationDate" (sorting by expiration date in ascending order), and "dxrExpirationDate:r" (sorting by expiration date in descending order). There’s no default value.

Response

HTTP Success Codes

  • OK (200) - The task list is returned.

Response Content

On success, the operation returns a JSON object with the task list:

{
 "errorCode": 0,
 "message": "Results for user cn=Hungs Olivier,o=My-Company,
             cn=Users,cn=My-Company",
 "authenticatedUser":"cn=Taspatch Nik,ou=Global IT,o=My-Company,
                      cn=Users,cn=My-Company",
 "payload":
 {
   "dn":"cn=14fca6bff94$-7ea7,cn=2015-09-14,cn=Manager Nomination,
         cn=Approval,cn=My-Company,cn=Monitor,cn=wfRoot,cn=My-Company",
   "uid": "14fca6bff94$-7ea7",
   "name": "Abele Marc -> Project Manager",
   "state": "RUNNING",
   "applicationState": null,
   "startDate":"20171212132937Z",
   "expirationDate":"20171216132937Z",
   (SOME STUFF ELIMINATED)…
   "task":
   {
     "name":"Approval by Privilege Managers-0",
     "description":"Please approve the following privilege request.\n
             Check it carefully and accept or reject it.\n
             It is good style to enter a reason (especially when rejecting).",
     "reason":null,
     "startDate":"20171212132940Z",
     "expirationDate":"20171213132941Z",
     "context":
     {
     },
     "participants":
     [
       "cn=Wagner Retha,ou=Global IT,o=My-Company,cn=Users,cn=My-Company",
       "cn=Taspatch Nik,ou=Global IT,o=My-Company,cn=Users,cn=My-Company"
     ]
   },
  (TRUNCATED)…
 ]
}

Response Data

  • errorCode - The operation’s result code; 0 for success. Error code 101 indicates that the result list is incomplete since the size limit has been exceeded.

  • message - A textual explanation of the error code.

  • authenticatedUser - The authenticated user’s DN.

  • payload - An array of JSON objects. Each object represents a workflow with its approval task. If a workflow has two approval tasks for the authenticated user, only one of them is returned. The payload array is empty if no workflows with approval tasks for the authenticated user exist.

An important attribute within a workflow representation is the workflow ID with name "uid". The ID can be used in subsequent operations to request individual information about the workflow or to accept or reject its approval task.

Each workflow object also includes sub-objects with details about its subject, resource, and initiator. You can configure the attributes to be returned in each of these sub-objects in the file approvals.properties via the properties worklist.subjectDetailAttributes, worklist.resourceDetailAttributes and worklist.initiatorDetailAttributes, respectively.

Counting the Workflows with Open Tasks

This operation counts the workflows with one ore more open tasks for the authenticated user.

The size limit is defined by

  • Configuration parameter "workklist.countSizelimit" in file approval.properties.

  • The hard-coded default value 1000.

in descending priority.

Request

HTTP Method and Path

GET /Approvals/count

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

Response

HTTP Success Codes

  • OK (200) - The number of open tasks is returned.

Response Content

On success, the operation returns a JSON object with number of open tasks:

{
"totalResults":13,
"sizeLimitExceeded":false
}

Response Data

  • totalResults - The number of open tasks.

  • sizeLimitExceeded - Whether (true) or not (false) the operation reached a size limit. Is usually only returned if the size limit has been exceeded.

Reading a Workflow with its Tasks

This operation retrieves the workflow with a given ID and its approval task for the authenticated user. The workflow ID can be obtained from the result of a list workflows operation.

Request

HTTP Method and Path

GET /Approvals/{workflowUID}

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow and task attributes.

Path Parameters

  • workflowUID - The UID of a workflow (dxruid). Note that the workflow DN will not work here.

Response

HTTP Success Codes

  • OK (200) - The workflow is returned.

Response Content

The operation returns a JSON object including an error code, a message, the authenticated user’s DN and a payload:

{
 "errorCode":0,
 "message":"Content for 1604a533039$-6c40",
 "authenticatedUser":"cn=Taspatch Nik,ou=Global IT,o=My-Company,
                      cn=Users,cn=My-Company",
 "payload":
 {
   "dn":"cn=1604a533039$-6c40,cn=2017-12-12,cn=4-Eye Approval,cn=Approval,
        cn=My-Company,cn=Monitor,cn=wfRoot,cn=My-Company",
   "uid":"1604a533039$-6c40",
   "name":"Abele Marc -> DXR Auditors",
   "state":"RUNNING",
   "applicationState":null,
   "startDate":"20171212132937Z",
   "expirationDate":"20171216132937Z",
   (SOME STUFF ELIMINATED)…
   "task":
   {
     "name":"Approval by Privilege Managers-0",
     "description":"Please approve the following privilege request.\n
             Check it carefully and accept or reject it.\n
             It is good style to enter a reason (especially when rejecting).",
     "reason":null,
     "startDate":"20171212132940Z",
     "expirationDate":"20171213132941Z",
     "context":
     {
     },
     "participants":
     [
       "cn=Wagner Retha,ou=Global IT,o=My-Company,cn=Users,cn=My-Company",
       "cn=Taspatch Nik,ou=Global IT,o=My-Company,cn=Users,cn=My-Company"
     ]
   },
 (TRUNCATED)…

Response Data

  • errorCode - The operation’s result code; 0 for success.

  • message - A textual explanation of the error code.

  • authenticatedUser - the authenticated user’s DN.

  • payload - The payload represents the workflow data in the same way as one of the objects in the payload of a list workflows request.

Accepting an Approval Task

This operation approves (accepts) the authenticated user’s approval tasks within a workflow with a given ID. The workflow ID can be obtained from the result of a list workflows operation. The reason for accepting the task is posted in the request body.

If the user has more than one open approval task within the specified workflow, all his open tasks are accepted. There’s no way to accept a specific task only.

Request

HTTP Method and Path

POST /Approvals/{workflowUID}/approve

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • workflowUID- The UID of a workflow (dxruid). Note that the workflow DN will not work here.

Request Body

The request body is a JSON object that specifies the reason for accepting the task:

{
   "reason":"Task 1604a533039$-6c40 accepted"
}

  • reason - The optional reason for accepting the task.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The task has been approved.

Response Content

The operation returns a JSON object including an error code, a message and the authenticated user’s DN:

{
  "errorCode":0,
  "message":"Workflow ID 1604a533039$-6c40 accepted",
  "authenticatedUser":"cn=Taspatch Nik,ou=Global IT,o=My-Company,
                      cn=Users,cn=My-Company",
}

Response Data

  • errorCode - The operation’s result code; 0 for success.

  • message - A textual explanation of the error code.

  • authenticatedUser - The authenticated user’s DN.

Rejecting an Approval Task

This operation rejects the authenticated user’s approval tasks within a workflow with a given ID. The workflow ID can be obtained from the result of a list workflows operation. The reason for rejecting the task is posted in the request body.

If the user has more than one open approval task within the specified workflow, all his open tasks are rejected. There’s no way to reject a specific task only.

Request

HTTP Method and Path

POST /Approvals/{workflowUID}/reject

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Path Parameters

  • workflowUID- The UID of a workflow (dxruid). Note that the workflow DN will not work here.

Request Body

The request body is a JSON object that specifies the reason for rejecting the task:

{
   "reason":"Task 1604a533039$-6c40 rejected"
}

  • reason - The optional reason for rejecting the task.

Response

HTTP Success Codes

  • NO_CONTENT (204) - The task has been rejected.

Response Content

The operation returns a JSON object including an error code, a message and the authenticated user’s DN:

{
 "errorCode":0,
 "message":"Workflow ID 1604a533039$-6c40 rejected",
 "authenticatedUser":"cn=Taspatch Nik,ou=Global IT,o=My-Company,
                      cn=Users,cn=My-Company",
}

Response Data

  • errorCode - The operation’s result code; 0 for success.

  • message - The textual explanation of the error code.

  • authenticatedUser - The authenticated user’s DN.

Bulk Approving a List of Tasks

The bulk operation is a fast operation for handling approvals. It allows the client to approve (accept or reject) multiple workflow tasks with one request. The operation returns the response to the client immediately after the modifications in the LDAP directory are completed. This operation performs direct LDAP modifications and does not use the Identity service layer. It finishes the activity by setting the activity state to SUCCEEDED and the application state to ACCEPTED. It also removes the approver from the list of current approvers in the workflow entry, so that a subsequent request for the approver’s work list will not contain this workflow. The Web Service notifies the workflow engine and writes audit records in separate threads, so they do not block returning the response.

By default, the bulk operation approves tasks of the authenticated user. Access rights permitting; however, the authenticated user may also approve tasks of another user. In this case, the authenticated user is audited as active participant in audit records, while the other user is listed as active participant in the workflows themselves.

Request

HTTP Method and Path

POST /Approvals/bulk

Relevant HTTP Headers

  • Content-Type - The content type is "application/json; charset=UTF-8".

  • Accept - The header is optional but is recommended to be set to application/json.

Request Body

The request body is a JSON object that specifies the list of workflows to be accepted or rejected, the reason for accepting or rejecting, and the actual participant of the tasks:

{
  "bulkApprove" : {
     "participant":"cn=Hungs Olivier,o=My-Company,cn=Users,cn=My-Company",
     "accept": {
        "workflowID": [
           "1604a533039$-6c40",
           "1604a533039$-6edb"
        ],
        "reason":"Two tasks accepted"
     },
     "reject": {
        "workflowID": [
           "1604a533039$-6ae2",
           "1604a533039$-639d"
        ],
        "reason":"Another two tasks rejected"
     }
  }
}

  • participant - The DN of the user whose tasks are approved. By default, the authenticated user. If different, the authenticated user approves the tasks of the specified participant, access rights permitting.

  • accept - The list of requests to be accepted.

    • reason - The optional reason for accepting a request. It applies to all accepted requests.

    • workflowID - The list with workflow UIDs to be accepted. The service accepts all currently running tasks of the approver in these workflows. Note that the workflow DNs will not work here.

  • reject - The list of requests to be rejected.

    • reason - The reason for rejecting a request. It applies to all rejected requests.

    • workflowID - The list with workflow UIDs to be rejected. The service rejects all currently running tasks of the approver in these workflows. Note that the workflow DNs will not work here.

Response

HTTP Success Codes

  • NO_CONTENT (204) - All the tasks have been successfully approved.

  • OK (200) - One or more approvals have failed. Error details are returned in the response content.

Response Content

The operation returns a JSON object including an error code, a message and the authenticated user’s DN, and a payload. The payload includes information about failures for specific workflows. Note that requested approvals for all other workflows are not affected by these failures and are regularly processed.

{
 "errorCode":0,
 "message":"Bulk approval has ended with success",
 "authenticatedUser":"cn=Taspatch Nik,ou=Global IT,o=My-Company,
                      cn=Users,cn=My-Company",
 "payload": {
   "response": {
     "failed": {
       "reason":"Errors",
       "workflows": [
       {
         "id":"1604a533039$-6c40",
         "name":"Abele Marc -> DXR Auditors",
         "errorCode":30,
         "errorMessage":"Provided user is not in the participants list"
       }
     ]
   }
 }
}

Response Data

  • errorCode - The operation’s result code; 0 for success.

  • message - The textual explanation of the error code.

  • authenticatedUser - The authenticated user’s DN.

  • payload/response/failed - Details about approval failures.

    • reason - The failure reason.

    • workflows - The list of workflows which failed to be approved.

      • id - The workflow ID.

      • name - The workflow or activity name.

      • errorCode - 1x for error at activity level, 2x for error at workflow level, 3x for error related to participant, 4x for invalid workflow ID.

      • errorMessage - The textual explanation of the error code.

Listing Closed Tasks

This operation lists the workflows with approval tasks that have been performed by the authenticated user.

The list of attributes returned for each closed task is fixed.

The size limit is defined by

  • Request parameter "$top"

  • Configuration parameter "workklist.sizelimit" in file approval.properties.

  • The hard-coded default value 1000.

in descending priority.

The maximum size limit is defined by

  • Configuration parameter "workklist.sizelimit" in file approval.properties.

  • The hard-coded default value 1000.

in descending priority.

Request

HTTP Method and Path

GET /Approvals/closedTasks

Relevant HTTP Headers

  • Accept - The header is optional but is recommended to be set to application/json.

  • Accept-Language - The header is evaluated for localizable workflow and task attributes.

Query Parameters

  • $top - The number of workflows to return.

  • $sort - A comma-separated list of task attribute names that specify the sort order when searching the tasks in LDAP. If the search hits the size limit, the list returned from the LDAP server contains the first entries according to the sort order. The list returned to the HTTP client contains the same entries but possibly in a different order. Reasonable sort criteria are for example "dxrEndDate" (sorting by task end date in ascending order), and "dxrEndDate:r" (sorting by task end date in descending order). The default value is "dxrEndDate:r".

  • filterValue - A filter value for the workflow subject, initiator, and resource. The value is to replace the placeholder in configuration parameter "valueFilter" in section "search” of the resource type configurations for "User" (subject and initiator) and, depending on the workflow resource’s type, for "Role", "Permission" or "Group” (resource). Asterisks (*) within the filter value serve as wildcards. If left unspecified, no filter is applied.

  • from - The earliest task end date (for example "2021-03-10T00:00:00.000Z"). By default, there’s no lower bound for the end date.

  • to - The latest task end date (for example "2021-06-10T00:00:00.000Z"). By default, there’s no upper bound for the end date.

Response

HTTP Success Codes

  • OK (200) - The closed tasks are returned.

Response Content

On success, the operation returns a JSON object with the list of closed tasks:

{
 "errorCode":0,
 "message":"Results for user cn=Taspatch Nik,ou=Global IT,
            o=My-Company,cn=Users,cn=My-Company",
 "authenticatedUser":"",
 "payload":
 [
   {
     "dn":"cn=17912df61f5$-2c38,cn=2021-04-27,cn=4-Eye Approval,cn=Approval,
           cn=My-Company,cn=Monitor,cn=wfRoot,cn=My-Company",
     "uid":"17912df61f5$-2c38",
     "name":"Maskery Guy -> Manager Analyst Relations",
     "state":"RUNNING",
     "applicationState":null,
     "description":"Approval of a privilege assignment in parallel by -
                    Manager of the user - Owner of the privilege",
     "startDate":"20210427144037Z",
     "expirationDate":"20210501144037Z",
     "subject":
     {
       "id":"cn=Maskery Guy,o=Mercato Aurum,dc=Customers,cn=Users,cn=My-Company",
       "dxruid":"7765-2",
       "attributes":
       {
         "folders":
         [
           "Mercato Aurum",
           "Customers",
           "Users",
           "My-Company"
         ],
         "facsimiletelephonenumber":"+39 6 2345-8873",
         "telephonenumber":"+39 6 2345-5463",
         "mail":
         [
           "Guy.Maskery@Mercato-Aurum.com"
         ],
         "givenname":"Guy",
         "ou":"Proc 12",
         "name":"Maskery Guy",
         "description":"Procurement Europe",
         "sn":"Maskery"
       },
       "modifications":
       {
       },
       "metadata":
       {
         "orderType":"INFO",
         "activationDate":null,
         "directoryType":"dxrUser",
         "objectType":"User"
       }
     },
     "privileges":
     [
       {
         "assignment":
         {
           "id":"cn=add.svc.uid-a5dcb1--612bb328-17913b78ef3--7fae,
                 cn=Maskery Guy,o=Mercato Aurum,dc=Customers,
                 cn=Users,cn=My-Company",
           "dxruid":"7765-2 - uid-7f001-6f26d110-11da5aeefcf--78a9",
           "attributes":
           {
             "dxrEndDate":"20220426220000Z",
             "dxrNeedsReapproval":"true"
           },
           "modifications":
           {
           },
           "metadata":
           {
             "orderType":"ADD",
             "activationDate":null,
             "directoryType":"dxrRole",
             "objectType":"UserToRole",
             "resourceType":"dxrUserToRole",
             "directAssigned":true,
             "ruleAssigned":false,
             "boinherited":false
           },
           "roleparameters":
           [
           ],
           "roleParModifications":
           [
           ],
           "userDN":"cn=Maskery Guy,o=Mercato Aurum,dc=Customers,
                     cn=Users,cn=My-Company",
           "privilegeDN":"cn=Manager Analyst Relations,cn=Self Service,
                          cn=Corporate Roles,cn=RoleCatalogue,cn=My-Company",
           "sodViolations":null,
           "violatesSod":false
         },
         "resource":
         {
           "id":"cn=Manager Analyst Relations,cn=Self Service,
                 cn=Corporate Roles,cn=RoleCatalogue,cn=My-Company",
           "dxruid":null,
           "attributes":
           {
             "folders":
             [
               "Self Service",
               "Corporate Roles",
               "RoleCatalogue",
               "My-Company"
             ],
             "name":"Manager Analyst Relations",
             "description":"Allows managing relations to analysts",
             "cn":"Manager Analyst Relations"
           },
           "modifications":
           {
           },
           "metadata":
           {
             "orderType":"INFO",
             "activationDate":null,
             "directoryType":"dxrRole",
             "objectType":"Role"
           }
         }
       }
     ],
     "initiator":
     {
       "id":"cn=Ratnam Dilip,ou=Sales US,ou=Sales,o=My-Company,
             cn=Users,cn=My-Company",
       "dxruid":null,
       "attributes":
       {
         "folders":
         [
           "Sales US",
           "Sales",
           "My-Company",
           "Users",
           "My-Company"
         ],
         "facsimiletelephonenumber":"+1 408 876-35267",
         "telephonenumber":"+1 408 876-9021",
         "mail":
         [
           "Dilip.Ratnam@My-Company.com"
         ],
         "givenname":"Dilip",
         "ou":"Sales",
         "name":"Ratnam Dilip",
         "description":"Sales NorthEast Region",
         "sn":"Ratnam"
       },
       "modifications":
       {
       },
       "metadata":
       {
         "orderType":null,
         "activationDate":null,
         "directoryType":null,
         "objectType":null
       }
     },
     "context":
     {
       "auditrecid":"uid-a5dcb1-1ff387a9-179128e8a82--320e",
       "requestreason":"Guy is an important manager",
       "correlationid":"uid-a5dcb1--612bb328-17913b78ef3--7faf"
     },
     "task":null,
     "tasks":
     [
       {
         "name":"Approval by User Manager-0",
         "description":"Please approve the following privilege request.\n
                        Check it carefully and accept or reject it.\n
                        It is good style to enter a reason
                        (especially when rejecting).",
         "reason":"approved by taspatch",
         "state":"SUCCEEDED",
         "approvalResult":"ACCEPTED",
         "startDate":"20210427144037Z",
         "endDate":"20210427144136Z",
         "expirationDate":"20210428144037Z",
         "context":null,
         "participants":
         [
           "cn=Taspatch Nik,ou=Global IT,o=My-Company,cn=Users,cn=My-Company"
         ]
       }
     ],
     "operation":"ADD"
   }
 ]
}

Response Data

  • errorCode - The operation’s result code; 0 for success.

  • message - The textual explanation of the error code.

  • authenticatedUser - The authenticated user’s DN.

  • payload - A list of workflows with closed tasks performed by the authenticated user.

    • subject - The workflow subject.

    • privileges - The privilege in case of privilege assignment workflows .

    • initiator - The workflow initiator.

    • context - The workflow context attributes.

    • tasks - The list of approval tasks performed by the authenticated user.

Assigning Roles with Parameters

When assigning a role with parameters to a user, you need information about the role parameters; for example, their types, default values and proposal values.For role parameters of type hierarchical DN (HDN), you also need the children of a HDN node in order to let the assigner navigate through the HDN tree to select the parameter values.The information is also needed when changing a role assignment.This section shows you how to get that information.

There are two starting points.When creating a new assignment, we start with reading the role.When changing an existing assignment, we read the assignment.Then we read the details of the role parameter definitions.Finally, for an HDN parameter, we show how to retrieve the children of a given HDN node.

The examples use the Cost Location Manager role from the DirX Identity sample domain which has a single role parameter of type HDN.We use self service requests to show how the authenticated user can assign the role to himself.For assignments to other users, simply change the "Me" prefix of the sample request paths to "Users/{id}", replacing {id} with the user’s UID.

Some parts of the sample responses are omitted for better readability.

Getting an Existing Role Assignment

To display or change an assignment of role Cost Location Manager, issue the request:

GET Me/roles

The request returns the list of role assignments for the authenticated user, among them the Cost Location Manager assignment with its role parameter and parameter values:

{
 "display":"Cost Location Manager",
 "assignment":
 {
   "uid":"uid-a5d19c8--7644586-1626276b0a1--7fa9",
   "roleParameters": [
     {
       "uid":"uid-7f001--6c1b645f-112e5d0d91a--7ffc",
       "name":"Cost Locations",
       "type":"HDN",
       "values": [
         {
           "uid":"uid-7f001-6f26d110-11da5aeefcf--76e2",
           "display":"A11, A1, Cost Locations, Groups, SAP R3, TargetSystems",
           "value":"cn=A11,cn=A1,cn=Cost Locations,cn=Groups,cn=SAP R3,
                        cn=TargetSystems,cn=My-Company"
         },
         {
           "uid":"uid-7f001-6f26d110-11da5aeefcf--76d4",
           "display":"A12, A1, Cost Locations, Groups, SAP R3, TargetSystems",
           "value":"cn=A12,cn=A1,cn=Cost Locations,cn=Groups,cn=SAP R3,
                        cn=TargetSystems,cn=My-Company"
         }
       ]
     }
   ]
 }
}

The response contains:

  • The assignment UID "uid-a5d19c8—​7644586-1626276b0a1—​7fa9".

  • The parameter UID "uid-7f001—​6c1b645f-112e5d0d91a—​7ffc".

  • For each parameter value (a HDN node), its UID, DN and display value.

Getting an Assignable Role

To assign the role Cost Location Manager again to the authenticated user, issue the request:

GET Me/assignableRoles

The request returns the list of roles that can be assigned to the authenticated user, among them the Cost Location Manager role:

{
 "display":"Cost Location Manager",
 "value":"uid-7f001-6f26d110-11da5aeefcf--78b4",
 "roleParameters": [
   {
     "uid":"uid-7f001--6c1b645f-112e5d0d91a--7ffc",
     "name":"Cost Locations",
     "type":"HDN"
   }
 ]
}

The response contains:

  • The role UID "uid-7f001-6f26d110-11da5aeefcf—​78b4".

  • The parameter UID "uid-7f001—​6c1b645f-112e5d0d91a—​7ffc".

The response does not include any parameter value since the role isn’t assigned yet.

Reading Role Parameter Details

To get details about the parameters of the Cost Location Manager role, issue a request containing either the UID of the existing assignment of the Cost Location Manager role:

GET Me/roles/uid-a5d19c8—​111d2744-162d2bde752—​7fa0/roleParams

or the UID of the Cost Location Manager role itself:

GET Me/roles/uid-7f001-6f26d110-11da5aeefcf—​78b4/roleParams

Both requests return identical results:

[
 {
   "name":"Cost Locations",
   "uid":"uid-7f001--6c1b645f-112e5d0d91a--7ffc",
   "type":"HDN",
   "proposals": [
     {
       "display":"A1, Cost Locations, Groups, SAP R3, TargetSystems",
       "uid":"uid-7f001-6f26d110-11da5aeefcf--76e3",
       "value":"cn=A1,cn=Cost Locations,cn=Groups,cn=SAP R3,
                      cn=TargetSystems,cn=My-Company",
       "selectable":true,
       "leaf":false
     }
   ]
 }
]

The response contains:

  • The parameter UID "uid-7f001—​6c1b645f-112e5d0d91a—​7ffc".

  • For each parameter proposal value (an HDN node), its UID, DN and display value. The proposal values are the base nodes for selecting parameter values.

Listing the Children of an HDN Node

To get the children of a HDN node for parameter Cost Locations, issue a request containing:

  • The UID of the existing assignment of the Cost Location Manager role or the UID of the Cost Location Manager role itself.

  • The UID of the Cost Location parameter.

  • The UID of the HDN node.

The alternative requests for the children of the base node from the previous step are either

GET Me/roles/uid-7f001-6f26d110-11da5aeefcf—​78b4/roleParams/uid-7f001—​6c1b645f-112e5d0d91a—​7ffc/proposal/uid-7f001-6f26d110-11da5aeefcf—​76e3

or

GET Me/roles/uid-a5d19c8—​7644586-1626276b0a1—​7fa9/roleParams/uid-7f001—​6c1b645f-112e5d0d91a—​7ffc/proposal/uid-7f001-6f26d110-11da5aeefcf—​76e3

Both requests return identical results:

[
 {
   "display":"A11",
   "uid":"uid-7f001-6f26d110-11da5aeefcf--76e2",
   "value":"cn=A11,cn=A1,cn=Cost Locations,cn=Groups,cn=SAP R3,
            cn=TargetSystems,cn=My-Company",
   "selectable":true,
   "leaf":false
 },
 {
   "display":"A12",
   "uid":"uid-7f001-6f26d110-11da5aeefcf--76d4",
   "value":"cn=A12,cn=A1,cn=Cost Locations,cn=Groups,cn=SAP R3,
            cn=TargetSystems,cn=My-Company",
   "selectable":true,
   "leaf":false
 }
]

The response contains the UID, the DN and the display value of each child.Note that the display value is relative to the parent node.

Since both children "A11" and "A12" are non-leafs, you can now retrieve their children in the same way:

GET Me/roles/uid-7f001-6f26d110-11da5aeefcf—​78b4/roleParams/uid-7f001—​6c1b645f-112e5d0d91a—​7ffc/proposal/uid-7f001-6f26d110-11da5aeefcf—​76e2

and

GET Me/roles/uid-7f001-6f26d110-11da5aeefcf—​78b4/roleParams/uid-7f001—​6c1b645f-112e5d0d91a—​7ffc/proposal/uid-7f001-6f26d110-11da5aeefcf—​76d4

References