Security identity definition examples

This is for:

Developer System Administrator

The permission model of a secured item typically refers to existing security identities, which the Push API allows you to define and manage in a security identity provider.

A security identity definition must minimally contain the name of the defined security identity itself, as well as its entity type (that is, User, Group, VirtualGroup, or Unknown). Additionally, it may contain:

  • The name and entity type of each of its members, if the defined security identity is a group or virtual group.

  • The name and entity type (normally, Group or VirtualGroup) of each of its granted identities.

    Note

    Granted identities used to be called well known groups.

    For backwards compatibility reasons, the Push API still requires you to specify the granted identities of a security identity in an array property whose name is wellKnowns.

See Security identity models - IdentityBody.

The following security identity definition examples rely on one another and are increasingly complex.

Defining a basic group

A group typically has an array of Members, unless this group is intended to be used as a granted identity (see Defining a granted identity).

{
  "identity": {
    "name": "SampleTeam1",
    "type": "Group"
  },
  "members": [
    {
      "name": "asmith@example.com",
      "type": "User"
    },
    {
      "name": "bjones@example.com",
      "type": "User"
    }
  ]
}

In this example, the asmith@example.com and bjones@example.com users are explicitly included as members of the SampleTeam1 group.

You would typically create aliases on those members to map them to their respective corresponding identities in other security identity providers (see About the email security provider and User alias definition examples).

Important

When pushing a group, you overwrite the current version of that group. Therefore, if you want to keep existing group members, be sure to include them in the new group configuration. If this isn’t viable, consider using granted security identities instead.

Defining a granted identity

A granted identity is initially defined as a group or virtual group that doesn’t have an array of Members.

{
  "identity": {
    "name": "Everyone",
    "type": "Group"
  }
}
Note

While uncommon, it’s possible for a granted identity to have its own array of wellKnowns.

In this example, the Everyone group doesn’t have any members. Actually, those members will be included "the other way around" (see Defining a user with granted identities).

Defining a user with granted identities

A granted identity is essentially a group whose members are included "the other way around".

Whenever you define a security identity, it automatically becomes a member of all granted identities included in its array of wellKnowns.

In the following example, suppose that the Domain Users group was previously defined exactly as the Everyone group was (see Defining a granted identity).

{
  "identity": {
    "name": "cbrown@example.com",
    "type": "User"
  },
  "wellKnowns": [
    {
      "name": "Domain Users",
      "type": "Group"
    },
    {
      "name": "Everyone",
      "type": "Group"
    }
  ]
}

In this example, the cbrown@example.com user automatically becomes a member of the Domain Users and Everyone groups.

Note

A user entity can also be defined with one or several aliases (see User alias definition examples).

Example cases of when to use granted identities

It’s not always necessary to use granted identities in Coveo implementations. They should be considered when they can serve as a simplifying measure. Below are some example cases.

  • A group named Everyone is attributed to all users by default. This group is meant to denote membership to a given organization. Every time a new member joins the organization, they must be added to the group, and inversely when a member leaves. This requires a lot of group management and can quickly lead to human errors. To prevent this scenario, the granted identity Everyone can be systematically used when declaring new users:

    {
  "identity": {
    "name": "newuser@example.com",
    "type": "User"
  },
  "wellKnowns": [
    {
      "name": "Everyone",
      "type": "Group"
    }
  ]
}

  • In a case where group membership eligibility can be determined based on a set of automated rules, it can be wise to link users to groups on user creation. Conversely, if the rule was applied on group creation, the system would need to iterate over every existing member to determine which ones qualify for group membership, for every group. A better design is to run the group membership rules on user creation and to use granted identities:

    {
  "identity": {
    "name": "newuser@example.com",
    "type": "User"
  },
  "wellKnowns": [
    {
      "name": "Everyone",
      "type": "Group"
    },
    {
      "name": "Security_Team",
      "type": "Group"
    },
    {
      "name": "Developer",
      "type": "Group"
    },
    ...
  ]
}

Defining a group with many member types

A group can have many security identity types in its array of Members.

{
  "identity": {
    "name": "SampleTeam2",
    "type": "Group"
  },
  "members": [
    {
      "name": "Domain Users",
      "type": "Group"
    },
    {
      "name": "dmoore@example.com",
      "type": "User"
    }
  ]
}

In this example, since the Domain Users group is included as a member of the SampleTeam2 group, all users who have the Domain Users granted identity also become members of the SampleTeam2 group.

Consequently, the cbrown@example.com user becomes a member of the SampleTeam2 group (see Defining a user with granted identities).

You would typically create an alias on dmoore@example.com to map that identity to corresponding identities in other security identity providers (see About the email security provider and User alias definition examples).

Important

When pushing a group, you overwrite the current version of that group. Therefore, if you want to keep existing group members, be sure to include them in the new group configuration. If this isn’t viable, consider using granted security identities instead.

Defining a group with granted identities

A group can have granted identities. Any security identity that’s a member of that group receives these granted identities.

In the following example, suppose that the Superuser group was previously defined exactly as the Everyone group was (see Defining a granted identity).

{
  "identity": {
    "name": "SampleGroup",
    "type": "VirtualGroup"
  },
  "members": [
    {
      "name": "SampleTeam1",
      "type": "Group"
    },
    {
      "name": "SampleTeam2",
      "type": "Group"
    }
  ],
  "wellKnowns": [
    {
      "name": "Superuser",
      "type": "Group"
    }
  ]
}
Note

In this example, the SampleGroup security identity is defined as a virtual group.

The only difference between a group and a virtual group is semantics: a virtual group doesn’t exist in the indexed enterprise system, whereas a group does.

In this example, the SampleGroup virtual group ultimately resolves to the following individual user entities:

Each of those users automatically becomes a member of the Superuser group.

How security identities and permission models interact

Once all security identities in the security identity provider have been properly resolved to individual user entities, the index can evaluate the effective permissions of each item in the secured Push source (see Defining a permission model - Effective permission evaluation with many permission sets).

Suppose that an item in a secured Push source has the following permission model (see Simple permission model definition examples):

[
  {
    "allowAnonymous": false,
    "allowedPermissions": [
      {
        "identity": "Superusers",
        "identityType": "Group"
      }
    ],
    "deniedPermissions": [
      {
        "identity": "MysteryUserX",
        "identityType": "User"
      }
    ]
  }
]

Moreover, suppose that the MysteryUserX alias has been defined as follows in the same security identity provider (see User alias definition examples):

{
  "identity": {
    "name": "MysteryUserX",
    "type": "User"
  },
  "mappings": [
    {
      "name": "asmith@example.com",
      "type": "User",
      "provider": "Email Security Provider"
    }
  ]
}

In this example:

  • The Superusers group resolves to the asmith@example.com, bjones@example.com, cbrown@example.com, and dmoore@example.com users (see Defining a group with many member types).

  • The MysteryUserX alias resolves to the asmith@example.com user entity.

  • As a result, once effective permission have been evaluated, the asmith@example.com user is denied access to the item, and only the bjones@example.com, cbrown@example.com, and dmoore@example.com users can see the item in their query results.