Skip to content

Commit de3471f

Browse files
wollefitzwollefitz
committed
docs(web-modeler): backport changes to previous versions
1 parent fff9ef7 commit de3471f

File tree

16 files changed

+251
-19
lines changed

16 files changed

+251
-19
lines changed

‎docs/self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md

+9-13
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,16 @@
11
---
22
id: troubleshoot-login
3-
title: "Troubleshooting log in issues"
4-
sidebar_label: "Log in issues"
3+
title: "Troubleshooting login issues"
4+
sidebar_label: "Login issues"
55
---
66

77
:::note
8-
Web Modeler Self-Managed is available to [Enterprise customers](../../../../reference/licenses.md#web-modeler) only.
8+
Web Modeler Self-Managed is available to [enterprise customers](../../../../reference/licenses.md#web-modeler) only.
99
:::
1010

11-
## Problem
12-
1311
Logging in to Web Modeler doesn't work as expected and shows an error or a blank page when accessing the application.
1412

15-
## Solution
16-
17-
To resolve this issue, check the [log output](docs/self-managed/modeler/web-modeler/configuration/logging.md) of the `modeler-restapi` and `modeler-webapp` services for errors and warnings.
13+
To further debug this issue, check the [log output](docs/self-managed/modeler/web-modeler/configuration/logging.md) of the `modeler-restapi` and `modeler-webapp` services for errors and warnings.
1814

1915
## Unique constraint violation
2016

@@ -41,22 +37,22 @@ As a workaround, you can manually update the user ID in the Web Modeler database
4137
WHERE realm_id = 'camunda-platform' AND email IS NOT NULL;
4238
```
4339
2. Create a new table in the **Web Modeler database**:
44-
3. ```sql
40+
```sql
4541
CREATE TABLE keycloak_users (
4642
id varchar(255),
4743
email varchar(255)
4844
);
4945
```
50-
4. Import the CSV file from **Step 1** into the new `keycloak_users` table.
51-
5. Update the user IDs by running the following query in the **Web Modeler database**:
46+
3. Import the CSV file from **Step 1** into the new `keycloak_users` table.
47+
4. Update the user IDs by running the following query in the **Web Modeler database**:
5248
```sql
5349
UPDATE users u
5450
SET iam_id = k.id
5551
FROM keycloak_users k
5652
WHERE k.email = u.email;
5753
```
58-
6. Verify that the login is working again.
59-
7. Delete the `keycloak_users` table:
54+
5. Verify that the login is working again.
55+
6. Delete the `keycloak_users` table:
6056
```sql
6157
DROP TABLE keycloak_users;
6258
```

‎docs/self-managed/operational-guides/backup-restore/modeler-backup-and-restore.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ After the database has been restored, you can start Web Modeler again.
3737

3838
:::warning
3939
When restoring Web Modeler data from a backup, ensure that the ids of the users stored in your OIDC provider (e.g. Keycloak) do not change in between the backup and restore.
40-
Otherwise, users may not be able to log in after the restore (see [Web Modeler's log in troubleshooting guide](docs/self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md#unique-constraint-violation)).
40+
Otherwise, users may not be able to log in after the restore (see [Web Modeler's login troubleshooting guide](docs/self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md#unique-constraint-violation)).
4141
:::
4242

4343
:::tip

‎docs/self-managed/operational-guides/update-guide/keycloak/keycloak-update.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,5 @@ When updating Keycloak, follow the [Keycloak upgrade guide](https://www.keycloak
99
:::danger
1010
When updating Keycloak, ensure that you carry along its existing database.
1111
**Do not** update by creating a new Keycloak instance and re-importing your users from external sources (e.g. LDAP) as this will result in new Keycloak-internal ids.
12-
Otherwise, users may not be able to access their data (e.g. Optimize collections) or log in to Web Modeler (see [Web Modeler's log in troubleshooting guide](docs/self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md#unique-constraint-violation)) after the update as their Keycloak-internal ids may change.
12+
Otherwise, users may not be able to access their data (e.g. Optimize collections) or log in to Web Modeler (see [Web Modeler's login troubleshooting guide](self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md#unique-constraint-violation)) after the update.
1313
:::

‎optimize_sidebars.js

+10
Original file line numberDiff line numberDiff line change
@@ -1946,6 +1946,12 @@ module.exports = {
19461946
"self-managed/operational-guides/update-guide/elasticsearch/7-to-8/"
19471947
),
19481948
],
1949+
Keycloak: [
1950+
docsLink(
1951+
"Update Keycloak",
1952+
"self-managed/operational-guides/update-guide/keycloak/keycloak-update"
1953+
),
1954+
],
19491955
},
19501956
],
19511957
},
@@ -2460,6 +2466,10 @@ module.exports = {
24602466
"Zeebe connection",
24612467
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-zeebe-connection/"
24622468
),
2469+
docsLink(
2470+
"Login issues",
2471+
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login/"
2472+
),
24632473
],
24642474
},
24652475
],

‎versioned_docs/version-8.2/guides/update-guide/keycloak/keycloak-update.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
id: keycloak-update
3+
title: Update Keycloak
4+
description: "Review what has to be taken into account when updating Keycloak."
5+
---
6+
7+
When updating Keycloak, follow the [Keycloak upgrade guide](https://www.keycloak.org/docs/latest/upgrading/index.html) and refer to the [supported environments](reference/supported-environments.md#camunda-8-self-managed) to ensure compatibility with tested Keycloak versions.
8+
9+
:::danger
10+
When updating Keycloak, ensure that you carry along its existing database.
11+
**Do not** update by creating a new Keycloak instance and re-importing your users from external sources (e.g. LDAP) as this will result in new Keycloak-internal ids.
12+
Otherwise, users may not be able to access their data (e.g. Optimize collections) or log in to Web Modeler (see [Web Modeler's login troubleshooting guide](self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md#unique-constraint-violation)) after the update.
13+
:::

‎versioned_docs/version-8.2/self-managed/backup-restore/modeler-backup-and-restore.md

+1
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ After the database has been restored, you can start Web Modeler again.
3737

3838
:::warning
3939
When restoring Web Modeler data from a backup, ensure that the ids of the users stored in your OIDC provider (e.g. Keycloak) do not change in between the backup and restore.
40+
Otherwise, users may not be able to log in after the restore (see [Web Modeler's login troubleshooting guide](docs/self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md#unique-constraint-violation)).
4041
:::
4142

4243
:::tip

‎versioned_docs/version-8.2/self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
id: troubleshoot-login
3+
title: "Troubleshooting login issues"
4+
sidebar_label: "Login issues"
5+
---
6+
7+
:::note
8+
Web Modeler Self-Managed is available to [enterprise customers](../../../../reference/licenses.md#web-modeler) only.
9+
:::
10+
11+
Logging in to Web Modeler doesn't work as expected and shows an error or a blank page when accessing the application.
12+
13+
To further debug this issue, check the [log output](docs/self-managed/modeler/web-modeler/configuration/logging.md) of the `modeler-restapi` and `modeler-webapp` services for errors and warnings.
14+
15+
## Unique constraint violation
16+
17+
When you try to log in to Web Modeler using Keycloak as an OIDC provider, you see an error message in the `modeler-restapi` logs similar to this:
18+
19+
```
20+
org.postgresql.util.PSQLException: ERROR: duplicate key value violates unique constraint "users_email_key"
21+
Detail: Key (email)=(***************) already exists.
22+
```
23+
24+
### Ensure the Keycloak-managed user id didn't change
25+
26+
Web Modeler uses the value of the `sub` (subject) claim in the JSON Web Token (JWT) issued by the configured OIDC provider (by default Keycloak) to identify users and correlate them with their data created in Web Modeler.
27+
It is important that this value doesn't change over time, for example when the user is deleted and re-created in Keycloak or re-imported from an external user directory, or when reinstalling/updating/switching Keycloak instances.
28+
29+
If the `sub` claim value changes for an existing user, Web Modeler will try to create a new user record in its database for the user, which will lead to the error above when the user tries to log in.
30+
31+
As a workaround, you can manually update the user ID in the Web Modeler database:
32+
33+
1. Export the users from the **Keycloak database** to a CSV file. The following query can be used to select the relevant data:
34+
```sql
35+
SELECT id, email
36+
FROM user_entity
37+
WHERE realm_id = 'camunda-platform' AND email IS NOT NULL;
38+
```
39+
2. Create a new table in the **Web Modeler database**:
40+
```sql
41+
CREATE TABLE keycloak_users (
42+
id varchar(255),
43+
email varchar(255)
44+
);
45+
```
46+
3. Import the CSV file from **Step 1** into the new `keycloak_users` table.
47+
4. Update the user IDs by running the following query in the **Web Modeler database**:
48+
```sql
49+
UPDATE users u
50+
SET iam_id = k.id
51+
FROM keycloak_users k
52+
WHERE k.email = u.email;
53+
```
54+
5. Verify that the login is working again.
55+
6. Delete the `keycloak_users` table:
56+
```sql
57+
DROP TABLE keycloak_users;
58+
```

‎versioned_docs/version-8.3/self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
id: troubleshoot-login
3+
title: "Troubleshooting login issues"
4+
sidebar_label: "Login issues"
5+
---
6+
7+
:::note
8+
Web Modeler Self-Managed is available to [enterprise customers](../../../../reference/licenses.md#web-modeler) only.
9+
:::
10+
11+
Logging in to Web Modeler doesn't work as expected and shows an error or a blank page when accessing the application.
12+
13+
To further debug this issue, check the [log output](docs/self-managed/modeler/web-modeler/configuration/logging.md) of the `modeler-restapi` and `modeler-webapp` services for errors and warnings.
14+
15+
## Unique constraint violation
16+
17+
When you try to log in to Web Modeler using Keycloak as an OIDC provider, you see an error message in the `modeler-restapi` logs similar to this:
18+
19+
```
20+
org.postgresql.util.PSQLException: ERROR: duplicate key value violates unique constraint "users_email_key"
21+
Detail: Key (email)=(***************) already exists.
22+
```
23+
24+
### Ensure the Keycloak-managed user id didn't change
25+
26+
Web Modeler uses the value of the `sub` (subject) claim in the JSON Web Token (JWT) issued by the configured OIDC provider (by default Keycloak) to identify users and correlate them with their data created in Web Modeler.
27+
It is important that this value doesn't change over time, for example when the user is deleted and re-created in Keycloak or re-imported from an external user directory, or when reinstalling/updating/switching Keycloak instances.
28+
29+
If the `sub` claim value changes for an existing user, Web Modeler will try to create a new user record in its database for the user, which will lead to the error above when the user tries to log in.
30+
31+
As a workaround, you can manually update the user ID in the Web Modeler database:
32+
33+
1. Export the users from the **Keycloak database** to a CSV file. The following query can be used to select the relevant data:
34+
```sql
35+
SELECT id, email
36+
FROM user_entity
37+
WHERE realm_id = 'camunda-platform' AND email IS NOT NULL;
38+
```
39+
2. Create a new table in the **Web Modeler database**:
40+
```sql
41+
CREATE TABLE keycloak_users (
42+
id varchar(255),
43+
email varchar(255)
44+
);
45+
```
46+
3. Import the CSV file from **Step 1** into the new `keycloak_users` table.
47+
4. Update the user IDs by running the following query in the **Web Modeler database**:
48+
```sql
49+
UPDATE users u
50+
SET iam_id = k.id
51+
FROM keycloak_users k
52+
WHERE k.email = u.email;
53+
```
54+
5. Verify that the login is working again.
55+
6. Delete the `keycloak_users` table:
56+
```sql
57+
DROP TABLE keycloak_users;
58+
```

‎versioned_docs/version-8.3/self-managed/operational-guides/backup-restore/modeler-backup-and-restore.md

+1
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ After the database has been restored, you can start Web Modeler again.
3737

3838
:::warning
3939
When restoring Web Modeler data from a backup, ensure that the ids of the users stored in your OIDC provider (e.g. Keycloak) do not change in between the backup and restore.
40+
Otherwise, users may not be able to log in after the restore (see [Web Modeler's login troubleshooting guide](docs/self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md#unique-constraint-violation)).
4041
:::
4142

4243
:::tip

‎versioned_docs/version-8.3/self-managed/operational-guides/update-guide/keycloak/keycloak-update.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
id: keycloak-update
3+
title: Update Keycloak
4+
description: "Review what has to be taken into account when updating Keycloak."
5+
---
6+
7+
When updating Keycloak, follow the [Keycloak upgrade guide](https://www.keycloak.org/docs/latest/upgrading/index.html) and refer to the [supported environments](reference/supported-environments.md#camunda-8-self-managed) to ensure compatibility with tested Keycloak versions.
8+
9+
:::danger
10+
When updating Keycloak, ensure that you carry along its existing database.
11+
**Do not** update by creating a new Keycloak instance and re-importing your users from external sources (e.g. LDAP) as this will result in new Keycloak-internal ids.
12+
Otherwise, users may not be able to access their data (e.g. Optimize collections) or log in to Web Modeler (see [Web Modeler's login troubleshooting guide](self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md#unique-constraint-violation)) after the update.
13+
:::

‎versioned_docs/version-8.4/self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
id: troubleshoot-login
3+
title: "Troubleshooting login issues"
4+
sidebar_label: "Login issues"
5+
---
6+
7+
:::note
8+
Web Modeler Self-Managed is available to [enterprise customers](../../../../reference/licenses.md#web-modeler) only.
9+
:::
10+
11+
Logging in to Web Modeler doesn't work as expected and shows an error or a blank page when accessing the application.
12+
13+
To further debug this issue, check the [log output](docs/self-managed/modeler/web-modeler/configuration/logging.md) of the `modeler-restapi` and `modeler-webapp` services for errors and warnings.
14+
15+
## Unique constraint violation
16+
17+
When you try to log in to Web Modeler using Keycloak as an OIDC provider, you see an error message in the `modeler-restapi` logs similar to this:
18+
19+
```
20+
org.postgresql.util.PSQLException: ERROR: duplicate key value violates unique constraint "users_email_key"
21+
Detail: Key (email)=(***************) already exists.
22+
```
23+
24+
### Ensure the Keycloak-managed user id didn't change
25+
26+
Web Modeler uses the value of the `sub` (subject) claim in the JSON Web Token (JWT) issued by the configured OIDC provider (by default Keycloak) to identify users and correlate them with their data created in Web Modeler.
27+
It is important that this value doesn't change over time, for example when the user is deleted and re-created in Keycloak or re-imported from an external user directory, or when reinstalling/updating/switching Keycloak instances.
28+
29+
If the `sub` claim value changes for an existing user, Web Modeler will try to create a new user record in its database for the user, which will lead to the error above when the user tries to log in.
30+
31+
As a workaround, you can manually update the user ID in the Web Modeler database:
32+
33+
1. Export the users from the **Keycloak database** to a CSV file. The following query can be used to select the relevant data:
34+
```sql
35+
SELECT id, email
36+
FROM user_entity
37+
WHERE realm_id = 'camunda-platform' AND email IS NOT NULL;
38+
```
39+
2. Create a new table in the **Web Modeler database**:
40+
```sql
41+
CREATE TABLE keycloak_users (
42+
id varchar(255),
43+
email varchar(255)
44+
);
45+
```
46+
3. Import the CSV file from **Step 1** into the new `keycloak_users` table.
47+
4. Update the user IDs by running the following query in the **Web Modeler database**:
48+
```sql
49+
UPDATE users u
50+
SET iam_id = k.id
51+
FROM keycloak_users k
52+
WHERE k.email = u.email;
53+
```
54+
5. Verify that the login is working again.
55+
6. Delete the `keycloak_users` table:
56+
```sql
57+
DROP TABLE keycloak_users;
58+
```

‎versioned_docs/version-8.4/self-managed/operational-guides/backup-restore/modeler-backup-and-restore.md

+1
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ After the database has been restored, you can start Web Modeler again.
3737

3838
:::warning
3939
When restoring Web Modeler data from a backup, ensure that the ids of the users stored in your OIDC provider (e.g. Keycloak) do not change in between the backup and restore.
40+
Otherwise, users may not be able to log in after the restore (see [Web Modeler's login troubleshooting guide](docs/self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md#unique-constraint-violation)).
4041
:::
4142

4243
:::tip

‎versioned_docs/version-8.4/self-managed/operational-guides/update-guide/keycloak/keycloak-update.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
id: keycloak-update
3+
title: Update Keycloak
4+
description: "Review what has to be taken into account when updating Keycloak."
5+
---
6+
7+
When updating Keycloak, follow the [Keycloak upgrade guide](https://www.keycloak.org/docs/latest/upgrading/index.html) and refer to the [supported environments](reference/supported-environments.md#camunda-8-self-managed) to ensure compatibility with tested Keycloak versions.
8+
9+
:::danger
10+
When updating Keycloak, ensure that you carry along its existing database.
11+
**Do not** update by creating a new Keycloak instance and re-importing your users from external sources (e.g. LDAP) as this will result in new Keycloak-internal ids.
12+
Otherwise, users may not be able to access their data (e.g. Optimize collections) or log in to Web Modeler (see [Web Modeler's login troubleshooting guide](self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login.md#unique-constraint-violation)) after the update.
13+
:::

‎versioned_sidebars/version-8.2-sidebars.json

+4-2
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,8 @@
5656
]
5757
},
5858
{
59-
"Elasticsearch": ["guides/update-guide/elasticsearch/7-to-8"]
59+
"Elasticsearch": ["guides/update-guide/elasticsearch/7-to-8"],
60+
"Keycloak": ["guides/update-guide/keycloak/keycloak-update"]
6061
}
6162
]
6263
},
@@ -1400,7 +1401,8 @@
14001401
],
14011402
"Troubleshooting": [
14021403
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-database-connection",
1403-
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-zeebe-connection"
1404+
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-zeebe-connection",
1405+
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login"
14041406
]
14051407
}
14061408
]

‎versioned_sidebars/version-8.3-sidebars.json

+5-1
Original file line numberDiff line numberDiff line change
@@ -1023,6 +1023,9 @@
10231023
{
10241024
"Elasticsearch": [
10251025
"self-managed/operational-guides/update-guide/elasticsearch/7-to-8"
1026+
],
1027+
"Keycloak": [
1028+
"self-managed/operational-guides/update-guide/keycloak/keycloak-update"
10261029
]
10271030
}
10281031
]
@@ -1495,7 +1498,8 @@
14951498
],
14961499
"Troubleshooting": [
14971500
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-database-connection",
1498-
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-zeebe-connection"
1501+
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-zeebe-connection",
1502+
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login"
14991503
]
15001504
}
15011505
]

‎versioned_sidebars/version-8.4-sidebars.json

+5-1
Original file line numberDiff line numberDiff line change
@@ -1079,6 +1079,9 @@
10791079
{
10801080
"Elasticsearch": [
10811081
"self-managed/operational-guides/update-guide/elasticsearch/7-to-8"
1082+
],
1083+
"Keycloak": [
1084+
"self-managed/operational-guides/update-guide/keycloak/keycloak-update"
10821085
]
10831086
}
10841087
]
@@ -1555,7 +1558,8 @@
15551558
],
15561559
"Troubleshooting": [
15571560
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-database-connection",
1558-
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-zeebe-connection"
1561+
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-zeebe-connection",
1562+
"self-managed/modeler/web-modeler/troubleshooting/troubleshoot-login"
15591563
]
15601564
}
15611565
]

0 commit comments

Comments
 (0)