In OAuth 2.0 Login mode, LuciadFusion acts as an OAuth 2.0 client using the Authorization Code flow. When a user opens the LuciadFusion Studio web application, the server redirects the browser to the external identity provider’s login page. After successful authentication, the identity provider redirects back to LuciadFusion, which establishes a server-side session for the user.

For an explanation of how this mode compares to OAuth 2.0 Resource Server, see OAuth 2.0 authentication in LuciadFusion.

Prerequisites

The prerequisites below describe what LuciadFusion requires from your identity provider. For general client setup such as enabling the Authorization Code flow or assigning roles to users, refer to your identity provider’s documentation.

Configure OAuth 2.0 Login

Set the authentication type

In the LuciadFusion configuration file, set fusion.security.authenticationTypes to oauth2Login: 

fusion.security:
  authenticationTypes:
    - oauth2Login

When using OAuth 2.0 authentication, leave the fusion.security.authenticationManager property empty.

oauth2Login must be the only entry in fusion.security.authenticationTypes. It can’t be combined with other authentication types.

For more information about the LuciadFusion configuration file, see Configuring LuciadFusion Studio.

Configure LuciadFusion as an OAuth 2.0 client

To perform the Authorization Code flow, LuciadFusion needs to know how to reach your identity provider and how to identify itself to it. You provide this information by setting standard Spring Boot OAuth 2.0 Client properties in the LuciadFusion configuration file. Refer to Spring Security OAuth 2.0 Login for the full list of available properties and customization beans.

Example: Keycloak 

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: <your-client-id>
            client-secret: <your-client-secret>
            scope: openid, profile, email
            authorization-grant-type: authorization_code
        provider:
          keycloak:
            issuer-uri: https://<keycloak-host>/realms/<your-realm>

fusion:
  security:
    oauth2:
      registration-id: keycloak

fusion.security.oauth2.registration-id is the id of the OAuth 2.0 client registration that is used for the OAuth 2.0 Login. It is required, and must match one of the registration ids configured above it.

Configure the username

By default, the sub claim is used as the username, which is often an opaque UUID rather than a human-readable name. If you want to use a different claim instead, such as the preferred_username claim in Keycloak, set the user-name-attribute property on the OAuth 2.0 client provider configuration. Check your IdP’s documentation for the correct claim name in your setup. 

spring:
  security:
    oauth2:
      client:
        provider:
          keycloak:
            user-name-attribute: preferred_username

Role mapping

LuciadFusion supports role-based access control. If you use this, provide a custom GrantedAuthoritiesMapper bean to map identity provider roles to LuciadFusion roles. See the Using a GrantedAuthoritiesMapper for more details.

This example handles Keycloak, which places realm roles under the realm_access.roles claim. We also assume the Keycloak server has been configured to add these roles to the UserInfo response. Check your IdP’s documentation for the correct configuration. 

@Configuration
public class OAuth2LoginConfiguration {

  @Bean
  public GrantedAuthoritiesMapper authoritiesMapper() {
    return authorities -> {
      Set<GrantedAuthority> mappedAuthorities = new HashSet<>();
      for (GrantedAuthority authority : authorities) {
        if (!(authority instanceof OidcUserAuthority oidcAuthority)) {
          continue;
        }
        Map<String, Object> realmAccess = oidcAuthority.getUserInfo().getClaim("realm_access");
        if (realmAccess != null) {
          List<String> roles = (List<String>) realmAccess.get("roles");
          if (roles != null) {
            for (String role : roles) {
              mappedAuthorities.add(new SimpleGrantedAuthority("ROLE_" + role));
            }
          }
        }
      }
      return mappedAuthorities;
    };
  }
}

To make LuciadFusion pick up this configuration, add its package to the scan path:

fusion.config.additionalScanPackages: <your.package>