From cde83e8818153af6e36597fd7af5c7f39e713a49 Mon Sep 17 00:00:00 2001 From: Mateusz Mandera Date: Sat, 17 Aug 2024 20:42:37 +0200 Subject: [PATCH] saml: Add documentation about user role/custom profile fields sync. With substantial rewriting by tabbott, including moving mostly irrelevant references to very old Zulip versions. --- docs/production/authentication-methods.md | 60 ++++++++++++++--------- 1 file changed, 38 insertions(+), 22 deletions(-) diff --git a/docs/production/authentication-methods.md b/docs/production/authentication-methods.md index d9a454a995..f83908e42a 100644 --- a/docs/production/authentication-methods.md +++ b/docs/production/authentication-methods.md @@ -498,9 +498,8 @@ the bottom of the problem: ## SAML -Zulip 2.1 and later supports SAML authentication, used by Okta, -OneLogin, and many other IdPs (identity providers). You can configure -it as follows: +Zulip supports SAML authentication, used by Okta, OneLogin, and many +other IdPs (identity providers). You can configure it as follows: 1. These instructions assume you have an installed Zulip server; if you're using Zulip Cloud, see [this article][saml-help-center], @@ -599,25 +598,6 @@ it as follows: 1. Enable the `zproject.backends.SAMLAuthBackend` auth backend, in `AUTHENTICATION_BACKENDS` in `/etc/zulip/settings.py`. -1. (Optional) New in Zulip 5.0: Zulip can synchronize [custom profile - fields][custom-profile-fields] from the SAML provider. Just - configure the `SOCIAL_AUTH_SYNC_CUSTOM_ATTRS_DICT`; the - [LDAP](#synchronizing-custom-profile-fields) documentation for - synchronizing custom profile fields will be helpful. Servers - installed before Zulip 5.0 may want to [update inline comment - documentation][update-inline-comments] so they can take advantage - of the latest inline SAML documentation in - `/etc/zulip/settings.py`. - - Note that in contrast with LDAP, Zulip can only query the SAML - database for a user's settings when the user authenticates to Zulip - using SAML, so custom profile fields are only synchronized when the - user logs in. - - Note also that the SAML feature currently only synchronizes custom - profile fields during login, not during account creation; we - consider this [a bug](https://github.com/zulip/zulip/issues/18746). - 1. [Restart the Zulip server](settings.md) to ensure your settings changes take effect. The Zulip login page should now have a button for SAML authentication that you can use to log in or @@ -629,6 +609,7 @@ it as follows: IdP. [saml-help-center]: https://zulip.com/help/saml-authentication +[user-role-help-center]: https://zulip.com/help/roles-and-permissions ### IdP-initiated SSO @@ -675,6 +656,41 @@ to the root and `engineering` subdomains: ``` +### Synchronizing user role or custom profile fields during login + +In contrast with SCIM or LDAP, the SAML protocol only allows Zulip to +access data about a user when that user authenticates to Zulip using +SAML, so metadata can only be synchronized when the user logs in. + +As a result, most installations using SAML will want to use [SCIM +provisioning](./scim.md) to synchronize metadata continuously. Zulip +nonetheless includes support for copying certain fields from a SAML +database, which can be a good option when a SAML provider does not +offer SCIM or the fields one is interested in syncing change rarely +enough that asking users to logout and then login again to resync +their metadata might feel reasonable. + +Specifically, Zulip supports synchronizing the [user +role][user-role-help-center] and [custom profile +fields][custom-profile-fields] from the SAML provider. + +In order to use this functionality, configure +`SOCIAL_AUTH_SYNC_ATTRS_DICT` in `/etc/zulip/settings.py` according to +the instructions in the inline documentation in the file. Servers +installed before Zulip 10.0 may want to [update inline comment +documentation][update-inline-comments] first in order to access it. + +Custom profile fields are only synchronized during login, not during +account creation; we consider this [a +bug](https://github.com/zulip/zulip/issues/18746). User role is +synchronized during both account creation and each consecutive login. + +:::{note} +When user role is provided by the SAML IdP during signup of a +user who's coming from an invitation link, the IdP-provided role will +take precedence over the role set in the invitation. +::: + ### SCIM Many SAML IdPs also offer SCIM provisioning to manage automatically