Hey everyone, in recent Apicurio Registry versions we’ve introduced support for securing the application using different OpenID Connect (OIDC) servers, and not just Keycloak. In this blog post, I will explain how to configure the application to secure it using Microsoft Azure Active Directory (Azure AD).
Core Features
In this blog post, we will cover the following:
- Authentication based on Azure Active Directory - optionally protect Apicurio Registry so that the registry API and web console require users to authenticate (OAuth Authorization Code Flow supported)
Azure Active Directory Configuration
Authentication based on Azure AD
In order to secure Apicurio Registry you will need a valid directory in Azure and some specific configuration (described below). Essentially, you must register the Apicurio Registry application in the Azure portal. Log in to the Azure Portal. You can use your personal email address or your GitHub account to log in. After logging in, navigate to the Azure AD control panel by using the menu in the top-left corner. It should look like this:
Let’s dig into the Azure AD configuration for your Apicurio Registry deployment. Select Manage > App registrations in the menu on the left. Select New registration, and fill in the form. Enter apicurio-registry-example as the application name. We’ll also allow users from any organizational directory to log in.
Important: Register the host of the server hosting your Apicurio Registry application as a redirect URI. As part of the logon process, users will be redirected from our application to Azure AD for authentication. We want to send them back to our application afterwards. Azure AD will not allow any redirect URLs that are not registered. We’ll come back to this later.
Click Register. You should now be able to find the app registration by selecting Manage > App registrations in the menu on the left.
We can now find the parameters we need to set up Apicurio Registry with Azure AD OIDC. Click apicurio-registry-example to display its details:
Select Manage > Authentication to configure the application with the redirect URLs and token as follows:
To configure Apicurio Registry with Azure AD, you must configure the following environment variables in Apicurio Registry using the Azure AD Application ID and the Azure AD Directory ID, along with some Apicurio Registry-specific configuration:
REGISTRY_AUTH_ENABLED=true
KEYCLOAK_API_CLIENT_ID=459569e9-c5f7-410a-a6e7-8db28d7e3647 #Azure AD > Admin > App registrations > Your app > Application (client) ID
REGISTRY_UI_AUTH_TYPE=oidc
REGISTRY_AUTH_URL_CONFIGURED=https://login.microsoftonline.com/6f8ef45b-456d-49e3-b5ba-1f6fe4c0fb78/v2.0 #Azure AD > Admin > App registrations > Your app > Directory (tenant) ID
REGISTRY_OIDC_UI_CLIENT_ID=459569e9-c5f7-410a-a6e7-8db28d7e3647 #Azure AD > Admin > App registrations > Your app > Application (client) ID
CORS_ALLOWED_ORIGINS=https://test-registry.com #The host for your Apicurio Registry deployment
REGISTRY_OIDC_UI_REDIRECT_URL=https://test-registry.com/ui/ #The host for your Apicurio Registry console
ROLE_BASED_AUTHZ_ENABLED=true
QUARKUS_OIDC_ROLES_ROLE_CLAIM_PATH=roles
Role based authorization
To enable roles, you must set the ROLE_BASED_AUTHZ_ENABLED property to true.
Of course, if you enable roles in Apicurio Registry, you must also create them in Azure AD.
You must create them as Application roles. The default roles expected by Apicurio Registry are sr-admin, sr-developer, and sr-readonly.
Another extremely important configuration is QUARKUS_OIDC_ROLES_ROLE_CLAIM_PATH=true because Azure AD stores the roles in a claim called roles.
Last, but not least, we still have a lot of things to do! As always, you can see the stuff we’re tracking by viewing the GitHub issues for the project.
If you find bugs or want to request a new feature, that’s a great place to start!