Building Custom Search Experiences

Modern search experiences are provided with Workplace Search, allowing team members and collaborators to find information and files from a feature-rich, standalone platform. It is a fast, scalable, and intuitive way to rollout search across your organization, and will continue evolving over time.

Figure 114. Workplace Search web-based search experience

In some instances, adding unified search to an area of your virtual workplace that already generates high levels of engagement or traffic is desirable. Intranet systems and other knowledge platforms are prime candidates as they represent a natural gravitational pole for members of your team. Workplace Search boasts flexible programmatic search capabilities via the Search API, allowing you to replace an existing search bar or add a new one to an internal application.

Using a simple example might be the best way to illustrate how custom search experiences are implemented with Workplace Search. For our purpose, let’s transport ourselves to Acme Inc, where an internal knowledge platform acts as the launch board for members of the organization on a daily basis. Given that our intranet-like application has already gained a fair amount of traction with the various teams across the organization, providing a unified search experience along with the useful actions already available is a great way to enhance the discovery experience.

Figure 115. Adding a search experience to an internal knowledge portal

One of our colleagues is looking for information about a specific project, where content and files may be found across a variety of sources, from cloud storage to internal knowledge bases. From the newly rolled out unified search experience found on the Acme Inc intranet, our teammate enters a search query and is immediately presented with results tailored specifically for them, taking into consideration their level of access to various pieces of content across the organization. This personalization drives both increased relevance and enhanced security, all backed by an effective authentication mechanism which relies on the OAuth standard.

The first step towards designing and implementing a custom search experience for Workplace Search is to create an OAuth application from the administrative dashboard. This OAuth application will ensure proper authentication of users and secure access to content.

Step 1. Locate the Settings area in the Workplace Search administrative dashboard, and click OAuth Application.

Step 2. We must configure our OAuth application. Provide a name that matches the platform on which you intend to embed the unified search experience.

Figure 116. Configuring the OAuth application

Step 3. Provide a list of authorized redirect URIs. These should match the target destination where you expect a user to return after successfully authenticating with the Workplace Search service.

Step 4. Select the type of application you would like to create.

Step 5. Save the changes. A Client ID will be created, as well as a Client Secret if Confidential was previously set for the OAuth application.

Figure 117. Retrieving the OAuth credentials

With the help of our newly created OAuth application, we are now ready to implement unified search on the Acme Inc. internal knowledge platform. Depending on the strategy you chose, the access token and authentication sequence will differ slightly.

The confidential OAuth flow requires that the application server (in this case our internal knowledge platform) handles the trading of a generated authorization code and client secret in exchange for an access token.

Figure 118. Confidential OAuth flow overview

Step 1. The Client ID generated is first passed to the oauth/authorize endpoint to retrieve an authorization code.

The authorization endpoint that you use depends on which user interface you are using to manage Enterprise Search. Enterprise Search in Kibana and standalone Enterprise Search use different authorization endpoints on different hosts. See user interfaces for details on each UI.

If you are using standalone Enterprise Search you’ll use the authorization endpoint hosted by your Enterprise Search deployment:

Standalone Enterprise Search Examples:

# Deployment using a custom domain name
https://www.example.com/ws/oauth/authorize?response_type=code&client_id=ca6e5332...&redirect_uri=https://one.acme.co


# Deployment using a default Elastic Cloud domain name
https://c3397e558e404195a982cb68e84fbb42.ent-search.us-east-1.aws.found.io:443/ws/oauth/authorize?response_type=code&client_id=ca6e5332...&redirect_uri=https://one.acme.co


# Unsecured local development environment for Standalone Enterprise Search
http://localhost:3002/ws/oauth/authorize?response_type=code&client_id=ca6e5332...&redirect_uri=https://one.acme.co

If you are using Enterprise Search in Kibana you’ll use the authorization endpoint hosted by your Kibana deployment. The host should correspond to the value of kibana.external_url in your enterprise-search.yml.

Enterprise Search in Kibana Examples:

# Deployment using a custom domain name for Kibana
https://www.example.com/app/enterprise_search/workplace_search/p/oauth/authorize?response_type=code&client_id=ca6e5332...&redirect_uri=https://one.acme.co

# Deployment using a default Elastic Cloud domain name for Kibana
https://c3397e558e404195a982cb68e84fbb42.kb.us-east-1.aws.found.io:443/app/enterprise_search/workplace_search/p/oauth/authorize?response_type=code&client_id=ca6e5332...&redirect_uri=https://one.acme.co

# Unsecured local Kibana environment
http://localhost:5601/app/enterprise_search/workplace_search/p/oauth/authorize?response_type=code&client_id=ca6e5332...&redirect_uri=https://one.acme.co

Step 2. The user must authorize the application to issue search requests on their behalf.

Figure 119. Authorizing access

Step 3. Successful authorization redirects the user in accordance to the redirect URI provided (and configured for the application).

https://one.acme.co/?code=78hasd9h324h...

Step 3a. The application server must now request for a search access_token, which is generated by Workplace Search using the oauth/token endpoint, using the Client ID and Client Secret.

The token endpoint is the same regardless of which user interface you are using to manage Enterprise Search. Enterprise Search in Kibana and standalone Enterprise Search use the same token endpoint, hosted by your Enterprise Search deployment.

# Important note: the hostname should be relative to the one you have configured.

curl -X POST 'http://localhost:3002/ws/oauth/token?grant_type=authorization_code&client_id=ca6e5332b...&client_secret=c5d51a8c...&redirect_uri=https://one.acme.co&code=78hasd9h324h...'

