API Authentication Reference

edit

API Authentication Reference

edit

Workplace Search APIs support multiple authentication methods:

Workplace Search API keys

edit

Workplace Search API keys are tokens created specifically for Workplace Search API access. Workplace Search admins can create and manage these keys within Kibana.

Workplace Search API keys are not associated with a user. Therefore, document-level permissions are not applied to requests using Workplace Search API keys. These requests can access all documents for a content source.

Workplace Search API keys are useful for integrators who are building their own connectors using custom sources. For example, an integrator can use a Workplace Search API key to list all documents for a content source to determine which documents to delete.

Workplace Search API keys can be used with organization content sources only. They cannot be used with private content sources.

Manage Workplace Search API keys in Kibana:

You must be a Workplace Search admin user to manage Workplace Search API keys.

  1. Navigate to SearchEnterprise SearchWorkplace SearchAPI keys
  2. From that interface: List, create, or delete API keys

You cannot edit an existing key. Instead, delete the key and create a new one.

Use a Workplace Search API key as a bearer token in the Authorization header of each API request:

curl -X POST <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/[ID]/documents/bulk_create \
-H "Authorization: Bearer [API_KEY]" \
-H "Content-Type: application/json" \
-d "..."

Workplace Search API keys cannot be used with the Search API and the Analytics Events API. For these endpoints, the authentication mechanisms follow the Search API OAuth flow, basic authentication or Elasticsearch bearer token strategies.

Basic authentication

edit

Workplace Search APIs support basic authentication headers to authenticate users. Consult your HTTP client’s documentation for its support of the basic authentication scheme. For example, cURL provides the -u and --user arguments to provide a username and password for each request.

curl -X POST <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/search \
-u "[USERNAME]:[PASSWORD]" \
-H "Content-Type: application/json" \
-d '{
  "query": "denali"
}'

All Workplace Search APIs support basic authentication.

Basic authentication cannot be used with Elasticsearch SAML user management mode.

Elasticsearch tokens

edit

Workplace Search APIs support Elasticsearch tokens generated by the Elasticsearch Token Service.

curl -X POST <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/search \
-H "Authorization: Bearer [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "query": "denali"
}'

All Workplace Search APIs support Elasticsearch tokens as an authentication method.

JWT token authentication

edit

You can utilize JWT token-based authentication to connect to Workplace Search endpoints. To allow this you will need to configure a third party JWT authorization service to issue JWT tokens, and ensure the JWT realm configuration is set up in your Elasticsearch instance.

In addition, you will need to provide one or more appropriate role mappings to enable the permissions you want for your JWT tokens. At a minimum, when you configure Elasticsearch role mappings for JWT usage, provide the correct Workplace Search role mappings based on the principal username, or, any JWT claim data that can be found in the metadata.

Example - A GET request to retrieve the current user information using a JWT Token.

curl \
--request 'GET' \
--url "<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/whoami?get_token=true" \
--header "Authorization: Bearer $JWT_TOKEN"

Workplace Search OAuth access tokens

edit

The Search API, the Analytics Events API and the Who Am I? API support user access tokens generated by the Workplace Search OAuth Service. The token is acquired via an OAuth authorization flow. User access tokens are meant to be used for Custom Search Experiences.

curl -X POST <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/search \
-H "Authorization: Bearer [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "query": "denali"
}'

Only the Search API, the Analytics Events API and the Who Am I? API support user access tokens.

Who Am I? Current User API

edit

With token authentication mechanisms, it is easy to get confused about exactly who is authenticated. To remove all doubt, you can check who the authenticated user is with the below API.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/whoami

Request headers

edit
Authorization

Bearer token permitting API access, or basic auth.

Request example

edit
curl \
--request 'GET' \
--url "<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/whoami?get_token=true" \
--header "Authorization: Bearer $ACCESS_TOKEN"

Response

edit
200 OK

The username and the email address of the current user are returned.

{
  "email": "ent-search@example.com",
  "username": "enterprise_search"
}
401 Unauthorized

The authorization header was missing from the request or authentication failed.