Identity Provisioning Configuration Process
This section is describing the overall configuration process.
General Configuration
The following steps may be used as a guideline to create and configure a policy.
- Create and configure a data source. It should include options for Host/IP Address, Port number, Admin DN and password, etc.
- Configure SMTP settings
- Create one or more schedules.
- Create and configure a policy.
- Configure actions used by the policy.
- Configure options for logs and alerts.
- Save configuration.
Configuration Objects
Data Sources
Create an LDAP Data Source Object
Open Provisioning Configurator, click on the data source category and select “LDAP”. In the following example, a Microsoft Active Directory is configured.
LDAP Data Source Settings
| Option | Value | Description |
| Name | Microsoft Active Directory | Data source name |
| Type | LDAP | Each data source type have different options |
| General tab | ||
| Host IP/DNS | localhost | IP address or DNS name of LDAP host(s). Add multiple servers separated by a space for fault tolerance. If LDAP source is Active Directory, do NOT use the domain name, make sure to add specific LDAP servers. |
| Portnr | 636 | LDAP port number to use, usually 389 or 636 |
| SSL | Enabled | When SSL should be used to communicate with LDAP host |
| TLS | Not enabled | When TLS should be used to communicate with LDAP host |
| Admin DN | cn=Administrator,cn=users,DC=YourDomain,DC=local | Full DN of an administrative user account |
| Password | ********** | The administrative user account password |
| Used Paged Result | true / false | If simple paged result (RFC 2696) should be used when searching the directory |
| Use Common Connection Pool | true / false | Use a common connection pool to share the communication between actions. Enable this to avoid connecting and disconnecting LDAP connection between actions. Read more in PSD5006. |
| Ignore LDAP Referral | true / false | If LDAP referrals should be followed or not. |
| Other tab | ||
| Description | This active directory is set to work in 2003 forest mode. | Database description |
| Usage tab | ||
| Usage | Shows policies associated with this database. Double-click an entry to jump to policy object |
Test the configuration using the Test LDAP connection button. The LDAP connection test will also control if the LDAP directory supports “Paged result” and “persistent search”.
General tab
The Data Source Viewer/Editor button can be used after a successful connection to view structure and objects in the directory.
Other tab
Usage tab is showing associated policies.
Create an SQL Data Source Object
Open Provisioning Configurator, click on the data source category and select “SQL”.
In the following example a Microsoft SQL Express database is configured.
SQL Database Settings
| Option | Value | Description |
| General tab | ||
| JDBC Driver | com.microsoft.jdbc.sqlserver.SQLServerDriver | Driver to connect to the database |
| Database URL | jdbc:sqlserver://localhost:1433;DatabaseName=Employee | Example: jdbc:odbc:UserDB |
| Admin name | sa | Full DN of an administrative account |
| Password | ********* | Administrative account password |
| View SQL | Example select * from ADM_PERSON. This will show all objects from the table “ADM_PERSON” in the “Employee” database | Use this button to perform a test query to an existing table |
| Other tab | ||
| Description | This is configuration how to reach the employee database | Database description |
| Usage tab | ||
| Associated polices | Show policies associated with this database. Double click an entry to jump to policy object. |
Testing database connection
Click on the button “View SQL” to execute an SQL query. This is to verify that a result can be received from the database.
SQL query result
Create a CSV File Data Source Object
Open Provisioning Configurator, click on the data source category and select “File”, default type is CSV.
In the following example a semi-colon file is used.
CSV Database Settings
| Option | Value | Description |
| General tab | ||
| Specific file | Enabled | Select a file. |
| Scan file directory | Not enabled | Scan a file directory and match file after a pattern. For example *.txt |
| File name/scan directory | C:\Program Files \PhenixID\Provisioning\Import\ADM_PERSON.csv | Select the file name. |
| Separator | , | Select a character as field separator. |
| Text separator | Select separator that marks text fields. | |
| Start record | 1 | Select the start record to read. This is used when the first row (row 0) is specifying field names. |
| Encoding | ISO-8859-1 | Select the files encoding method. |
| Field names | Populate fields from first record by clicking on the button . | |
| +/- | Add or remove a field name. | |
| View file | View file data. | |
| Post process | Do nothing | Select an option after file has been processed |
| Other tab | ||
| Description | This text file is an extract from the telephone system. | A description of this database. |
| Usage tab | ||
| Associated policies | Shows associated policies with this database. Double click an entry to go to policy. |
View of text file data
Creating LDIF File Data Source
Open Provisioning Configurator and click on the databases category and select “File”, and then “LDIF File”.
Data Source Settings
| Option | Value | Description |
| General tab | ||
| Specific file | Enabled | Select a specific file. |
| Scan file directory | Not enabled | Scan a file directory and match file after a pattern. Example filename.ldif. |
| File name | E:\Install\Provisioning\peopleExport.ldif | Select the file name. |
| View file | View file data. | |
| Post process | Do nothing | Select an option after file has been processed |
| Other tab | ||
| Description | This text file is an extract from the LDAP directory. | A description of this database. |
| Usage tab | ||
| Associated polices | Shows associated policies with this database. Double click a entry to go to policy. |
View of LDIF file data
Create a Web Service Data Source
Included with Identity Provisioning are two web service packages (WSDD package):
- A package for sending from one Identity Provisioning to another Identity Provisioning service. One PIP instance is using the action “Session Object Transmitter” acting as a web service client and the other PIP instance is the “Web Service Receiver”
- A generic web service that can handle request of typical LDAP directory request. There is four types of request for objects: CREATE, MODIFY, DELETE and SEARCH.
There is support for custom made web service used in development projects.
Web Service Listener Options and Certificate
Configure web service port and certificate to use from the menu “Tools-Options” or the button from the tool bar.
Tools-Options-Web Service Listener
Creating a Web Service Receiver Data Source
Open Provisioning Configurator and click on the Data Sources category and select “Web Service”. In this example we prepare a web service listener.
Policy Using a Web Service as Data Source
In a policy that use this web service data source, an administrative user account and password must be configured to allow messages to be exchanged.
Policy using web service data source
Data Source Settings for Custom Web Service
| Option | Value | Description |
| Web Services tab | ||
| WSDD Package
Custom Web Service |
/com/acme/provisioning/deploy.wsdd | The Java package where the custom wsdd file describing the web service resides. Example: /com/acme/provisioning/deploy.wsdd |
| Other | ||
| Description | PIP web service listener for customers. | A description of this database. |
| Usage | ||
| Associated polices | Shows associated policies with this database. Double click a entry to go to policy. |
Configure SMTP Settings
Several actions included in Identity Provisioning is sending e-mail. A typical example could be to send reports or alerts to various stakeholders.
SMTP Settings
| Option | Value | Description |
| SMTP Host | smtp.yourdomain.com | The SMTP server IP-address or DNS |
| SMTP Port | 25 | The SMTP server port, usually 25 |
| SSL/TLS | Enabled | If the SMTP server requires SSL/TLS |
| Mime Encode | Enter the mime encoding. If no encoding is specified, iso-8859-1 will be used. | |
| Sender email | PIPService@yourdomain.com | The senders email address |
| Sender name | Identity Provisioning | The name of the sender |
| Master email | PIPService@yourdomain.com | The email address that will be used if no one is configured in an action |
| Authentication | ||
| User name | IdentityProvisioning | User name for authentication to the SMTP server. |
| Password | ******** | User password for authentication to the SMTP server. |
Click on button Test Mail to test configuration and send a mail to sender email address.
Creating a Schedule
A schedule is used by policy to define when it should run. A policy can be associated with more than one schedule.
Week Day Schedule Settings
| Option | Description |
| Basic tab | |
| Name | Set a name describing the schedule |
| Days | Enable days the scheduler should run |
| Time | |
| Fixed hour | Run at fixed hour (24 hour format) |
| Interval | Enter the interval in minutes. To select seconds add a s at the end of the value. Example: 10s for every 10 seconds |
| Run once | Run only once and then exit. |
| Shutdown on next schedule | If PIP service is currently running, checking this will shutdown AAM when next schedule occur! |
| Exclude hours tab | |
| Exclude the scheduler to run on the following hours. | Several entry can exists. Use 24 hour format. Syntax: HH:MM-HH:MM. Example: 01:00-05-00 |
| Exclude dates tab | |
| Exclude dates | Several entry can exists. Excludes the scheduler to run on the following dates. |
| General tab | |
| Stop Scheduler at Policy Failure | If a policy in this scheduler is failing, the rest of the policies will not start to execute. The next time it’s time for the scheduler to start, it will run all policies again. |
| Stop Following Policies but Run Scheduler at Next Scheduled Time | If a policy in this scheduler is failing, the rest of the policies will not start to execute. The next time it’s time for the scheduler to start, it will run all policies again. Default not enabled |
| Stop Following Policies and Disable Scheduler until Service is Restarted | If a policy in this scheduler is failing, the rest of the policies will not start to execute. The scheduler will not start to run any policies again until the service is restarted. Default not enabled |
| Description | Enter a description for the schedule. Example: This schedule is set to run every 90 minutes except during hours 01:00-05-00. |
Specific Dates Schedule Settings
| Option | Description |
| Advanced | |
| Run at time | Specify a time when the scheduler should run (24 hour format). |
| Repeated days every month | Several entries can exist. Repeated days the scheduler should run every month. |
| Specific dates | Several entries can exist. Specific dates to run the schedule. |
Schedule example
Log Settings
Configure log settings. Default the log level is set to “Info” for the Identity Provisioning service.
Audit logging is only used in “output” actions .eg.
Write To LDAP
Write to SQL
Write and MAtch to SQL
Rename LDAP Object
Post HTTP Handler
Fix LDAP Backlinks
Move LDAP Object
Launch Application
Delete Object in LDAP
Delete Attribute Value in LDAP
Create LDAP Object
Manage LDAP Object Members
An example of an audit event using the action Delete Object in LDAP can look like this:
“2012-12-04 13:15:00,553: INFO: plugins.v3.DeleteObjectInLDAP Object “CN=astrom,OU=Users,DC=Company,DC=local” was deleted in directory “Microsoft ADLDS”.
| Option | Value | Description |
| Service Log Settings | ||
| Log File | logs/provisioning.txt | Enter the log filename (including full or relative part) to the log file for the service. |
| Level | Info | Severity level. Default the log level is set to “Info”. |
| Max Log File Size | 20000 | Enter the maximum size of the logfile before rolling (in kilobytes) |
| Max backup index | 50 | Enter the number of backup index before starting to removing the oldest. |
| Use External Logging | Default not enabled | To use external logging read more here |
| Configurator Log Settings | ||
| Log to Console | Default not enabled | If all logging should be displayed in the Java Console (system.out) |
| Log File | logs/configurator.txt | Enter the log filename (including full or relative part) to the log file for the Provisioning Configurator. |
| Level | Debug | Severity level.Default the log level is set to “Debug”. |
| Max log-file size | 20000 | Enter the maximum file size before rolling in kilobyte. |
| Max backup index | 50 | Enter the number of backup index before removing the oldest entry. |
| Audit Log Settings | ||
| Use Audit Logging | Default not enabled | |
| Log FIle | logs/auditlog.txt | Enter the log file name (including full or relative part) to the log file for the audit log. |
| Max log-file size | 20000 | Enter the maximum file size before rolling in kilobyte. |
| Max backup index | 25 | Enter the number of backup index before removing the oldest entry. |
Log Settings
Alerts
Alerts can be used if something unpredictable happens.
| Option | Value | Description |
| Enable alerts | Enabled | Enable if alerts should be used |
| Enabled | If sending the alert by SMTP. | |
| Run Policy | Select a Policy that should be executed when an Alert is generated.
For each recipient a Session Object will created that contains these Session Attributes: recipient The address of the recipient. message The alert message |
|
| Notify recipients | firstname.lastname@yourcompany.com | Add a recipient to the address list. This can be an email address if using the Mail check box or recipients that can be called from a Run policy |
| Policy Failure | Enabled | Send an alert if policy fails |
| Preflight check failure | Enabled | Send an alert if a preflight check on a policy fails. |
| Schedule failure | Enabled | Send an alert if a schedule is not complete in a specific number of minutes. |
| Max minutes for schedules | 720 | The maximum minutes a schedule can run before generating an alert. |
Actions
One or multiple actions contain definitions of what shall be executed for one or multiple session objects. A policy also states in which order one or multiple actions shall be applied.
Actions can be simple. For example, changing the value of a specific session attribute, or creating a Microsoft Excel file with contents from objects- and session attributes. Actions can also be more advanced, for instance synchronizing users between two or more data sources.
Identity Provisioning contains a number of accompanying actions that can be used to build the logic that shall be applied to the information that is being parsed. These actions are divided into three different categories that state the specific type, Input, Process, Output.
Full description of all actions and usage examples can be read in the Action documentation.
Input Actions
Input actions are used to parse and create new session objects and associated session attributes. It can also complement an existing session object with information from other data sources and add these as new session attributes.
Example of “input” actions
| Name | Description |
| Add Data from SQL | Add data from an JDBC/ODBC database. |
| Add Static Attribute | Adds a static attribute and value. If the attribute is unicodePwd, the value will automatically be converted to Microsoft Active Directory format. |
| Get Attributes from LDAP | Get attribute value from an LDAP object. |
| Search LDAP | Searches an LDAP database and creates session objects from the result. |
Table with examples of “input” actions
Process Actions
Process actions are used to change existing session objects and associated session attributes. There are a large number of available actions in this category.
Examples of usage areas:
- Control that the session attribute “mail” follows the standard. If not, change the attribute to the correct standard.
- Convert a time stamp format so that it, in a later action, can be exported to a Microsoft Excel sheet where it can be more easily read.
Example of “process” actions
| Name | Description |
| Certificate Handler | Manage certificate information |
| Check Group Membership | Check if a user belongs to a specific LDAP group. Support nested groups. |
| Convert Session Attribute to Session Object | Converting a session attribute to a session object. Example: Convert all values in the “members” attribute to session objects. |
| Create Password Value | Generate a password attribute. |
| Date Handler | Convert a date value from one format to another. Includes support for deleting session objects if a date is older or newer than a specific date. |
| Format Attribute Value | Format a session attribute value. If the attribute is unicodePwd, the value will automatically be converted to Microsoft Active Directory format. |
| Match to LDAP Object | Match LDAP object |
| Nested Group Extract | A nested group extractor. Will check all members in a session attribute and if they are a group object, and if so it will include all it’s members. |
| String Replacer | Replace or remove characters in a string. |
Table with example of “Process” actions and description
Output Actions
Output actions are used to write/save data from session objects and associated session attributes to one or more sources (LDAP, database, file, web services, etc.).
Examples of usage areas:
- Create a Microsoft Excel or a PDF report and send via e-mail to an indicated recipient.
- Synchronize session objects that have been collected from an LDAP database and that have been changed via actions, and save these to an SQL database.
- Write back changed session objects to their original data source.
Example of “output” actions
| Name | Description |
| Auto Attribute Populator | Uses Idapurl (RFC 2255) and syntax to point out an object and attributes containing values that shall be parsed and where values shall be parsed and update a new or existing session attribute. Can be used for example to update and control group memberships and to update/synchronize these to a group in another database. |
| Create LDAP Object | Create an LDAP object based on session objects and attributes. |
| Excel Export | Create reports in an Excel-format. |
| Google Apps User Integration | Google apps user provisioning action. Create, modify and delete Google apps user accounts |
| Launch Application | Launch an external application or script. If there will be ANY parameter, wrap ‘ ‘ around for ALL parameters |
| Send Mail | Send mail with information about one or more session objects. Possible to add file attachments. |
| Session Object Transmitter | Sending session objects to another Identity Provisioning through web services. |
| Write to LDAP | Write attribute values to LDAP. |
| Write to SQL | Write attribute values to SQL. |
Table with example of output actions
Import External Action Package
There are a number of external action packages. These action packages have been created for specific integration with application or cloud/service providers. Contact PhenixID support for more information.
To import a external action package go to Tools-Action Package Manager or click icon in tool bar
Action Package Manager
In this example a package for Windows Powershell is imported. When Action Package Manager window is open click on Import from File and browse to the action package.
Import action package
Accept default action package name or give it a more descriptive name.
Action package name
Click OK and then close Action Package Manager. The new action is now available for configuration.
Powershell action
API for Developers
There is also an API to develop customized actions in the event that none of the associated actions are suitable for the specific purpose. See documentation here