Documentation

Documentation

Azure AD Integration

How to use SSO Kit with Azure Active Directory (Microsoft Entra ID).

Azure Active Directory (now renamed to Microsoft Entra ID) is a commercial identification and access management solution. This tutorial shows how to restrict access to a Vaadin view by using SSO Kit together with Azure Active Directory.

This tutorial assumes you have a subscription with access to SSO Kit or a trial license, as well as an Azure account. It also assumes you already have a Vaadin application with SSO Kit. If not, see the Getting Started tutorial to learn how to configure your application for SSO Kit.

Access Azure Active Directory

You can access Azure AD through the Microsoft Azure Portal after registering. A default directory and an administrative user is included with your account.

New Application Registration

To create a new application registration, select Azure Active Directory from the Azure services list in the portal. You’re presented initially with the default directory overview that shows your details. Click the + sign next to Add. Choose App registration to register your Vaadin application in Azure AD.

Give the registration a name and choose a scope for the registration. You may choose among the following options:

  • Accounts in this organizational directory only;

  • Accounts in any organizational directory;

  • Accounts in any organizational directory and personal Microsoft accounts; and

  • Personal Microsoft accounts only.

The first option is for the default directory provided by Microsoft when creating an Azure account.

Select Web as the application type and click register to complete your registration.

Sign-In & Sign-Out URIs

To set the sign-in and sign-out URIs, open your App registration and select Authentication from the sidebar menu. Then enter the following URIs, where Azure redirects users when they sign in and out of the application:

Redirect URI

http://localhost:8080/login/oauth2/code/azure

Front-channel logout URI

https://login.microsoftonline.com/common/oauth2/v2.0/logout

Configure Application for Azure AD

Open the application.properties file located in your Vaadin project and add the client ID and issuer URI to the Spring Security configurations. The issuer URI in this example is https://login.microsoftonline.com/common/v2.0, where common is a general Tenant ID and v2.0 is the token type.

You can find your Tenant ID in the Properties menu in the Azure Active Directory dashboard.

Client Secret

You can use secret identifications to establish a secure connection with your Vaadin application. To create a secret, select your newly created App Registration and navigate to Certificates & secrets from the sidebar menu. Copy and paste the secret immediately to your Vaadin project as it can only be viewed once. Click New client secret and then Save to create a new secret ID. Copy and paste it to your applications.properties file, like so:

spring.security.oauth2.client.registration.azure.client-secret=Paste your Client secret here

Access Tokens

Add the URIs for your access tokens to your applications.properties file. You can find them in the Azure portal by selecting Endpoints from your App registration, like so:

security.oauth2.client.access-token-uri=https://login.microsoftonline.com/common/oauth2/v2.0/token
security.oauth2.client.user-authorization-uri=https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Configure the Manifest

Navigate to Manifest from the sidebar menu and replace "accessTokenAcceptedVersion": null, with "accessTokenAcceptedVersion": 2, and click Save. This allows you to use v2 access tokens in your application. The first lines of the manifest should then look something like this:

{
	"id": "934i9efugsf0s0poq+wdlwa9e0d8awfj",
	"acceptMappedClaims": null,
	"accessTokenAcceptedVersion": 2,
	"addIns": [],
}

Views protected by the @PermitAll annotation now redirect to Microsoft for login.

Create a Security Key

You need a security key if you want to use the HTTPS protocol on localhost. Use the keytool command in your application terminal to create a new Security Key. You would enter something like this:

keytool -genkeypair -alias testCert -keyalg RSA -storetype PKCS12 -keystore keystore.p12 -storepass password

You would, of course, adjust this for your password and other details. This results in the following properties:

Password: password
Alias: testCert
Type: PKCS12
Path: {your vaadin app root}/keystore.p12

Then add the key to your application.properties file. It should look something like this:

# SSO Kit configuration


vaadin.sso.login-route=/oauth2/authorization/azure
spring.security.oauth2.client.registration.azure.client-secret=Paste your Client secret here
spring.security.oauth2.client.registration.azure.client-id=Paste your Client ID here
spring.security.oauth2.client.registration.azure.scope=openid
spring.security.oauth2.client.provider.azure.issuer-uri=https://login.microsoftonline.com/common/
security.oauth2.client.access-token-uri=https://login.microsoftonline.com/common/oauth2/v2.0/token
security.oauth2.client.user-authorization-uri=https://login.microsoftonline.com/common/oauth2/v2.0/authorize


# Common settings
server.port=${PORT:8080}


# SSL configuration
server.ssl.key-store=/Users/mikael/Desktop/sso-kit-demo-app/keystore.p12
server.ssl.key-store-password=password
server.ssl.key-store-type=PKCS12
server.ssl.key-alias=testCert
server.ssl.key-password=password

Assign Permissions

Users need to provide consent for using the permissions set by the OpenID protocol. They can accept the permissions when signing into your application, or you may grant permission for users as an administrator for testing purposes.

Select API Permissions from the sidebar menu and choose Add a permission. Click Microsoft Graph from the menu and then Delegated permissions. You can then type openid to find it from the list of permissions. Tick the box next to openid and click Add permissions at the bottom of the menu.

Tip
Grant Consent to Users
If you want to grant consent for your users, you can click Grant admin consent for Default Directory in the API Permissions page.

Add New Users

In the Azure developer dashboard, select your directory and select Users from the sidebar menu. Click New user to start the user creation wizard and fill in the user details. Click Create to create the user.

Assign Users to Application

Navigate to Enterprise applications in your directory dashboard. Select your application from the list and select Users and groups from the sidebar menu. Add the user to the application by selecting Add user/group. Your administrator user account is added already by default.