sa6anw/hedgedoc-hedgeagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fix Keycloak Integration Documentation (#6107)

Browse Source
This commit is contained in:
Lars Kiesow
2025-08-14 14:44:44 +02:00
committed by GitHub
parent 8c4b60a13c
commit eba0fc51f0
1 changed files with 26 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
docs/content/guides/auth/keycloak.md
View File

@@ -2,22 +2,22 @@
## Prerequisites ## Prerequisites
This guide assumes you have run and configured Keycloak. If you'd like to meet this prerequisite quickly, it can be achieved by running a `jboss/keycloak` container and attaching it to your network. Set the environment variables KEYCLOAK_USER and `KEYCLOAK_PASSWORD`, and expose port 8080. This guide assumes you have run and configured Keycloak.
If you'd like to meet this prerequisite quickly, it can be achieved by running a `quay.io/keycloak/keycloak` container and attaching it to your network.
For details and quick-start command, take a look at [the Keycloak Docker documentation](https://www.keycloak.org/getting-started/getting-started-docker).
Where HTTPS is specified throughout, use HTTP instead. You may also have to specify the exposed port, 8080. Where HTTPS is specified throughout, use HTTP instead. You may also have to specify the exposed port, 8080.
## Steps ## Steps
1. Sign in to the administration portal for your Keycloak instance at <https://keycloak.example.com/auth/admin/master/console> 1. Sign in to the administration portal for your Keycloak instance at <https://keycloak.example.com/admin/master/console>.
You may note that a separate realm is specified throughout this tutorial. It is best practice not to use the master realm, as it normally contains the realm-management client that federates access using the policies and permissions you can create. > You may note that a separate realm is specified throughout this tutorial. It is best practice not to use the `master` realm, as it normally contains the realm-management client that federates access using the policies and permissions you can create.
2. Navigate to the client management page at `https://keycloak.example.com/auth/admin/master/console/#/realms/your-realm/clients` (admin permissions required) 2. Navigate to the client management page at <https://keycloak.example.com/admin/master/console/#/your-realm/clients> (admin permissions required)
3. Click **Create** to create a new client and fill out the registration form. You should set the Root URL to the fully qualified public URL of your HedgeDoc instance. 3. Click **Create** to create a new client and fill out the registration form. You should set the “Root URL” to the fully qualified public URL of your HedgeDoc instance.
4. Click **Save** 4. Click **Save**
5. Set the **Access Type** of the client to `confidential`. This will make your client require a client secret upon authentication. 5. Set the **Access Type** of the client to `confidential`. This will make your client require a client secret upon authentication.
---
### Additional steps to circumvent generic OAuth2 issue ### Additional steps to circumvent generic OAuth2 issue
@@ -26,25 +26,27 @@ You may note that a separate realm is specified throughout this tutorial. It is
3. Create a new mapper under the Mappers tab. This should reference the User Property `id`. `Claim JSON Type` should be String and all switches below should be enabled. Save the mapper. 3. Create a new mapper under the Mappers tab. This should reference the User Property `id`. `Claim JSON Type` should be String and all switches below should be enabled. Save the mapper.
4. Go to the client you set up in the previous steps using the Clients page, then choose the Client Scopes tab. Apply the scope you've created. This should mitigate errors as seen in [hedgedoc/hedgedoc#56](https://github.com/hedgedoc/hedgedoc/issues/56), as the `/userinfo` endpoint should now bring back the user's ID under the `id` key as well as `sub`. 4. Go to the client you set up in the previous steps using the Clients page, then choose the Client Scopes tab. Apply the scope you've created. This should mitigate errors as seen in [hedgedoc/hedgedoc#56](https://github.com/hedgedoc/hedgedoc/issues/56), as the `/userinfo` endpoint should now bring back the user's ID under the `id` key as well as `sub`.
--- ## Container Configuration
5. In the `docker-compose.yml` add the following environment variables to `app:` `environment:` In the `docker-compose.yml` add the following environment variables to `app.environment:`
```yaml ```yaml
CMD_OAUTH2_USER_PROFILE_URL=https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/userinfo app:
CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=preferred_username environment:
CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=name - CMD_OAUTH2_USER_PROFILE_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/userinfo
CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=email - CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=preferred_username
CMD_OAUTH2_TOKEN_URL=https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/token - CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=name
CMD_OAUTH2_AUTHORIZATION_URL=https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/auth - CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=email
CMD_OAUTH2_CLIENT_ID=<your client ID> - CMD_OAUTH2_TOKEN_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/token
CMD_OAUTH2_CLIENT_SECRET=<your client secret, which you can find under the Credentials tab for your client> - CMD_OAUTH2_AUTHORIZATION_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/auth
CMD_OAUTH2_PROVIDERNAME=Keycloak - CMD_OAUTH2_CLIENT_ID=<your client ID>
CMD_OAUTH2_SCOPE=openid email profile - CMD_OAUTH2_CLIENT_SECRET=<your client secret, which you can find under the Credentials tab for your client>
CMD_DOMAIN=<hedgedoc.example.com> - CMD_OAUTH2_PROVIDERNAME=Keycloak
CMD_PROTOCOL_USESSL=true - CMD_OAUTH2_SCOPE=openid email profile
CMD_URL_ADDPORT=false - CMD_DOMAIN=<hedgedoc.example.com>
- CMD_PROTOCOL_USESSL=true
- CMD_URL_ADDPORT=false
``` ```
6. Run `docker-compose up -d` to apply your settings. After running `docker-compose up -d` to apply your settings,
7. Sign in to your HedgeDoc using your Keycloak ID you should now be able to sign in to your HedgeDoc using your Keycloak.