Differences

This shows you the differences between two versions of the page.

--- blocks:sso:keycloak [2019-03-12 14:49]
max
+++ blocks:sso:keycloak [2024-08-02 14:39] (current)
melvin Minor changes for Keycloak 25.0.2
@@ Line 1: / Line 1: @@
-====KeyCloak====
+====== Keycloak ======
-  - Install, configure and run KeyCloak: https://www.keycloak.org/docs/latest/server_installation/index.html
+Here's a [[https://vimeo.com/356912392|video]] showing how SSO based on Keycloak can be used.
-  - Login to the admin pages of KeyCloak.
-    * {{:blocks:sso:keycloak.png|}}
+  - Install, configure and run Keycloak: [[https://www.keycloak.org/getting-started/getting-started-zip|https://www.keycloak.org/getting-started/getting-started-zip]]
-  - Click the "Clients" button in the sidebar menu and add a new client by clicking the "Create" button in the top right corner.
+  - Login to the admin pages of Keycloak.
-  - Give it a name and select "openid-connect" as the Client Protocol.
-  - On the settings page of your new client, add "[BLOCKS-IP]/rest/auth/*" as a "Valid Redirect URI" and set "Access Type" to "confidential", save your changes.
+{{ :blocks:sso:keycloak.png?direct&600 |}}
-  - Select the "Credentials" tab at the top of your client settings page and note the "Secret" for use as [CLIENT-SECRET] in step 9.
-  - Click the "Roles" button in the sidebar menu. Click the "Add Role" button and add the role "Admin". Repeat the process until you end up with the following roles listed:
+  - Click the "Clients" button in the sidebar menu and add a new client by clicking the "Create client" button.
+  - Give it an ID and select "OpenID Connect" as the Client Type.
+  - On the next screen, turn on Client authentication, click Next and then click Save.
+  - On the settings page of your new client, add "http://[BLOCKS-IP-OR-DOMAIN]/rest/auth/*" as a "Valid Redirect URI". Save your changes.
+  - Select the "Credentials" tab at the top of your client settings page and note the "Client secret" for use as [CLIENT-SECRET] in step 1 of the Blocks specific section below.
+  - Click the "Realm roles" button in the sidebar menu. Click the "Create role" button and add the role "Admin". Repeat the process until you end up with the following roles listed:
     * Admin
     * Manager
@@ Line 15: / Line 20: @@
     * Contributor
     * Staff
-  - Click the "Users" button in the sidebar menu. Click the "Add user" button in the top right corner and add your first user. On the edit page for the newly created user, select the "Role Mappings" tab at the top and assign the roles you want this user to have.
+  - Click the "Users" button in the sidebar menu. Click the "Add user" button and add your first user. On the edit page for the newly created user, select the "Role mapping" tab at the top and assign the roles you want this user to have. You may need to change the filter from "Filter by clients" to "Filter by realm roles" to see the roles.
-  - Open your server configuration file and add the "auth" section below to the already existing "server" section. Replace the values of [BLOCKS-IP], [KEYCLOAK-IP], [REALM-NAME], [CLIENT-ID] and [CLIENT-SECRET]. If you didn't configure your own realm for your users, [REALM-NAME] is the default "Master" realm. [CLIENT-ID] is the name of the client from step 4.
+  - Select the "Credentials" tab at the top to create a password for the user.
-<code>
-    server:
+===== Blocks specific steps =====
-      auth:
-        urlResolver: null
+  - Open your Blocks configuration file on your Blocks server and add the "auth" section below to the already existing "server" section. Replace the values of [BLOCKS-IP], [KEYCLOAK-IP], [REALM-NAME], [CLIENT-ID] and [CLIENT-SECRET]. If you didn't configure your own realm for your users, [REALM-NAME] is the default "master" realm. [CLIENT-ID] is the name of the client from step 4 in the section above.
-        ajaxRequestResolver: null
+    * <code>
-        callbackUrl: https://[BLOCKS-IP]/rest/auth/callback
+server:
-        rolesOwner: claims
+  type: pixilab_server
-        rolesPath: realm_access.roles
+  auth:
-        clients:
+    urlResolver: null
-          - org.pac4j.oidc.client.OidcClient:
+    ajaxRequestResolver: null
-              configuration:
+    callbackUrl: http://[BLOCKS-IP-OR-DOMAIN]/rest/auth/callback
-                discoveryURI: [KEYCLOAK-IP]/auth/realms/[REALM-NAME]/.well-known/openid-configuration
+    rolesOwner: claims
-                clientId: [CLIENT-ID]
+    rolesPath: realm_access.roles
-                secret: [CLIENT-SECRET]
+    clients:
-                clientAuthenticationMethod: client_secret_basic
+      - org.pac4j.oidc.client.OidcClient:
-                scope: openid profile groups
+          configuration:
-        servlet:
+            discoveryURI: https://[KEYCLOAK-IP]/realms/[REALM-NAME]/.well-known/openid-configuration
-        security:
+            clientId: [CLIENT-ID]
-          - matchers: internalMatcher
+            secret: [CLIENT-SECRET]
+            clientAuthenticationMethod: client_secret_basic
+            scope: openid profile
+    servlet:
+      security:
+        - matchers: internalMatcher
           clients: OidcClient
           authorizers: isAuthenticated
+</code>
+  - Start Blocks and go to "/edit" for login.
+===== Role Mapping =====
+If the roles you've added to Keycloak does not match the roles used by blocks, or if you have set up roles on Keycloak already and would like to re-use them, you can add role mapping to the Blocks configuration file. You do this by defining a server.auth.rolesMapping parameter where the keys are the roles of your Keycloak configuration and the values the roles Blocks know about. For example:
+<code>
+rolesMapping:
+  KeycloakAdmin: Admin
+  KeycloakManager: Manager
+  KeycloakCreator: Creator
+  KeycloakEditor: Editor
+  KeycloakContributor: Contributor
+  KeycloakStaff: Staff
 </code>
-Start Blocks and go to "/edit" for login.