Sub-Claims
For some of the Auth Methods like JWT/OIDC, K8s, SAML, and LDAP that contain sub-claims or attribute-based access control (ABAC), also known as policy-based access control, as part of the given signed token, you can restrict the authorizations of the associated role to these specific claims or attributes. In other words, only clients whose token contains these sub-claims (in the case of JWT/OIDC) or attributes (in the case of SAML) will be allowed to access the rules defined in the role.
The sub-claims definition is in the structure of a map that contains keys that represent the field name of the sub-claims, and each key can contain several values so that the sub-claim must contain one of those values. The keys and values are case-sensitive.
For example, assume sub-claims are set to:
Groups=Engineering
[email protected]
Only JWTs or SAML-XML containing both the Groups
and Email
claims/attributes, and respective matching values of Engineering
and [email protected]
, would be authorized.
If the expected value is a list, the claim must match one of the items on the list. For example, assume sub-claims are set to:
Groups=Engineering,Security
[email protected],[email protected]
Only JWTs or SAML-XML containing both the Groups
and Email
claims/attributes, and respective matching values of [Engineering
or Security
] and [[email protected]
or [email protected]
], would be authorized.
Info
You may also use wildcard characters to allow a wider range of permissions. The supported wildcard characters are:
?
: Replaces one character. For example, the string1?1
will accept121
but not1231
.
*
: Replaces any amount of characters. For example, the string*@example.com
will accept any address in that domain.
You can set the relevant sub-claims to an existing role using the Akeyless Command Line Interface (CLI)
akeyless assoc-role-am --role-name r1 --am-name Okta --sub-claims Groups=Engineering,Security --sub-claims [email protected],[email protected]
Or directly from the Akeyless Console using the Access Roles with Authentication Methods association.
Path Templating
For easier management of your access rules, sub-claims keys can be utilized for quicker and more scalable rule definitions for the access path.
Each sub-claim key should be wrapped by double curly braces, i.e. {{Sub-Claim Name}}
with a /
as a separator for folders.
For example, say that the following sub-claims exist in your Access Role:
Groups=Engineering,Security,DevOps
Username=Alice,Bob,Charlie,Dennis
And this is the original mapping in your Identity Provider:
Groups | Username |
---|---|
Engineering | Alice |
Security | Bob, Charlie |
DevOps | Dennis |
Those claims can be templated as /{{Groups}}/{{Username}}/*
(or the relevant attribute in your IdP) for your rule path:
akeyless set-role-rule --role-name r1 --path "/{{Groups}}/{{Username}}/*" -c read
Each user will get read
permissions for the relevant paths, based on the sub-claims key values.
This means that Alice
will get read
permissions under/Engineering/Alice/*
, Bob
&Charlie
will have access to /Security/Bob/*
and /Security/Charlie/*
accordingly, and Dennis
will have access to /DevOps/Dennis/*
.
Note
Templating Access Rules supports Access Role case-sensitive settings.
View Sub-Claims
To review the current Sub-Claims available for your Authentication Method, from the Akeyless Console, simply click on your account logo and click on Show Sub Claims.
To view the available Sub-Claims of your Authentication Method from the Akeyless CLI based on the CLI profile you are using, run the following command:
akeyless describe-sub-claims
Alternatively, to view a different Authentication Method available sub-claims you can specify the exact token or the relevant CLI profile name:
akeyless describe-sub-claims --profile <CLI profile>
Updated 9 months ago