Cloudera Docs

Manage Knox metadata

This document describes how to manage Token Metadata.

As indicated in the previous sections, the KNOXTOKEN service maintains some hard-coded token metadata out-of-the-box:

  • userName

  • comment

  • enabled

  • passcode

  • createdBy (in case of impersonated tokens)

In Cloudera Runtime version 7.2.16, Cloudera has introduced support for a new feature that allows end-users to add accept query parameters starting with the md_ prefix and treat them as Knox Token Metadata.

Example

curl -iku admin:admin-password -X GET 'https://$KNOX_GATEWAY_HOST:8443/gateway/sandbox/knoxtoken/api/v1/token?md_notebookName=accountantKnoxToken&md_souldBeRemovedBy=31March2022&md_otherMeaningfuMetadata=KnoxIsCool'

When such a token is created by Knox, the following metadata should be saved:

  • notebookName=accountantKnoxToken

  • shouldBeRemovedBy=31March2022

  • otherMeaningfulMetadata=KnoxIsCool

It will not only enable Knox to save these metadata, but will also enable Knox's existing getUserTokens API endpoint to fetch basic token information using the supplied metadata name besides the username information.

Example:
curl -iku admin:admin-password -X GET 'https://$KNOX_GATEWAY_HOST:8443/gateway/sandbox/knoxtoken/api/v1/token/getUserTokens?userName=admin&md_notebookName=accountantKnoxToken&md_name=*'

It will return all Knox tokens where metadata with notebookName exists and equals accountantKnoxToken OR metadata with name exists.

Another Sample:

  1. Create token1 with md_Name=reina&md_Score=50

  2. Create token2 with md_Name=mary&md_Score=100

  3. Create token3 with md_Name=mary&md_Score=20&md_Grade=A

The following table shows the returned token(s) in case metadata filtering is added in the getUserTokens API:

Metadata Token returned
md_Name=reina token1
md_Name=mary token2 and token3
md_Score=100 token2
md_Name=mary&md_Score=20 token2 and token3
md_Name=mary&md_Name=reina token1, token2 and token3
md_Name=* token1, token2 and token3
md_Uknown=* Empty list

For more information on sample curl commands, see Managing custom Knox Token metadata.