From 573997870b7f295da4018cf77c1b278d21c1a706 Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 19:37:39 -0400 Subject: [PATCH 01/13] Fix some typos, improvements the Keycloak settings for the server and the client --- README.rst | 155 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 92 insertions(+), 63 deletions(-) diff --git a/README.rst b/README.rst index 19c3ef4..bd1a23f 100644 --- a/README.rst +++ b/README.rst @@ -30,8 +30,8 @@ pas.plugins.oidc ================ -This is an Plone authentication plugin for OpenID Connect. -OAuth 2.0 should work as well, because OpenID Connect is built on top of this protocol. +This is a Plone authentication plugin for OpenID Connect. +OAuth 2.0 should work as well because OpenID Connect is built on top of this protocol. Features -------- @@ -43,7 +43,7 @@ Features Installation ------------ -Install ``pas.plugins.oidc`` by adding it to your buildout:: +Install ``pas.plugins.oidc`` by adding it to your buildout: :: [buildout] @@ -58,7 +58,7 @@ and then running ``bin/buildout`` Warning ------- -Pay attention to the customization of `User info property used as userid` field, with the wrong configuration it's easy impersonate another user. +Pay attention to the customization of `User info property used as userid` field, with the wrong configuration it's easy to impersonate another user. Install and configure the plugin @@ -67,32 +67,36 @@ Install and configure the plugin * Go to the Add-ons control panel and install ``pas.plugins.oidc``. * In the ZMI go to the plugin properties at http://localhost:8080/Plone/acl_users/oidc/manage_propertiesForm * Configure the properties with the data obtained from your provider: - * OIDC/Oauth2 Issuer - * Client ID - * Client secret - * redirect_uris: this needs to match the **public URL** where the user will be redirected after the login flow is completed. It needs to include the `/Plone/acl_users/oidc/callback` part. When using Volto you need to expose Plone somehow to have the login process finish correctly. + * ``OIDC/Oauth2 Issuer`` + * ``Client ID`` + * ``Client secret`` + * ``redirect_uris``: this needs to match the **public URL** where the user will be redirected after the login flow is completed. It needs to include + the `/Plone/acl_users/oidc/callback` part. When using Volto you need to expose Plone somehow to have the login process finish correctly. * Use Zope session data manager: see the section below about the usage of session. - * Create user / update user properties: when selected the user data in Plone will be updated with the data coming from the OIDC provider.ç + * Create user / update user properties: when selected the user data in Plone will be updated with the data coming from the OIDC provider. * Create authentication __ac ticket: when selected the user will be allowed to act as a logged-in user in Plone. - * Create authentication auth_token (volto/restapi) ticket: when selected the user will be allowed to act as a logged-in user in the Volto frontend. + * Create authentication auth_token (Volto/REST API) ticket: when selected the user will be allowed to act as a logged-in user in the Volto frontend. * Open ID scopes to request to the server: information requested to the OIDC provider. Leave it as it is or modify it according to your provider's information. * Use PKCE: when enabled uses PKCE_ when requesting authentication from the provider. Login and Logout URLs --------------------- -When using this plugin the standard Plone URLs used for login (`http://localhost:8080/Plone/login`) and logout (`http://localhost:8080/Plone/logout`) will not trigger the usage of the plugin. +When using this plugin, the standard Plone URLs used for login (`http://localhost:8080/Plone/login`) and logout (`http://localhost:8080/Plone/logout`) +will not trigger the usage of the plugin. -When using this plugin with a Volto frontend the standard URLs for login (`http://localhost:3000/login`) and logout (`http://localhost:3000/logout`) will not trigger the usage of the plugin. +When using this plugin with a Volto frontend the standard URLs for login (`http://localhost:3000/login`) and logout (`http://localhost:3000/logout`) +will not trigger the usage of the plugin. To login into a site using the OIDC provider, you will need to change those login URLs to the following: -* Login: //acl_users//login -* Logout: //acl_users//logout +* Login: /````/acl_users/````/login +* Logout: /````/acl_users/````/logout -Where: - - Plone Site Id: is the id you gave to the Plone site when you created it. It is usually `Plone` but may vary. It is the last part of the URL when you browse Plone directly without using any proxy server, ex. `http://localhost:8080/Plone+ -> `Plone` - - oidc pas plugin id: is the id you gave to the OIDC plugin when you created it inside the Plone PAS administration panel. If you just used the default configuration and installed this plugin using Plone's Add-on Control Panel, this id will be `oidc` + *Where:* + + * ``Plone Site Id``: is the id you gave to the Plone site when you created it. It is usually `Plone` but may vary. It is the last part of the URL when you browse Plone directly without using any proxy server, ex. `http://localhost:8080/Plone+` -> `Plone`. + * ``oidc pas plugin id``: is the id you gave to the OIDC plugin when you created it inside the Plone PAS administration panel. If you just used the default configuration and installed this plugin using Plone's Add-on Control Panel, this id will be `oidc`. When using Volto as a frontend, you need to expose those login and logout URLs somehow to make the login and logout process work. @@ -106,52 +110,75 @@ Please refer to the `Keycloak documentation `_. This does **not** give you a production setup, but it is fine for local development. -Keycloak runs on port 8080 by default. -Plone uses the same port. -When you are reading this, you probably know how to let Plone use a different port. -So let's indeed let Keycloak use its preferred port. -At the moment of writing, this is how you start a Keycloak container:: +**Note:** Keycloak runs on port ``8080`` by default. Plone uses the same port. When you are reading this, you probably know how to let Plone use a different port. +So let's indeed let Keycloak use its preferred port. At the moment of writing, this is how you start a Keycloak container: :: docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:19.0.3 start-dev -The plugin can be used with legacy(deprecated) keycloak redirect_uri parameter. To use this you need to enable the option in the plugin configuration. To test that you can run the keycloak server with the option--spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true:: +The plugin can be used with legacy (deprecated) Keycloak ``redirect_uri`` parameter. To use this you need to enable the option +in the plugin configuration. To test that you can run the Keycloak server with the `--spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true` +option: :: docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:19.0.3 start-dev --spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true -Note: when you exit this container, it still exists and you can restart it so you don't lose your configuration. +**Note:** when you exit this container, it still exists and you can restart it so you don't lose your configuration. With ``docker ps -a`` figure out the name of the container and then use ``docker container start -ai ``. Follow the Keycloak Docker documentation further: -* Create a realm. Give this the name ``plone``. -* Create a user. Remember to set a password for this user in the Credentials tab. -* Open a different browser and check that you can login to Keycloak with this user. +* Open the `Keycloak Admin Console `_, make sure you are logged in as ``admin``. + +* Click the word ``master`` in the top-left corner, then click ``Create Realm``. + +* Enter `plone` in the ``Realm name`` field. + +* Click ``Create``. + +* Click the word ``master`` in the top-left corner, then click ``plone``. + +* Click ``Manage`` -> ``Users`` in the left-hand menu. + +* Click ``Create new user``. + +* Remember to set a password for this user in the ``Credentials`` tab. + +* Open a different browser and check that you can login to `Keycloak Account Console `_ with this user. In the original browser, follow the steps for securing your first app. But we will be using different settings for Plone. And when last I checked, the actual UI differed from the documentation. So: -* Make sure you are logged in as admin in Keycloak, and are in the Plone realm. -* Go to Clients. -* Click 'Create client': +* Open the `Keycloak Admin Console `_, make sure you are logged in as ``admin``. + +* Click the word ``master`` in the top-left corner, then click ``plone``. + +* Click ``Manage`` -> ``Clients`` in the left-hand menu. + +* Click ``Create client``: + + * ``Client type``: *OpenID Connect* + + * ``Client ID``: *plone* + + * Turn ``Always display in console`` to ``On`` Useful for testing. + + * Click ``Next`` and click ``Save``. + +* Now you can fill in the ``Settings`` -> ``Access settings``. We will assume Plone runs on port 8081: + + * ``Root URL``: `http://localhost:8081/Plone/` - * client type: OpenID Connect - * client ID: plone - * Turn 'always display in console' on. Useful for testing. - * Click Next and Save. + * ``Home URL``: `http://localhost:8081/Plone/` -* Now you can fill in the Access settings. We will assume Plone runs on port 8081: + * ``Valid redirect URIs``: `http://localhost:8081/Plone*` - * Root URL: http://localhost:8081/Plone/ - * Home URL: http://localhost:8081/Plone/ - * Valid redirect URIs: http://localhost:8081/Plone* - * Leave the rest at the defaults, unless you know what you are doing, and click Save. + * Leave the rest at the defaults, unless you know what you are doing, and click ``Save``. Keycloak is ready. -Setup Plone as client -~~~~~~~~~~~~~~~~~~~~~ +Setup Plone as a client +~~~~~~~~~~~~~~~~~~~~~~~ * In your Zope instance configuration, make sure Plone runs on port 8081. * Make sure ``pas.plugins.oidc`` is installed with pip or Buildout. @@ -161,24 +188,27 @@ Setup Plone as client * Set these properties: * OIDC/Oauth2 Issuer: http://localhost:8080/realms/plone/ - * client ID: plone. This must match the client ID you have set in Keycloak. - * Use deprecated redirect_uri. Use this if you need to run old versions of keycloak. + * Client ID: plone. This must match the client ID you have set in Keycloak. + * Use deprecated ``redirect_uri``. Use this if you need to run old versions of Keycloak. * Leave the rest at the default and save the changes. [TODO] screenshot. -Attention, before keycloak 18, the parameter for logout was redirect_uri and it is deprecated since version 18. But the keycloak server can run with the redirect_uri if needed, it is possible to use the plugin with the legacy parameter enabled also. The problem is that if the deprecated parameter is enabled in the plugin but not in the server, the plugin will not work. +Attention, before Keycloak 18, the parameter for logout was ``redirect_uri`` and it has been deprecated since version 18. But the +Keycloak server can run with the ``redirect_uri`` if needed, it is possible to use the plugin with the legacy parameter enabled also. +The problem is that if the deprecated parameter is enabled in the plugin but not in the server, the plugin will not work. -So this is the way it works: +So, this is the way it works: -* With legacy enabled in keycloak, the plugin works in default mode. -* With legacy enabled in keycloak, the plugin also works with legacy mode. -* With legacy disabled in keycloak(default after version 18), the plugin works in default mode. -* With legacy disabled in keycloak(default after version 18), the plugin do NOT works with legacy mode. +* With legacy enabled in Keycloak, the plugin works in default mode. +* With legacy enabled in Keycloak, the plugin also works with legacy mode. +* With legacy disabled in Keycloak (default after version 18), the plugin works in default mode. +* With legacy disabled in Keycloak (default after version 18), the plugin does NOT work with legacy mode. -So, for keycloak, it do not matter if we use the default or legacy mode if the keycloak runs in legacy mode. +So, for Keycloak, it does not matter if we use the default or legacy mode if the Keycloak runs in legacy mode. -If legacy is disabled in keycloak, this is the default since version 18 of keycloak according to this comment in starckoverflow: https://stackoverflow.com/a/72142887, the plugin will work only if the option use legacy mode is off(un-checked). +If legacy is disabled in Keycloak, this is the default since version 18 of Keycloak according to this comment in *Starck Overflow*: https://stackoverflow.com/a/72142887, +the plugin will work only if the option use legacy mode is off (un-checked). Login ~~~~~ @@ -187,12 +217,12 @@ Go to the other browser, or logout as admin from Keycloak. Currently, the Plone login form is unchanged. Instead, go to the login page of the plugin: http://localhost:8081/Plone/acl_users/oidc/login This will take you to Keycloak to login, and then return. -You should now be logged in to Plone, and see the fullname and email, if you have set this in Keycloak. +You should now be logged in to Plone, and see the *full name* and *email*, if you have set this in Keycloak. Logout ~~~~~~ -If the login did worked as expected you can try to logout. +If the login did work as expected you can try to logout. Go to the logout page of the plugin: http://localhost:8081/Plone/acl_users/oidc/logout This will take you to Keycloak to logout, and then return to the post logout redirect url. @@ -206,31 +236,30 @@ and comes back from there. The plugin has 2 ways of working with sessions: - Use the Zope Session Management: if the "Use Zope session data manager" option in the plugin configuration is enabled, - the plugin will use the sessioning configuration configured in Zope. To do so we advise to use `Products.mcdutils`_ + the plugin will use the sessioning configuration configured in Zope. To do so we advise using `Products.mcdutils`_ to save the session data in a memcached based storage. Otherwise Zope will try to use ZODB based sessioning which has shown several problems in the past. -- Use the cookie based session management: if the "Use Zope session data manager" option in the plugin +- Use the cookie-based session management: if the "Use Zope session data manager" option in the plugin configuration is disabled, the plugin will use a Cookie to save that information in the client's browser. Settings in environment variables --------------------------------- -Instead of editing your OIDC provider settings through the ZMI, you can use `collective.regenv`_ and provide -a YAML file with your settings. This is very useful if you have different settings in different environments -and and you do not want to edit the settings each time -you move the contents. +Optionally, instead of editing your OIDC provider settings through the ZMI, you can use `collective.regenv`_ and provide +a ``YAML`` file with your settings. This is very useful if you have different settings in different environments +and you do not want to edit the settings each time you move the contents. Varnish ------- -If you are using the Varnish caching server in front of Plone, you may see this plugin only partially working. -Especially the ``came_from`` parameter may be ignored. +Optionally, if you are using the `Varnish caching server `_ in front +of Plone, you may see this plugin only partially working. Especially the ``came_from`` parameter may be ignored. This is because the standard configuration from ``plone.recipe.varnish`` removes most cookies to improve anonymous caching. -Solution is to make sure the ``__ac_session`` cookie is added to the ``cookie-pass`` option. -Check what the current default is in the recipe, and update it:: +The solution is to make sure the ``__ac_session`` cookie is added to the ``cookie-pass`` option. +Check what the current default is in the recipe, and update it: :: [varnish-configuration] recipe = plone.recipe.varnish:configuration From ff35c01d5a0e545dc14ef2e6523b650ce1a9b1c2 Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 19:46:58 -0400 Subject: [PATCH 02/13] Updated the Login and Logout URLs section --- README.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index bd1a23f..51778e6 100644 --- a/README.rst +++ b/README.rst @@ -82,20 +82,22 @@ Install and configure the plugin Login and Logout URLs --------------------- -When using this plugin, the standard Plone URLs used for login (`http://localhost:8080/Plone/login`) and logout (`http://localhost:8080/Plone/logout`) +When using this plugin with *Plone 6 Classic UI* the standard URLs used for login (`http://localhost:8080/Plone/login`) and logout (`http://localhost:8080/Plone/logout`) will not trigger the usage of the plugin. -When using this plugin with a Volto frontend the standard URLs for login (`http://localhost:3000/login`) and logout (`http://localhost:3000/logout`) -will not trigger the usage of the plugin. +When using this plugin with a `Volto frontend `_ the standard URLs for login (`http://localhost:3000/login`) +and logout (`http://localhost:3000/logout`) will not trigger the usage of the plugin. To login into a site using the OIDC provider, you will need to change those login URLs to the following: -* Login: /````/acl_users/````/login -* Logout: /````/acl_users/````/logout +* **Login URL**: /````/acl_users/````/login + +* **Logout URL**: /````/acl_users/````/logout *Where:* * ``Plone Site Id``: is the id you gave to the Plone site when you created it. It is usually `Plone` but may vary. It is the last part of the URL when you browse Plone directly without using any proxy server, ex. `http://localhost:8080/Plone+` -> `Plone`. + * ``oidc pas plugin id``: is the id you gave to the OIDC plugin when you created it inside the Plone PAS administration panel. If you just used the default configuration and installed this plugin using Plone's Add-on Control Panel, this id will be `oidc`. When using Volto as a frontend, you need to expose those login and logout URLs somehow to make the login and logout process work. From 209ad4d33b2af159c9fa4ec3b53105ebc854db57 Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 19:52:26 -0400 Subject: [PATCH 03/13] Added more format for the sections in the documentation --- README.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/README.rst b/README.rst index 51778e6..1ed5d5d 100644 --- a/README.rst +++ b/README.rst @@ -65,20 +65,34 @@ Install and configure the plugin -------------------------------- * Go to the Add-ons control panel and install ``pas.plugins.oidc``. + * In the ZMI go to the plugin properties at http://localhost:8080/Plone/acl_users/oidc/manage_propertiesForm + * Configure the properties with the data obtained from your provider: + * ``OIDC/Oauth2 Issuer`` + * ``Client ID`` + * ``Client secret`` + * ``redirect_uris``: this needs to match the **public URL** where the user will be redirected after the login flow is completed. It needs to include the `/Plone/acl_users/oidc/callback` part. When using Volto you need to expose Plone somehow to have the login process finish correctly. + * Use Zope session data manager: see the section below about the usage of session. + * Create user / update user properties: when selected the user data in Plone will be updated with the data coming from the OIDC provider. + * Create authentication __ac ticket: when selected the user will be allowed to act as a logged-in user in Plone. + * Create authentication auth_token (Volto/REST API) ticket: when selected the user will be allowed to act as a logged-in user in the Volto frontend. + * Open ID scopes to request to the server: information requested to the OIDC provider. Leave it as it is or modify it according to your provider's information. + * Use PKCE: when enabled uses PKCE_ when requesting authentication from the provider. +---- + Login and Logout URLs --------------------- @@ -102,6 +116,8 @@ To login into a site using the OIDC provider, you will need to change those logi When using Volto as a frontend, you need to expose those login and logout URLs somehow to make the login and logout process work. +---- + Example setup with Keycloak --------------------------- @@ -179,19 +195,29 @@ So: Keycloak is ready. +---- + Setup Plone as a client ~~~~~~~~~~~~~~~~~~~~~~~ * In your Zope instance configuration, make sure Plone runs on port 8081. + * Make sure ``pas.plugins.oidc`` is installed with pip or Buildout. + * Start Plone and create a Plone site with id Plone. + * In the Add-ons control panel, install ``pas.plugins.oidc``. + * In the ZMI go to the plugin properties at http://localhost:8081/Plone/acl_users/oidc/manage_propertiesForm + * Set these properties: * OIDC/Oauth2 Issuer: http://localhost:8080/realms/plone/ + * Client ID: plone. This must match the client ID you have set in Keycloak. + * Use deprecated ``redirect_uri``. Use this if you need to run old versions of Keycloak. + * Leave the rest at the default and save the changes. [TODO] screenshot. @@ -203,8 +229,11 @@ The problem is that if the deprecated parameter is enabled in the plugin but not So, this is the way it works: * With legacy enabled in Keycloak, the plugin works in default mode. + * With legacy enabled in Keycloak, the plugin also works with legacy mode. + * With legacy disabled in Keycloak (default after version 18), the plugin works in default mode. + * With legacy disabled in Keycloak (default after version 18), the plugin does NOT work with legacy mode. So, for Keycloak, it does not matter if we use the default or legacy mode if the Keycloak runs in legacy mode. @@ -212,6 +241,8 @@ So, for Keycloak, it does not matter if we use the default or legacy mode if the If legacy is disabled in Keycloak, this is the default since version 18 of Keycloak according to this comment in *Starck Overflow*: https://stackoverflow.com/a/72142887, the plugin will work only if the option use legacy mode is off (un-checked). +---- + Login ~~~~~ @@ -229,6 +260,8 @@ If the login did work as expected you can try to logout. Go to the logout page of the plugin: http://localhost:8081/Plone/acl_users/oidc/logout This will take you to Keycloak to logout, and then return to the post logout redirect url. +---- + Usage of sessions in the login process -------------------------------------- @@ -245,6 +278,7 @@ The plugin has 2 ways of working with sessions: - Use the cookie-based session management: if the "Use Zope session data manager" option in the plugin configuration is disabled, the plugin will use a Cookie to save that information in the client's browser. +---- Settings in environment variables --------------------------------- @@ -253,6 +287,7 @@ Optionally, instead of editing your OIDC provider settings through the ZMI, you a ``YAML`` file with your settings. This is very useful if you have different settings in different environments and you do not want to edit the settings each time you move the contents. +---- Varnish ------- @@ -268,6 +303,7 @@ Check what the current default is in the recipe, and update it: :: ... cookie-pass = "auth_token|__ac(|_(name|password|persistent|session))=":"\.(js|css|kss)$" +---- Contribute ---------- From 975ad4f0761e1064d9e9e06eec0297e4696633a4 Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 19:59:46 -0400 Subject: [PATCH 04/13] Updated the Sphinx format to the README file --- README.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README.rst b/README.rst index 1ed5d5d..ce88c97 100644 --- a/README.rst +++ b/README.rst @@ -70,26 +70,26 @@ Install and configure the plugin * Configure the properties with the data obtained from your provider: - * ``OIDC/Oauth2 Issuer`` + * ``OIDC/Oauth2 Issuer`` - * ``Client ID`` + * ``Client ID`` - * ``Client secret`` + * ``Client secret`` - * ``redirect_uris``: this needs to match the **public URL** where the user will be redirected after the login flow is completed. It needs to include + * ``redirect_uris``: this needs to match the **public URL** where the user will be redirected after the login flow is completed. It needs to include the `/Plone/acl_users/oidc/callback` part. When using Volto you need to expose Plone somehow to have the login process finish correctly. - * Use Zope session data manager: see the section below about the usage of session. + * Use Zope session data manager: see the section below about the usage of session. - * Create user / update user properties: when selected the user data in Plone will be updated with the data coming from the OIDC provider. + * Create user / update user properties: when selected the user data in Plone will be updated with the data coming from the OIDC provider. - * Create authentication __ac ticket: when selected the user will be allowed to act as a logged-in user in Plone. + * Create authentication __ac ticket: when selected the user will be allowed to act as a logged-in user in Plone. - * Create authentication auth_token (Volto/REST API) ticket: when selected the user will be allowed to act as a logged-in user in the Volto frontend. + * Create authentication auth_token (Volto/REST API) ticket: when selected the user will be allowed to act as a logged-in user in the Volto frontend. - * Open ID scopes to request to the server: information requested to the OIDC provider. Leave it as it is or modify it according to your provider's information. + * Open ID scopes to request to the server: information requested to the OIDC provider. Leave it as it is or modify it according to your provider's information. - * Use PKCE: when enabled uses PKCE_ when requesting authentication from the provider. + * Use PKCE: when enabled uses PKCE_ when requesting authentication from the provider. ---- @@ -179,11 +179,11 @@ So: * ``Client ID``: *plone* - * Turn ``Always display in console`` to ``On`` Useful for testing. + * Turn ``Always display in console`` to ``On``, *Useful for testing*. * Click ``Next`` and click ``Save``. -* Now you can fill in the ``Settings`` -> ``Access settings``. We will assume Plone runs on port 8081: +* Now you can fill in the ``Settings`` -> ``Access settings``. We will assume Plone runs on port ``8081``: * ``Root URL``: `http://localhost:8081/Plone/` @@ -214,7 +214,7 @@ Setup Plone as a client * OIDC/Oauth2 Issuer: http://localhost:8080/realms/plone/ - * Client ID: plone. This must match the client ID you have set in Keycloak. + * Client ID: plone. **Note:** This must match the ``Client ID`` you have set in Keycloak. * Use deprecated ``redirect_uri``. Use this if you need to run old versions of Keycloak. From 813d1ef67bf61ea4dcfc0c7207d7837df2b326f3 Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 20:20:00 -0400 Subject: [PATCH 05/13] Updated the README file --- README.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index ce88c97..ed8bb68 100644 --- a/README.rst +++ b/README.rst @@ -79,17 +79,17 @@ Install and configure the plugin * ``redirect_uris``: this needs to match the **public URL** where the user will be redirected after the login flow is completed. It needs to include the `/Plone/acl_users/oidc/callback` part. When using Volto you need to expose Plone somehow to have the login process finish correctly. - * Use Zope session data manager: see the section below about the usage of session. + * ``Use Zope session data manager``: see the section below about the usage of session. - * Create user / update user properties: when selected the user data in Plone will be updated with the data coming from the OIDC provider. + * ``Create user / update user properties``: when selected the user data in Plone will be updated with the data coming from the OIDC provider. - * Create authentication __ac ticket: when selected the user will be allowed to act as a logged-in user in Plone. + * ``Create authentication __ac ticket``: when selected the user will be allowed to act as a logged-in user in Plone. - * Create authentication auth_token (Volto/REST API) ticket: when selected the user will be allowed to act as a logged-in user in the Volto frontend. + * ``Create authentication auth_token (Volto/REST API) ticket``: when selected the user will be allowed to act as a logged-in user in the Volto frontend. - * Open ID scopes to request to the server: information requested to the OIDC provider. Leave it as it is or modify it according to your provider's information. + * ``Open ID scopes to request to the server``: information requested to the OIDC provider. Leave it as it is or modify it according to your provider's information. - * Use PKCE: when enabled uses PKCE_ when requesting authentication from the provider. + * ``Use PKCE``: when enabled uses PKCE_ when requesting authentication from the provider. ---- @@ -270,12 +270,12 @@ and comes back from there. The plugin has 2 ways of working with sessions: -- Use the Zope Session Management: if the "Use Zope session data manager" option in the plugin configuration is enabled, +- Use the Zope Session Management: if the ``Use Zope session data manager`` option in the plugin configuration is enabled, the plugin will use the sessioning configuration configured in Zope. To do so we advise using `Products.mcdutils`_ to save the session data in a memcached based storage. Otherwise Zope will try to use ZODB based sessioning which has shown several problems in the past. -- Use the cookie-based session management: if the "Use Zope session data manager" option in the plugin +- Use the cookie-based session management: if the ``Use Zope session data manager`` option in the plugin configuration is disabled, the plugin will use a Cookie to save that information in the client's browser. ---- From 08e03cb61d295893e6828e730dece428604fdfc5 Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 20:21:31 -0400 Subject: [PATCH 06/13] Updated README file --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index ed8bb68..df2a571 100644 --- a/README.rst +++ b/README.rst @@ -77,7 +77,7 @@ Install and configure the plugin * ``Client secret`` * ``redirect_uris``: this needs to match the **public URL** where the user will be redirected after the login flow is completed. It needs to include - the `/Plone/acl_users/oidc/callback` part. When using Volto you need to expose Plone somehow to have the login process finish correctly. + the `/Plone/acl_users/oidc/callback` part. When using Volto you need to expose Plone somehow to have the login process finish correctly. * ``Use Zope session data manager``: see the section below about the usage of session. From c00be215bea6d0d9b3db5a08c1798d04bbf77718 Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 20:47:34 -0400 Subject: [PATCH 07/13] Added more improvements about the legacy redirect_uri parameter --- README.rst | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/README.rst b/README.rst index df2a571..485b46e 100644 --- a/README.rst +++ b/README.rst @@ -223,42 +223,45 @@ Setup Plone as a client [TODO] screenshot. Attention, before Keycloak 18, the parameter for logout was ``redirect_uri`` and it has been deprecated since version 18. But the -Keycloak server can run with the ``redirect_uri`` if needed, it is possible to use the plugin with the legacy parameter enabled also. +Keycloak server can run with the ``redirect_uri`` if needed, it is possible to use the plugin with the legacy ``redirect_uri`` parameter enabled also. The problem is that if the deprecated parameter is enabled in the plugin but not in the server, the plugin will not work. So, this is the way it works: -* With legacy enabled in Keycloak, the plugin works in default mode. +* With legacy ``redirect_uri`` parameter enabled in Keycloak, the plugin works in default mode. -* With legacy enabled in Keycloak, the plugin also works with legacy mode. +* With legacy ``redirect_uri`` parameter enabled in Keycloak, the plugin also works with legacy mode. -* With legacy disabled in Keycloak (default after version 18), the plugin works in default mode. +* With legacy ``redirect_uri`` parameter disabled in Keycloak (default after version 18), the plugin works in default mode. -* With legacy disabled in Keycloak (default after version 18), the plugin does NOT work with legacy mode. +* With legacy ``redirect_uri`` parameter disabled in Keycloak (default after version 18), the plugin does NOT work with legacy mode. So, for Keycloak, it does not matter if we use the default or legacy mode if the Keycloak runs in legacy mode. -If legacy is disabled in Keycloak, this is the default since version 18 of Keycloak according to this comment in *Starck Overflow*: https://stackoverflow.com/a/72142887, -the plugin will work only if the option use legacy mode is off (un-checked). +If legacy ``redirect_uri`` parameter is disabled in Keycloak, this is the default since version 18 of Keycloak according to this comment in +*Starck Overflow*: https://stackoverflow.com/a/72142887, the plugin will work only if the ``Use deprecated redirect_uri for logout url(/Plone/acl_users/oidc/logout)`` +option is un-checked at the plugin properties at http://localhost:8081/Plone/acl_users/oidc/manage_propertiesForm. ---- Login ~~~~~ -Go to the other browser, or logout as admin from Keycloak. +Go to the other browser, or logout as admin from `Keycloak Admin Console `_. Currently, the Plone login form is unchanged. -Instead, go to the login page of the plugin: http://localhost:8081/Plone/acl_users/oidc/login -This will take you to Keycloak to login, and then return. -You should now be logged in to Plone, and see the *full name* and *email*, if you have set this in Keycloak. + +Instead, for testing go to the login page of the plugin: http://localhost:8081/Plone/acl_users/oidc/login, +this will take you to Keycloak to login, and then return. You should now be logged in to Plone, and see the +*full name* and *email*, if you have set this in Keycloak. Logout ~~~~~~ -If the login did work as expected you can try to logout. +If the login did work as expected you can try to Plone logout. +Currently, the Plone logout form is unchanged. -Go to the logout page of the plugin: http://localhost:8081/Plone/acl_users/oidc/logout -This will take you to Keycloak to logout, and then return to the post logout redirect url. +Instead, for testing go to the logout page of the plugin: http://localhost:8081/Plone/acl_users/oidc/logout, +this will take you to Keycloak to logout, and then return to the post-logout redirect URL. ---- From 9cfb5046a2a7c7e0bfa40e904aa077de53ed15f6 Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 20:55:42 -0400 Subject: [PATCH 08/13] Updated the README file --- README.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 485b46e..5ef29f2 100644 --- a/README.rst +++ b/README.rst @@ -238,9 +238,12 @@ So, this is the way it works: So, for Keycloak, it does not matter if we use the default or legacy mode if the Keycloak runs in legacy mode. -If legacy ``redirect_uri`` parameter is disabled in Keycloak, this is the default since version 18 of Keycloak according to this comment in -*Starck Overflow*: https://stackoverflow.com/a/72142887, the plugin will work only if the ``Use deprecated redirect_uri for logout url(/Plone/acl_users/oidc/logout)`` -option is un-checked at the plugin properties at http://localhost:8081/Plone/acl_users/oidc/manage_propertiesForm. +*Notes:* + * If legacy ``redirect_uri`` parameter is disabled in Keycloak, this is the default since version 18 of Keycloak according + to this comment in *Starck Overflow*: https://stackoverflow.com/a/72142887. + + * The plugin will work only if the ``Use deprecated redirect_uri for logout url(/Plone/acl_users/oidc/logout)`` + option is un-checked at the plugin properties at http://localhost:8081/Plone/acl_users/oidc/manage_propertiesForm. ---- From e38532a6e32af2c05c610a14ce9a15ae4599f7de Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 21:18:57 -0400 Subject: [PATCH 09/13] Added the Client secret section for the documentation --- README.rst | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 5ef29f2..c3f46ed 100644 --- a/README.rst +++ b/README.rst @@ -191,7 +191,17 @@ So: * ``Valid redirect URIs``: `http://localhost:8081/Plone*` - * Leave the rest at the defaults, unless you know what you are doing, and click ``Save``. + **Tip:** Leave the rest at the defaults, unless you know what you are doing. + +* Now you can fill in the ``Settings`` -> ``Capability config``. + + * Turn ``Client authentication`` to ``On``. This defines the type of the OIDC client. When it's ON, the + OIDC type is set to confidential access type. When it's OFF, it is set to public access type. + + * Click ``Save``. + +* Now you can access ``Credentials`` -> ``Client secret`` and click on the clipboard icon to copy it. This will + be necessary to configure the plugin in Plone. Keycloak is ready. @@ -212,13 +222,21 @@ Setup Plone as a client * Set these properties: - * OIDC/Oauth2 Issuer: http://localhost:8080/realms/plone/ + * ``OIDC/Oauth2 Issuer``: http://localhost:8080/realms/plone/ + + * ``Client ID``: *plone* + + **Warning:** This must match the ``Client ID`` you have set in Keycloak. + + * ``Client secret``: *••••••••••••••••••••••••••••••••* - * Client ID: plone. **Note:** This must match the ``Client ID`` you have set in Keycloak. + **Warning:** This must match the ``Client secret`` you have get in Keycloak. - * Use deprecated ``redirect_uri``. Use this if you need to run old versions of Keycloak. + * ``Use deprecated redirect_uri for logout url(/Plone/acl_users/oidc/logout)``. Use this if you need to run old versions of Keycloak. - * Leave the rest at the default and save the changes. + **Tip:** Leave the rest at the defaults, unless you know what you are doing. + + * Click ``Save``. [TODO] screenshot. @@ -239,6 +257,7 @@ So, this is the way it works: So, for Keycloak, it does not matter if we use the default or legacy mode if the Keycloak runs in legacy mode. *Notes:* + * If legacy ``redirect_uri`` parameter is disabled in Keycloak, this is the default since version 18 of Keycloak according to this comment in *Starck Overflow*: https://stackoverflow.com/a/72142887. From d2c36e2f530386cf40c2e8c488876f89f3767711 Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 21:21:44 -0400 Subject: [PATCH 10/13] Updated the README file --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index c3f46ed..1baef99 100644 --- a/README.rst +++ b/README.rst @@ -258,11 +258,11 @@ So, for Keycloak, it does not matter if we use the default or legacy mode if the *Notes:* - * If legacy ``redirect_uri`` parameter is disabled in Keycloak, this is the default since version 18 of Keycloak according - to this comment in *Starck Overflow*: https://stackoverflow.com/a/72142887. +* If legacy ``redirect_uri`` parameter is disabled in Keycloak, this is the default since version 18 of Keycloak according + to this comment in *Starck Overflow*: https://stackoverflow.com/a/72142887. - * The plugin will work only if the ``Use deprecated redirect_uri for logout url(/Plone/acl_users/oidc/logout)`` - option is un-checked at the plugin properties at http://localhost:8081/Plone/acl_users/oidc/manage_propertiesForm. +* The plugin will work only if the ``Use deprecated redirect_uri for logout url(/Plone/acl_users/oidc/logout)`` + option is un-checked at the plugin properties at http://localhost:8081/Plone/acl_users/oidc/manage_propertiesForm. ---- From b017ee3f4696d38b8c3621ac9e226771041341ba Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Mon, 30 Oct 2023 22:11:54 -0400 Subject: [PATCH 11/13] Updated the README file --- README.rst | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 1baef99..12f2999 100644 --- a/README.rst +++ b/README.rst @@ -134,7 +134,7 @@ So let's indeed let Keycloak use its preferred port. At the moment of writing, t docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:19.0.3 start-dev The plugin can be used with legacy (deprecated) Keycloak ``redirect_uri`` parameter. To use this you need to enable the option -in the plugin configuration. To test that you can run the Keycloak server with the `--spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true` +in the plugin configuration. To test that you can run the Keycloak server with the ``--spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true`` option: :: docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:19.0.3 start-dev --spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true @@ -148,7 +148,7 @@ Follow the Keycloak Docker documentation further: * Click the word ``master`` in the top-left corner, then click ``Create Realm``. -* Enter `plone` in the ``Realm name`` field. +* Enter *plone* in the ``Realm name`` field. * Click ``Create``. @@ -203,7 +203,7 @@ So: * Now you can access ``Credentials`` -> ``Client secret`` and click on the clipboard icon to copy it. This will be necessary to configure the plugin in Plone. -Keycloak is ready. +**Keycloak is ready done configured!** ---- @@ -212,7 +212,7 @@ Setup Plone as a client * In your Zope instance configuration, make sure Plone runs on port 8081. -* Make sure ``pas.plugins.oidc`` is installed with pip or Buildout. +* Make sure ``pas.plugins.oidc`` is installed with `pip `_ or `Buildout `_. * Start Plone and create a Plone site with id Plone. @@ -238,11 +238,14 @@ Setup Plone as a client * Click ``Save``. +**Plone is ready done configured!** + [TODO] screenshot. Attention, before Keycloak 18, the parameter for logout was ``redirect_uri`` and it has been deprecated since version 18. But the -Keycloak server can run with the ``redirect_uri`` if needed, it is possible to use the plugin with the legacy ``redirect_uri`` parameter enabled also. -The problem is that if the deprecated parameter is enabled in the plugin but not in the server, the plugin will not work. +Keycloak server can run with the ``redirect_uri`` if needed, it is possible to use the plugin with the legacy ``redirect_uri`` +parameter enabled also. The problem is that if the deprecated parameter is enabled in the plugin but not in the server, the plugin +will not work. So, this is the way it works: @@ -319,9 +322,11 @@ Varnish Optionally, if you are using the `Varnish caching server `_ in front of Plone, you may see this plugin only partially working. Especially the ``came_from`` parameter may be ignored. -This is because the standard configuration from ``plone.recipe.varnish`` removes most cookies to improve anonymous caching. +This is because the buildout standard configuration from `plone.recipe.varnish `_ +removes most cookies to improve anonymous caching. + The solution is to make sure the ``__ac_session`` cookie is added to the ``cookie-pass`` option. -Check what the current default is in the recipe, and update it: :: +Check what the current default is in the buildout recipe, and update it: :: [varnish-configuration] recipe = plone.recipe.varnish:configuration From 92836a0d536a1abbc5af4b2c6d11b62113e6bfaf Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Tue, 31 Oct 2023 03:34:24 -0400 Subject: [PATCH 12/13] Updated the Setup Plone as a client section --- README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 12f2999..0851bdf 100644 --- a/README.rst +++ b/README.rst @@ -226,13 +226,13 @@ Setup Plone as a client * ``Client ID``: *plone* - **Warning:** This must match the ``Client ID`` you have set in Keycloak. + **Warning:** This property must match the ``Client ID`` you have set in Keycloak. * ``Client secret``: *••••••••••••••••••••••••••••••••* - **Warning:** This must match the ``Client secret`` you have get in Keycloak. + **Warning:** This property must match the ``Client secret`` you have get in Keycloak. - * ``Use deprecated redirect_uri for logout url(/Plone/acl_users/oidc/logout)``. Use this if you need to run old versions of Keycloak. + * ``Use deprecated redirect_uri for logout url(/Plone/acl_users/oidc/logout)`` checked. Use this if you need to run old versions of Keycloak. **Tip:** Leave the rest at the defaults, unless you know what you are doing. From 7efd0eae74874b05f7838daea4076e34c85bf8ca Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Tue, 31 Oct 2023 03:41:42 -0400 Subject: [PATCH 13/13] Updated the README docs --- README.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.rst b/README.rst index 0851bdf..4954ec7 100644 --- a/README.rst +++ b/README.rst @@ -242,6 +242,8 @@ Setup Plone as a client [TODO] screenshot. +*Warning:* + Attention, before Keycloak 18, the parameter for logout was ``redirect_uri`` and it has been deprecated since version 18. But the Keycloak server can run with the ``redirect_uri`` if needed, it is possible to use the plugin with the legacy ``redirect_uri`` parameter enabled also. The problem is that if the deprecated parameter is enabled in the plugin but not in the server, the plugin