Configuring role mappings

When a user authenticates using SAML, they are identified to the Elastic Stack, but this does not automatically grant them access to perform any actions or access any data.

Your SAML users cannot do anything until they are assigned roles. This can be done through either the add role mapping API or with authorization realms.

You cannot use role mapping files to grant roles to users authenticating via SAML.

This is an example of a simple role mapping that grants the example_role role to any user who authenticates against the saml1 realm:

  1. PUT /_security/role_mapping/saml-example
  2. {
  3.   "roles": [ "example_role" ], 
  4.   "enabled": true,
  5.   "rules": {
  6.     "field": { "realm.name": "saml1" }
  7.   }
  8. }

The example_role role is not a builtin Elasticsearch role. This example assumes that you have created a custom role of your own, with appropriate access to your data streams, indices, and Kibana features.

The attributes that are mapped via the realm configuration are used to process role mapping rules, and these rules determine which roles a user is granted.

The user fields that are provided to the role mapping are derived from the SAML attributes as follows:

  • username: The principal attribute
  • dn: The dn attribute
  • groups: The groups attribute
  • metadata: See User metadata

For more information, see Mapping users and groups to roles and Role mappings.

If your IdP has the ability to provide groups or roles to Service Providers, then you should map this SAML attribute to the attributes.groups setting in the Elasticsearch realm, and then make use of it in a role mapping as per the example below.

This mapping grants the Elasticsearch finance_data role, to any users who authenticate via the saml1 realm with the finance-team group.

  1. PUT /_security/role_mapping/saml-finance
  2. {
  3.   "roles": [ "finance_data" ],
  4.   "enabled": true,
  5.   "rules": { "all": [
  6.         { "field": { "realm.name": "saml1" } },
  7.         { "field": { "groups": "finance-team" } }
  8.   ] }
  9. }

If your users also exist in a repository that can be directly accessed by Elasticsearch (such as an LDAP directory) then you can use authorization realms instead of role mappings.

In this case, you perform the following steps: 1. In your SAML realm, assigned a SAML attribute to act as the lookup userid, by configuring the attributes.principal setting. 2. Create a new realm that can lookup users from your local repository (e.g. an ldap realm) 3. In your SAML realm, set authorization_realms to the name of the realm you created in step 2.