Managed Organizations
Organization objects let you arrange and manage users in hierarchical trees. Organizations also let you give users fine-grained administrative privileges to various parts of the tree, based on their location in that tree. For example, an administrator of one organization might have full access to the users within that organization, but no access to the users in an adjacent organization.
An organization object (defined in the managed object configuration) has an array of admins, an array of owners, and an array of members. These relationship properties enable the hierarchical organization model. Users and organizations have a set of relationship-derived virtual properties used by the delegated administration filters to provide the visibility and access constraints that underpin the organization model. Users have the ids of all the organizations of which they are members, and organizations have the ids of all their admin and owner users.
Only IDM administrative users can create top-level organizations. Within organizations, there are various levels of privileges, depending on how a user is related to the organization.
The following diagram gives a high-level overview of how privileges are assigned to various entities in the organization hierarchy:
An organization owner can manipulate all organizations, members, and admins in their ownership area. The ownership area includes any part of the tree in or beneath the organization that they own. So, in the preceding image, the owner of Org A can do the following anywhere within their ownership area (the pale green region):
Add and update members.
Note
Organization owners only have access to the members in their ownership area. So, an owner can create a new user as a member of their organization, but cannot add an existing managed user to their organization if that user is outside of their ownership area (that is, in any part of the tree not in or beneath the organization that they own).
Add and update sub-organizations, such as Org B and Org C.
Give an organization member the
adminprivilege for the parent organization or any sub-organizations.
An organization owner cannot create additional owners in their root organization.
Caution
An organization owner does not have to be a member of the organization. If the organization owner is a member of the organization, that owner is automatically in the administrative area of any admins of that organization, and can therefore be manipulated by an organization admin. To avoid accidentally giving organization admins privileges over an organization owner, do not make the owner a member of the organization.
An organization admin has control over their administrative area. The administrative area includes any part of the tree in or beneath the organization that they administer. In the preceding diagram, the administrative area of Admin A is shaded red. The administrative areas of Admins B and C are shaded grey. An admin can do the following in their administrative area:
Add and update members.
Note
Organization admins only have access to the members in their administrative area. So, an admin can create a new user as a member of their organization, but cannot add an existing managed user to their organization if that user is outside of their administrative area (that is, in any part of the tree not in or beneath the organization that they administer).
Add and update sub-organizations of the organization they administer.
Notice that Admin B and C are outside of the administrative area of Admin A. An organization admin cannot create additional admins in their administrative areas.
An organization admin must be a member of the organization, so must either be an existing member of the organization, or must be given the
memberOfOrgrelationship at the time they are created.Organization members are regular users, with no special privileges in the organization hierarchy.
Managed users have a
memberOfOrgIDsrelationship-derived virtual property that lists the organizations to which the user belongs (either directly, or through any parent organizations).Parent and child organizations are essentially relationships between an organization and existing organizations in the tree.
Important
Organizations rely on the privilege mechanism. To use organizations effectively, you must therefore enable dynamic role calculation, as required by the privilege model.
Note
This is not required if you are authenticating through AM, using the rsFilter authentication module.
Select in the Admin UI or set the enableDynamicRoles property to true in the sessionModule in your conf/authentication.json file:
"sessionModule" : {
"name" : "JWT_SESSION",
"properties" : {
"maxTokenLifeMinutes" : 120,
"tokenIdleTimeMinutes" : 30,
"sessionOnly" : true,
"isHttpOnly" : true,
"enableDynamicRoles" : true
}
}For more information about dynamic role calculation, see "Dynamic Role Calculation".
Manage Organizations Over REST
IDM provides RESTful access to managed organizations, at the context path /openidm/managed/organization. You can add, change, and delete organizations by using the Admin UI or over the REST interface. To use the Admin UI, select Manage > Organization.
The following examples show how to add, change, and delete organizations over the REST interface. For a reference of all managed organization endpoints and actions, see "Managed Organizations". You can also use the REST API Explorer as a reference to the managed object REST API.
Only IDM administrators can create top level organizations.
curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "If-None-Match: *" \ --request PUT \ --data '{ "name": "example-org" }' \ "http://localhost:8080/openidm/managed/organization/example-org"{ "_id": "example-org", "_rev": "00000000bc9871c8", "adminIDs": [], "ownerIDs": [], "parentAdminIDs": [], "parentIDs": [], "parentOwnerIDs": [], "name": "example-org" }
IDM administrators can create owners for an organization. This example makes bjensen the owner of the organization created previously. The example assumes that the managed user bjensen already exists:
curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{"_ref":"managed/user/bjensen"}' \ "http://localhost:8080/openidm/managed/organization/example-org/owners?_action=create"{ "_id": "fcb0f4d0-dad2-4138-a80c-62407a8e831e", "_rev": "00000000496d9920", "_ref": "managed/user/bjensen", "_refResourceCollection": "managed/user", "_refResourceId": "bjensen", "_refProperties": { "_id": "fcb0f4d0-dad2-4138-a80c-62407a8e831e", "_rev": "00000000496d9920" } }
This example lists the organizations of which bjensen is an owner:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user/bjensen/ownerOfOrg?_queryFilter=true"{ "result": [ { "_id": "fcb0f4d0-dad2-4138-a80c-62407a8e831e", "_rev": "00000000496d9920", "_ref": "managed/organization/example-org", "_refResourceCollection": "managed/organization", "_refResourceId": "example-org", "_refProperties": { "_id": "fcb0f4d0-dad2-4138-a80c-62407a8e831e", "_rev": "00000000496d9920" } } ], ... }
Organization owners can create members in the organizations that they own. In this example bjensen creates user scarter and makes him a member of the organization created previously:
curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: bjensen" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request PUT \ --data '{ "userName": "scarter", "sn": "Carter", "givenName": "Steven", "mail": "scarter@example.com", "password": "Th3Password", "memberOfOrg": [{"_ref": "managed/organization/example-org"}] }' \ "http://localhost:8080/openidm/managed/user/scarter"{ "_id": "scarter", "_rev": "00000000eac81c23" }
Organization owners can view the members of the organizations that they own. In this example bjensen lists the members of example-org:
curl \ --header "X-OpenIDM-Username: bjensen" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/organization/example-org/members?_queryFilter=true"{ "result": [ { "_id": "b71e8dd9-6224-466f-9630-4358a69c69fd", "_rev": "0000000038ea999e", "_ref": "managed/user/scarter", "_refResourceCollection": "managed/user", "_refResourceId": "scarter", "_refProperties": { "_id": "b71e8dd9-6224-466f-9630-4358a69c69fd", "_rev": "0000000038ea999e" } } ], ... }
Organization owners can create admins of the organizations that they own. An organization admin must be a member of the organization. In this example bjensen makes scarter an admin of example-org:
curl \ --header 'Content-Type: application/json' \ --header "Accept-API-Version: resource=1.0" \ --header 'X-OpenIDM-Username: bjensen' \ --header 'X-OpenIDM-Password: Th3Password' \ --request PATCH \ --data '[ { "operation": "add", "field": "/admins/-", "value": { "_ref": "managed/user/scarter" } } ]' \ "http://localhost:8080/openidm/managed/organization/example-org"{ "_id": "example-org", "_rev": "000000009c248a4a", "adminIDs": [ "scarter" ], "ownerIDs": [ "bjensen" ], "parentAdminIDs": [], "parentIDs": [], "parentOwnerIDs": [], "name": "example-org" }
An organization owner, or admin, can only see the organizations that they own or administer. In this example, the admin scarter lists the organizations, and sees only those of which he is an admin:
curl \ --header "X-OpenIDM-Username: scarter" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/organization?_queryFilter=true"{ "result": [ { "_id": "example-org", "_rev": "000000009c248a4a", "adminIDs": [ "scarter" ], "ownerIDs": [ "bjensen" ], "parentAdminIDs": [], "parentIDs": [], "parentOwnerIDs": [], "name": "example-org" } ], ... }
Organization admins can also add members to the organizations they administer. In this example, the organization admin, scarter, creates a new member, jsanchez, and makes her a member of example-org:
curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: scarter" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request PUT \ --data '{ "userName": "jsanchez", "sn": "Sanchez", "givenName": "Juanita", "mail": "jsanchez@example.com", "password": "Th3Password", "memberOfOrg": [{"_ref": "managed/organization/example-org"}] }' \ "http://localhost:8080/openidm/managed/user/jsanchez"{ "_id": "jsanchez", "_rev": "00000000f9341bd6" }
Organization owners and admins can list the organizations of which a user is a member, as long as those organizations are owned or administrated by them. In this example, scarter lists the organizations of which jsanchez is a member:
curl \ --header "X-OpenIDM-Username: scarter" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user/jsanchez?_fields=memberOfOrg"{ "_id": "jsanchez", "_rev": "00000000f9341bd6", "memberOfOrg": [ { "_ref": "managed/organization/example-org", "_refResourceCollection": "managed/organization", "_refResourceId": "example-org", "_refProperties": { "_id": "078d14b2-e5f1-4b21-9801-041138e691f4", "_rev": "00000000ac2e9927" } } ] }
The organization established by the previous set of examples can be represented as follows:
In this organization, both bjensen and scarter can create and delete sub-organizations, also known as child organizations, of example-org, and can create and delete members within these child organizations.
The following example shows how to add and delete child organizations over the REST interface:
Organization owners and admins can create and manage child organizations of the organizations that they own or administer. In this example, the organization owner, bjensen, creates a new organization named example-child-org, and makes it a child organization of example-org:
curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: bjensen" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --header "If-None-Match: *" \ --request PUT \ --data '{ "name": "example-child-org", "parent": {"_ref": "managed/organization/example-org"} }' \ "http://localhost:8080/openidm/managed/organization/example-child-org"{ "_id": "example-child-org", "_rev": "00000000db852a9d" }
Note
The organization model is based on delegated administration. As with delegated administration, you cannot explicitly change the relationship endpoints. So, for example, so you cannot create, update, delete or patch relationship edges. The following type of request is therefore not possible with the organization model:
curl \
--header "Content-Type: application/json" \
--header "X-OpenIDM-Username: bjensen" \
--header "X-OpenIDM-Password: Th3Password" \
--header "Accept-API-Version: resource=1.0" \
--header "If-None-Match: *" \
--request PUT \
--data '{
"name": "example-child-org",
"parent": {"_ref": "managed/organization/example-org"}
}' \
"http://localhost:8080/openidm/managed/organization/children?_action=create"Organization owners and admins have access to any organizations that are child organizations of their own orgs. In this example, admin scarter lists his visible organizations again:
curl \ --header "X-OpenIDM-Username: scarter" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/organization?_queryFilter=true"{ "result": [ { "_id": "example-org", "_rev": "000000009c248a4a", "adminIDs": [ "scarter" ], "ownerIDs": [ "bjensen" ], "parentAdminIDs": [], "parentIDs": [], "parentOwnerIDs": [], "name": "example-org" }, { "_id": "example-child-org", "_rev": "00000000db852a9d", "adminIDs": [], "ownerIDs": [], "parentAdminIDs": [ "scarter" ], "parentIDs": [ "example-org" ], "parentOwnerIDs": [ "bjensen" ], "name": "example-child-org" } ], ... }
Notice that scarter can now see the example-child-org that bjensen created in the previous example.
Manipulating Organizational Hierarchies in High Latency Environments
The relationship-derived virtual properties that support the organization model are generally calculated in response to relationship signals that travel down the organization tree hierarchy. Imagine, for example, that a new root organization is added to an existing organization hierarchy (or that a new admin or owner is added to the root of an existing organization hierarchy). The relationship signals that trigger relationship-derived virtual property calculation are propagated down the organization hierarchy, and to all members of the organizations in this hierarchy. This, in turn, updates their relationship-derived virtual property state.
If there are many thousands of members of the organizations in the hierarchy, this operation can take a long time to complete. It is therefore best practice to grow an organization hierarchy downwards, adding new organizations as leaves to an existing hierarchy, and adding new admins and members to the leaves in the hierarchy tree. This is preferable to growing the hierarchy upwards, starting with the leaves, and growing the hierarchy up towards the root.
If you must add a new root to an existing organization hierarchy with many organizations and many members, or a new admin or owner to an organization near the top of the hierarchy, rather perform this request over the command-line, using the examples provided in the previous section.