For new users, we recommend using our Elasticsearch-native tools, rather than the standalone Workplace Search product. See this blog post for more information about upgrading your internal knowledge search, to make it an amazing experience for your users!

« Search API Reference Analytics event API reference »

› ›

OAuth Service API Reference

edit

OAuth Service API Reference

edit

The Custom search experiences guide provides conceptual walkthrough of the steps involved in issuing search requests on behalf of users via OAuth.

In this API reference

edit

OAuth Service API Overview

edit

The OAuth Service API provides endpoints to generate user access tokens allowing applications to issue search requests on behalf of an authenticated user. It supports both a confidential flow (which involves generating an authorization code using a Client Secret) and an implicit flow (which allows a user’s client to request access tokens directly).

In the following:

Replace <KIBANA_BASE_URL> with the base URL of your Kibana instance.
Replace <ENTERPRISE_SEARCH_BASE_URL> with the Enterprise Search base URL for your deployment.

The available endpoints are as follows:

# Confidential flow
GET https://<KIBANA_BASE_URL>/app/enterprise_search/workplace_search/p/oauth/authorize?response_type=code&client_id=ca6e5332...&redirect_uri=https://one.acme.co
POST https://<ENTERPRISE_SEARCH_BASE_URL>/ws/oauth/token?grant_type=authorization_code&client_id=ca6e5332b...&client_secret=c5d51a8c...&redirect_uri=https://one.acme.co&code=78hasd9h324h
POST https://<ENTERPRISE_SEARCH_BASE_URL>/ws/oauth/token?grant_type=refresh_token&refresh_token=89d2a...&client_id=ca6e5332...&redirect_uri=https://one.acme.co

# Implicit flow
GET https://<KIBANA_BASE_URL>/app/enterprise_search/workplace_search/p/oauth/authorize?response_type=token&client_id=ca6e5332...&redirect_uri=https://one.acme.co

`response_type`	required	`code` for confidential flow, `token` for implicit flow
`client_id`	required	Client ID as generated when setting up the OAuth Application
`client_secret`	required for Confidential	Client Secret as generated when setting up the OAuth Application
`redirect_uri`	required	Location to redirect user to once the OAuth process completed. Must match a URI as configured in the OAuth Application
`code`	required	Authorization code as returned by the `/authorize` endpoint for the confidential flow
`grant_type`	required	Required for `token` endpoint for the confidential flow, with value of `authorization_code` or `refresh_token`
`access_token`	response	Token used for issuing search requests on behalf of an authenticated user, generated from a successful OAuth flow
`refresh_token`	response	Token used for retrieving a new access token in the confidential flow

To learn more about setting up and configuring the Search OAuth application, refer to the Configuring the OAuth Application for Search guide.

Managing tokens

edit

Access tokens usually expire after 2 hours. Refresh tokens do not expire.

A refresh token can be exchanged for a new access token in the confidential flow. This means clients can continue to have valid access without asking the user to re-authenticate. The refresh token is issued together with the access token and it has to be exchanged for a new access token before expiration.

The Confidential approach is recommended wherever possible. This provides more control over the generation and refreshing of access tokens.

OAuth API Visual Reference

edit

Figure 140. Confidential OAuth flow overview

Figure 141. Implicit OAuth flow overview

« Search API Reference Analytics event API reference »