Namespace claims for JWT tokens

Learn about the namespace claims you can include in JWT tokens

Vault supports special meaning to JWT claims under the https://app.piiano.io/ namespace. You can include these claims JWT tokens to control access more granularly than the user's role. In addition, you can include namespace claim details in the IAM configuration to provide additional validation of a JWT token.

https://app.piiano.io/role

The https://app.piiano.io/role claim is used to specify the user's role. The value of the claim is a string. roles_claim overrides this configuration if specified.

https://app.piiano.io/prop/<prop>

Vault supports object-level access control using claims under the https://app.piiano.io/prop/ namespace. The https://app.piiano.io/prop/<prop> claim is used to specify the value of a property required when interacting with objects, tokens, and encrypted objects.

The value of the claim is a string or an array of strings. If the value is an array, the operation is allowed when the property value matches any of the values in the array.

For example, these claims enforce that the request is allowed only if the user_id property is user1 and the group_id property is either group-1 or group-2 in the accessed object, token, or ciphertext:

{
  "https://app.piiano.io/prop/user_id": "user1",
  "https://app.piiano.io/prop/group_id": ["group-1", "group-2"]
}

These API operations support object-level access control:

Operation	Description
add-object	Object fields must match the property values specified by the claim.
get-object-by-id	Returned objects must match the property values specified by the claim.
update-object-by-id	The fields of an updated object must match the property values specified by the claim before and after the update.
delete-objects	The object to delete must match the property values specified by the claim.
search-objects	Returned objects must match the property values specified by the claim.
list-objects	Returned objects must match the property values specified by the claim.
update-objects	The fields of the updated objects must match the property values specified by the claim before and after the update.
delete-objects	The objects to delete must match the property values specified by the claim.
tokenize	The new tokens' fields must match the property values specified by the claim.
detokenize	Detokenized token's field must match the property values specified by the claim.
update-tokens	The fields of the updated token must match the property values specified by the claim before and after the update. The non-reversible token type is not supported and returns an error.
encrypt	The fields to encrypt must match the property values specified by the claim.
decrypt	Decrypted fields must match the property values specified by the claim.
update-encrypted	The updated encrypted object must match the property values specified by the claim before and after the update.
hash-objects	Fields to be hashed must match the property values specified by the claim.
invoke-http-call-action	The objects, tokens, and encrypted-objects accessed by the action role must match the property values specified by the claim.
invoke-action	The objects, tokens, and encrypted-objects accessed by the custom action role must match the property values specified by the claim.

Other API operations return an error if the https://app.piiano.io/prop/<prop> claim is in the JWT access token.

tip

When using object-level access control, the properties enforced must be present in the object, token, or ciphertext operated on. If the property is not present, the operation fails.

To allow a property to be optional, set the value of the claim to null or include null in the array of values.

note

JSON and BLOB data types are not supported for object-level access control.

warning

Claims within a JWT are not encrypted and are visible in plain text. Therefore, do not include any sensitive information in these claims. JWTs are best suited for non-sensitive properties like id, tenant_id, owner_id, and owner_collection.

https://app.piiano.io/prop-claim-ref/<prop>

The https://app.piiano.io/prop-claim-ref/<prop> claim is used to specify that the value for the property is in another claim in the JWT token. The value of the claim is the name of the claim in the JWT access token. Then, the property is validated like the https://app.piiano.io/prop/<prop> claim.

For example, these claims enforce that the request is allowed only if the user_id property is user1 in the object, token, or ciphertext accessed. Vault looks for the value of the myapp_user_id claim in the JWT access token:

{
  "myapp_user_id": "user1",
  "https://app.piiano.io/prop-claim-ref/user_id": "myapp_user_id"
}

tip

The https://app.piiano.io/prop-claim-ref/<prop> claim is useful to avoid repeating the same value in multiple claims, or when only static custom claims are supported by the identity provider.

https://app.piiano.io/any-of

The https://app.piiano.io/any-of claim is used to specify enforcement among multiple properties. The claim is an object, where each key is another namespace claim.

The keys of the object do not have to be prefixed by the https://app.piiano.io/ namespace, and can be used with the path part only (i.e., https://app.piiano.io/prop/<prop> can be written as prop/<prop>).

For example, these claims enforce that the request is allowed only if the user_id property is user1 OR the group_id property is either group-1 or group-2 in the object, token, or ciphertext accessed:

{
  "https://app.piiano.io/any-of": {
    "prop/user_id": "user1",
    "prop/group_id": ["group-1", "group-2"]
  }
}

You can think of the https://app.piiano.io/any-of claim as an OR statement between the properties. If any of the properties are satisfied, the operation is allowed.

The https://app.piiano.io/any-of claim can be nested within other claims. For example, these claims enforce that the request is allowed only if the tenant_id property is tenant1 AND either the user_id property is user1 OR the group_id property is either group-1 or group-2 in the object, token, or ciphertext accessed:

{
  "https://app.piiano.io/any-of": {
	  "prop/tenant_id": "tenant1",
	  "any-of": {
	    "prop/user_id": "user1",
	    "prop/group_id": ["group-1", "group-2"]
	  }
	  }
}

The namespace claims can be nested to 5 levels.

tip

When using multiple https://app.piiano.io/any-of claims at the same level, add an identifier to separate them. For example, https://app.piiano.io/any-of/1, https://app.piiano.io/any-of/2, etc.

https://app.piiano.io/all-of

The https://app.piiano.io/all-of claim is used to enforce multiple properties. The claim is an object, where each key is another namespace claim. See any-of for more details about the structure.

You can think of the https://app.piiano.io/all-of claim as an AND statement between the properties. If all of the properties are satisfied, the operation is allowed.

For example, these claims enforce that the request is allowed only if the user_id property is user1 AND the group_id property is either group-1 or group-2 in the object, token, or ciphertext accessed:

{
  "https://app.piiano.io/all-of": {
    "prop/user_id": "user1",
    "prop/group_id": ["group-1", "group-2"]
  }
}

By default, if not using the https://app.piiano.io/any-of claim, then namespace claims at the same level are considered an AND statement.

tip

When using multiple https://app.piiano.io/all-of claims at the same level, add an identifier to separate them. For example, https://app.piiano.io/all-of/1, https://app.piiano.io/all-of/2, etc.