User alias definition examples

This is for:

Developer System Administrator

The Push API allows you to define security identity relationships between a user security identity and other user identities defined across multiple security identity providers. These aliases indicate that all of the defined security identities correspond to the same person.

An alias definition must minimally contain:

  • The name of the security identity for which you want to create an alias in the security identity provider of your secured push source, as well as its entity type (normally USER).

  • The name, entity type (normally USER), and security identity provider of each security identity with which to establish an alias relationship.

Notes

  • The security identity for which you want to create an alias doesn’t need be defined in the security identity provider of your secured Push source.

  • The security identity provider of your secured Push source must be configured to cascade to the security identity providers containing the security identities with which you want to establish an alias relationship.

    If your security identity provider only cascades to a single security identity provider (for example, Email Security Provider), you don’t need to specify a value for the provider property when creating an alias, as this cascading security identity provider will be used by default.

The alias definition may also contain the name and type (normally GROUP or VIRTUAL_GROUP) of each granted identity to assign to the alias (see MappedIdentityBody).

Note

Granted identities used to be called well known groups. To ensure backwards compatibility, the Push API still requires that you specify the granted identities of an alias in an array property whose name is wellKnowns.
Tip
Leading practice: Only define aliases between USER entities

Although you can establish alias relationships between any type of security identity, you should generally only define aliases between USER entities.

Defining a single alias for a user

Assuming that the target security identity provider only cascades to the Email Security Provider, this establishes an alias relationship between the user asmith in the target security identity provider and the user asmith@example.com in the Email Security Provider. This also assigns the Everyone granted identity to the alias.

{
  "identity": {
    "name": "asmith",
    "type": "USER"
  },
  "mappings": [
    {
      "name": "asmith@example.com",
      "type": "USER"
    }
  ],
  "wellKnowns": [
    {
      "name": "Everyone",
      "type": "GROUP"
    }
  ]
}

Defining many aliases for a user

This establishes an alias relationship between the user bjones@example.com in the target security identity provider and the users bjones@example.com and bjones1@example.com in the Email Security Provider, as well as the user bob_jones in mysecurityidentityprovider. This implies that the target security identity provider is properly configured to cascade to both of these security identity providers.

{
  "identity": {
    "name": "bjones@example.com",
    "type": "USER"
  },
  "mappings": [
    {
      "name": "bjones@example.com",
      "type": "USER",
      "provider": "Email Security Provider"
    },
    {
      "name": "bjones1@example.com",
      "type": "USER",
      "provider": "Email Security Provider"
    },
    {
      "name": "bob_jones",
      "type": "USER",
      "provider": "mysecurityidentityprovider"
    }
  ]
}