From 7d2148dbc8bfef72e7eb93471d425e270e5252e3 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Mon, 16 Nov 2020 11:22:46 -0500 Subject: [PATCH] [DOCS] Adding authorization_realms setting for OIDC (#64877) * Adding authorization_realms setting for OIDC. * Fix typo * Splitting note into separate notes. --- .../settings/security-settings.asciidoc | 7 +++++ .../authentication/oidc-guide.asciidoc | 7 +++-- .../authorization/mapping-roles.asciidoc | 28 +++++++++---------- 3 files changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/reference/settings/security-settings.asciidoc b/docs/reference/settings/security-settings.asciidoc index 4fffea07529b2..72bf73c799bcb 100644 --- a/docs/reference/settings/security-settings.asciidoc +++ b/docs/reference/settings/security-settings.asciidoc @@ -1610,6 +1610,13 @@ File-based resources are polled at a frequency determined by the global {es} `resource.reload.interval.high` setting, which defaults to 5 seconds. // end::oidc-op-jwkset-path-tag[] +`authorization_realms`:: +(<>) +The names of the realms that should be consulted for delegated authorization. +If this setting is used, then the OpenID Connect realm does not perform role +mapping and instead loads the user from the listed realms. +See <>. + // tag::rp-client-id-tag[] `rp.client_id` {ess-icon}:: (<>) diff --git a/x-pack/docs/en/security/authentication/oidc-guide.asciidoc b/x-pack/docs/en/security/authentication/oidc-guide.asciidoc index 7b066de5868bc..2f6e86b76c2b9 100644 --- a/x-pack/docs/en/security/authentication/oidc-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/oidc-guide.asciidoc @@ -481,12 +481,13 @@ If your users also exist in a repository that can be directly accessed by {es} <> instead of role mappings. In this case, you perform the following steps: + 1. In your OpenID Connect realm, assign a claim to act as the lookup userid, by configuring the `claims.principal` setting. -2. Create a new realm that can lookup users from your local repository (e.g. an +2. Create a new realm that can look up users from your local repository (e.g. an `ldap` realm) -3. In your OpenID Connect realm, set `authorization_realms` to the name of the realm you - created in step 2. +3. In your OpenID Connect realm, set `authorization_realms` to the name of the +realm you created in step 2. [[oidc-user-metadata]] === User metadata diff --git a/x-pack/docs/en/security/authorization/mapping-roles.asciidoc b/x-pack/docs/en/security/authorization/mapping-roles.asciidoc index f05672a874f47..9badd93439006 100644 --- a/x-pack/docs/en/security/authorization/mapping-roles.asciidoc +++ b/x-pack/docs/en/security/authorization/mapping-roles.asciidoc @@ -10,6 +10,9 @@ For other types of realms, you must create _role-mappings_ that define which roles should be assigned to each user based on their username, groups, or other metadata. +NOTE: When <> is enabled, the roles +of the anonymous user are assigned to all the other users as well. + You can define role-mappings via an <> or manage them through <>. These two sources of role-mapping are combined inside of the {es} @@ -17,6 +20,8 @@ These two sources of role-mapping are combined inside of the {es} possible for a single user to have some roles that have been mapped through the API, and other roles that are mapped through files. +NOTE: Users with no roles assigned will be unauthorized for any action. + When you use role-mappings, you assign existing roles to users. The available roles should either be added using the {ref}/security-api.html#security-role-apis[role management APIs] or defined in the @@ -25,13 +30,8 @@ either role management method. For example, when you use the role mapping API, you are able to map users to both API-managed roles and file-managed roles (and likewise for file-based role-mappings). -NOTE: The PKI, LDAP, Kerberos and SAML realms support using -<> as an alternative to role mapping. - -NOTE: When <> is enabled, the roles -of the anonymous user are assigned to all the other users as well. - -NOTE: Users with no roles assigned will be unauthorized for any action. +TIP: The PKI, LDAP, Kerberos, OpenID Connect, and SAML realms support using +<> as an alternative to role mapping. [[mapping-roles-api]] ==== Using the role mapping API @@ -49,10 +49,10 @@ this. By default, role mappings are stored in `ES_PATH_CONF/role_mapping.yml`, where `ES_PATH_CONF` is `ES_HOME/config` (zip/tar installations) or `/etc/elasticsearch` (package installations). To specify a different location, -you configure the `files.role_mapping` setting in the -{ref}/security-settings.html#ref-ad-settings[Active Directory], -{ref}/security-settings.html#ref-ldap-settings[LDAP], and -{ref}/security-settings.html#ref-pki-settings[PKI] realm settings in +you configure the `files.role_mapping` setting in the +<>, +<>, and +<> realm settings in `elasticsearch.yml`. Within the role mapping file, the security roles are keys and groups and users @@ -67,9 +67,9 @@ this is a common setting in Elasticsearch, changing its value might effect other schedules in the system. While the _role mapping APIs_ is the preferred way to manage role mappings, using -the `role_mappings.yml` file becomes useful in a couple of use cases: +the `role_mappings.yml` file becomes useful in a couple of use cases: -. If you want to define fixed role mappings that no one (besides an administrator +. If you want to define fixed role mappings that no one (besides an administrator with physical access to the {es} nodes) would be able to change. . If cluster administration depends on users from external realms and these users @@ -82,7 +82,7 @@ as a minimal administrative function and is not intended to cover and be used to define roles for all use cases. IMPORTANT: You cannot view, edit, or remove any roles that are defined in the role -mapping files by using the role mapping APIs. +mapping files by using the role mapping APIs. ==== Realm specific details [discrete]