Fact

• PhenixID Identity Manager (IM) 5.5.0 or later
• PhenixID Identity Provisioning (PIP) 5.2.0 or later
• NOTE: IM 5.4.2 and PIP 5.1.2 or earlier versions included an earlier version of the Web Service and client. You can read about client configuration for that version in PSD1063.

Situation

You like to use IM as UI for end-users to create, change, rename or disable and send all form data to PIP. PIP will then manage that data.

Configuration

There are two things you need to do to have PIM send data to PIP.

1. Add a filter to a form/tab so PIM knows that it should NOT write to store. IM should send the data to PIP.
2. Add polices/tab parameters how and what data should be sent.

1. Add the filter PIPfilter to form/tab

1. Open IM Configurator
2. Open a create or an edit form
3. Click Tools -> Tab External Filters
4. Click Add Filter
5. Add filter.PIPFilter as value
6. Click OK and save the form

2. There are two ways to configure PIM how and what data to send to PIP.

• DSEditor.properties. Add the Web Service polices to DSEditor.properties. All forms that like to send data to PIP will use the same policies to do so.
• Tab Parameters. Add parameters to a form. This means that you can have different parameters on different forms.
• NOTE 1. We call it policies in DSEditor.properties and Tab Parameters in a form.
• NOTE 2. If you have the same policy and tab parameter with different values, the tab parameter in the form will be used.

Add policies to DSEditor.properties

Open DSEditor.properties and add policies, for example at the bottom of the file. See the “Policies/Tab Parameters” section below for all parameters.

Add Tab Parameters to a form

For more information how to add tab parameters, please read, PSD1164
See the “Policies/Tab Parameters” section below for all parameters.

Policies/Tab Parameters

Below you have all the policies/tab parameters available for the new REST Web Service and PIPFilter. Where an # is added it is meant as a comment. Working policies/tab parameters are added in BOLD.

# Start - Below is configuration policies for PIP REST Web Service
#
# URL to the PIP server, including /rest
# Example if running on PIP 127.0.0.1 on port 8085
# filter.PIPFilter.URL=http://127.0.0.1:8085/rest
filter.PIPFilter.URL=

# What end point data should be sent to. The end point will be added
# to the URL to create the complete web service URL.
filter.PIPFilter.REQUEST_1_ENDPOINT=

# If value is true (this is default), values from the form will be sent to PIP
# If value is false, the response values from the last request will 
# be sent. This is nice if you do several requests, one after the 
# other, in a form. For example Request 1 generates UserID 
# (sAMAccountName) where answer needs to be returned before next 
# request is run which might need the UserID to create a UserPrincipalName (upn).
# For the first request, the values from the form will always be sent.
filter.PIPFilter.REQUEST_1_USE_INITAL_VALUES=true/false

# If value is true (this is default), if an error occurs the 
# execution will be cancelled with an error response for the user.
# If value is false, if an error occurs the next request will run 
# and the error message(s) is/are sent to user after the last 
# request has been executed.
filter.PIPFilter.REQUEST_1_HALT_ON_ERROR= true/false

# You can have several endpoints running after each other. For the three 
# parameters above, add a 2 instead of 1 and so on.

# You must have one authentication method configured. If you have 
# both, certificate will be used.
# Certificate authentication
filter.PIPFilter.CERTIFICATE_FILE=
filter.PIPFilter.CERTIFICATE_PASSWORD=

# Basic authentication
filter.PIPFilter.USER=
filter.PIPFilter.PASSWORD=

# Should any attribute be encrypted and what is the encryption key?
filter.PIPFilter.ENCRYPTED_ATTRIBUTES=
filter.PIPFilter.AES_ENCRYPTION_KEY=

# When this policy/parameter is set to true the DN of the logged in 
# user will be sent as LoggedInUserDN to PIP
filter.PIPFilter.ADD_LOGGED_IN_USER_DN= true/false

# When this policy/parameter is set to true the tab description will
# be sent as TabDescription to PIP
filter.PIPFilter.ADD_TAB_DESCRIPTION= true/false

# When this policy/parameter is set to true the unique name of the 
# tab will be sent as TabUniqueName to PIP
filter.PIPFilter.ADD_TAB_UNIQUE_NAME= true/false

# This option tells IM to send all attributes to PIP, no matter if 
# they are touched. Default is false, only send the touched attributes.
filter.PIPFilter.SEND_UNTOUCHED= true/false

# This option tells IM to only send attributes from modified forms 
# to PIP. Default is false.
filter.PIPFilter.CHECK_IF_ANY_IS_TOUCHED= true/false

# This option tells IM to check if all mandatory attributes have a 
# value. If any mandatory attribute is missing value the request 
# will not be sent. Default is false.
filter.PIPFilter.CHECK_MANDATORY= true/false

# For PIM 5.6.1 we added support to specify what controls to send to PIP. The controls not sent will be handled by PIM.
# There are two policies to choose from. If both are used and a there is a conflict, ATTRIBUTES_TO_SEND will precede.
filter.PIPFilter.ATTRIBUTES_NOT_SEND= add controls comma separated
filter.PIPFilter.ATTRIBUTES_TO_SEND= add controls comma separated #
# End of PIP REST Web Services policies

NewDN

If you send the attribute NewDN in the response back to PIM, the edited object will be this DN. This can be convenient when creating users or when editing users and scenarios where rename and move happens. and objects DN changes.
For PIP, NewDN is just another attribute that you create in an action with the value of the new DN. The PIP REST client however knows how to use NewDN.

Status Code

Successful replies
A reply from PIP with a status code between 0 and 499 will be considered a successful reply.

Unsuccessful replies
A reply from PIP with status code 500 or above will be considered an unsuccessful reply.

Status Messages

If a status message is sent from PIP, this will be displayed as a pop-up. The content of the pop-up will be the value of the statusMessage attribute sent from PIP.

Note. The status message supports HTML formatting.

Binary values

Binary values are base 64 encoded before sent to PIP. In PIP you must decode binary encoded values before using the. For example sending images from PIM to PIP.

PIM REST Client Edition

We have created a number of example use cases using PIM and PIP in a Windows and Active Directory environment. (if you have another LDAP or using Linux, the example use cases are quite easily to port to other environments)

For more information about PIM REST Client Edition, please read PSD1169