Docs

Docs

Identity Management

Manage users, groups, and roles in your deployed applications.

Control Center provides powerful tools to manage users, groups, roles, and identity providers for Vaadin applications deployed in a Kubernetes cluster. These features are essential for controlling access to various parts of an application and providing secure authentication and authorization for users.

With Control Center, you can do several things that allow you to centralize user management, enforce security policies, and control access across different parts of a Vaadin application:

  • Manage Users: Create and manage user accounts, enable or disable them, request password changes, or enable Multi-Factor Authentication (MFA).

  • Create & Assign Groups: Organize user accounts into groups, assign specific roles to the groups, and streamline permissions management.

  • Manage Roles: Define roles that can be used to control access to specific views or functionality in an application.

  • Manage Identity Providers: Create identity providers (e.g., a social provider), to manage the authentication of users.

Before starting, make sure you’ve already deployed an application as described in Application Deployment.

Creating a New User

To create a new user account, first select the relevant application from the Application Selector, as shown in the screenshot here. It’ll display the application’s dashboard.

Application Selector

The dashboard provides an overview of the current user base for the selected application.

Application Dashboard

Navigate to the Identity Management section and select Users. Then, click the Create button to open the user creation form.

Create User Form

Once you’re in the user creation form, fill in the required fields:

  • First Name & Last Name: The user’s display name.

  • Email Address: This is used for the user’s login.

  • Password: Set an initial password for the user. You can also enable the Request password change option to force the user to change this password at the next login.

  • Multi-Factor Authentication: Enable MFA to require the user to verify their identity with an additional factor, such as an authenticator application.

Once all of the information has been entered, click Create to finalize the process. The new user account should appear in the list of users for the application.

Creating a New Role

Next, you may want to define specific roles to make controlling access easier within your application. Roles can be used to limit access for a set of users to certain views or features.

In the Identity Management section, navigate to Roles and click the Create button to open the role creation form.

Create Role Form

Fill in the fields in the role creation form:

  • Name: The name of the role (e.g., ADMIN).

  • Description: A brief description of what this role entails (e.g., "Role for administrators.").

Click Create to save the new role. This role can now be assigned to users or to groups to control access.

Creating a Group & Assigning a Role

To manage the permissions efficiently, you can organize users into groups and assign roles to these groups. This saves you the time of having to assign the same privileges to each person. For instance, you might have all sales people in a group called, sales and all managers in another group called, managers. And if you have a few users who are sales managers, you can assign them to both groups.

To create a group, in the Identity Management section, navigate to Groups and click the Create button.

Create Group Form

Fill in the fields to create a new group:

  • Name: Enter the name of the group (e.g., Administrators).

  • Roles: Select the roles for the group (e.g., ADMIN).

  • Members: Add users to the group by selecting them from the list of users.

Once the group is created, the assigned users inherit the permissions associated with the roles assigned to the group.

Creating Identity Providers

An identity provider represents an external service, which can be used to authenticate access to Control Center, or a deployed application. This can be a social provider or a custom provider. The supported social providers are GitHub, Google, LinkedIn, Microsoft, and X (formerly Twitter). A custom provider can be any that implements the OpenID Connect 1.0 protocol (e.g., Okta).

When creating an identity provider, you need to choose the type of the provider you want to create from the list presented. Afterwards, in the case of social providers, you need to specify the Alias, Display Name, Client ID, and Client Secret. If you’ve already registered a client with an external identity provider, you only need to provide its ID and secret. If not, you can follow the link under the provider list, which takes you to the provider’s page where you can create a new client.

When everything is filled in, you can copy the Login Redirect URI or the Logout Redirect URI, and use them in your external provider’s client to tell it where to redirect the user after a successful authentication or logout, respectively. At the end, click on the Create button. As an example, creating a Google identity provider looks like this:

Create Identity Provider Form

After creating an identity provider, you can find it in the Identity Providers list. You can select one to check its details, update some of the fields, or to delete it:

Identity Provider Detail Form

When you want to create a custom OpenID Connect 1.0 provider, you’ll also need to specify the Discovery Endpoint. This is used during the provider creation to get relevant metadata from the external provider. The endpoint URL has a specific format: It always ends with the .well-known/openid-configuration path. (e.g., https://1234-admin.okta.com/.well-known/openid-configuration). Usually, you can find the discovery endpoint in the client details after you create it with the external provider. As an example, creating an Okta provider looks like this:

Create Custom Identity Provider Form

After creating providers, you can see them on the login form. If you want to remove any of the providers, you can disable or delete them in the provider settings. This login form shows the previously created identity providers:

Identity Provider Login Form

When you click on one of the providers, it redirects you to the external provider’s login page where you’ll need to specify your external username and password:

Custom Identity Provider Login

After a successful authentication, if a user with the same email already exists in Control Center, you can link that user with one or more identities from identity providers, or create a new user based on the identity information from them:

Link User Profile Form

If you click on the Review Profile button, you can edit the identity information before linking it to a user in Control Center:

Review User Profile Form

After successfully linking a user and an external identity, you need to confirm this link by logging in with your user:

Confirm User Profile Form

The authentication process behind these steps is the following:

  • The unauthenticated user requests a protected view in an application.

  • The application then redirects the user to Control Center to authenticate, where it displays the login page with a list of configured identity providers.

  • Here the user selects one of the identity providers by clicking its respective button.

  • Control Center then issues an authentication request to the target identity provider, asking for authentication and redirects the user to the identity provider’s login page.

  • Next, the user provides credentials or consents to authenticate with the identity provider.

  • Upon successful authentication by the identity provider, the user is redirected back to Control Center with an authentication response.

  • Control Center checks if the response from the identity provider is valid. If it is, one of two things happen: If the user already exists, Control Center asks the user to link the accounts (i.e., link the identity returned from the identity provider with the existing user). If the user doesn’t exist, Control Center imports and creates a user.

After the user has completed this authentication process, Control Center permits access to the protected view.

Login & Logout Controls

To create login and logout links or buttons in your Vaadin application, refer to the guide on Creating Login and Logout Controls.