External Identities API Referenceedit

Refer to the Document permissions for custom sources for the conceptual walkthrough related to this API reference. See also Document access strategies for content sources for guidance specific to the first-party (out-of-the-box) content sources.

In this API referenceedit

API Authenticationedit

Workplace Search APIs support multiple methods of authentication.

For simplicity, the examples from this page use a bearer token.

External Identities API Overviewedit

An external identity is a mapping from external to internal users.

Each mapping you create is bound to a single content source, represented by [CONTENT_SOURCE_ID]. This means that you will need to create an object for each content source, and then map the third-party user to the Workplace Search user. Furthermore: you will need to set up external identities for all users if you are connecting a content source with permissions enabled.

content_source_id

required

Unique ID for a Custom API source, provided upon creation of a Custom API Source.

token

required

Must be included in HTTP authorization headers.

external_user_id

required

The username or identifier for this user at the external source. See the guides for each source’s user IDS:

external_user_properties

required

List of properties that can be used to map the external user to the Workplace Search user. Each property is an object that has an attribute_name and an attribute_value. Currently, the only allowed attribute_name is _elasticsearch_username.

permissions

required

List of permissions associated with this external user. Each permission is an arbitrary string. For more information on document permissions, see the following guides:

Add an external identityedit

POST <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities

Adds a new external identity per content source.

curl -X POST <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities \
-H "Authorization: Bearer [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "external_user_id": "john.doe@example.com",
  "external_user_properties": [
    {
      "attribute_name": "_elasticsearch_username",
      "attribute_value": "john.doe"
    }
  ],
  "permissions": []
}'

Example response:

{
  "content_source_id": "[CONTENT_SOURCE_ID]",
  "external_user_id": "john.doe@example.com",
  "external_user_properties": [
    {
      "attribute_name": "_elasticsearch_username",
      "attribute_value": "john.doe"
    }
  ],
  "permissions": []
}

If the same _elasticsearch_username is present in multiple authentication realms configured for Enterprise Search, they will all be mapped to external_user_id.

Show an external identityedit

GET <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities/[EXTERNAL_USER_ID]

Retrieves an external identity for a content source:

curl -X GET <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities/john.doe%40example.com \
-H "Authorization: Bearer [TOKEN]"

Response:

{
  "content_source_id": "[CONTENT_SOURCE_ID]",
  "external_user_id": "john.doe@example.com",
  "external_user_properties": [
    {
      "attribute_name": "_elasticsearch_username",
      "attribute_value": "john.doe"
    }
  ],
  "permissions": []
}

The parameter external_user_id should be URL encoded.

List all external identitiesedit

GET <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities

Retrieves all external identities for a content source.

curl -X GET <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities
-H "Authorization: Bearer [TOKEN]"
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 25
    }
  },
  "results": [
    {
      "content_source_id": "[CONTENT_SOURCE_ID]",
      "external_user_id": "john.doe@example.com",
      "external_user_properties": [
        {
          "attribute_name": "_elasticsearch_username",
          "attribute_value": "john.doe"
        }
      ],
      "permissions": []
    }
  ]
}

This endpoint can be paginated with current and size query parameters.

Update an external identityedit

PUT <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities/[EXTERNAL_USER_ID]

Updates an external identity.

curl -X PUT <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities/john.doe%40example.com \
-H "Authorization: Bearer [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
    "permissions": ["permission1"]
}'

Response:

{
  "content_source_id": "[CONTENT_SOURCE_ID]",
  "external_user_id": "john.doe@example.com",
  "external_user_properties": [
    {
      "attribute_name": "_elasticsearch_username",
      "attribute_value": "john.doe"
    }
  ],
  "permissions": ["permission1"]
}

Remove an external identityedit

DELETE <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities/[external_user_id]

Deletes an external identity for a content source.

curl -X DELETE <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[CONTENT_SOURCE_ID]/external_identities/john.doe%40example.com \
-H "Authorization: Bearer [TOKEN]"

Response:

"ok"