From f0216cf90f7c29105b7c68b2bc5026b029c51a71 Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Tue, 10 Sep 2024 10:47:31 +0200 Subject: [PATCH 01/12] feat(oauth2): add Spring Security OAuth2 documentation https://github.com/camunda/camunda-bpm-platform/issues/4454 --- content/user-guide/camunda-bpm-run.md | 8 + .../spring-security.md | 180 ++++++++++++++++++ 2 files changed, 188 insertions(+) create mode 100644 content/user-guide/spring-boot-integration/spring-security.md diff --git a/content/user-guide/camunda-bpm-run.md b/content/user-guide/camunda-bpm-run.md index 653d38c5a..6f85008de 100644 --- a/content/user-guide/camunda-bpm-run.md +++ b/content/user-guide/camunda-bpm-run.md @@ -103,6 +103,14 @@ The start scripts (`start.bat` for Windows, `start.sh` for Linux/Mac) accept the enabled + + --oauth2 + + Enables Spring Security OAuth2 integration. + See dedicated }}">Spring Security OAuth2 Integration documentation for details. + + false + --help Prints a message showing the available start script arguments. diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md new file mode 100644 index 000000000..ce483e1f2 --- /dev/null +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -0,0 +1,180 @@ +--- + +title: 'Spring Security OAuth2 Integration' +weight: 80 + +menu: + main: + identifier: "user-guide-spring-security-integration" + parent: "user-guide-spring-boot-integration" + +--- + + +Camunda provides Spring Security OAuth2 integration with the `camunda-bpm-spring-boot-starter-security` library. +This library contains the Spring Security and Spring Security OAuth2 dependencies along with +configuration classes that integrate Spring Security with Camunda Webapp's authentication. + +This is available both for Spring Boot and Camunda Run. + +# Spring Boot + +In order to enable the Spring Security OAuth2 integration in Spring Boot, add the following dependency to your project: + +```xml + + org.camunda.bpm.springboot + camunda-bpm-spring-boot-starter-security + +``` + +# Camunda Run + +In order to enable the Spring Security OAuth2 integration in Camunda Run, start Run with an extra `--oauth2` argument: + +```shell +./start.sh --webapps --rest --example --oauth2 +``` + +# Auto Configuration + +The Camunda integration has two default auto configurations. Depending on the OAuth2 client +registration in the application properties (`spring.security.oauth2.client.registration`) either the +`CamundaSpringSecurityOAuth2AutoConfiguration` or the `CamundaBpmSpringSecurityDisableAutoConfiguration` will be used. + +## OAuth2 Auto Configuration + + +Starts if there is OAuth2 client registration configured. This class configures the Spring +Security filter chain to a permit all mode. + +Spring auto configuration class: {{< javadocref page="org/camunda/bpm/spring/boot/starter/security/oauth2/impl/CamundaSpringSecurityOAuth2AutoConfiguration.html" text="CamundaSpringSecurityOAuth2AutoConfiguration" >}} + +## Disable Auto Configuration + +Starts if there is **no** OAuth2 client registration configured. This class configures the Spring +Security filter chain to a permit all mode. + +Spring auto configuration class: {{< javadocref page="org/camunda/bpm/spring/boot/starter/security/oauth2/impl/CamundaBpmSpringSecurityDisableAutoConfiguration.html" text="CamundaBpmSpringSecurityDisableAutoConfiguration" >}} + + +# OAuth2 Integration + +Once the Camunda Spring Security OAuth2 integration is active and there is an OAuth2 client +registration configured, the Webapps will use the configured OAuth2 identity provider for authentication. + +For the client registration, please refer to the official Spring Security's [OAuth2 Core Configuration][OAuth2Config] documentation to configure your choice of identity provider. + +Camunda's integration uses the **name** field from Spring Security's principal object for the user +authentication. This needs to match the User ID in Camunda. + +{{< note title="Heads Up!" class="info" >}} +At this stage, OAuth2 is only used for authentication. Meaning, that the user needs to be +also configured with the matching User ID and proper authorizations in Camunda. + +If the user is not available or doesn't have sufficient authorizations, they won't be able to access the Webapps. +{{< /note >}} + +### User Name Mapping + +Spring Security provides an attribute to override the default scope (`sub`) used for the username. +This is the `spring.security.oauth2.client.provider.[providerId].user-name-attribute` from the +above-mentioned [OAuth2 Core Configuration][OAuth2Config]. + +If you wish to use a default attribute (claim) as the username, then make sure to override the `user-name-attribute` in your application properties. + +### Initial User + +In order to create an initial user in your application, you can either use the `camunda.bpm.admin-user` property: + +```yaml +camunda.bpm: + admin-user: + id: demo + password: demo + firstName: Demo + lastName: Demo +``` + +Or the `AdministratorAuthorizationPlugin`, see [The Administrator Authorization Plugin]({{< ref "/user-guide/process-engine/authorization-service.md#the-administrator-authorization-plugin" >}}) documentation for more details. + + +## OAuth2 Identity Provider + +Additionally to the OAuth2 login, Camunda also provides support to use groups from OAuth2. +This is achieved with a custom [identity service]({{< ref "/user-guide/process-engine/identity-service.md" >}}), called {{< javadocref page="org/camunda/bpm/spring/boot/starter/security/oauth2/impl/OAuth2IdentityProvider.html" text="OAuth2IdentityProvider" >}} + +This is a read-only identity provider that configures user's groups from the [Spring Security's granted authorities][Authorities]. +Additionally, the identity provider also contains the default Camunda Database Identity Service as a fallback. + +TODO add more details + +In order to activate this, add the following properties: +```yaml +camunda.bpm.oauth2: + identity-provider: + enabled: true +``` + +### Authorities mapping + +We also provide a default granted authorities mapper, that can override the Spring Security +authorities, that are populated by default with the scope claim. + +This mapper can be enabled with the `camunda.bpm.oauth2.identity-provider.group-name-attribute` property: +```yaml +camunda.bpm.oauth2: + identity-provider: + enabled: true + group-name-attribute: cognito:groups +``` + +Alternatively, you can also define your own [GrantedAuthoritiesMapper][GrantedAuthoritiesMapper], if you need more customization. + +## Security Recommendations + +If you decide to use OAuth2 for login in Camunda, we highly recommend to consult and implement the current industry recommended security standards. +Additionally, also follow the security recommendations specified by your identity provider. + +### Token Lifetime + +As OAuth2 works with the exchange of tokens and tokens are valid until the specified expiration ( +`exp` claim), it is inevitable that in a few cases tokens might outlive the main SSO session. +Meaning, the user might be already logged out but still have valid tokens on other pages. + +In order to minimize the occurrence if this, we recommend the use of short-lived access tokens along with refresh tokens. + +TODO add some links +? https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics + + +## Disabling Auto Configuration + +If you wish to completely disable Camunda's integration, refer to Spring's [Disabling Specific Auto-configuration Classes][DisableAutoConfig] documentation. + +With the `@EnableAutoConfiguration` annotation: + +```java +@EnableAutoConfiguration(exclude={ + CamundaSpringSecurityOAuth2AutoConfiguration.class, + CamundaBpmSpringSecurityDisableAutoConfiguration.class +}); +``` + +Or in the application properties: + +```yaml +spring: + autoconfigure: + exclude: + - org.camunda.bpm.spring.boot.starter.security.oauth2.CamundaSpringSecurityOAuth2AutoConfiguration + - org.camunda.bpm.spring.boot.starter.security.oauth2.CamundaBpmSpringSecurityDisableAutoConfiguration +``` + +[SpringSecurity]: https://docs.spring.io/spring-security/reference/index.html +[SpringSecurityOAuth2]: https://docs.spring.io/spring-security/reference/servlet/oauth2/index.html +[OAuth2Config]: https://docs.spring.io/spring-security/reference/servlet/oauth2/login/core.html +[Authorities]: https://docs.spring.io/spring-security/reference/servlet/authorization/architecture.html +[GrantedAuthoritiesMapper]: https://docs.spring.io/spring-security/reference/servlet/oauth2/login/advanced.html#oauth2login-advanced-map-authorities +[DisableAutoConfig]: https://docs.spring.io/spring-boot/reference/using/auto-configuration.html#using.auto-configuration.disabling-specific + From 107b50fc25a423b95aa69a76bc245add34d5608e Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Thu, 26 Sep 2024 13:15:49 +0200 Subject: [PATCH 02/12] add more sections & details --- .../spring-security.md | 228 ++++++++++++++---- 1 file changed, 179 insertions(+), 49 deletions(-) diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index ce483e1f2..880660070 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -17,7 +17,11 @@ configuration classes that integrate Spring Security with Camunda Webapp's authe This is available both for Spring Boot and Camunda Run. -# Spring Boot +Camunda's integration comes with multiple components and configurations. In the next sections you can find more details to each of them. + +# Activate OAuth2 + +## Spring Boot In order to enable the Spring Security OAuth2 integration in Spring Boot, add the following dependency to your project: @@ -28,8 +32,9 @@ In order to enable the Spring Security OAuth2 integration in Spring Boot, add th ``` -# Camunda Run +## Camunda Run +Camunda Run already contains the required libraries, all you need to do is to activate them. In order to enable the Spring Security OAuth2 integration in Camunda Run, start Run with an extra `--oauth2` argument: ```shell @@ -40,52 +45,51 @@ In order to enable the Spring Security OAuth2 integration in Camunda Run, start The Camunda integration has two default auto configurations. Depending on the OAuth2 client registration in the application properties (`spring.security.oauth2.client.registration`) either the -`CamundaSpringSecurityOAuth2AutoConfiguration` or the `CamundaBpmSpringSecurityDisableAutoConfiguration` will be used. - -## OAuth2 Auto Configuration +`CamundaSpringSecurityOAuth2AutoConfiguration` or the `CamundaBpmSpringSecurityDisableAutoConfiguration` will be activated. +## OAuth2 Enabled Configuration -Starts if there is OAuth2 client registration configured. This class configures the Spring -Security filter chain to a permit all mode. +Configuration activates if there is OAuth2 client registration configured. This class configures the Spring +Security filter chain to secure the Camunda Webapps. Spring auto configuration class: {{< javadocref page="org/camunda/bpm/spring/boot/starter/security/oauth2/impl/CamundaSpringSecurityOAuth2AutoConfiguration.html" text="CamundaSpringSecurityOAuth2AutoConfiguration" >}} -## Disable Auto Configuration +## Spring Security Disabled Auto Configuration -Starts if there is **no** OAuth2 client registration configured. This class configures the Spring +Configuration activates if there is **no** OAuth2 client registration configured. This class configures the Spring Security filter chain to a permit all mode. Spring auto configuration class: {{< javadocref page="org/camunda/bpm/spring/boot/starter/security/oauth2/impl/CamundaBpmSpringSecurityDisableAutoConfiguration.html" text="CamundaBpmSpringSecurityDisableAutoConfiguration" >}} +# OAuth2 Client Registration -# OAuth2 Integration +For the client registration, please refer to the official Spring +Security's [OAuth2 Core Configuration][OAuth2Config] documentation to configure your choice of +identity provider. -Once the Camunda Spring Security OAuth2 integration is active and there is an OAuth2 client -registration configured, the Webapps will use the configured OAuth2 identity provider for authentication. +Once there is an OAuth2 client registration configured and the Camunda Spring Security OAuth2 +integration is enabled, the Webapps will use the configured OAuth2 provider for +authentication. -For the client registration, please refer to the official Spring Security's [OAuth2 Core Configuration][OAuth2Config] documentation to configure your choice of identity provider. +# User Name Mapping -Camunda's integration uses the **name** field from Spring Security's principal object for the user -authentication. This needs to match the User ID in Camunda. +Camunda's integration uses the **name** field from Spring Security's principal object as the User ID +in the Webapps. -{{< note title="Heads Up!" class="info" >}} -At this stage, OAuth2 is only used for authentication. Meaning, that the user needs to be -also configured with the matching User ID and proper authorizations in Camunda. +Spring Security by default uses the subject (`sub`) claim as the principal name. As the User ID in Camunda is +an important part for authorizations, it's important that the right claim is used. -If the user is not available or doesn't have sufficient authorizations, they won't be able to access the Webapps. -{{< /note >}} - -### User Name Mapping - -Spring Security provides an attribute to override the default scope (`sub`) used for the username. +Spring Security provides a way to change the default attribute used for the username. This is the `spring.security.oauth2.client.provider.[providerId].user-name-attribute` from the above-mentioned [OAuth2 Core Configuration][OAuth2Config]. -If you wish to use a default attribute (claim) as the username, then make sure to override the `user-name-attribute` in your application properties. +{{< note title="Heads Up!" class="info" >}} +Make sure to correctly configure which token attribute should be used as the User ID. +{{< /note >}} -### Initial User +## Configuring Initial Authorizations -In order to create an initial user in your application, you can either use the `camunda.bpm.admin-user` property: +In order to create an initial authorizations in your application, you can either use the `camunda.bpm.admin-user` property: ```yaml camunda.bpm: @@ -96,32 +100,33 @@ camunda.bpm: lastName: Demo ``` -Or the `AdministratorAuthorizationPlugin`, see [The Administrator Authorization Plugin]({{< ref "/user-guide/process-engine/authorization-service.md#the-administrator-authorization-plugin" >}}) documentation for more details. +See [Camunda Engine Properties]({{< ref "/user-guide/spring-boot-integration/configuration#camunda-engine-properties" >}}) documentation for more details. +Or the [Administrator Authorization Plugin]({{< ref "/user-guide/process-engine/authorization-service.md#the-administrator-authorization-plugin" >}}). -## OAuth2 Identity Provider +# OAuth2 Identity Provider Additionally to the OAuth2 login, Camunda also provides support to use groups from OAuth2. This is achieved with a custom [identity service]({{< ref "/user-guide/process-engine/identity-service.md" >}}), called {{< javadocref page="org/camunda/bpm/spring/boot/starter/security/oauth2/impl/OAuth2IdentityProvider.html" text="OAuth2IdentityProvider" >}} This is a read-only identity provider that configures user's groups from the [Spring Security's granted authorities][Authorities]. -Additionally, the identity provider also contains the default Camunda Database Identity Service as a fallback. - -TODO add more details +This identity provider also supports the default Camunda Database Identity Service as a fallback for authentications for the REST API. -In order to activate this, add the following properties: +The identity provider is activated by default. You can override this with the following properties: ```yaml camunda.bpm.oauth2: identity-provider: - enabled: true + enabled: false ``` -### Authorities mapping +See [Configuration](#configuration) section for more infos. + +## Granted Authorities Mapper We also provide a default granted authorities mapper, that can override the Spring Security -authorities, that are populated by default with the scope claim. +authorities, that are by default populated with the scope (`scp`) claim. -This mapper can be enabled with the `camunda.bpm.oauth2.identity-provider.group-name-attribute` property: +This mapper can be enabled with the `group-name-attribute` property: ```yaml camunda.bpm.oauth2: identity-provider: @@ -129,30 +134,151 @@ camunda.bpm.oauth2: group-name-attribute: cognito:groups ``` +The mapper is only activated if the property is configured. +It supports claims with types of collection of `String`s and `String`. +If the claim is a `String`, it will try to split it with a delimiter which is comma by default. +You can override the default delimiter with the `group-name-delimiter` property. + +See [Configuration](#configuration) section for more infos. + +### Custom Granted Authorities Mapper + Alternatively, you can also define your own [GrantedAuthoritiesMapper][GrantedAuthoritiesMapper], if you need more customization. -## Security Recommendations +In Spring Boot this can be done by registering your own `GrantedAuthoritiesMapper` bean. + +In Camunda Run a JAR file needs to be built and copied into the `userlib` folder. +This needs to contain a [Spring auto configuration][AutoConfig] with the custom granted authorities mapper bean. + +## Configuration + +All configuration properties of the identity provider start with the prefix `camunda.bpm.oauth2.identity-provider`. +The following properties are available: + + + + + + + + + + + + + + + + + + + + + + +
PropertyDescriptionDefault
enabled + Activated and deactivates the OAuth2 Identity Service registration.
+ Enabled by default! + 		true
group-name-attribute + Activates and configures the OAuth2 Granted Authorities Mapper. + null
group-name-delimiter + Configures the delimiter used in the OAuth2 Granted Authorities Mapper. + It's only used if the configured group-name-attribute contains String value. + , (comma)
+ +## Limitations + +As previously mentioned, this provider is a read-only provider, so creating users, group or memberships is not available. +Due to the fallback to DB Identity Service this provider is still defined as writeable which means the create buttons are still visible on the Admin pages, but are non-functional. + +OAuth2 doesn't return information about other users or groups. This means users and even admins can only see their own user and groups on the Admin pages. + +Furthermore, it only shows groups from OAuth2 and doesn't show groups configured in Camunda database. + +## Disabling Identity Provider + +With the [above-mentioned property](#configuration), the identity provider can be deactivated. +Without identity provider OAuth2 is only used for authentication. This means, that the user needs to +be also configured with the matching User ID in Camunda database. + +If the user is not available or doesn't have sufficient authorizations, they won't be able to access +the Webapps. + +# Logout + +We provide support for local and client initiated SSO logout as well. +In order to support both logouts, the Camunda integration also contains a Frontend Plugin that overrides the Webapps default logout behaviour. +As a consequence, when the Webapp user clicks on the logout, it invokes Spring's logout endpoint (`/logout`) instead of Camunda's. + +## Client Initiated SSO Logout + +We support client initiated OIDC SSO logout. +Please refer Spring's [OpenID Connect 1.0 Client-Initiated Logout][SSOLogout] section for more information. + +In order to configure this feature, use the following properties: + +```yaml +camunda.bpm.oauth2: + sso-logout: + enabled: true + postLogoutRedirectUri: https://camunda.com/ +``` + +See [Configuration](#configuration-1) section for more infos. + +## Configuration + +All configuration properties of the identity provider start with the prefix `camunda.bpm.oauth2.sso-logout`. +The following properties are available: + + + + + + + + + + + + + + + + + +
PropertyDescriptionDefault
enabled + Activated the client initiated OIDC logout feature. + false
post-logout-redirect-uri + Configures the URI the user is redirected after SSO logout from the provider. + {baseUrl}
+ +## Limitations + +Currently, it's not possible to change the default Spring logout endpoint, which is `/logout`. + +# Security Recommendations If you decide to use OAuth2 for login in Camunda, we highly recommend to consult and implement the current industry recommended security standards. Additionally, also follow the security recommendations specified by your identity provider. -### Token Lifetime +## Token Lifetime -As OAuth2 works with the exchange of tokens and tokens are valid until the specified expiration ( -`exp` claim), it is inevitable that in a few cases tokens might outlive the main SSO session. +As OAuth2 works with the exchange of tokens and tokens are valid until the specified expiration (`exp`), +it is inevitable that in a few cases tokens might outlive the main SSO session. Meaning, the user might be already logged out but still have valid tokens on other pages. -In order to minimize the occurrence if this, we recommend the use of short-lived access tokens along with refresh tokens. - -TODO add some links -? https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics +In order to minimize the risk of this, we recommend the use of short-lived access tokens along with +refresh tokens. +Refresh tokens can be revoked, and issuing new access tokens require interaction with the provider, +which means the user session can be revalidated more frequently. +# Disable Auto Configuration -## Disabling Auto Configuration +If you wish to use Spring Security but without Camunda's integration classes, you can do so by +excluding the two auto configuration classes: -If you wish to completely disable Camunda's integration, refer to Spring's [Disabling Specific Auto-configuration Classes][DisableAutoConfig] documentation. - -With the `@EnableAutoConfiguration` annotation: +Either with the `@EnableAutoConfiguration` annotation: ```java @EnableAutoConfiguration(exclude={ @@ -171,10 +297,14 @@ spring: - org.camunda.bpm.spring.boot.starter.security.oauth2.CamundaBpmSpringSecurityDisableAutoConfiguration ``` +For more information, please refer to Spring's [Disabling Specific Auto-configuration Classes][DisableAutoConfig] documentation. + [SpringSecurity]: https://docs.spring.io/spring-security/reference/index.html [SpringSecurityOAuth2]: https://docs.spring.io/spring-security/reference/servlet/oauth2/index.html [OAuth2Config]: https://docs.spring.io/spring-security/reference/servlet/oauth2/login/core.html [Authorities]: https://docs.spring.io/spring-security/reference/servlet/authorization/architecture.html [GrantedAuthoritiesMapper]: https://docs.spring.io/spring-security/reference/servlet/oauth2/login/advanced.html#oauth2login-advanced-map-authorities [DisableAutoConfig]: https://docs.spring.io/spring-boot/reference/using/auto-configuration.html#using.auto-configuration.disabling-specific +[AutoConfig]: https://docs.spring.io/spring-boot/reference/features/developing-auto-configuration.html#features.developing-auto-configuration.locating-auto-configuration-candidates +[SSOLogout]: https://docs.spring.io/spring-security/reference/reactive/oauth2/login/logout.html#oauth2login-advanced-oidc-logout From 67782bf7cffe8784f7e914c6a4fa11619aa20b82 Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Thu, 26 Sep 2024 13:36:22 +0200 Subject: [PATCH 03/12] add cross-links & details --- content/user-guide/process-engine/identity-service.md | 4 ++++ content/user-guide/security.md | 4 ++++ .../user-guide/spring-boot-integration/spring-security.md | 7 +++++-- 3 files changed, 13 insertions(+), 2 deletions(-) diff --git a/content/user-guide/process-engine/identity-service.md b/content/user-guide/process-engine/identity-service.md index ed54e4c78..e824a5ddd 100644 --- a/content/user-guide/process-engine/identity-service.md +++ b/content/user-guide/process-engine/identity-service.md @@ -376,6 +376,10 @@ The LDAP Identity Provider provides the following configuration properties: +# The OAuth2 Identity Service + +See the Spring Security OAuth2 Integration's [OAuth2 Identity Provider]({{< ref "/user-guide/spring-boot-integration/spring-security.md#oauth2-identity-provider" >}}) documentation. + # Throttle login attempts A mechanism exists for preventing subsequent unsuccessful login attempts.The essence of it is that the user is not able to log in for a specific amount of time after unsuccessful login attempts. diff --git a/content/user-guide/security.md b/content/user-guide/security.md index bb8577e9d..5aad600f4 100644 --- a/content/user-guide/security.md +++ b/content/user-guide/security.md @@ -167,6 +167,10 @@ To prevent this: 4. Don't allow to reuse an id of a deleted user. +## Spring Security OAuth2 + +See the Spring Security OAuth2 Integration's [Security Recommendations]({{< ref "/user-guide/spring-boot-integration/spring-security.md#security-recommendations" >}}) documentation. + ## Deployments [Deployments]({{< ref "/user-guide/process-engine/deployments.md" >}}) to the process engine can contain resources that are interpreted like code: diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index 880660070..51bfa2886 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -89,7 +89,7 @@ Make sure to correctly configure which token attribute should be used as the Use ## Configuring Initial Authorizations -In order to create an initial authorizations in your application, you can either use the `camunda.bpm.admin-user` property: +In order to create initial authorizations in your application, you can either use the `camunda.bpm.admin-user` property to create an admin user with authorizations: ```yaml camunda.bpm: @@ -102,7 +102,8 @@ camunda.bpm: See [Camunda Engine Properties]({{< ref "/user-guide/spring-boot-integration/configuration#camunda-engine-properties" >}}) documentation for more details. -Or the [Administrator Authorization Plugin]({{< ref "/user-guide/process-engine/authorization-service.md#the-administrator-authorization-plugin" >}}). +Or the [Administrator Authorization Plugin]({{< ref "/user-guide/process-engine/authorization-service.md#the-administrator-authorization-plugin" >}}) +to grant administrator authorizations for a particular OAuth2 user or group. # OAuth2 Identity Provider @@ -259,6 +260,8 @@ Currently, it's not possible to change the default Spring logout endpoint, which # Security Recommendations +Camunda's integration heavily relies on Spring Security's OAuth2 support. + If you decide to use OAuth2 for login in Camunda, we highly recommend to consult and implement the current industry recommended security standards. Additionally, also follow the security recommendations specified by your identity provider. From 493730d90e97782d66d32941f42f7ad7096a8955 Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Thu, 26 Sep 2024 13:49:18 +0200 Subject: [PATCH 04/12] logging --- .../spring-boot-integration/spring-security.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index 51bfa2886..99293dd8a 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -276,6 +276,17 @@ refresh tokens. Refresh tokens can be revoked, and issuing new access tokens require interaction with the provider, which means the user session can be revalidated more frequently. +# Logging + +We use debug logging for several things such as bean registrations, user authentication or logout and token authorization. +Logging can be enabled for the package via the following property: + +```yaml +logging: + level: + org.camunda.bpm.spring.boot.starter.security.oauth2: DEBUG +``` + # Disable Auto Configuration If you wish to use Spring Security but without Camunda's integration classes, you can do so by From 44432e98d1e501cedd56c7433c4b00933916388f Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Thu, 26 Sep 2024 14:55:24 +0200 Subject: [PATCH 05/12] example --- .../spring-security.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index 99293dd8a..78f99b3a3 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -287,6 +287,44 @@ logging: org.camunda.bpm.spring.boot.starter.security.oauth2: DEBUG ``` +# Example + +In this section we provide an example configuration with OKTA as OIDC provider. +Additionally, we also mark and explain a few lines: + +```yaml +camunda.bpm.oauth2: + sso-logout: # 1 + enabled: true + postLogoutRedirectUri: https://camunda.com/ + identity-provider: + group-name-attribute: okta-groups # 2 + +spring.security: # 3 + oauth2: + client: + registration: + okta: + clientId: + clientSecret: + scope: openid,profile,email,offline_access # 4 + provider: + okta: + issuerUri: + user-name-attribute: preferred_username # 5 +``` + +- Client initiated SSO activated, redirect uri overridden. (1) +- Identity provider groups loaded from custom `okta-groups` claim. (2) + - This also needs to be configured on the provider page in order for the id token to contain the claim. +- Uses the traditional Spring Security properties. (3) + - Alternatively, `okta-spring-security-oauth2` library and its properties could be used too. +- Defines the `openid,profile,email,offline_access` scopes. (4) + - Scopes are provider dependent. `openid` is required usually. + - In case of OKTA `profile` and `email` are useful to access firstname, lastname and email in Camunda but not mandatory. + - `offline_access` activates the refresh_token grant, not mandatory. +- Configures the `preferred_username` as the username attribute, which is also used as the Camunda User ID. (5) + # Disable Auto Configuration If you wish to use Spring Security but without Camunda's integration classes, you can do so by From 931167edeb7c7a5940baac7de02420e315425707 Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Fri, 27 Sep 2024 15:23:24 +0200 Subject: [PATCH 06/12] add configs to main page & some fixes --- .../spring-boot-integration/configuration.md | 36 +++++++++++++ .../spring-security.md | 54 +++++++++---------- 2 files changed, 60 insertions(+), 30 deletions(-) diff --git a/content/user-guide/spring-boot-integration/configuration.md b/content/user-guide/spring-boot-integration/configuration.md index f250ece70..f6b18a770 100644 --- a/content/user-guide/spring-boot-integration/configuration.md +++ b/content/user-guide/spring-boot-integration/configuration.md @@ -823,6 +823,42 @@ When setting to /, the legacy behavior of Camunda Spring Boot Start - + + + OAuth2 + + + + camunda.bpm.oauth2.identity-provider + .enabled + Enables the OAuth2 identity provider. + true + + + .group-name-attribute + Enables and configures the OAuth2 Granted Authorities Mapper. + - + + + .group-name-delimiter + + Configures the delimiter used in the OAuth2 Granted Authorities Mapper. + It's only used if the configured group-name-attribute contains String value. + + , (comma) + + + camunda.bpm.oauth2.sso-logout + .enabled + Activates the client initiated OIDC logout feature. + false + + + .post-logout-redirect-uri + Configures the URI the user is redirected after SSO logout from the provider. + {baseUrl} + + diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index 78f99b3a3..d77280f36 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -89,20 +89,20 @@ Make sure to correctly configure which token attribute should be used as the Use ## Configuring Initial Authorizations -In order to create initial authorizations in your application, you can either use the `camunda.bpm.admin-user` property to create an admin user with authorizations: - -```yaml -camunda.bpm: - admin-user: - id: demo - password: demo - firstName: Demo - lastName: Demo -``` - -See [Camunda Engine Properties]({{< ref "/user-guide/spring-boot-integration/configuration#camunda-engine-properties" >}}) documentation for more details. - -Or the [Administrator Authorization Plugin]({{< ref "/user-guide/process-engine/authorization-service.md#the-administrator-authorization-plugin" >}}) +For creating initial authorizations in your application, you have the following options available: + +1. The `camunda.bpm.admin-user` property to create an admin user with authorizations: + ```yaml + camunda.bpm: + admin-user: + id: demo + password: demo + firstName: Demo + lastName: Demo + ``` + + - See [Camunda Engine Properties]({{< ref "/user-guide/spring-boot-integration/configuration#camunda-engine-properties" >}}) documentation for more details. +2. The [Administrator Authorization Plugin]({{< ref "/user-guide/process-engine/authorization-service.md#the-administrator-authorization-plugin" >}}) to grant administrator authorizations for a particular OAuth2 user or group. # OAuth2 Identity Provider @@ -158,24 +158,22 @@ The following properties are available: - + - + - - + + @@ -189,7 +187,7 @@ The following properties are available: ## Limitations -As previously mentioned, this provider is a read-only provider, so creating users, group or memberships is not available. +As previously mentioned, this provider is a read-only provider, so creating users, groups or memberships is not available. Due to the fallback to DB Identity Service this provider is still defined as writeable which means the create buttons are still visible on the Admin pages, but are non-functional. OAuth2 doesn't return information about other users or groups. This means users and even admins can only see their own user and groups on the Admin pages. @@ -234,22 +232,18 @@ The following properties are available:
PropertyProperty name DescriptionDefaultDefault value
enabled - Activated and deactivates the OAuth2 Identity Service registration.
+ Enables the OAuth2 identity provider.
Enabled by default! 		true
group-name-attribute - Activates and configures the OAuth2 Granted Authorities Mapper. - nullEnables and configures the OAuth2 Granted Authorities Mapper.-
group-name-delimiter
- + - + - + - +
PropertyProperty name DescriptionDefaultDefault value
enabled - Activated the client initiated OIDC logout feature. - Activates the client initiated OIDC logout feature. false
post-logout-redirect-uri - Configures the URI the user is redirected after SSO logout from the provider. - Configures the URI the user is redirected after SSO logout from the provider. {baseUrl}
From 9904282d8b5b221b8ac47855ff23bd606e314101 Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Mon, 30 Sep 2024 15:51:34 +0200 Subject: [PATCH 07/12] Update content/user-guide/spring-boot-integration/spring-security.md Co-authored-by: yanavasileva --- content/user-guide/spring-boot-integration/spring-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index d77280f36..04dbfb22a 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -315,7 +315,7 @@ spring.security: # 3 - Alternatively, `okta-spring-security-oauth2` library and its properties could be used too. - Defines the `openid,profile,email,offline_access` scopes. (4) - Scopes are provider dependent. `openid` is required usually. - - In case of OKTA `profile` and `email` are useful to access firstname, lastname and email in Camunda but not mandatory. + - In case of OKTA, `profile` and `email` are useful to access firstname, lastname and email in Camunda but not mandatory. - `offline_access` activates the refresh_token grant, not mandatory. - Configures the `preferred_username` as the username attribute, which is also used as the Camunda User ID. (5) From ea45c5a10ee4503d55ebe20e48df09874a975d9c Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Mon, 30 Sep 2024 15:51:49 +0200 Subject: [PATCH 08/12] Update content/user-guide/spring-boot-integration/spring-security.md Co-authored-by: yanavasileva --- content/user-guide/spring-boot-integration/spring-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index 04dbfb22a..519c5b8d8 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -108,7 +108,7 @@ to grant administrator authorizations for a particular OAuth2 user or group. # OAuth2 Identity Provider Additionally to the OAuth2 login, Camunda also provides support to use groups from OAuth2. -This is achieved with a custom [identity service]({{< ref "/user-guide/process-engine/identity-service.md" >}}), called {{< javadocref page="org/camunda/bpm/spring/boot/starter/security/oauth2/impl/OAuth2IdentityProvider.html" text="OAuth2IdentityProvider" >}} +This is achieved with a custom [identity service]({{< ref "/user-guide/process-engine/identity-service.md" >}}), called {{< javadocref page="org/camunda/bpm/spring/boot/starter/security/oauth2/impl/OAuth2IdentityProvider.html" text="OAuth2IdentityProvider" >}}. This is a read-only identity provider that configures user's groups from the [Spring Security's granted authorities][Authorities]. This identity provider also supports the default Camunda Database Identity Service as a fallback for authentications for the REST API. From 345fb43a71e0b11e973cde76840b993d826e54d2 Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Mon, 30 Sep 2024 15:52:02 +0200 Subject: [PATCH 09/12] Update content/user-guide/spring-boot-integration/spring-security.md Co-authored-by: yanavasileva --- content/user-guide/spring-boot-integration/spring-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index 519c5b8d8..b2e023898 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -38,7 +38,7 @@ Camunda Run already contains the required libraries, all you need to do is to ac In order to enable the Spring Security OAuth2 integration in Camunda Run, start Run with an extra `--oauth2` argument: ```shell -./start.sh --webapps --rest --example --oauth2 +./start.sh --webapps --rest --oauth2 ``` # Auto Configuration From 2ede3d0c09e9bcc77e1f807b3ba0851b4fc9d1fa Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Mon, 30 Sep 2024 15:52:15 +0200 Subject: [PATCH 10/12] Update content/user-guide/spring-boot-integration/spring-security.md Co-authored-by: yanavasileva --- content/user-guide/spring-boot-integration/spring-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index b2e023898..59bdf6f19 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -91,7 +91,7 @@ Make sure to correctly configure which token attribute should be used as the Use For creating initial authorizations in your application, you have the following options available: -1. The `camunda.bpm.admin-user` property to create an admin user with authorizations: +1. The `camunda.bpm.admin-user` property to create an administrator user with authorizations: ```yaml camunda.bpm: admin-user: From 26b072f1894bc7135b24409fa0127e3566332e20 Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Mon, 30 Sep 2024 15:52:25 +0200 Subject: [PATCH 11/12] Update content/user-guide/spring-boot-integration/spring-security.md Co-authored-by: yanavasileva --- content/user-guide/spring-boot-integration/spring-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index 59bdf6f19..13e07f55d 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -120,7 +120,7 @@ camunda.bpm.oauth2: enabled: false ``` -See [Configuration](#configuration) section for more infos. +See [Configuration](#configuration) section for more information. ## Granted Authorities Mapper From 13c161a72aab84df5bb20c8b227573853089ed56 Mon Sep 17 00:00:00 2001 From: Daniel Kelemen Date: Mon, 30 Sep 2024 15:57:51 +0200 Subject: [PATCH 12/12] review feedback --- .../spring-security.md | 26 +++++++++---------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/content/user-guide/spring-boot-integration/spring-security.md b/content/user-guide/spring-boot-integration/spring-security.md index 13e07f55d..0fd998a43 100644 --- a/content/user-guide/spring-boot-integration/spring-security.md +++ b/content/user-guide/spring-boot-integration/spring-security.md @@ -140,7 +140,7 @@ It supports claims with types of collection of `String`s and `String`. If the claim is a `String`, it will try to split it with a delimiter which is comma by default. You can override the default delimiter with the `group-name-delimiter` property. -See [Configuration](#configuration) section for more infos. +See [Configuration](#configuration) section for more information. ### Custom Granted Authorities Mapper @@ -223,8 +223,6 @@ camunda.bpm.oauth2: postLogoutRedirectUri: https://camunda.com/ ``` -See [Configuration](#configuration-1) section for more infos. - ## Configuration All configuration properties of the identity provider start with the prefix `camunda.bpm.oauth2.sso-logout`. @@ -272,7 +270,7 @@ which means the user session can be revalidated more frequently. # Logging -We use debug logging for several things such as bean registrations, user authentication or logout and token authorization. +You can switch the level of the following logger to track bean registrations, user authentication or logout, and token authorizations. Logging can be enabled for the package via the following property: ```yaml @@ -308,16 +306,16 @@ spring.security: # 3 user-name-attribute: preferred_username # 5 ``` -- Client initiated SSO activated, redirect uri overridden. (1) -- Identity provider groups loaded from custom `okta-groups` claim. (2) - - This also needs to be configured on the provider page in order for the id token to contain the claim. -- Uses the traditional Spring Security properties. (3) - - Alternatively, `okta-spring-security-oauth2` library and its properties could be used too. -- Defines the `openid,profile,email,offline_access` scopes. (4) - - Scopes are provider dependent. `openid` is required usually. - - In case of OKTA, `profile` and `email` are useful to access firstname, lastname and email in Camunda but not mandatory. - - `offline_access` activates the refresh_token grant, not mandatory. -- Configures the `preferred_username` as the username attribute, which is also used as the Camunda User ID. (5) +1. Client initiated SSO activated, redirect uri overridden. +2. Identity provider groups loaded from custom `okta-groups` claim. + - This also needs to be configured on the provider page in order for the id token to contain the claim. +3. Uses the traditional Spring Security properties. + - Alternatively, `okta-spring-security-oauth2` library and its properties could be used too. +4. Defines the `openid,profile,email,offline_access` scopes. + - Scopes are provider dependent. `openid` is required usually. + - In case of OKTA, `profile` and `email` are useful to access firstname, lastname and email in Camunda but not mandatory. + - `offline_access` activates the refresh_token grant, not mandatory. +5. Configures the `preferred_username` as the username attribute, which is also used as the Camunda User ID. # Disable Auto Configuration