Spring Security OAuth2 Integration

CIB seven provides Spring Security OAuth2 integration with the cibseven-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 the CIB seven engine REST and the legacy Camunda Webapp’s authentication.

This is available both for Spring Boot and CIB seven.

CIB seven’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:

<dependency>
  <groupId>org.cibseven.bpm.springboot</groupId>
  <artifactId>cibseven-bpm-spring-boot-starter-security</artifactId>
</dependency>

CIB seven Run

CIB seven 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 CIB seven Run, start Run with an extra --oauth2 argument:

./start.sh --webapps --rest --oauth2

Auto Configuration

The CIB seven integration provides several default auto configurations. Depending on the OAuth2 client registration defined in the application properties (spring.security.oauth2.client.registration) either the CamundaSpringSecurityOAuth2WebappAutoConfiguration or the CamundaBpmSpringSecurityDisableAutoConfiguration will be activated.

Additionaly, if the OAuth2 resource server configuration is defined in the application properties, the CamundaSpringSecurityOAuth2EngineAutoConfiguration will be activated.

OAuth2 Enabled Configuration for the Engine REST

This configuration activates when OAuth2 resource server registration is defined. This class configures the Spring Security filter chain to secure the engine REST.

Spring auto configuration class: CamundaSpringSecurityOAuth2EngineAutoConfiguration

OAuth2 Configurations for legacy Camunda Webapp

OAuth2 Enabled Configuration

This configuration activates when OAuth2 client registration is defined. This class configures the Spring Security filter chain to secure the legacy Camunda Webapp.

Spring auto configuration class: CamundaSpringSecurityOAuth2WebappAutoConfiguration

Spring Security Disabled Configuration

This configuration activates when no OAuth2 client registration is defined. This class configures the Spring Security filter chain to allow all requests related to the legacy Camunda webapp.

Spring auto configuration class: CamundaBpmSpringSecurityDisableAutoConfiguration

OAuth2 Client Registration

For the client registration, please refer to the official Spring Security’s OAuth2 Core Configuration documentation to configure your choice of identity provider.

Once there is an OAuth2 client registration configured and the CIB seven Spring Security OAuth2 integration is enabled, the legacy Camunda webapps will use the configured OAuth2 provider for authentication.

OAuth2 Resource Server

For the resource server configuration, please refer to the official Spring Security OAuth2 Resource Server Configuration documentation to configure your preferred settings.

Once the OAuth2 resource server is configured and the CIB seven Spring Security OAuth2 integration is enabled, the CIB seven Engine REST will use the configured OAuth2 settings for authentication.

User Name Mapping

CIB seven’s integration uses the name field from Spring Security’s principal object as the User ID in the Webapps.

Spring Security by default uses the subject (sub) claim as the principal name. As the User ID in CIB seven is an important part for authorizations, it’s important that the right claim is used.

When configuring Spring Security as an OAuth2 client, it provides a way to change the default attribute used for the username. This is done via the spring.security.oauth2.client.provider.[providerId].user-name-attribute from the above-mentioned OAuth2 Core Configuration.

On the other hand, if we configure Spring Security as an OAuth2 resource server to secure engine REST, we can set our custom principal name via spring.security.oauth2.resourceserver.jwt.principal-claim-name. CIB seven defaulted it to be preferred_username.

Configuring Initial Authorizations

For creating initial authorizations in your application, you have the following options available:

1. The camunda.bpm.admin-user property to create an administrator user with authorizations:

   camunda.bpm:
     admin-user:
       id: demo
       password: demo
       firstName: Demo
       lastName: Demo
   

• See CIB seven Engine Properties documentation for more details.

2. The Administrator Authorization Plugin to grant administrator authorizations for a particular OAuth2 user or group.

OAuth2 Identity Provider

Additionally to the OAuth2 login, CIB seven also provides support to use groups from OAuth2. This is achieved with a custom identity service, called OAuth2IdentityProvider .

This is a read-only identity provider that configures user’s groups from the Spring Security’s granted authorities. This identity provider also supports the default CIB seven Database Identity Service as a fallback for authentications for the REST API.

The identity provider is activated by default. You can override this with the following properties:

camunda.bpm.oauth2:
  identity-provider:
    enabled: false

See Configuration section for more information.

Granted Authorities Mapper

We also provide a mechanisms to override the Spring Security authorities, which are by default populated with the scope (scp) claim. Specifically, these are a default granted authorities mapper and a JWT authentication converter.

These can be enabled using the group-name-attribute property:

camunda.bpm.oauth2:
  identity-provider:
    enabled: true
    group-name-attribute: cognito:groups

Then, the mapper and the authentication converter are activated automatically, depending on whether an OAuth2 client is registered or an OAuth2 resource server is configured, respectively.

These mechanisms support claims with types of collection of Strings 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 section for more information.

Custom Granted Authorities Mapper

Alternatively, you can also define your own GrantedAuthoritiesMapper or JwtAuthenticationConverter, if you need more customization.

