IDM Examples with Role Properties

This is a demo showing how to work with relationship properties (aka role parameters) in ForgeRock IDM >=6.5. In this demo I also show a solution to query this parameters. In the demo I create a role “Driver” and the role parameters are all cars that “belong” to the “Driver”. In some use cases I want to query not only “who is a driver?” or “Is the user a driver?”, I might also query “Who is the driver of this car?”.

I like to thank my dear college Tim Vogt who provided me with input.

You can download the code and test it here!

[bogo]

Purpose

The purpose of this demo is to show how relationship properties work with ForgeRock IDM 6.5x. You can define “role parameters” to present a individual information that connects the role to a user. This parameters can be added to the managed objects in IDM. The relationship represents a link from and to a role to a user object. In this links you can assign parameters (we call them relationship properties). This “parameters” are specific to this “link”. IDM leverage this by DEFAULT in the roles object that can be assigned to a user object. In this case a time constraint can be created to allow a role assignment to be only temporary for this user. The roles can also be used to provision to target systems like AD, LDAP and many other target systems you may have.

You can leverage this object model to any managed object in IDM. The advantage is to create a “linking parameter” individual to this link between this objects.

A second use case is, to query this parameter. In my example I create a role “driver” and assign this to a user with the parameter of the car license plate “M-HN 1234”. Now I would like to query “With user/s have the role driver for the car M-HN 1234”. The rest call can be adjusted to get the responds of user ids as well.

If you like one query to get, for example, all user objects as response, I recommend a custom endpoint that queries the car parameter and does a “complete” read of the users objects in return of the custom endpoint. Of course you can create a custom endpoint to enrich the respond as you need.

overview roles in idm

In the chapter “Managing Roles” you will find more details on how roles work with IDM in general.

Starting IDM

to start the demo just call

./startup.sh -p pathto/object-properties -w pathto/object-properties

config/prep of IDM

  • reconcile the csv demo users (you will have two users for testing: bjensen and acarter)
either do it from the admin console
http://localhost:8080/admin/#properties/systemCsvfileAccounts_managedUser/

or use a restcall:

curl --request POST \
  --url 'http://localhost:8080/openidm/recon?_action=recon&mapping=systemCsvfileAccounts_managedUser&waitForCompletion=true' \
  --header 'X-OpenIDM-Password: openidm-admin' \
  --header 'X-OpenIDM-Username: openidm-admin' \

Response:
{
    "_id": "9a7c0543-235b-4eb2-b289-e4a3b5233ce2-67370",
    "state": "SUCCESS"
}
  • create a role “driver”:
curl --request POST \
  --url 'https://localhost:8443/openidm/managed/role/?action=create' \
  --header 'X-OpenIDM-Password: openidm-admin' \
  --header 'X-OpenIDM-Username: openidm-admin' \
  --data '{\n	"_id": "driver",\n  "name": "Driver",\n  "description": "Example role for Drivers"\n}'

Response:
{
    "_id": "driver",
    "_rev": "0000000097815538",
    "name": "Driver",
    "description": "Example role for Drivers"
}

HINT: I am using here the _id to call the role directly with /managed/role/driver instead of a UUID!
role driver

use case: assigning the role “driver” to a user with the role property

I assign the role to a user with the parameter “cars” to the user “bjensen”:

curl --request PATCH \
  --url https://localhost:8443/openidm/managed/user/bjensen \
  --header 'Content-Type: application/json' \
  --header 'X-OpenIDM-Password: openidm-admin' \
  --header 'X-OpenIDM-Username: openidm-admin' \
  --data '[\n   {\n     "operation" : "add",\n     "field" : "/roles/-",\n     "value" : {\n     	"_ref": "managed/role/driver",\n        "_refProperties": { "cars": "M-HN 1234" }\n     }\n   }\n ]'

Response:
{
    "_id": "bjensen",
    "_rev": "0000000070dd1b5e",
    "mail": "bjensen@example.com",
    "givenName": "Barbara",
    "sn": "Jensen",
    "description": "Created By CSV",
    "userName": "bjensen",
    "telephoneNumber": "1234567",
    "accountStatus": "active",
    "effectiveRoles": [
        {
            "_ref": "managed/role/driver"
        }
    ],
    "effectiveAssignments": []
}

The user should now have the role driver:

from the relationship side it looks like this:

Example admin dashboard for relation user->role

Example admin dashboard for relation role->user

example curl

calling direct the role

curl --request GET \
  --url 'http://localhost:8080/openidm/managed/user/bjensen?_fields=roles'
  --header 'X-OpenIDM-Password: openidm-admin' \
  --header 'X-OpenIDM-Username: openidm-admin' \


sample respond:
{
    "_id": "bjensen",
    "_rev": "00000000a0aa11bb",
    "roles": [
        {
            "_ref": "managed/role/driver",
            "_refResourceCollection": "managed/role",
            "_refResourceId": "driver",
            "_refProperties": {
                "cars": "M-HN 1234",
                "_id": "1fc4f216-eedb-4c61-bc6e-d505e87d3e11",
                "_rev": "00000000d8639b19"
            }
        }
    ]
}

calling the user bjensen


curl --request GET \
  --url 'http://localhost:8080/openidm/managed/user/bjensen?_fields=roles' \
  --header 'X-OpenIDM-Password: openidm-admin' \
  --header 'X-OpenIDM-Username: openidm-admin' \

respond:

{
    "_id": "bjensen",
    "_rev": "00000000a0aa11bb",
    "roles": [
        {
            "_ref": "managed/role/driver",
            "_refResourceCollection": "managed/role",
            "_refResourceId": "driver",
            "_refProperties": {
                "cars": "M-HN 1234",
                "_id": "1fc4f216-eedb-4c61-bc6e-d505e87d3e11",
                "_rev": "00000000d8639b19"
            }
        }
    ]
}

use case: query relationship properties to a role property “car”

the query in a more reader friendly way:
openidm/repo/relationships/?_queryFilter=firstResourceCollection eq 'managed/role' and properties/cars eq "M-HN 1234"


curl --request GET \
  --url 'http://localhost:8080/openidm/repo/relationships/?_queryFilter=firstResourceCollection%20eq%20%27managed/role%27%20and%20properties/cars%20eq%20%22M-HN%201234%22' \
  --header 'X-OpenIDM-Password: openidm-admin' \
  --header 'X-OpenIDM-Username: openidm-admin' \

response:
{
    "result": [
        {
            "_id": "1fc4f216-eedb-4c61-bc6e-d505e87d3e11",
            "_rev": "00000000d8639b19",
            "firstResourceCollection": "managed/role",
            "firstResourceId": "driver",
            "firstPropertyName": "members",
            "secondResourceCollection": "managed/user",
            "secondResourceId": "bjensen",
            "secondPropertyName": "roles",
            "properties": {
                "cars": "M-HN 1234"
            }
        }
    ],
    "resultCount": 1,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}

postman collections

coming soon.

Copyright

============= Copyright 2014-2017 ForgeRock AS. All Rights Reserved

Use of this code requires a commercial software license with ForgeRock AS. or with one of its affiliates. All use shall be exclusively subject to such license between the licensee and ForgeRock AS.

This demo is based on the sample: One-Way Sync With CSV Sample

This sample demonstrates reconciliation between a CSV file and the managed/user repository. For documentation relating to this sample, see https://backstage.forgerock.com/docs/idm/6.5/samples-guide#chap-sync-with-csv

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.