{
  "access_token": "79e765efe18f5f5f2dbcb8404097d52c64ceb84a3cb0a51205157b4141cdd77d",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "fe010bbca37279ae6b4c0f117cf15a37d992adb50a6d83c930ab827ec4081e07",
  "scope": "search"
}

Step 4. The access_token can now be used as an authorization header to issue a search request on behalf of the user.

# Important note: the hostname should be relative to the one you have configured.

curl -X POST 'localhost:3002/api/ws/v1/search' \
-H 'Authorization: Bearer 79e765efe18f5f5f2dbcb8404097d52c64ceb84a3cb0a51205157b4141cdd77d'

The implicit OAuth flow is generally better suited for environments in which the client secret cannot be kept confidential, such as native mobile applications and single-page applications.

Figure 120. Implicit OAuth flow overview

Step 1. The Client ID generated is first passed to the oauth/authorize endpoint to retrieve an access token.

The authorization endpoint that you use depends on which user interface you are using to manage Enterprise Search. Enterprise Search in Kibana and standalone Enterprise Search use different authorization endpoints on different hosts. See user interfaces for details on each UI.

If you are using standalone Enterprise Search you’ll use the authorization endpoint hosted by your Enterprise Search deployment:

Standalone Enterprise Search Examples:

# Deployment using a custom domain name
https://www.example.com/ws/oauth/authorize?response_type=token&client_id=ca6e5332...&redirect_uri=https://one.acme.co


# Deployment using a default Elastic Cloud domain name
https://c3397e558e404195a982cb68e84fbb42.ent-search.us-east-1.aws.found.io:443/ws/oauth/authorize?response_type=token&client_id=ca6e5332...&redirect_uri=https://one.acme.co


# Unsecured local development environment for Standalone Enterprise Search
http://localhost:3002/ws/oauth/authorize?response_type=token&client_id=ca6e5332...&redirect_uri=https://one.acme.co

If you are using Enterprise Search in Kibana you’ll use the authorization endpoint hosted by your Kibana deployment. The host should correspond to the value of kibana.external_url in your enterprise-search.yml.

Enterprise Search in Kibana Examples:

# Deployment using a custom domain name for Kibana
https://www.example.com/app/enterprise_search/workplace_search/p/oauth/authorize?response_type=token&client_id=ca6e5332...&redirect_uri=https://one.acme.co

# Deployment using a default Elastic Cloud domain name for Kibana
https://c3397e558e404195a982cb68e84fbb42.kb.us-east-1.aws.found.io:443/app/enterprise_search/workplace_search/p/oauth/authorize?response_type=token&client_id=ca6e5332...&redirect_uri=https://one.acme.co

# Unsecured local Kibana environment
http://localhost:5601/app/enterprise_search/workplace_search/p/oauth/authorize?response_type=token&client_id=ca6e5332...&redirect_uri=https://one.acme.co

Step 2. The user must authorize the application to issue search requests on their behalf.

Figure 121. Authorizing access

Step 3. Successful authorization redirects the user in accordance to the redirect URI provided (and configured for the application).

https://one.acme.co/#access_token=16j212as76das...

Step 4. The access_token can now be used as an authorization header to issue a search request on behalf of the user.

# Important note: the hostname should be relative to the one you have configured.

curl -X POST 'localhost:3002/api/ws/v1/search'\
-H 'Authorization: Bearer 16j212as76das...'

Now that we’ve successfully generated an access token, our application can now issue search requests on behalf of our user. A typical search query requires three main items:

# Important note: the hostname should be relative to the one you have configured.

curl -X POST http://localhost:3002/api/ws/v1/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "query": "america",
  "search_fields": {
    "title": {
      "weight": 10
    },
    "description": {}
  },
  "sort": [
    { "square_km": "desc" },
    { "date_established": "asc" }
  ]
}'

The results are returned in JSON format, and can be displayed any way that suits your use case best. Sometimes, implementations with small footprints can complement the first-party Workplace Search experience; other times, complex integrations are required for a more immersive and contextually relevant search.

{
  "meta": {
    ...
  },
  "results": [
    {
      "title": {
        "raw": "American Samoa",
        "snippet": "<em>American</em> Samoa"
      },
      "_meta": {
        "source": "custom",
        "last_updated": "2020-03-27T20:10:33+00:00",
        "content_source_id": "5e7e5d911897c6dbb7e3e72a",
        "id": "park_american-samoa",
        "score": 6.359234
      },
      "source": {
        "raw": "custom"
      },
      "states": {
        "snippet": "<em>American</em> Samoa"
      },
      "description": {
        "raw": "The southernmost National Park is on three Samoan",
        "snippet": "The southernmost National Park is on three Samoan"
      },
      "last_updated": {
        "raw": "2020-03-27T20:10:33+00:00"
      },
      "content_source_id": {
        "raw": "5e7e5d911897c6dbb7e3e72a"
      },
      "id": {
        "raw": "park_american-samoa"
      }
    },
    {
      "title": {
        "raw": "Denali",
        "snippet": null
      },
      "_meta": {
        "source": "custom",
        "last_updated": "2020-03-27T20:10:33+00:00",
        "content_source_id": "5e7e5d911897c6dbb7e3e72a",
        "id": "park_denali",
        "score": 6.357545
      },
      "source": {
        "raw": "custom"
      },
      "states": {
        "snippet": null
      },
      "description": {
        "raw": "Centered on Denali, the tallest mountain in North",
        "snippet": " <em>America</em>, Denali is serviced by a single road"
      },
      "last_updated": {
        "raw": "2020-03-27T20:10:33+00:00"
      },
      "content_source_id": {
        "raw": "5e7e5d911897c6dbb7e3e72a"
      },
      "id": {
        "raw": "park_denali"
      }
    },
    ...
  ]
}