In Spring Boot this can be done by registering your own GrantedAuthoritiesMapper bean or JwtAuthenticationConverter bean.

In CIB seven Run a JAR file needs to be built and copied into the userlib folder. This needs to contain a Spring auto configuration 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:

Limitations

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.

Furthermore, it only shows groups from OAuth2 and doesn’t show groups configured in CIB seven database.

Disabling Identity Provider

With the above-mentioned property, 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 CIB seven database.

If the user is not available or doesn’t have sufficient authorizations, they won’t be able to access the Webapps.

Logout for legacy Camunda Webapp

We provide support for local and client initiated SSO logout as well. In order to support both logouts, the CIB seven 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 legacy Camunda’s.

Client Initiated SSO Logout

We support client initiated OIDC SSO logout. Please refer Spring’s OpenID Connect 1.0 Client-Initiated Logout section for more information.

In order to configure this feature, use the following properties:

camunda.bpm.oauth2:
  sso-logout:
    enabled: true
    postLogoutRedirectUri: https://example.org/

Configuration

All configuration properties of the identity provider start with the prefix camunda.bpm.oauth2.sso-logout. The following properties are available:

Limitations

Currently, it’s not possible to change the default Spring logout endpoint, which is /logout.

Security Recommendations

CIB seven’s integration heavily relies on Spring Security’s OAuth2 support.

If you decide to use OAuth2 for login in CIB seven, 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), 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 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.

Logging

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:

logging:
  level:
    org.cibseven.bpm.spring.boot.starter.security.oauth2: DEBUG

To inspect granted authorities, you can add this log level:

logging:
  level:
    org.springframework.security.oauth2.server.resource.web.authentication.BearerTokenAuthenticationFilter: DEBUG

Examples

Securing Engine REST

In this section we provide an example configuration using Keycloak as OIDC provider. Additionally, we highlight and explain a few lines for clarity:

camunda.bpm.oauth2:
 identity-provider:
   group-name-attribute: keycloak-groups # 4

spring.security: # 5
 oauth2:
   resourceserver:
    jwt:
      # principal-claim-name: preferred_username # 7
      jwk-set-uri: <certsUri>

cibseven.webclient:
    user:
      provider: org.cibseven.webapp.auth.KeycloakUserProvider # 1
    sso: # 2
      active: true
      endpoints:
        authorization: <authUri>
        token: <tokenUri>
        jwks: <certsUri>
        user: <usersUri>
      clientId: <clientId>
      clientSecret: <clientSecret>
      scopes: openid email profile # 6
      userIdProperty: preferred_username
      userNameProperty: name
      accessTokenToEngineRest: true # 3

1. Using KeycloakUserProvider.
2. SSO login enabled for CIB seven webclient.
3. CIB seven webclient enabled for OAuth2 communication with the engine REST.
4. Identity provider groups are loaded from custom keycloak-groups claim.
   • This must also be configured on the provider page so that the id token includes the claim.
5. Uses the traditional Spring Security properties to configure our resource server.
6. Defines the openid, profile and email scopes.
7. Configures the preferred_username as the principal claim name, which is also used as the CIB seven User ID.
   • CIB seven defaults the principal-claim.name value to preferred_username.

For additional information, check CIB seven webclient properties.

Securing legacy Camunda Webapp

In this section we provide an example configuration with OKTA as OIDC provider. Additionally, we also mark and explain a few lines:

camunda.bpm.oauth2:
 sso-logout: # 1
   enabled: true
   postLogoutRedirectUri: https://example.org/
 identity-provider:
   group-name-attribute: okta-groups # 2

spring.security: # 3
 oauth2:
   client:
     registration:
       okta:
         clientId: <clientId>
         clientSecret: <clientSecret>
         scope: openid,profile,email,offline_access # 4
     provider:
       okta:
         issuerUri: <issuerUri>
         user-name-attribute: preferred_username # 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 CIB seven 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 CIB seven User ID.

Disable Auto Configuration

If you wish to use Spring Security but without CIB seven’s integration classes, you can do so by excluding the auto configuration classes:

Either with the @EnableAutoConfiguration annotation:

@EnableAutoConfiguration(exclude={
    CamundaSpringSecurityOAuth2EngineAutoConfiguration.class,
    CamundaSpringSecurityOAuth2WebappAutoConfiguration.class,
    CamundaBpmSpringSecurityDisableAutoConfiguration.class
});

Or in the application properties:

spring:
  autoconfigure:
    exclude:
      - org.cibseven.bpm.spring.boot.starter.security.oauth2.CamundaSpringSecurityOAuth2EngineAutoConfiguration
      - org.cibseven.bpm.spring.boot.starter.security.oauth2.CamundaSpringSecurityOAuth2WebappAutoConfiguration
      - org.cibseven.bpm.spring.boot.starter.security.oauth2.CamundaBpmSpringSecurityDisableAutoConfiguration

For more information, please refer to Spring’s Disabling Specific Auto-configuration Classes documentation.