Documentation

Authenticated API Access in Mach5 Search

Mach5 uses Keycloak to manage authentication and authorization, ensuring secure logins and access control for entities in the system.

Prerequisites

  • Mach5 Search should be running with oidc.enabled set to true.
  • Mach5 Search is running at say, <MACH5_HOST>:<MACH5_PORT>
  • User(s) should be available in the default realm with their credentials configured.

API access for users

Token generation:

  • Run the following command to generate the access token:
curl -X POST \
'<MACH5_HOST>:<MACH5_PORT>/keycloak/realms/default/protocol/openid-connect/token' \
-H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=mach5' \
--data-urlencode 'grant_type=password' --data-urlencode 'client_secret=mach5-client-secret' \
--data-urlencode 'scope=openid mach5' --data-urlencode 'username=<username>' \
--data-urlencode 'password=<password>' | jq -r '[.access_token, .refresh_token]'
  • The access token generated from the above command can now be used to authenticate API calls to Mach5 Search.
  • There are additional methods for configuring access in Keycloak. For more details, refer to Keycloak’s official documentation.

API access for Users

  • The token generated from the step above can be used as follows:
curl -k \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
<MACH5_HOST>:<MACH5_PORT>/warehouse/default/<warehouse-name>/opensearch/
  • To list indices, use:
curl -k \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
<MACH5_HOST>:<MACH5_PORT>/warehouse/default/<warehouse-name>/opensearch/_cat/indices
  • To query, use:
curl -X POST -H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
<MACH5_HOST>:<MACH5_PORT>/warehouse/default/<warehouse-name>/opensearch/ \
opensearch_dashboards_sample_data_ecommerce/_search -d '{"query":{"match_all":{}}}'

Set Token Expiration Time

By default, access tokens in Keycloak expire after 5 minutes. Once expired, they cannot be used for authentication or API calls. A user will need to request a new access token using the refresh token or by re-authenticating.

This expiration time can be set from the Mach5 Keycloak Administration console, using the following steps:

  • Navigate to <MACH5_HOST>:<MACH5_PORT>/keycloak and log in using the admin credentials. By default, you’ll be logged into the master realm.
  • Change the realm from the top left drop-down menu to default.
  • In the left sidebar, go to Realm Settings → Tokens.
  • Locate the Access Token Lifespan field.
  • Set the desired interval (e.g., 5m for 5 minutes, 30m for 30 minutes, 1h for 1 hour).
  • Click Save.

This setting determines how long an access token remains valid before requiring a refresh token.

Using Refresh Tokens

Once you have a refresh token, you can use it to request a new access token without requiring the user’s credentials again.

curl -X POST \
'<MACH5_HOST>:<MACH5_PORT>/keycloak/realms/default/protocol/openid-connect/token' \
-H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=mach5' \
--data-urlencode 'grant_type=refresh_token' --data-urlencode 'client_secret=mach5-client-secret' \
--data-urlencode 'scope=openid mach5'  -d "refresh_token=<REFRESH_TOKEN>"

The response will include a new access token, as well as a new refresh token. Always use the latest refresh token when making future refresh requests.