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.