diff --git a/docs/production/authentication-methods.md b/docs/production/authentication-methods.md index a53e0d0de9..343a6d35fc 100644 --- a/docs/production/authentication-methods.md +++ b/docs/production/authentication-methods.md @@ -41,9 +41,13 @@ Zulip 2.1 and later 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. You - can have created an organization already using EmailAuthBackend, or - plan to create the organization using SAML authentication. +1. These instructions assume you have an installed Zulip server; if + you're using Zulip Cloud, see [this article][saml-help-center], + which also has IdP-side configuration advice for common IdPs. + + You can have created a Zulip organization already using the default + EmailAuthBackend, or plan to create the organization using SAML + authentication. 1. Tell your IdP how to find your Zulip server: @@ -135,6 +139,8 @@ found at `https://yourzulipdomain.example.com/saml/metadata.xml`. You can use this for verifying your configuration or provide it to your IdP. +[saml-help-center]: https://zulip.com/help/saml-authentication + ### IdP-initiated SSO The above configuration is sufficient for Service Provider initialized diff --git a/static/images/help/onelogin_parameters.png b/static/images/help/onelogin_parameters.png new file mode 100644 index 0000000000..7395308cb2 Binary files /dev/null and b/static/images/help/onelogin_parameters.png differ diff --git a/templates/zerver/help/include/sidebar_index.md b/templates/zerver/help/include/sidebar_index.md index f5bea7cb74..3326fb74e1 100644 --- a/templates/zerver/help/include/sidebar_index.md +++ b/templates/zerver/help/include/sidebar_index.md @@ -137,6 +137,7 @@ * [Configure authentication methods](/help/configure-authentication-methods) * [Add a custom linkification filter](/help/add-a-custom-linkification-filter) * [Message retention policy](/help/message-retention-policy) +* [SAML authentication](/help/saml-authentication) ## Users & bots * [Invite new users](/help/invite-new-users) diff --git a/templates/zerver/help/saml-authentication.md b/templates/zerver/help/saml-authentication.md new file mode 100644 index 0000000000..e8b740ca8f --- /dev/null +++ b/templates/zerver/help/saml-authentication.md @@ -0,0 +1,62 @@ +# SAML Authentication + +Zulip supports using SAML authentication for Single Sign On, both when +self-hosting or on the Zulip Cloud Plus plan. + +This page documents details on how to setup SAML authentication with +Zulip with various common SAML Identity Providers. + +## Configure SAML with Okta + +1. Make sure you have created your organization. We'll assume its URL is + `https://.zulipchat.com` in the instructions below. +1. Set up SAML authentication by following + [Okta's documentation](https://developer.okta.com/docs/guides/saml-application-setup/overview/). + Specify: + * `https://.zulipchat.com/complete/saml/` for the "Single sign on URL"`. + * `https://zulipchat.com` for the "Audience URI (SP Entity ID)". + * Skip "Default RelayState". + * Skip "Name ID format". + * Set 'Email` for "Application username format". + * Provide "Attribute statements" of `email` to `user.email`, + `first_name` to `user.firstName`, and `last_name` to `user.lastName`. +1. Assign the appropriate accounts in the "Assignments" tab. These are the users + that will be able to log in to your Zulip organization. +1. Send the following information to us at support@zulipchat.com: + * The URL of your zulipchat-hosted organization. + * The "Identity Provider metadata" provided by Okta for the application. + * The name "X" that will be displayed on the "Log in with X" button in Zulip. + * Optionally you can also send us an icon that should be shown on the button. +1. We will take care of the server-side setup and let you know as soon as it's ready. + +## Configure SAML with Onelogin + +1. Make sure you have created your organization. We'll assume its URL is + `https://.zulipchat.com` in the instructions below. +1. Navigate to the Onelogin Applications page, and click "Add App". +1. Search for the "OneLogin SAML Test (IdP)" app and select it. +1. Set a name and logo according to your preferences and click "Save". This doesn't affect anything in Zulip, + but will be shown on your OneLogin Applications page. +1. Go to the "Configuration" section: + * Set `https://.zulipchat.com/complete/saml/` as the SAML Consumer URL, SAML Recipient + and ACS URL Validator. + * Set `https://zulipchat.com` as the SAML Audience. +1. Go to the "Parameters" section and configure it to match the following screenshot: + + ![](/static/images/help/onelogin_parameters.png) + + Make sure to set the "Include in SAML assertion" flag on these parameters. + +1. The OneLogin side of configuration should be ready! + Send the following information to us at support@zulipchat.com: + * The URL of your zulipchat-hosted organization. + * The issuer URL from the "SSO" section. It contains Identity Provider metadata that we will need. + * The name "X" that will be displayed on the "Log in with X" button in Zulip. + * Optionally you can also send us an icon that should be shown on the button. +1. We will take care of the server-side setup and let you know as soon as it's ready. + +## Related Articles + +* [SAML configuration][saml-readthedocs] for self-hosting. + +[saml-readthedocs]: https://zulip.readthedocs.io/en/stable/production/authentication-methods.html#saml