--- title: Groups description: This is not a comprehensive Advanced Identity Software implementation guide. These sample setup instructions show a minimal integration of Advanced Identity Software components to get you started. component: platform version: 8 page_id: platform:sample-setup:groups canonical_url: https://docs.pingidentity.com/platform/8/sample-setup/groups.html page_aliases: ["platform-setup-guide:groups.adoc"] section_ids: add_groups_as_a_managed_object: Add groups as a managed object user_group_attributes_in_use: User group attributes in use --- # Groups | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This is *not* a comprehensive Advanced Identity Software implementation guide. These sample setup instructions show a minimal integration of Advanced Identity Software components to get you started.Ping Advanced Identity Software offers maximum extensibility and flexibility in self-managed deployments. Advanced Identity Software includes many features and options these sample setup instructions do not cover. If you don't need maximum extensibility and flexibility, there are simpler alternatives:- To consume the Advanced Identity Software as a service, use [PingOne Advanced Identity Cloud](https://docs.pingidentity.com/pingoneaic). - To deploy in Kubernetes, start with the [ForgeOps](https://docs.pingidentity.com/forgeops/2025.1) reference implementation.For help with your deployment and to validate your plans before deploying in production, contact [Ping Identity](https://www.pingidentity.com). | Groups are an important tool for identity management. They greatly simplify managing collections of users, applying permissions and authorizations to all members of a group, rather than to individual users. These groups might follow an organization structure, but might instead be based on the needs and privileges for an otherwise arbitrary set of users. The managed *group* object is an optional managed object type and is defined defined in `managed.json` like any other managed object type. Managed groups simplify management by using common groups across the entire platform. Users are made members of groups through the [relationships](https://docs.pingidentity.com/pingidm/8/objects-guide/relationships.html) mechanism. You should understand how relationships work before you read about PingIDM groups. ## Add groups as a managed object To add groups as a managed object type, update `managed.json` and `repo.ds.json` in your PingIDM `conf/` directory: In `managed.json`: 1. Add `groups` to the `order` property in the `user` managed object: ```none ... "stateProvince", "roles", "groups", "manager", ... ``` 2. Add a `groups` property to the `user` managed object type: ```json "groups" : { "description" : "Groups", "title" : "Group", "id" : "urn:jsonschema:org:forgerock:openidm:managed:api:User:groups", "viewable" : true, "userEditable" : false, "returnByDefault" : false, "usageDescription" : "", "isPersonal" : false, "type" : "array", "relationshipGrantTemporalConstraintsEnforced" : false, "items" : { "type" : "relationship", "id" : "urn:jsonschema:org:forgerock:openidm:managed:api:User:groups:items", "title" : "Groups Items", "reverseRelationship" : true, "reversePropertyName" : "members", "notifySelf" : true, "validate" : true, "properties" : { "_ref" : { "description" : "References a relationship from a managed object", "type" : "string" }, "_refProperties" : { "description" : "Supports metadata within the relationship", "type" : "object", "title" : "Groups Items _refProperties", "properties" : { "_id" : { "description" : "_refProperties object ID", "type" : "string" }, "_grantType" : { "description" : "Grant Type", "type" : "string", "label" : "Grant Type" } } } }, "resourceCollection" : [ { "path" : "managed/group", "label" : "Group", "conditionalAssociationField" : "condition", "query" : { "queryFilter" : "true", "fields" : [ "name" ], "sortKeys" : [ "name" ] } } ] } }, ``` 3. Add the `group` managed object type: ```json { "name" : "group", "schema" : { "id" : "urn:jsonschema:org:forgerock:openidm:managed:api:Group", "title" : "Group", "icon" : "fa-group", "mat-icon" : "group", "viewable" : true, "$schema" : "http://json-schema.org/draft-03/schema", "order" : [ "_id", "name", "description", "condition", "members" ], "required" : [ "name" ], "properties" : { "_id" : { "description" : "Group ID", "type" : "string", "viewable" : false, "searchable" : false, "userEditable" : false, "usageDescription" : "", "isPersonal" : false }, "name" : { "title" : "Name", "description" : "Group Name", "type" : "string", "viewable" : true, "searchable" : true }, "description" : { "title" : "Description", "description" : "Group Description", "type" : "string", "viewable" : true, "searchable" : true, "userEditable" : false }, "condition" : { "description" : "A filter for conditionally assigned members", "title" : "Condition", "viewable" : false, "searchable" : false, "isConditional" : true, "type" : "string" }, "members" : { "description" : "Group Members", "title" : "Members", "viewable" : true, "searchable" : false, "userEditable" : false, "policies" : [ ], "returnByDefault" : false, "type" : "array", "items" : { "type" : "relationship", "id" : "urn:jsonschema:org:forgerock:openidm:managed:api:Group:members:items", "title" : "Group Members Items", "reverseRelationship" : true, "reversePropertyName" : "groups", "validate" : true, "properties" : { "_ref" : { "description" : "References a relationship from a managed object", "type" : "string" }, "_refProperties" : { "description" : "Supports metadata within the relationship", "type" : "object", "title" : "Group Members Items _refProperties", "properties" : { "_id" : { "description" : "_refProperties object ID", "type" : "string" }, "_grantType" : { "description" : "Grant Type", "type" : "string", "label" : "Grant Type" } } } }, "resourceCollection" : [ { "notify" : true, "conditionalAssociation" : true, "path" : "managed/user", "label" : "User", "query" : { "queryFilter" : "true", "fields" : [ "userName", "givenName", "sn" ] } } ] } } } } } ``` In `repo.ds.json`: 1. Add groups as a property for `managed/user`: ```json "managed/user" : { "dnTemplate" : "ou=user,ou=managed,dc=openidm,dc=forgerock,dc=com", ... "properties" : { ... "groups" : { "type" : "reference", "ldapAttribute" : "fr-idm-managed-user-groups", "primaryKey" : "cn", "resourcePath" : "managed/group", "isMultiValued" : true }, ... ``` 2. Add the `managed/group` object type: ```json "managed/group" : { "dnTemplate" : "ou=groups,ou=identities", "namingStrategy" : { "type" : "clientDnNaming", "dnAttribute" : "cn" }, "nativeId" : false, "objectClasses" : [ "top", "groupOfURLs", "fr-idm-managed-group" ], "jsonAttribute" : "fr-idm-managed-group-json", "jsonQueryEqualityMatchingRule" : "caseIgnoreJsonQueryMatch", "properties" : { "_id" : { "primaryKey" : true, "type" : "simple", "ldapAttribute" : "cn", "writability" : "createOnly" }, "_rev" : { "type" : "simple", "ldapAttribute" : "etag" }, "description" : { "type" : "simple", "ldapAttribute" : "description" }, "condition" : { "type" : "simple", "ldapAttribute" : "fr-idm-managed-group-condition" }, "memberURL" : { "type" : "simple", "ldapAttribute" : "memberURL", "isMultiValued" : true, "writability" : "createOnly" }, "members" : { "type" : "reverseReference", "resourcePath" : "managed/user", "propertyName" : "groups", "isMultiValued" : true } } }, ``` ## User group attributes in use A group can be assigned to a user manually, as a static value of the user's `groups` attribute, or dynamically, as a result of a condition or script. For example, a user might be assigned to a group such as `sales` dynamically, if that user is in the `sales` organization. A user's `groups` attribute takes an array of *references* as a value, where the references point to the managed groups. For example, if user bjensen has been assigned to two groups (`employees` and `supervisors`), the value of bjensen's `groups` attribute would look something like the following: ```json "groups": [ { "_ref": "managed/group/supervisors", "_refResourceCollection": "managed/group", "_refResourceId": "supervisors", "_refProperties": { "_id": "61315165-9269-4944-8db9-98f681c6b0a9", "_rev": "00000000586a94fd" } }, { "_ref": "managed/group/employees", "_refResourceCollection": "managed/group", "_refResourceId": "employees", "_refProperties": { "_id": "2a965519-5788-428c-92d1-19fac497db8f", "_rev": "000000001e1793bc" } } ] ``` The `_refResourceCollection` is the container that holds the group. The `_refResourceId` is the ID of the group. The `_ref` property is a resource path that is derived from the `_refResourceCollection` and the URL-encoded `_refResourceId`. `_refProperties` provides more information about the relationship. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------- | | | In most cases, PingIDM uses UUIDs as the `_id` for managed objects. Managed groups are an exception: the `_id` and `name` properties should match. | While managed groups appear in the PingAM admin UI and can serve the same function as a static group created in PingAM, they are not the same. A managed group supports dynamic, conditional membership and can be leveraged in other parts of the platform. We recommend using managed objects for all data management in the platform.