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/locale/admin-docs.pot b/locale/admin-docs.pot index 81ecf010..c2d7c955 100644 --- a/locale/admin-docs.pot +++ b/locale/admin-docs.pot @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Zammad Admin Documentation pre-release\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-10-10 11:53+0200\n" +"POT-Creation-Date: 2024-10-10 14:52+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -8467,7 +8467,7 @@ msgstr "" #: ../manage/slas/index.rst:51 #: ../manage/slas/index.rst:92 -#: ../settings/security/third-party.rst:81 +#: ../settings/security/third-party.rst:82 #: ../settings/system/frontend.rst:54 #: ../system/maintenance.rst:70 #: ../system/maintenance.rst:94 @@ -12846,35 +12846,35 @@ msgstr "" msgid "You can deactivate logging in via :ref:`security_password_login` if any of the mentioned authentication providers are enabled in your instance." msgstr "" -#: ../settings/security/third-party.rst:27 +#: ../settings/security/third-party.rst:28 msgid "We're currently missing documentation for the following login providers:" msgstr "" -#: ../settings/security/third-party.rst:29 +#: ../settings/security/third-party.rst:30 msgid "LinkedIn" msgstr "" -#: ../settings/security/third-party.rst:30 +#: ../settings/security/third-party.rst:31 msgid "Weibo" msgstr "" -#: ../settings/security/third-party.rst:35 +#: ../settings/security/third-party.rst:36 msgid "Automatic Account Link on Initial Logon" msgstr "" -#: ../settings/security/third-party.rst:37 +#: ../settings/security/third-party.rst:38 msgid "In general there's two possible options for Zammad on how to deal with already known users as they try to authenticate against a third-party application. By default, Zammad will not automatically link \"unknown\" authentication providers to existing accounts." msgstr "" -#: ../settings/security/third-party.rst:42 +#: ../settings/security/third-party.rst:43 msgid "This means that the user has to manually link authentication providers to their accounts (for more about this :user-docs:`consult the user documentation `)." msgstr "" -#: ../settings/security/third-party.rst:46 +#: ../settings/security/third-party.rst:47 msgid "Sometimes this doesn't come in handy as this also means you'll receive error messages about \"email address being in use already\" for (yet) unknown third-party authentication methods." msgstr "" -#: ../settings/security/third-party.rst:50 +#: ../settings/security/third-party.rst:51 msgid "If you want to allow your users to always be able to log in, no matter what, you may want to enable ``Automatic account link on initial logon``." msgstr "" @@ -12883,19 +12883,19 @@ msgid "Screenshot highlighting the \"Automatic account link on initial logon\"\n "setting" msgstr "" -#: ../settings/security/third-party.rst:60 +#: ../settings/security/third-party.rst:61 msgid "Automatic Account Linking Notification" msgstr "" -#: ../settings/security/third-party.rst:64 +#: ../settings/security/third-party.rst:65 msgid "To improve security and your users awareness, you can enable Zammad to notify your users when a new third-party application has been linked to their account." msgstr "" -#: ../settings/security/third-party.rst:68 +#: ../settings/security/third-party.rst:69 msgid "This notification is sent out once per third-party application. Zammad does also mention the method used, e.g.: ``Microsoft``." msgstr "" -#: ../settings/security/third-party.rst:71 +#: ../settings/security/third-party.rst:72 msgid "By default this setting is not active (set to ``no``)." msgstr "" @@ -12904,19 +12904,19 @@ msgid "Screenshot showing sample notification mail after initial\n" "third-party linking" msgstr "" -#: ../settings/security/third-party.rst:85 +#: ../settings/security/third-party.rst:86 msgid "This notification is only sent if the account in question already exists. If the login via the third-party also creates the missing account, the notification will be skipped." msgstr "" -#: ../settings/security/third-party.rst:89 +#: ../settings/security/third-party.rst:90 msgid "This means it only affects:" msgstr "" -#: ../settings/security/third-party.rst:91 +#: ../settings/security/third-party.rst:92 msgid "manual account linking within the third-party page of the users profile" msgstr "" -#: ../settings/security/third-party.rst:92 +#: ../settings/security/third-party.rst:93 msgid "logging into an existing local account by utilizing the *automatic account link on initial logon* functionality" msgstr "" @@ -12925,15 +12925,15 @@ msgid "Screenshot showing the \"automatic account linking notification\"\n" "setting" msgstr "" -#: ../settings/security/third-party.rst:100 +#: ../settings/security/third-party.rst:101 msgid "No User Creation on Logon" msgstr "" -#: ../settings/security/third-party.rst:102 +#: ../settings/security/third-party.rst:103 msgid "By default, Zammad will create a new user account if the user logs in via a third-party application and the account doesn't exist yet." msgstr "" -#: ../settings/security/third-party.rst:105 +#: ../settings/security/third-party.rst:106 msgid "If you want to prevent Zammad from creating new accounts on logon, you can disable this feature by setting ``No user creation on logon`` to ``yes``." msgstr "" @@ -13319,6 +13319,153 @@ msgid "Screencast showing how to add app credentials and activating the\n" "authentication method" msgstr "" +#: ../settings/security/third-party/openid-connect.rst:2 +msgid "OpenID Connect" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:4 +msgid "Connect your OpenID provider (OP) as a single sign-on (SSO) method." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:6 +msgid "OpenID is an easy and safe way for people to reuse an existing account and user profile from an OpenID provider." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:8 +msgid "The current implementation of OpenID Connect in Zammad is requiring OpenID Connect Discovery to simplify the configuration." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:10 +msgid "The relying party (RP) is Zammad, and the OpenID provider is a software service that you either host or subscribe to. (*e.g.,* `Keycloak `_)." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:12 +msgid "This guide assumes you are already using OpenID Connect within your organization (i.e., that your OP is fully set up)." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:14 +#: ../settings/security/third-party/saml.rst:21 +msgid "Please note: Our instructions are based on connecting Zammad with Keycloak." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:17 +msgid "Step 1: Configure Your OP" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:20 +msgid "Add a new Client" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:22 +msgid "Create a new client in your OP with the following settings:" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:26 +msgid "General settings" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:25 +msgid "Client type: OpenID Connect" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:26 +msgid "Client ID: ``zammad`` (or any other name you prefer)" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:30 +msgid "Capability config" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:29 +msgid "Client authentication: Off" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:30 +msgid "Authentication flow: Standard flow" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:35 +msgid "Login settings" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:33 +msgid "Valid redirect URIs: ``https://your.zammad.domain/auth/openid_connect/callback``" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:34 +msgid "Valid post logout redirect URIs: ``https://your.zammad.domain/*``" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:35 +msgid "Web origins: ``+``" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:37 +msgid "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**." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:40 +#: ../settings/security/third-party/saml.rst:105 +msgid "Step 2: Configure Zammad" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:42 +msgid "Enable OpenID Connect and enter your OP's details in the Admin Panel under **Settings > Security > Third Party Applications > Authentication via OpenID Connect**:" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:None +msgid "Example configuration of OpenID Connect" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:52 +#: ../settings/security/third-party/saml.rst:119 +msgid "Display name" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:50 +msgid "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." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:52 +msgid "Defaults to ``OpenID Connect``." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:55 +msgid "Identifier" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:55 +msgid "The client ID you defined in your OP." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:58 +msgid "Issuer" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:58 +msgid "The issuer URL of your OP. Used for discovery." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:61 +msgid "UID field" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:61 +msgid "Here you can define an attribute that uniquely identifies the user. If unset, ``sub`` is used." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:64 +msgid "Scopes" +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:64 +msgid "The scopes that Zammad should request from the OP. Defaults to ``openid``, ``email`` and ``profile``." +msgstr "" + +#: ../settings/security/third-party/openid-connect.rst:66 +msgid "See :ref:`automatic account linking ` for details on how to link existing Zammad accounts to OP accounts." +msgstr "" + #: ../settings/security/third-party/saml.rst:2 msgid "SAML" msgstr "" @@ -13339,10 +13486,6 @@ msgstr "" msgid "This guide assumes you are already using SAML within your organization (i.e., that your IdP is fully set up)." msgstr "" -#: ../settings/security/third-party/saml.rst:21 -msgid "Please note: Our instructions are based on connecting Zammad with Keycloak." -msgstr "" - #: ../settings/security/third-party/saml.rst:25 msgid "Step 1: Configure Your IdP" msgstr "" @@ -13459,10 +13602,6 @@ msgstr "" msgid "You also need to enable **Sign assertions**." msgstr "" -#: ../settings/security/third-party/saml.rst:105 -msgid "Step 2: Configure Zammad" -msgstr "" - #: ../settings/security/third-party/saml.rst:107 msgid "Enable SAML and enter your IdP's details in the Admin Panel under **Settings > Security > Third Party Applications > Authentication via SAML**:" msgstr "" @@ -13471,10 +13610,6 @@ msgstr "" msgid "Example configuration of SAML part 1" msgstr "" -#: ../settings/security/third-party/saml.rst:119 -msgid "Display name" -msgstr "" - #: ../settings/security/third-party/saml.rst:116 msgid "Allows you to define a custom button name for SAML. This helps your users to understand better what the button on the login page does." msgstr "" 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..99d3dd61 --- /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.