4744N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
446N/A * Copyright 2015 ForgeRock AS. All rights reserved.
446N/A * The contents of this file are subject to the terms
446N/A * of the Common Development and Distribution License
446N/A * (the License). You may not use this file except in
446N/A * compliance with the License.
446N/A * You can obtain a copy of the License at
446N/A * See the License for the specific language governing
446N/A * permission and limitations under the License.
446N/A * When distributing Covered Code, include this CDDL
446N/A * Header Notice in each file and include the License file
446N/A * If applicable, add the following below the CDDL Header,
446N/A * with the fields enclosed by brackets [] replaced by
873N/A * your own identifying information:
446N/A * "Portions Copyrighted [year] [name of copyright owner]"
446N/ARoles Sample: Roles and Provisioning
5073N/A=====================================
446N/AOne of the great features of OpenIDM Roles is the ability to provision a set
446N/Aof attributes based on role membership.
4744N/ALet's take a concrete example and continue with our Employee and Contractor
4744N/Aroles example that was provided in the _crudops_ sample. This example will
4744N/Aalso build on _sample2b_ to provision user entries from Managed User to OpenDJ.
4744N/AAs an employee of the company a worker should be added to a couple of groups in
4744N/AOpenDJ (presumably to get access to some internal applications): the Employees
4744N/Agroup and the Chat Users group. But as a Contractor, workers will be added
4744N/Ato the Contractors group only. We also want the type of employee to be set
4744N/Aproperly in OpenDJ, based on the role allocated to each user.
4744N/APre-requisites: we assume that you are familiar with _sample2b_ and already
4744N/Ahave installed OpenDJ according to the instructions and configuration provided
4744N/Ain that sample. We also assume here that you have reconciled the entries as
4744N/Aexplained in that sample's section 2 & 4, but for this current sample.
4744N/Aif that wasn't done previously.
5073N/AThis sample should be run like the others using the following command:
4744N/Ain order to pick up the configuration that's provided here. The reconciliation
4744N/Aof the external system (OpenDJ) can also performed easily via the UI by running
4744N/Areconciliation for the first mapping (DJ --> Managed User) in order to populate
4744N/AThis sample provides all the information you need to cover the following use
4744N/A* Update a role with an entitlement (called assignments in OpenIDM)
4744N/A* Assign a role to a user and observe the entitlements for that user
4744N/A* Specify how entitlements will be propagated to an external system (OpenDJ)
4744N/A* Deallocate a role from a user and observe how the entitlements are withdrawn
4744N/ANote: throughout this document we refer to entitlements and assignments
4744N/Ainterchangeably, as they relate to roles.
4744N/A1. Update the Employee role to add the correct groups and employee type
4744N/ALet's take a look at the roles we created in the _crudops_ sample first:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "description" : "Role assigned to workers on the payroll."
4744N/A "description" : "Role assigned to contract workers."
4744N/A "pagedResultsCookie" : null,
4618N/A "remainingPagedResults" : -1
4744N/ANow, according to our company's policy, we need to make sure that every employee
4744N/Awill have the correct _employeeType_ attribute in OpenDJ (corporate directory).
4744N/AThis is achieved in several steps. The first one is to add an _assignments_
4744N/Aproperty to the Employee role. Since we already have that role we will just
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "assignmentOperation" : "mergeWithTarget",
4744N/A "unassignmentOperation" : "removeFromTarget"
4744N/A {"properties":{"name":"Employee","description":"Role assigned to workers on the payroll."},"_id":"Employee","_rev":"2","assignments":{"ldap":{"attributes":[{"name":"employeeType","value":"Employee","assignmentOperation":"mergeWithTarget","unassignmentOperation":"removeFromTarget"}]}}}
4744N/A2. Allocate the Employee role to bjensen
4744N/AIn order to fully leverage _sample2b_ we will use Barbara Jensen as the employee.
4744N/ALet's take a look at the roles we should have right now:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "description" : "Role assigned to workers on the payroll."
4744N/A "assignmentOperation" : "mergeWithTarget",
4744N/A "unassignmentOperation" : "removeFromTarget"
4744N/A "description" : "Role assigned to contract workers."
4744N/A "pagedResultsCookie" : null,
5073N/A "remainingPagedResults" : -1
4744N/AOr something along those lines.
4744N/ANote: since the last step in the _crudops_ sample was to delete the Contractor
4744N/Arole via the Admin UI, you might have to issue the following request again to
4744N/Apopulate the Contractor role:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A --header "If-None-Match: *" \
4744N/A "description": "Role assigned to contract workers."
4744N/AOnce you have both roles listed, you just need to assign the Employee role to
4744N/Abjensen. But first you need to find out what the identifier is for bjensen's
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4618N/A "_id" : "8ff9639f-2a89-48a2-a0fd-9df4d5297eeb"
4744N/A "pagedResultsCookie" : null,
4744N/A "remainingPagedResults" : -1
4744N/ATherefore you can assign the Employee role by using:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
5073N/A {"displayName":"Barbara Jensen","description":"Created for OpenIDM","givenName":"Barbara","mail":"bjensen@example.com","telephoneNumber":"1-360-229-7105","sn":"Jensen","userName":"bjensen","ldapGroups":["cn=openidm2,ou=Groups,dc=example,dc=com"],"accountStatus":"active","roles":[{"_ref":"
managed/role/Employee","_refProperties":{"_id":"193a60b6-7b2e-467e-a8fc-a59d67fca858","_rev":"1"}}],"lastPasswordSet":"","postalCode":"","stateProvince":"","passwordAttempts":"0","lastPasswordAttempt":"Fri Apr 17 2015 16:57:21 GMT-0000 (UTC)","postalAddress":"","address2":"","country":"","city":"","effectiveRoles":[{"_ref":"
managed/role/Employee","_refProperties":{"_id":"193a60b6-7b2e-467e-a8fc-a59d67fca858","_rev":"1"}}],"_id":"8ff9639f-2a89-48a2-a0fd-9df4d5297eeb","_rev":"4","effectiveAssignments":{"ldap":{"attributes":[{"name":"employeeType","value":"Employee","assignmentOperation":"mergeWithTarget","unassignmentOperation":"removeFromTarget","assignedThrough":"
managed/role/Employee"}]}}}
4744N/ALet's take a closer look at bjensen's entry for what we're really interested
4744N/Ain,
i.e. the roles, effective roles and effective assignments:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "_id" : "8ff9639f-2a89-48a2-a0fd-9df4d5297eeb",
4744N/A "_id" : "193a60b6-7b2e-467e-a8fc-a59d67fca858",
4744N/A "_id" : "193a60b6-7b2e-467e-a8fc-a59d67fca858",
4744N/A "assignmentOperation" : "mergeWithTarget",
4744N/A "unassignmentOperation" : "removeFromTarget",
4744N/A "pagedResultsCookie" : null,
4744N/A "remainingPagedResults" : -1
4744N/AWe can now clearly see the impact of the new property we added to the role. The
4744N/Auser now has a new (calculated) property which includes the set of assignments
4744N/A(or entitlements) that pertain to the user with that role. Currently this only
4744N/Alist the _employeeType_ attribute.
4744N/A3. Pushing assignments out to OpenDJ (external system)
4744N/AThis sample's
sync.json adds on to _sample2b_'s mapping by incorporating an
4744N/Aadditional property, called _assignmentsToMap_:
5073N/A "name" : "managedUser_systemLdapAccounts",
4744N/A "links" : "systemLdapAccounts_managedUser",
4744N/ANow if you take a look at bjensen directly in the directory you should see the
4744N/Aattribute _employeeType_ being populated properly:
4744N/A $ ldapsearch -p 1389 -h localhost -b "dc=example,dc=com" -D "cn=Directory Manager" -w - -s sub uid=bjensen dn uid employeeType
4744N/A dn: uid=bjensen,ou=People,dc=example,dc=com
4744N/ANow let's make this a little more interesting by adding the groups that an
4744N/AEmployee should have in the corporate directory (OpenDJ).
4744N/AWe just need to update the Employee role with the appropriate entitlements.
4744N/AFirst, let's look at the Employee role entry one more time:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "description" : "Role assigned to workers on the payroll."
4744N/A "assignmentOperation" : "mergeWithTarget",
4744N/A "unassignmentOperation" : "removeFromTarget"
4744N/AWe simply need to add the entitlement for groups under:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "cn=Employees,ou=Groups,dc=example,dc=com",
4744N/A "cn=Chat Users,ou=Groups,dc=example,dc=com"
4744N/A "assignmentOperation" : "mergeWithTarget",
4744N/A "unassignmentOperation" : "removeFromTarget"
4744N/A {"properties":{"name":"Employee","description":"Role assigned to workers on the payroll."},"_id":"Employee","_rev":"3","assignments":{"ldap":{"attributes":[{"name":"employeeType","value":"Employee","assignmentOperation":"mergeWithTarget","unassignmentOperation":"removeFromTarget"},{"name":"ldapGroups","value":["cn=Employees,ou=Groups,dc=example,dc=com","cn=Chat Users,ou=Groups,dc=example,dc=com"],"assignmentOperation":"mergeWithTarget","unassignmentOperation":"removeFromTarget"}]}}}
4744N/AAfter adding this new entitlement to the Employee role, bjensen should be
4744N/Aadded to the Chat Users and Employees groups.
4744N/A $ ldapsearch -p 1389 -h localhost -b "dc=example,dc=com" -D "cn=Directory Manager" -w - -s sub uid=bjensen dn uid employeeType isMemberOf
4744N/A dn: uid=bjensen,ou=People,dc=example,dc=com
4744N/A isMemberOf: cn=Chat Users,ou=Groups,dc=example,dc=com
4744N/A isMemberOf: cn=Employees,ou=Groups,dc=example,dc=com
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "dn" : "uid=bjensen,ou=People,dc=example,dc=com",
4744N/A "employeeType" : "Employee",
4744N/A "ldapGroups" : [ "cn=Chat Users,ou=Groups,dc=example,dc=com", "cn=Employees,ou=Groups,dc=example,dc=com", ]
4744N/A "pagedResultsCookie" : null,
4744N/A "remainingPagedResults" : -1
4744N/ALet's continue with adding the appropriate entitlements to the Contractor role
4744N/Aand allocating that role to jdoe, who is a contractor and therefore not
4744N/Aentitled to access the internal chat application:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "cn=Contractors,ou=Groups,dc=example,dc=com"
4744N/A "assignmentOperation" : "mergeWithTarget",
4744N/A "unassignmentOperation" : "removeFromTarget"
4744N/A "assignmentOperation": "mergeWithTarget",
4744N/A "unassignmentOperation": "removeFromTarget"
4744N/A {"properties":{"name":"Contractor","description":"Role assigned to contract workers."},"_id":"Contractor","_rev":"2","assignments":{"ldap":{"attributes":[{"name":"ldapGroups","value":["cn=Contractors,ou=Groups,dc=example,dc=com"],"assignmentOperation":"mergeWithTarget","unassignmentOperation":"removeFromTarget"},{"name":"employeeType","value":"Contractor","assignmentOperation":"mergeWithTarget","unassignmentOperation":"removeFromTarget"}]}}}
4744N/ANow we just need to allocate the Contractor role to jdoe and he should be
4744N/Aautomatically added to the Contractors group in OpenDJ. Let's first take a look
4744N/Aat jdoe's entry to make sure we know the value of the identifier:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "_id" : "3f9ada28-2809-4909-aadf-815567b00a4d"
4744N/A "pagedResultsCookie" : null,
4744N/A "remainingPagedResults" : -1
4744N/ANow we can update jdoe's entry with the Contractor role:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
5073N/A {"_id":"3f9ada28-2809-4909-aadf-815567b00a4d","_rev":"2","displayName":"John Doe","description":"Created for OpenIDM","givenName":"John","mail":"jdoe@example.com","telephoneNumber":"1-415-599-1100","sn":"Doe","userName":"jdoe","accountStatus":"active","lastPasswordSet":"","postalCode":"","stateProvince":"","passwordAttempts":"0","lastPasswordAttempt":"Wed Oct 07 2015 13:17:57 GMT-0700 (PDT)","postalAddress":"","address2":"","country":"","city":"","effectiveRoles":[{"_ref":"
managed/role/Contractor","_refProperties":{"_id":"e8295a1f-f367-489d-9573-f4ccbb2822d1","_rev":"1"}}],"effectiveAssignments":[{"assignedThrough":"
managed/role/Contractor","name":"ldap","attributes":[{"name":"ldapGroups","value":["cn=Contractors,ou=Groups,dc=example,dc=com"],"assignmentOperation":"mergeWithTarget","unassignmentOperation":"removeFromTarget"},{"name":"employeeType","value":"Contractor","assignmentOperation":"mergeWithTarget","unassignmentOperation":"removeFromTarget"}]}],"roles":[{"_ref":"
managed/role/Contractor","_refProperties":{"_id":"e8295a1f-f367-489d-9573-f4ccbb2822d1","_rev":"1"}}],"authzRoles":null}
5073N/ALet's now take a look at jdoe's entry in order to make sure that the proper
4744N/Aemployee type has been set and that jdoe has been added to the Contractors
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "telephoneNumber" : "1-415-599-1100",
4744N/A "employeeType" : "Contractor",
4744N/A "dn" : "uid=jdoe,ou=People,dc=example,dc=com",
4744N/A "ldapGroups" : [ "cn=openidm,ou=Groups,dc=example,dc=com", "cn=Contractors,ou=Groups,dc=example,dc=com" ],
4744N/A "mail" : "jdoe@example.com",
4744N/A "description" : "Created for OpenIDM",
4744N/A "_id" : "uid=jdoe,ou=People,dc=example,dc=com"
4744N/A "pagedResultsCookie" : null,
4744N/A "remainingPagedResults" : -1
4744N/A4. Removing a role from a user
4744N/ANow we know what happens with entitlements when a role is assigned to a user,
4744N/Alet's take a look at what happens when a role is deallocated from a user entry.
4744N/AAgain, we take a look at jdoe's entry to find out about its state:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "_id" : "3f9ada28-2809-4909-aadf-815567b00a4d",
4744N/A "_id" : "e8295a1f-f367-489d-9573-f4ccbb2822d1",
5073N/A "pagedResultsCookie" : null,
4744N/A "remainingPagedResults" : -1
4744N/AWe therefore need to remove the 1st element of the roles array (index = 0) in
4744N/Aorder to remove the Contractor role -- also please note the entry's identifier
4744N/Athat is used in the request's URL:
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A {"displayName":"John Doe","description":"Created for OpenIDM","givenName":"John","mail":"jdoe@example.com","telephoneNumber":"1-415-599-1100","sn":"Doe","userName":"jdoe","ldapGroups":["cn=openidm,ou=Groups,dc=example,dc=com"],"accountStatus":"active","roles":[],"lastPasswordSet":"","postalCode":"","stateProvince":"","passwordAttempts":"0","lastPasswordAttempt":"Fri Apr 17 2015 16:57:21 GMT-0000 (UTC)","postalAddress":"","address2":"","country":"","city":"","effectiveRoles":[],"_id":"3f9ada28-2809-4909-aadf-815567b00a4d","_rev":"3","effectiveAssignments":{}}
4744N/AThis results in jdoe's entry in OpenDJ not belonging to the Contractors group
4744N/Aanymore and its employee type being undefined."
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A "telephoneNumber" : "1-415-599-1100",
4744N/A "dn" : "uid=jdoe,ou=People,dc=example,dc=com",
4744N/A "ldapGroups" : [ "cn=openidm,ou=Groups,dc=example,dc=com" ],
4744N/A "mail" : "jdoe@example.com",
4744N/A "description" : "Created for OpenIDM",
4744N/A "_id" : "uid=jdoe,ou=People,dc=example,dc=com"
4744N/A "pagedResultsCookie" : null,
4744N/A "remainingPagedResults" : -1
4744N/ANote: some additional samples might be provided to demonstrate the different
5073N/Aassignment operations (merge, replace, remove, etc.).
5073N/AThis is pretty much everything you need to know about roles and entitlements
4744N/Aand how to manipulate them via the REST API.
4744N/AAt this time entitlements are not available through the Admin UI, but they
4744N/AIf you need to reload the Employee and Contractor roles entirely without
4744N/Agoing through each step in the samples, here are the REST requests
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A --header "If-None-Match: *" \
4744N/A "description": "Role assigned to workers on the payroll."
4744N/A "cn=Employees,ou=Groups,dc=example,dc=com",
4618N/A "cn=Chat Users,ou=Groups,dc=example,dc=com"
4744N/A "assignmentOperation" : "mergeWithTarget",
4744N/A "unassignmentOperation" : "removeFromTarget"
4744N/A "assignmentOperation" : "mergeWithTarget",
4744N/A "unassignmentOperation" : "removeFromTarget"
4744N/A --header "X-OpenIDM-Username: openidm-admin" \
4744N/A --header "X-OpenIDM-Password: openidm-admin" \
4744N/A --header "If-None-Match: *" \
4744N/A "description": "Role assigned to contract workers."
4744N/A "cn=Contractors,ou=Groups,dc=example,dc=com"
4744N/A "assignmentOperation" : "mergeWithTarget",
4744N/A "unassignmentOperation" : "removeFromTarget"
4744N/A "assignmentOperation" : "mergeWithTarget",
4744N/A "unassignmentOperation" : "removeFromTarget"