OpenID Connect is an industry standard authentication protocol well supported by Microsoft Entra ID. In this section, you set up an OIDC provider with Microsoft Entra ID for use with your WebSphere Liberty/Open Liberty app. In a later section, you configure the WebSphere Liberty/Open Liberty app by using OIDC to authenticate and authorize users in your Microsoft Entra tenant.
Create users in Microsoft Entra tenant
First, create two users in your Microsoft Entra tenant by following the steps in How to create, invite, and delete users. You just need the Create a new user section. Use the following directions as you go through the article, then return to this article after you create users in your Microsoft Entra tenant.
To create a user to serve as an "admin" in the app, use the following steps:
When you reach the Basics tab in the Create a new user section, use the following steps:
For User principal name, enter admin. Save the value so you can use it later when you sign in to the app.
For Mail nickname, select Derive from user principal name
For Display name, enter Admin.
For Password, select Auto-generate password. Copy and save the Password value to use later when you sign in to the app.
Select Account enabled.
Select Review + create > Create. Wait until the user is created.
Wait a minute or so and select Refresh. You should see the new user in the list.
To create a user to serve as a "user" in the app, repeat these steps, but use the following values:
For Supported account types, select Accounts in this organizational directory only (Default directory only - Single tenant).
When registration finishes, save the Application (client) ID and Directory (tenant) ID values to use later in the app configuration.
When you reach the Add a redirect URI section, skip the steps as for now. You add the redirect URI later when you run and test the sample app locally in this article.
When you reach the Add credentials section, select the Add a client secret tab.
When you add a client secret, write down the Client secret value to use later in the app configuration.
In the Add Assignment pane, for Users, select user Admin and for Select a role, select role Admin. Then, select Assign. Wait until the application assignment succeeds. You might need to scroll the table sideways to see the Role assigned column.
Repeat the previous steps to assign the User role to user User.
Select Refresh and you should see the users and roles assigned in the Users and groups pane.
You might need to adjust the width of the column headers to make your view look like the image.
Don't follow any other steps in Add app roles to your application and receive them in the token.
Protect a WebSphere Liberty/Open Liberty app by using OpenID Connect
In this section, you secure a WebSphere Liberty/Open Liberty app that authenticates and authorizes users in your Microsoft Entra tenant by using OIDC. You also learn how to give users access to certain parts of the app using role-based access control (RBAC). The app uses the Programmatic Security Policy Configuration of the Jakarta Servlet specification. Jakarta EE also supports RESTful web services. See the Next steps section for a reference to an article about securing a RESTful web services application.
The sample WebSphere Liberty/Open Liberty app for this quickstart is on GitHub in the liberty-entra-id repository.
Enable authentication and authorization to secure app
The app has a welcome page resource defined in index.html, which is shown in the following example code. This page is accessible to unauthenticated users. The root path of the welcome page is at /.
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Greeting</title>
</head>
<body>
<h1>Hello, welcome to Open Liberty/WebSphere Liberty and Microsoft Entra ID integration!</h1>
<h1>
<a href="/profile/user">Sign in as user</a>
</h1>
<h1>
<a href="/profile/admin">Sign in as admin</a>
</h1>
</body>
</html>
From the welcome page, users can sign in to the app to access the profile page. The welcome page has links to sign in as a user or as an admin. The links are at /profile/user and /profile/admin, respectively.
Both /profile/user and /profile/admin links point to the profile servlet, defined in ProfileServlet.java, as shown in the following example code. This servlet is accessible only to authenticated users by using the annotation jakarta.servlet.annotation.ServletSecurity and annotation jakarta.servlet.annotation.HttpConstraint. The attribute rolesAllowed = {"users"} specifies that only authenticated users with security role users can access the /profile path. The authenticated user is automatically assigned the users role in the Liberty configuration file server.xml.
The profile servlet retrieves the user's roles from the ID token and checks if the user has the admin role when the user tries to access the /profile/admin path. If the user doesn't have the admin role, the servlet returns a 403 Forbidden error. In other cases, the servlet retrieves the user's name and forwards the request to the profile page with the user's name and roles.
The profile page is defined in profile.jsp, as shown in the following example. This page displays the user's name and roles. The profile page also has a sign-out link at /logout. The profile page is written JSP (Jakarta Server Pages). Note the use of ${} expressions in the page. ${} Indicates the use of Jakarta Expression Language (EL). EL expressions are replaced with the values of the corresponding variables when the page is rendered. See the Next steps section for a reference to the EL specification.
When the user selects the link to sign out, the app calls the sign out servlet, defined in LogoutServlet.java, as shown in the following example code. The sign out servlet calls the request.logout() method to sign out the user, and then redirects the user to the welcome page.
These environment variables provide the values for the built-in support of OIDC in WebSphere Liberty/Open Liberty. The corresponding OIDC configuration in the Liberty server.xml is shown in the following example.
If the value of a variable isn't defined in the configuration file, WebSphere Liberty/Open Liberty reads the value from the environment variables following its naming convention. For details on the naming conversion, see Variable substitution precedence.
Run the WebSphere Liberty/Open Liberty app
You can run the app using liberty-maven-plugin. To run the app, select one of the following methods:
Note
To enable WebSphere Liberty/Open Liberty to connect to Microsoft Entra ID, be sure to run the command in the shell in which you defined the environment variables shown in the preceding section.
Run the app in development mode:
mvn liberty:dev
Run the app in runtime mode:
mvn liberty:run
If you want to try different modes, use Ctrl+C to stop the app and then run the app in another mode.
Test the WebSphere Liberty/Open Liberty app
After the app is running, open a web browser with a private tab and navigate to https://localhost:9443. Since the certificate is self-signed, you might see a warning about the certificate. You can safely ignore the warning and proceed to the site.
You should see the welcome page with links to sign in as a user or as an admin. Using a private tab avoids polluting any existing Microsoft Entra ID activity you might have in your regular browser.
Gather the credentials for the two users
In this article, Microsoft Entra ID uses the email address of each user as the user ID for signing in. Use the following steps to get the email address for the admin user and regular user:
If you have access to multiple tenants, use the Settings icon (
) in the top menu to switch to the tenant in which you want to register the application from the Directories + subscriptions menu.
Browse to Identity > Users > All Users.
Locate the admin user in the list and select it.
Locate the User principal name field.
Use the copy icon next to the value of the field to save the email address of the user to the clipboard. Save the value for later use.
To get the email address for the regular user, follow the same steps.
Use the passwords for the admin user and regular user that you set when creating the users.
Exercise the functionality of the app
Use the following steps to exercise the functionality:
Select the Sign in as user link. Sign in with the regular user you created earlier. After you sign in, Microsoft Entra ID redirects you to the profile page, where you see your name and roles.
If this is the first time signing in, you're prompted to update your password. Follow the instructions to update your password.
If you're prompted with Your organization requires additional security information. Follow the prompts to download and set up the Microsoft Authenticator app, you can select Ask later to continue the test.
If you're prompted with Permissions requested, review the permissions requested by the app. Select Accept to continue the test.
Select Sign out to sign out from the app. After you sign out, you're redirected to the welcome page.
Select the Sign in as admin link. Microsoft Entra ID redirects you to the sign-in page. Sign in with the admin user you created earlier. After you sign in, Microsoft Entra ID redirects you to the similar profile page, with a different role admin.
Sign out again and try to Sign in as admin with the regular user you created earlier. You should see an error message because the regular user doesn't have the admin role.
Clean up resources
This article doesn't direct you to deploy your app on Azure. There are no Azure resources to clean up for the app, although there are Microsoft Entra ID resources. To deploy an app on Azure, you can follow the guidance referenced in the next section.
When you finish with the resources for this sample app, use the following steps to clean up the Microsoft Entra ID resources. Removing unused Microsoft Entra ID resources is an important security best practice.
The act of removing the app registration should also delete the enterprise application. For more information about deleting enterprise applications, see Delete an enterprise application.
In this quickstart, you protect WebSphere Liberty/Open Liberty applications with Microsoft Entra ID using OIDC. To learn more, explore the following resources: