From: Arran Cudbard-Bell Date: Tue, 22 Oct 2019 10:59:47 +0000 (-0400) Subject: Various tweaks, and information on performing group checks X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=71b67dcfc6e8808e655371c1e50544ded333eba0;p=thirdparty%2Ffreeradius-server.git Various tweaks, and information on performing group checks --- diff --git a/doc/antora/modules/howto/pages/modules/ldap/authorization/groups.adoc b/doc/antora/modules/howto/pages/modules/ldap/authorization/groups.adoc index e69de29bb2d..21399254cbc 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authorization/groups.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authorization/groups.adoc @@ -0,0 +1,192 @@ += Group authorization + +A very common requirement is to restrict access to particular groups within +LDAP, or to return different authorizational attributes based on a user's group +memberships. + +How groups are managed by different directories can differ significantly. + +Other sections in this tutorial have assigned variant numbers to the different +group mappings. The definitions of these variants is repeated below for easy +referencing: + +- _variant 1_ - User objects contain membership attributes referencing group objects by DN. +- _variant 2_ - User objects contain membership attributes referencing group objects by name. +- _variant 3_ - Group objects contain membership attributes referencing user objects by DN. +- _variant 4_ - Group objects contain membership attributes referencing user objects by name. + +== Configuring group lookups + +=== Editing mods-available/ldap to configure _variant 1_ group checks + +[source,config] +---- +ldap { + group { + # example - ou=groups,dc=example,dc=com + base_dn = '' <1> + + # example - groupOfNames + filter = '' <2> + + # example - cn + name_attribute = '' <3> + + # example - memberOf + membership_attribute = ' <4> + } +} +---- +<1> Where in the directory to begin the search for group objects. +<2> Filter matching the objectClass(es) of all relevant group objects. +<3> Attribute within the group object containing its name. +<4> Attribute within the user object referencing groups by their DNs. + +=== Editing mods-available/ldap to configure _variant 2_ group checks + +[source,config] +---- +ldap { + group { + # example - ou=groups,dc=example,dc=com + base_dn = '' <1> + + # example - groupOfNames + filter = '' <2> + + # example - cn + name_attribute = '' <3> + + # example - memberOf + membership_attribute = ' <4> + } +} +---- +<1> Where in the directory to begin the search for group objects. +<2> Filter matching the objectClass(es) of all relevant group objects. +<3> Attribute within the group object containing its name. +<4> Attribute within the user object referencing groups by their name. + +=== Editing mods-available/ldap to configure _variant 3_ group checks + +[source,config] +---- +ldap { + group { + # example - ou=groups,dc=example,dc=com + base_dn = '' <1> + + # example - groupOfNames + filter = '' <2> + + # example - cn + name_attribute = '' <3> + + # example - (member=%{control:Ldap-UserDn}) + membership_filter = "(=%{control:Ldap-UserDn})" <4> + } +} +---- +<1> Where in the directory to begin the search for group objects. +<2> Filter matching the objectClass(es) of all relevant group objects. +<3> Attribute within the group object containing its name. +<4> Attribute within the group object referencing users by their DN. + +=== Editing mods-available/ldap to configure _variant 4_ group checks + +[source,config] +---- +ldap { + group { + # example - ou=groups,dc=example,dc=com + base_dn = '' <1> + + # example - groupOfNames + filter = '' <2> + + # example - cn + name_attribute = '' <3> + + # example - (memberUid=%{control:Ldap-UserDn}) + membership_filter = "(=%{control:Ldap-UserDn})" <4> + } +} +---- +<1> Where in the directory to begin the search for group objects. +<2> Filter matching the objectClass(es) of all relevant group objects. +<3> Attribute within the group object containing its name. +<4> Attribute within the group object referencing users by their name (uid). + +== "Live" group lookups + +[TIP] +==== +For _variant 1_ and _variant 2_, when checking group memberships, it is most +efficient to specify the group in the same format as the reference. + +For example, if the directory implements _variant 1_, then the group would be +specified as a DN, and if the directory implements _variant 2_, then the group +would be specified by name. +==== + +Group checks are performed using the virtual attribute `LDAP-Group`. +Comparing this attribute to a group name or group DN, will, (if group caching +is not enabled) result in a query being sent to the LDAP Directory to determine +if the user is a member of the specified group. + +When performing group checks LDAP module abstracts away the differences between +group membership _variants [1-4]_ so long as it has been configured +appropriately. + +=== Group membership check by DN + +[source,unlang] +---- +if (LDAP-Group == 'cn=foo,ou=groups,dc=example,dc=com') { + update reply { + &Reply-Message := "Welcome member of group 'foo'" + } +} +---- + +=== Group membership check by name + +[source,unlang] +---- +if (LDAP-Group == 'foo') { + update reply { + &Reply-Message := "Welcome member of group 'foo'" + } +} +---- + +== Cached group lookups + +In some instances it's useful to retrieve complete group listings for users. +The most common reasons for this are: +- To maintain a local cache in case connectivity to the LDAP directory is lost. +- To perform group checks in ways not supported by the LDAP module. One example + of this is checking for membership in nested groups. + +When caching group membership information the LDAP module abstracts away the +differences between group membership _variants [1-4]_ so long as it has been +configured appropriately. + +Two configuration items control group caching: + +- `group.cacheable_name` - If set to 'yes', the names of groups the user is a member of will be cached. +- `group.cacheable_dn` - If set to 'yes', the DNs of the groups the user is a member of will be cached. + +The type of caching should match the format of the group check values. For +example, when checking for group memberships using DNs `group.cacheable_dn` +should be set, and when checking for group memberships using group names +`group.cacheable_name` should be set. + +One exception to this, is if nested group checks are being performed. +In this case `group.cacheable_dn` must be set, as the full path of the group +objects is required. + + + + + diff --git a/doc/antora/modules/howto/pages/modules/ldap/authorization/locating_the_user.adoc b/doc/antora/modules/howto/pages/modules/ldap/authorization/locating_the_user.adoc index 73f12ecfd5f..c3e59554350 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authorization/locating_the_user.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authorization/locating_the_user.adoc @@ -10,6 +10,8 @@ explaining how the different configuration items are used. See xref:modules/ldap/ldapsearch/index.adoc[ldapsearch] for how to determine the appropriate values for your directory. +== Editing mods-available/ldap to specify how to search for user objects + [source,config] ---- ldap { diff --git a/doc/antora/modules/howto/pages/modules/ldap/authorization/user_account_controls.adoc b/doc/antora/modules/howto/pages/modules/ldap/authorization/user_account_controls.adoc index 76962a0ef3c..cf4ea27740b 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authorization/user_account_controls.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authorization/user_account_controls.adoc @@ -35,7 +35,7 @@ is enabled, or disabled, depending on the value of `user.access_positive`. When a user is "locked out", the LDAP module will return `disallow` in (≥ v4.0.x) and `userlock` in (≤ v3.0.x). -=== Access attribute indicates account is enabled +=== Editing mods-available/ldap to only allow access if the 'Access Attribute' is present [source,config] ---- @@ -52,7 +52,7 @@ ldap { If the attribute is absent or set to false then the user will be "locked out". -=== Access attribute indicates account is disabled +=== Editing mods-available/ldap to disable access if the 'Access Attribute' is present [source,config] ---- diff --git a/doc/antora/modules/howto/pages/modules/ldap/authorization/user_disambiguation.adoc b/doc/antora/modules/howto/pages/modules/ldap/authorization/user_disambiguation.adoc index 755ce84ec0a..ade79729ff8 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authorization/user_disambiguation.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authorization/user_disambiguation.adoc @@ -31,6 +31,16 @@ As the error message states, there are multiple ways to resolve this issue: == Enabling and configuring Server Side Sorting +Server Side Sorting controls are specified by +https://tools.ietf.org/html/rfc2891[RFC 2891]. + +SSS controls allow the client to request the server sort results in a specific +and consistent order. This ensures that in the case where there is an ambiguous +result, the same user object (the first in the result set) will be used by the +LDAP module. + +Without SSS which object is used by the LDAP module will be essentially random. + [TIP] ==== If you followed the @@ -50,16 +60,6 @@ EOF ---- ==== -Server Side Sorting controls are specified by -https://tools.ietf.org/html/rfc2891[RFC 2891]. - -SSS controls allow the client to request the server sort results in a specific -and consistent order. This ensures that in the case where there is an ambiguous -result, the same user object (the first in the result set) will be used by the -LDAP module. - -Without SSS which object is used by the LDAP module will be essentially random. - == Editing mods-available/ldap to enable SSS [source,config] diff --git a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/locating_objects.adoc b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/locating_objects.adoc index d5a4badb7db..db699ccc6f4 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/locating_objects.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/locating_objects.adoc @@ -237,11 +237,11 @@ result: 0 Success ** `group_membership_attribute` - User object attribute containing group membership information. e.g. `memberOf`. * _variant 3_ -** `group_membership_filter_by_uid` - A filter matching user membership by DN -e.g. `(memberUid=%{%{Stripped-User-Name}:-%{User-Name}})`. +** `group_membership_dn_attribute` - An attribute in the group object referencing user objects by DN +e.g. `member`. * _variant 4_ -** `group_membership_filter_by_name` - A filter matching user membership uid -e.g. `(member=%{control:Ldap-UserDn})`. +** `group_membership_uid_attribute` - An attribute in the group object referencing user objects by UID +e.g. `memberUID`. .Locating groups in "mature" directories **** diff --git a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc index 8adadaf10a8..67a1caebb5d 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc @@ -49,7 +49,7 @@ User objects reference groups using DNs. [width="100%",cols="30%,70%",options="header",] |=== | Purpose | `ldap { group { ... } }` config item -| Specify how to find group objects by DN, when referenced by a user object. | ```group_membership_attribute = ''``` +| Specify how to find group objects by DN, when referenced by a user object. | ```membership_attribute = ''``` |=== == Groups - variant 2 @@ -59,7 +59,7 @@ User objects reference groups using group names. [width="100%",cols="30%,70%",options="header",] |=== | Purpose | `ldap { group { ... } }` config item -| Specify how to find group objects by name, when referenced by a user object. | ```group_membership_attribute = ''``` +| Specify how to find group objects by name, when referenced by a user object. | ```membership_attribute = ''``` |=== == Groups - variant 3 @@ -69,7 +69,7 @@ Group objects reference users using DNs. [width="100%",cols="30%,70%",options="header",] |=== | Purpose | `ldap { group { ... } }` config item -| Specify how to find group objects referencing a user by DN. | ```membership_filter = "(=%{control:Ldap-UserDn})"``` +| Specify how to find group objects referencing a user by DN. | ```membership_filter = "(=%{control:Ldap-UserDn})"``` |=== == Groups - variant 4 @@ -79,7 +79,7 @@ Group objects reference users using user names. [width="100%",cols="30%,70%",options="header",] |=== | Purpose | `ldap { group { ... } }` config item -| Specify how to find group objects referencing a user by name. | ```membership_filter = "(=%{%{Stripped-User-Name}:-%{User-Name}})"``` +| Specify how to find group objects referencing a user by name. | ```membership_filter = "(=%{%{Stripped-User-Name}:-%{User-Name}})"``` |=== .Mixing and matching group membership schemes