Authenticate with OAuth2

OAuth2 authentication servers provide an authentication service to Managed Search. Each Managed Search REST API call must include an Authorization header that contains a valid OAuth2 access token.

For clients other than SolrJ clients, your app must manage OAuth2 access tokens, and use them for authentication. You can also use this approach with SolrJ.

Manage OAuth2 access tokens yourself

For languages other than SolrJ, your app must manage OAuth2 access tokens and use them to authenticate applications.

You can also use this approach with SolrJ.

Workflow

This is the authentication workflow:

  1. A search app submits the organization’s clientId and clientSecret to the OAuth2 authentication server.

  2. The OAuth2 authentication server returns an access token. The token expires in one hour.

  3. The search app submits requests to the Managed Search HTTP API. Each request’s Authorization header contains the access token.

Get an OAuth2 access token

Any app that can make HTTP requests can use the APIs, if the app has a valid OAuth2 access token. Each request must supply the access token.

Important
If you are not using SolrJ, the OAuth2 access token expires after 1 hour. If the token expires, you need to repeat the steps to generate a new token.

Obtaining an OAuth2 access token is a four-step process.

1. Obtain OAuth2 credentials

Obtain your OAuth2 credentials (Client ID and secret) from Lucidworks.

2. Base64 encode the credentials

Base64 encode the string clientId:secret, for example:

python
>>> import base64
>>> clientId = '0ofcthlrhRu5Cq58a37f'
>>> secret = 'nwafkAULhdBDaRVPfJLkWGaUtRwmVBoYahzyj6Nu'
>>> print(base64.b64encode('%s:%s' % (clientId, secret)))
MG9mY3RobHJoUnU1Q3E1OGEzN2Y6bndhZmtBVUxoZEJEYVJWUGZKTGtXR2FVdFJ3bVZCb1lhaHp5ajZOdQ==
>>> exit()

3. Obtain an OAuth2 access token for Managed Search APIs

To obtain an OAuth2 access token for Managed Search APIs, provide the Base64-encoded OAuth2 credentials in an authorization header and specify the scope com.lucidworks.cloud.search.api.customer. For example:

curl https://pg01.us-west1.cloud.lucidworks.com/oauth2/default/{customerId}/v1/token \
-H 'accept: application/json' \
-H 'authorization: Basic MG9mY3RobHJoUnU1Q3E1OGEzN2Y6bndhZmtBVUxoZEJEYVJWUGZKTGtXR2FVdFJ3bVZCb1lhaHp5ajZOdQ==' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=com.lucidworks.cloud.search.api.customer'

The POST method is implicit.

In the above code, substitute your customer ID for customerId.

The response to the command contains the access token. For example:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyFraWQiOiI4VlFURDZLeklvaGhHa25fb0dVWTF1bjVDa3k5MjV4UER2ZUh1b0VJQ0ZRIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULm9aWjhPazVpRkhQWDNEMjFIZTZJNDlqZGZaeDVlWmJBYjlxeEI2Z1o4SG8iLCJpc3MiOiJodHRwczovL2Rldi0zNjIzODMub2t0YS5jb20vb2F1dGgyL2RlZmF1bHQiLCJhdWQiOiJhcGk6Ly9kZWZhdWx0IiwiaWF0IjoxNTYyNzg4NzIxLCJleHAiOjE1NjI3OTIzMjEsImNpZCI6IjBvYWNxaGxyaFm1NVNjNTg5MzU2Iiwic2NwIjpbImNvbS5sdWNpZHdvcmtzLmNsb3VkLnNlYXJjaC5hcGkuY3VzdG9tZXIiXSwic3ViIjoiMG9hY3FobHJoU3U1Q0k1ODkzNTYifQ.ACdEq9Wrv5LyTw503XWzeAdLKsb4aN_vyQJD-7ooN9IxEfNed7yapIsCBYJD1oI0D8dosHsg7ZhI5yUlipQeyWmWkm2uYltN1MEgEHz6HQqvbK4Imc9mt7UIdhmTu6M3j9DamMaaL_rEwlS8G-VqTklpZVMFCNo9IWDi8oO8muA7atKD5eBHxhvRy9S1maK25ykXVhV7AftTgOMDrdqFssfOvqinmHOK5c8S4mwnwWiIign7FloUpqU06jeHfNofDHJsFNBIXs7tMNISyHEymCh1TdL_MgL9hvxzW9a3_C6P1rg_wqF4LfleKA1bu2orUZ68arYDLCi8GXS4ygiBig",
  "scope": "com.lucidworks.cloud.search.api.customer"
}

4. Obtain an OAuth2 access token for Solr APIs

To obtain an OAuth2 access token for Solr APIs, provide the Base64-encoded OAuth2 credentials in an authorization header and specify the scope com.lucidworks.cloud.search.solr.customer. For example:

curl https://pg01.us-west1.cloud.lucidworks.com/oauth2/default/{customerId}/v1/token \
-H 'accept: application/json' \
-H 'authorization: Basic MG9iY3FobHJoVHU1Q0k1OGEzNWY6bndhZmtCVUxoY0JEc1JXUGZKSGtXR2FVd1J3bVZCb1lhaHpxajdOdQ==' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=com.lucidworks.cloud.search.solr.customer'

The POST method is implicit.

In the above code, substitute your customer ID for customerId.

The response to the command contains the access token. For example:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJraWQiOiI4VlFURDZLeklvaGhHa25fb0dVWTF1bjVDa3k5MjV4UER2ZUh1b0VJQ0ZRIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULnVuWEJoMksxdXRPYjJBVS1XLUsyNHRicjNZQkktT1ZWeXRZZmVIMHcwTUEiLCJpc3MiOiJodHRwczovL2Rldi0zNjIzODMub2t0YS5jb20vb2F1dGgyL2RlZmF1bHQiLCJhdWQiOiJhcGk6Ly9kZWZhdWx0IiwiaWF0IjoxNTYzMzk1MzUyLCJleHAiOjE1NjMzOTg5NTIsImNpZCI6IjBvYWNxaGxyaFm1NVNjNTg5MzU2Iiwic2NwIjpbImNvbS5sdWNpZHdvcmtzLmNsb3VkLnNlYXJjaC5zb2xyLmN1c3RvbWVyIl0sInN1YiI6IjBvYWNxaGxyaFm1NVNjNTg5MzU2In0.LYXXTb3yp4gpA_t_kN-CrDGiewlq1qTkj5McAZyljytx5XyaC5an7JGvHgkb8daUSKZioOSj3yebsYTs3mvx01AlB9YrNldJTcWJUHzg0uo3AbXGqhMG1i6rDHDqR-tc4VCSt8UMpAePxeWE3KBWmmXwPU16QNt0MEK-MGAUdtFcxEwY3F_xs9la6ZtHFfi7O5fj9TzCjHuiFf9MgAUWVjUfEkKd8HF2duvkZ9DdeCptAzx3F9qhNl5kgbIVW1i06jhit3NufrMnrj8htCMPQvmIxHYJ8VSNgSIb8VPcdspVs-7ixB_2NGaxqeXFZoiyzZT8Va0T5Hq004oJlbw2yA",
  "scope": "com.lucidworks.cloud.search.api.customer"
}