diff --git a/images/settings/security/third-party/openid-connect/zammad_connect_oidc_thirdparty_general.png b/images/settings/security/third-party/openid-connect/zammad_connect_oidc_thirdparty_general.png new file mode 100644 index 00000000..dc4ffb5e Binary files /dev/null and b/images/settings/security/third-party/openid-connect/zammad_connect_oidc_thirdparty_general.png differ diff --git a/settings/security/third-party.rst b/settings/security/third-party.rst index 4068bf45..e50d2193 100644 --- a/settings/security/third-party.rst +++ b/settings/security/third-party.rst @@ -19,8 +19,9 @@ of the mentioned authentication providers are enabled in your instance. third-party/gitlab third-party/google third-party/microsoft - third-party/twitter + third-party/openid-connect third-party/saml + third-party/twitter .. note:: @@ -107,4 +108,3 @@ disable this feature by setting ``No user creation on logon`` to ``yes``. .. figure:: /images/settings/security/login_no_user_creation.png :alt: Screenshot showing the "no user creation on logon" setting - diff --git a/settings/security/third-party/openid-connect.rst b/settings/security/third-party/openid-connect.rst new file mode 100644 index 00000000..21025255 --- /dev/null +++ b/settings/security/third-party/openid-connect.rst @@ -0,0 +1,66 @@ +OpenID Connect +============== + +Connect your OpenID provider (OP) as a single sign-on (SSO) method. + +OpenID is an easy and safe way for people to reuse an existing account and user profile from an OpenID provider. + +.. warning:: The current implementation of OpenID Connect in Zammad is requiring OpenID Connect Discovery to simplify the configuration. + +The relying party (RP) is Zammad, and the OpenID provider is a software service that you either host or subscribe to. (*e.g.,* `Keycloak `_). + +This guide assumes you are already using OpenID Connect within your organization (i.e., that your OP is fully set up). + +.. warning:: Please note: Our instructions are based on connecting Zammad with Keycloak. + +Step 1: Configure Your OP +-------------------------- + +Add a new Client +^^^^^^^^^^^^^^^^ + +Create a new client in your OP with the following settings: + +General settings +* Client type: OpenID Connect +* Client ID: ``zammad`` (or any other name you prefer) + +Capability config +* Client authentication: Off +* Authentication flow: Standard flow + +Login settings +* Valid redirect URIs: ``https://your.zammad.domain/auth/openid_connect/callback`` +* Valid post logout redirect URIs: ``https://your.zammad.domain/*`` +* Web origins: ``+`` + +In the **Logout settings** for the newly created client, set the **Backchannel logout URL** to ``https://your.zammad.domain/auth/openid_connect/backchannel_logout`` and switch on **Backchannel logout session required**. + +Step 2: Configure Zammad +------------------------ + +Enable OpenID Connect and enter your OP's details in the Admin Panel under **Settings > Security > Third Party Applications > Authentication via OpenID Connect**: + +.. image:: /images/settings/security/third-party/openid-connect/zammad_connect_oidc_thirdparty_general.png + :alt: Example configuration of OpenID Connect + :scale: 60% + :align: center + +Display name + Allows you to define a custom button name for OpenID Connect. This helps your users to understand better what the button on the login page does. + + Defaults to ``OpenID Connect``. + +Identifier + The client ID you defined in your OP. + +Issuer + The issuer URL of your OP. Used for discovery. + +UID field + Here you can define an attribute that uniquely identifies the user. If unset, ``sub`` is used. + +Scopes + The scopes that Zammad should request from the OP. Defaults to ``openid``, ``email`` and ``profile``. + +See :ref:`automatic account linking ` for details on how to link existing Zammad accounts to OP accounts.