Skip to content

Commit 3fba90e

Browse files
Ben-SheppardBen-Sheppard
authored
Merge pull request #7922 from camunda/npp-sso-callback
docs: ensure we configure redirect-uri to /sso-callback
2 parents c15ecbb + 61899dd commit 3fba90e

File tree

2 files changed

+68
-2
lines changed

2 files changed

+68
-2
lines changed

‎docs/self-managed/components/orchestration-cluster/identity/connect-external-identity-provider.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,40 @@ CAMUNDA_SECURITY_AUTHENTICATION_OIDC_SCOPE=["openid"]
106106
</TabItem>
107107
</Tabs>
108108

109-
- **Redirect URI**: By default, the redirect URI is `http://localhost:8080/sso-callback`. Update this if your deployment uses a different hostname or port.
109+
## Redirect URI
110+
111+
Use the redirect URI to define where the Identity Provider (IdP) sends users back after successful authentication.
112+
113+
By default, the redirect URI is:
114+
115+
`{baseUrl}/sso-callback`
116+
117+
At runtime, `{baseUrl}` resolves to the URL used to access your Orchestration Cluster deployment. In most cases, you do not need to change this value.
118+
119+
You may need to customize the redirect URI in advanced scenarios, such as:
120+
121+
- When your deployment is accessed through reverse proxies or load balancers
122+
- When you need to pass context information while configuring multiple OIDC providers
123+
124+
Regardless of customization, the redirect URI must always point to the `/sso-callback` endpoint of your Orchestration Cluster deployment.
125+
126+
Most Identity Providers require you to explicitly configure allowed redirect URIs for security reasons. Ensure the value configured in your IdP exactly matches the redirect URI used here, whether it is static or dynamically resolved using `{baseUrl}`.
127+
128+
:::note
129+
130+
`{baseUrl}` is dynamically resolved for each request based on the URL used to access the Orchestration Cluster instance. It is composed of the following parts:
131+
132+
- `{scheme}`: The transport scheme (`http` or `https`)
133+
- `{host}`: The hostname used to connect to the instance
134+
- `{port}`: The port number, if specified (omitted if not used)
135+
- `{contextPath}`: The context path of the Orchestration Cluster instance, if configured (omitted if none)
136+
137+
For example:
138+
139+
- Accessing the instance via `https://camunda.acme.com/identity` resolves `{baseUrl}` to `https://camunda.acme.com`
140+
- Accessing the instance via `https://services.acme.com:18080/camunda/` resolves `{baseUrl}` to `https://services.acme.com:18080/camunda`
141+
142+
:::
110143

111144
- **Username claim**: By default, the `sub` (subject) claim from the token is used as the username. If you want to use a different claim (such as `preferred_username` or `email`), ensure your IdP includes it in the token and set the `username-claim` property accordingly. You can use a [JSONPath expression](https://www.rfc-editor.org/rfc/rfc9535.html) to locate the username claim in the token (for example, `$['camundaorg']['username']`).
112145

‎versioned_docs/version-8.8/self-managed/components/orchestration-cluster/identity/connect-external-identity-provider.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,40 @@ CAMUNDA_SECURITY_AUTHENTICATION_OIDC_SCOPE=["openid"]
106106
</TabItem>
107107
</Tabs>
108108

109-
- **Redirect URI**: By default, the redirect URI is `http://localhost:8080/sso-callback`. Update this if your deployment uses a different hostname or port.
109+
## Redirect URI
110+
111+
Use the redirect URI to define where the Identity Provider (IdP) sends users back after successful authentication.
112+
113+
By default, the redirect URI is:
114+
115+
`{baseUrl}/sso-callback`
116+
117+
At runtime, `{baseUrl}` resolves to the URL used to access your Orchestration Cluster deployment. In most cases, you do not need to change this value.
118+
119+
You may need to customize the redirect URI in advanced scenarios, such as:
120+
121+
- When your deployment is accessed through reverse proxies or load balancers
122+
- When you need to pass context information while configuring multiple OIDC providers
123+
124+
Regardless of customization, the redirect URI must always point to the `/sso-callback` endpoint of your Orchestration Cluster deployment.
125+
126+
Most Identity Providers require you to explicitly configure allowed redirect URIs for security reasons. Ensure the value configured in your IdP exactly matches the redirect URI used here, whether it is static or dynamically resolved using `{baseUrl}`.
127+
128+
:::note
129+
130+
`{baseUrl}` is dynamically resolved for each request based on the URL used to access the Orchestration Cluster instance. It is composed of the following parts:
131+
132+
- `{scheme}`: The transport scheme (`http` or `https`)
133+
- `{host}`: The hostname used to connect to the instance
134+
- `{port}`: The port number, if specified (omitted if not used)
135+
- `{contextPath}`: The context path of the Orchestration Cluster instance, if configured (omitted if none)
136+
137+
For example:
138+
139+
- Accessing the instance via `https://camunda.acme.com/identity` resolves `{baseUrl}` to `https://camunda.acme.com`
140+
- Accessing the instance via `https://services.acme.com:18080/camunda/` resolves `{baseUrl}` to `https://services.acme.com:18080/camunda`
141+
142+
:::
110143

111144
- **Username claim**: By default, the `sub` (subject) claim from the token is used as the username. If you want to use a different claim (such as `preferred_username` or `email`), ensure your IdP includes it in the token and set the `username-claim` property accordingly. You can use a [JSONPath expression](https://www.rfc-editor.org/rfc/rfc9535.html) to locate the username claim in the token (for example, `$['camundaorg']['username']`).
112145

0 commit comments

Comments
 (0)