Documentation

Documentation versions (currently viewingVaadin 23)
New Acceleration Kits: Observability Kit, SSO Kit, and Swing Kit. Read the blog post.

Getting Started with SSO Kit

Step-by-step guide showing how to use SSO Kit in your application.

SSO Kit builds upon Spring Security. It comes with a starter module that configures the security settings needed to authenticate with your identity provider.

1. Add the SSO Kit Dependency

To get started, you need to add SSO Kit as a dependency to your application. For example, to add to your Maven project, do something like this:

<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>sso-kit-starter</artifactId>
</dependency>

Next, you need to set some configuration properties to connect SSO Kit to your OpenID Connect provider. These properties can be added to your application.properties file where you define the provider URL and the client registration details, such as credentials and scope.

Provider definition is configured within the spring.security.oauth2.provider namespace where you define a key to identify your provider, such as keycloak. Then you can use the same key to register the client for that provider within the spring.security.oauth2.registration namespace, where you specify client credentials and the requested scope. The scope is a list of keywords to request the provider for a specific set of information, such as user profile, email or roles. The following is an example of the properties to set to enable a Keycloak instance to perform authentication:

spring.security.oauth2.client.provider.keycloak.issuer-uri=https://my-keycloak.io/realms/my-realm
spring.security.oauth2.client.registration.keycloak.client-id= my-client
spring.security.oauth2.client.registration.keycloak.client-secret=very-secret-value
spring.security.oauth2.client.registration.keycloak.scope=profile,openid,email,roles

Once you have at least one client configured, you’re ready to secure your views.

2. Securing Views

The default configuration redirects requests to any view, to the provider’s login page. You can set which views require authentication, annotating them as described in Securing Spring Boot Applications: Annotating the View Classes. The following is an example how you might do this:

@PermitAll
@Route(value = "private")
public class ProfileView extends VerticalLayout {
    // ...
}

3. Single Sign-On

SSO Kit provides the SingleSignOnConfiguration auto-configuration class to setup Vaadin and Spring to allow single sign-on with external identity providers.

Note
Customized security configuration
If you need a customized security configuration, you can disable this auto-configuration class by setting the vaadin.sso.auto-configure property to false and define your own configuration class.

The following configuration enables login for the identity providers defined in the application configuration. It instructs the application to accept requests for the login route. It can be configured by setting the vaadin.sso.login-route property, which defaults to /login. If there is no view defined for this route, Spring auto-generates a page with links to each of the configured providers login forms. If you want to redirect automatically the users to the provider login form, you can set this property to /oauth2/authorization/{provider-key} where {provider-key} is the key used to configure the provider in application.properties file.

vaadin.sso.login-route=/oauth2/authorization/keycloak
Tip
Custom Login Page
Some providers support a custom theme for their login pages. Find out more in Theming.

4. Authentication Context

Upon successful authentication, the provider redirects the user back to the protected view. To access the authenticated user’s information (such as name, email and roles), SSO Kit provides the AuthenticationContext bean that can be used as a view constructor argument. Then you can get the authenticated user with getAuthenticatedUser(). It returns an Optional object containing the user instance if the session has an authenticated user or empty otherwise.

public class ProfileView extends VerticalLayout {
    public ProfileView(AuthenticationContext authContext) {
        authContext.getAuthenticatedUser().ifPresent(user -> {
            Avatar userAvatar = new Avatar(user.getFullName());
            add(userAvatar);
        });
    }
    // ...
}

By default, the user object returned by getAuthenticatedUser() is an instance of OidcUser. If your application defines a custom user service to provide a specialized implementation of OidcUser, you can use the getAuthenticatedUser(Class<U> userType), where userType is your own type that implements OidcUser.

5. Single Sign-Off

SSO Kit provides two methods for logging out the user, defined by the OpenID Connect specification:

5.1. RP-Initiated Logout

RP-Initiated Logout (i.e., Relaying Party, the application) enables the user to logout from the application itself, ensuring the connected provider session is terminated. The AuthenticationContext bean provides the logout() method to initiate the logout process programmatically. For example, inside a button click-listener:

@PermitAll
@Route(value = "private")
public class ProfileView extends VerticalLayout {
    public ProfileView(AuthenticationContext authContext) {
        add(new Button("Logout", e -> authContext.logout()));
    }
    // ...
}

After a successful logout, the user is redirected to the configured logout redirect route. That can be set with the vaadin.sso.logout-redirect-route property:

vaadin.sso.logout-redirect-route=/logout-successful

The default value of this property is the application root.

5.2. Back-Channel Logout

Back-Channel Logout is a feature that enables the provider to close user sessions from outside the application. For example, it can be done from the provider’s user dashboard or from another application. To enable the feature, you need to set the vaadin.sso.back-channel property to true:

vaadin.sso.back-channel-logout=true

Then, the client should be configured on the provider’s dashboard to send logout requests to a specific application URL: /logout/back-channel/{registration-key}, where {registration-key} is the provider key.