Skip to content

Commit

Permalink
[DOCS] Update SAML guide to reference attribute_delimiters.group (ela…
Browse files Browse the repository at this point in the history
…stic#103102)

This is a follow up PR from
elastic#102769. The SAML realm can
now be configured to split the `groups` attribute by delimiter, this
updates the docs to mention that.
  • Loading branch information
jfreden authored Dec 8, 2023
1 parent 47a640f commit 39d9ce8
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 24 deletions.
27 changes: 9 additions & 18 deletions docs/reference/security/authentication/saml-guide.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -328,24 +328,15 @@ groups:: _(Recommended)_
+
[NOTE]
====
Some IdPs are configured to send the `groups` list as a comma-separated string,
but {es} can't parse this string into an array of groups. To map this SAML
attribute to the `attributes.groups` setting in the {es} realm, a cluster
security administrator can use a wildcard when
<<saml-role-mapping,configuring role mappings>>. While flexible, wildcards are
less accurate and can match on unwanted patterns. Instead, a cluster security
administrator can use a regular expression to create a role mapping rule that
matches only a single group. For example, the following regular expression
matches only on the `elasticsearch-admins` group:
[source,sh]
----
/^(.*,)?elasticsearch-admins(,.*)?$/
----
These regular expressions are based on Lucene’s
{ref}/regexp-syntax.html[regular expression syntax], and can match more complex
patterns. All regular expressions must start and end with a forward slash.
Some IdPs are configured to send the `groups` list as a single value, comma-separated
string. To map this SAML attribute to the `attributes.groups` setting in the {es}
realm, you can configure a string delimiter using the `attribute_delimiters.group`
setting.
For example, splitting the SAML attribute value
`engineering,elasticsearch-admins,employees` on a delimiter value of `,` will
result in `engineering`, `elasticsearch-admins`, and `employees` as the list of
groups for the user.
====

name:: _(Optional)_ The user's full name.
Expand Down
12 changes: 6 additions & 6 deletions docs/reference/settings/security-settings.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -1222,7 +1222,7 @@ _Distinguished Name_.
`attribute_patterns.principal` {ess-icon}::
(<<static-cluster-setting,Static>>)
A Java regular expression that is matched against the SAML attribute specified
by `attributes.pattern` before it is applied to the user's _principal_ property.
by `attributes.principal` before it is applied to the user's _principal_ property.
The attribute value must match the pattern and the value of the first
_capturing group_ is used as the principal. For example, `^([^@]+)@example\\.com$`
matches email addresses from the "example.com" domain and uses the local-part as
Expand Down Expand Up @@ -1257,13 +1257,13 @@ As per `attribute_patterns.principal`, but for the _dn_ property.
`attribute_delimiters.groups` {ess-icon}::
(<<static-cluster-setting,Static>>)
A plain string that is used as a delimiter to split a single-valued SAML
attribute specified by attributes.groups before it is applied to the user's
groups property. For example, splitting the SAML attribute value
engineering,elasticsearch-admins,employees on a delimiter value of , will
result in engineering, elasticsearch-admins, and employees as the list of
attribute specified by `attributes.groups` before it is applied to the user's
_groups_ property. For example, splitting the SAML attribute value
`engineering,elasticsearch-admins,employees` on a delimiter value of `,` will
result in `engineering`, `elasticsearch-admins`, and `employees` as the list of
groups for the user. The delimiter will always be split on, regardless of
escaping in the input string. This setting does not support multi-valued SAML
attributes. It cannot be used together with the attribute_patterns setting.
attributes. It cannot be used together with the `attribute_patterns` setting.
You can only configure this setting for the groups attribute.
// end::saml-attributes-delimiters-groups-tag[]

Expand Down

0 comments on commit 39d9ce8

Please sign in to comment.