Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.
This commit is contained in:
Mateusz Mandera 2024-08-17 20:42:37 +02:00 committed by Tim Abbott
parent 833dce8a13
commit cde83e8818
1 changed files with 38 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
docs/production/authentication-methods.md
View File

@ -498,9 +498,8 @@ the bottom of the problem:
## SAML ## SAML
Zulip 2.1 and later supports SAML authentication, used by Okta, Zulip supports SAML authentication, used by Okta, OneLogin, and many
OneLogin, and many other IdPs (identity providers). You can configure other IdPs (identity providers). You can configure it as follows:
it as follows:
1. These instructions assume you have an installed Zulip server; if 1. These instructions assume you have an installed Zulip server; if
you're using Zulip Cloud, see [this article][saml-help-center], 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 1. Enable the `zproject.backends.SAMLAuthBackend` auth backend, in
`AUTHENTICATION_BACKENDS` in `/etc/zulip/settings.py`. `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 1. [Restart the Zulip server](settings.md) to ensure
your settings changes take effect. The Zulip login page should now 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 have a button for SAML authentication that you can use to log in or
@ -629,6 +609,7 @@ it as follows:
IdP. IdP.
[saml-help-center]: https://zulip.com/help/saml-authentication [saml-help-center]: https://zulip.com/help/saml-authentication
[user-role-help-center]: https://zulip.com/help/roles-and-permissions
### IdP-initiated SSO ### IdP-initiated SSO
@ -675,6 +656,41 @@ to the root and `engineering` subdomains:
</saml2:Attribute> </saml2:Attribute>
``` ```
### 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 ### SCIM
Many SAML IdPs also offer SCIM provisioning to manage automatically Many SAML IdPs also offer SCIM provisioning to manage automatically