Multi-Factor Authentication - Inero Software - Software Consulting

Secure Email Delivery in Keycloak 26.2 Using XOAUTH2

Andrzej Chybicki — Mon, 15 Sep 2025 10:48:22 +0000

Secure Email Delivery in Keycloak 26.2 Using XOAUTH2

Email has been one of the oldest and most fundamental services on the internet, used for notifications, password resets, verifications, and more. Over time we’ve seen major improvements — encryption via TLS, then STARTTLS, and now many providers are moving away from basic password authentication in favor of modern token-based schemes like XOAUTH2. With Keycloak 26.2, this evolution has arrived: Keycloak now supports XOAUTH2 for outgoing SMTP mail, adding greater security and compatibility with providers who have deprecated legacy authentication

1. What is XOAUTH2, and Why It Matters

XOAUTH2 is a means of authenticating to an SMTP (or other email-sending) server using an OAuth2 access token rather than a username + password. Some of the key benefits include:

- Improved Security: Tokens can be more tightly controlled, with limited scope and lifetime.
- Compliance with Modern Providers: Many providers are disabling basic auth.
- Centralised and Auditable Auth: Easier management and rotation. Each client’s access can be revoked independently of other clients’ operations.
- Reduced Risk of Credential Leakage: No raw passwords stored or transmitted.

2. How XOAUTH2 is Implemented in Keycloak 26.2

With version 26.2, Keycloak adds native support for XOAUTH2 when sending emails via SMTP. This means administrators can move away from static username and password credentials and instead configure Keycloak to obtain an OAuth2 access token at runtime.

In the Admin Console under Realm → Realm Settings → Email, you can now switch the Authentication Type from Password to Token (XOAUTH2). Once enabled, additional fields appear where you provide:

– Client ID and Client Secret from your identity provider (e.g., Azure AD).
– The OAuth2 Token Endpoint used to request an access token.
– Optional Scopes, depending on your provider (for Microsoft 365: https://outlook.office365.com/.default).
– A From address / SMTP username, which may still be required by the mail server.

Keycloak then handles the process of requesting and refreshing tokens using the Client Credentials Grant flow. You can use the “Test connection” button to verify that the configuration is correct and that emails can be sent successfully.

This approach aligns Keycloak with modern security standards and prepares deployments for providers that are phasing out legacy authentication.

Note: The Enable Debug SMTP option (visible at the bottom of the form) activates extended logging for outgoing email. When enabled, Keycloak produces detailed debug output of the SMTP communication, which can be very useful for diagnosing integration issues such as authentication failures, token retrieval problems, or TLS misconfigurations. It is recommended to use this setting only in testing or troubleshooting scenarios, as it may expose sensitive information in the logs.

Retirement of Basic Authentication for SMTP AUTH (Client Submission) in Exchange Online

Days

Hours

3. Why This Matters for Microsoft Azure / Office 365 Users

Microsoft has announced the retirement of Basic Authentication for SMTP AUTH (Client Submission) in Exchange Online. Starting March 1, 2026, Microsoft will begin phasing out Basic Auth, and by April 30, 2026, it will be completely disabled. This change directly impacts Keycloak deployments where outgoing emails are sent via Office 365 / Exchange Online SMTP.

If your Keycloak instance is still configured with a username and password for SMTP, it will stop working once Basic Auth is retired. The solution is to migrate to XOAUTH2 configuration in Keycloak 26.2.

By adopting XOAUTH2, you ensure:

- Continued compatibility with Microsoft email services
- Stronger security and compliance
- Reduced risk compared to static credentials

4. Beyond XOAUTH2?

There’s even more going on in modern email delivery. Many email delivery platforms steer away from traditional SMTP protocol towards API-based approach (e.g. MailJet, SendGrid or MailGun). This gives more flexibility to integrators and allows platform providers to offer additional features. API-based email sending is not jet supported by Keycloak out-of-the-box, but this support can be added via custom extensions. Contact us if you are interested in integrating Keycloak with API-based email delivery platforms.

Conclusion

The addition of XOAUTH2 support in Keycloak 26.2 is more than just a feature upgrade — it’s an essential step for organizations that rely on Office 365, Gmail, or other providers who are deprecating legacy authentication. By adopting XOAUTH2 today, you can future-proof your Keycloak deployment, comply with provider requirements, and improve overall email security.

Artykuł Secure Email Delivery in Keycloak 26.2 Using XOAUTH2 pochodzi z serwisu Inero Software - Software Consulting.

Setting Up Passwordless Login with Passkey on a Mobile Device

Marceli Formela — Wed, 12 Mar 2025 07:47:03 +0000

In our previous post, we demonstrated how to configure Passkeys in Keycloak, replacing traditional passwords with WebAuthn-based authentication. We covered the setup process, key advantages, and potential limitations, including the challenge of user adoption. This blog focuses on configuring Passkeys specifically for mobile devices, ensuring a seamless and secure passwordless experience.

Our first publication about Passkeys in Keycloak, you can find here: An introduction to Passkey with Keycloak

In this post, we’ll dive deeper into optimizing Passkey authentication in Keycloak, looking into a different approach, this time using more than one device.

Using a Passkey stored on a phone

When logging in on a different device, such as a laptop or desktop, users can authenticate using a Passkey stored on their phone. The process works as follows:

Selecting Passkey Login
Instead of entering a password, users choose the Passkey authentication option. The laptop’s browser generates a request for authentication. Now we have to establish a secure connection between your phone (e.g., iPhone) and your laptop.
Scanning a QR Code
The login interface generates a QR code, which users scan using their phone’s camera. Then the laptop sends a cryptographic challenge to the phone, asking it to sign a request using the stored passkey. The phone communicates securely with the laptop over Bluetooth or other close-range communication protocols (like NFC).
Confirming Identity
Once the phone receives the challenge, it asks the user for biometric authentication (e.g., Face ID or Touch ID). This verifies that the person attempting the login is the authorized user.
Secure Authentication
The laptop checks the response from the phone, verifying the cryptographic signature against the public key registered with the service. If the verification is successful, the user is logged in without having to enter a password.

Step by step: Configuring Passkey with a smartphone

Before we dive into our custom authentication flow, it’s important to check if the Webauthn Register Passwordless required action is enabled in the realm (Authentication -> Required actions tab).

This gives us, for example, the ability to enforce passkey configuration from users after their next successful login. However, it’s important to remember that this is just one of many ways to configure multiple authentication methods.

Once we confirm that this option is active, we can proceed with configuring the authentication flow.

This custom authentication flow for Keycloak is designed to demonstrate how users can choose between password-based authentication and passkey authentication (WebAuthn) during login. Here’s how it works:

- Users are required to provide their username to proceed with authentication.
- This step enforces authentication, but users can choose between password-based login or passkey-based login.
- If the user opts for password authentication, they enter their credentials here.
- If the user prefers passwordless authentication using passkeys, they can authenticate using this method instead.

In this step, users can enter their username or email to proceed with authentication. This is a required step, ensuring that the system identifies the user before offering authentication options.

At this stage, we can only use password authentication because we haven’t configured our Passkey (WebAuthn) yet. Once Passkey is set up, users will have the option to choose between password-based and passwordless authentication.

Instead of registering a device PIN as mentioned earlier, we will use authentication via a phone, specifically an iPhone, in this example

Now, a QR code should appear, allowing us to register a Passkey on our account. Let’s scan it using our phone’s camera and verify the operation, for example, using Face ID.

Now, our Passkey should be visible in the Credentials section.

During the next login, we should see the option to choose between password authentication and Passkey authentication.

This setup enhances user convenience by allowing them to pick their preferred authentication method. Passkeys provide a more secure and phishing-resistant login experience, while passwords remain available for users who prefer traditional authentication. With this flexibility, we can ensure both security and ease of access for different user preferences.

It is worth remembering that traditional passwords are a weak link in digital security, often compromised through reuse, phishing, or data breaches. Passkeys offer a modern, passwordless authentication method that enhances security and usability by leveraging cryptographic key pairs managed by platform authenticators. They provide phishing resistance, seamless multi-device access, and compliance with multi-factor authentication (MFA) standards.

Best Practices in Keycloak: Secure Your System in 5 Steps

Artykuł Setting Up Passwordless Login with Passkey on a Mobile Device pochodzi z serwisu Inero Software - Software Consulting.

Behind the Scenes #2: Implementing email-based MFA in Keycloak

Marceli Formela — Thu, 13 Feb 2025 09:50:32 +0000

Keycloak natively supports many secure login solutions and comes with built-in one-time password (OTP) mechanisms, such as authentication via mobile apps like Google Authenticator or our solution AuthM8. However, if we want to use other advanced authentication methods and for example send OTP codes via email, then similar to SMS multi factor authentication (more details HERE), we need to implement this functionality ourselves. In this post, we’ll explore a custom MFA implementation that sends a one-time authentication code to the user’s email.

How does email-based MFA work?

The authentication process consists of two main stages:

- Generating and sending the MFA code

If the user already has an active cookie confirming a previous MFA verification, they should be immediately authenticated. Otherwise, Keycloak creates a new credential for the user and generates a one-time code based on configurable parameters like length or time-to-live. The code is stored in the user’s credentials and then is emailed using the email provider.

- Verifying the entered code

When a user submits the code, KC retrieves the stored credential and compares the entered value. If the code is correct and still valid (not expired), authentication is successful, and a cookie is set to remember the verification. If the code is incorrect, the user is prompted to re-enter it and if the code has expired, an error message is shown and the process must be restarted.

Email MFA: Pros and Cons

Email-based MFA offers additional security when the primary factor, such as a password, has been compromised. This is particularly helpful in cases where passwords are brute-forced or easily guessed, such as with common combinations like 123456. Similarly, this solution offers protection against credential stuffing, where attackers use leaked passwords from other breaches to attempt logging into account.

There are several other benefits to using email as a MFA:

- Email MFA does not require users to provide additional sensitive information, such as a phone number, reducing concerns about privacy.

- It does not require users to install a separate app or complete a complicated setup, which simplifies the process.

- Users are accustomed to providing their email for various purposes, such as receiving important account updates or resetting passwords. This familiarity makes it more accessible.

However, email as a delivery channel does have some drawbacks. If an attacker compromises your email (gains access to an email account through stolen credentials or by exploiting an active session.), they could potentially reset other accounts’ passwords as well. For users in vulnerable situations, such as those with access to shared devices, email-based MFA can still leave them exposed. As with any security measure, it’s essential to weigh the benefits against the potential risks and mix email MFA with other safeguards, such as strong passwords policy and secure email practices.

Implementing Email MFA

In this modified Browser Authentication Flow, we integrate our custom MFA as an additional authentication method. There are two new steps:

- MFA Email setup – this step ensures that email is set up and verified for the user before proceeding. If the user does not have a custom MFA Credential (which stores OTP codes as secrets), it will be set as well.

public class MfaEmailSetupAuthenticator implements Authenticator, CredentialValidator {
@Override
public void authenticate(AuthenticationFlowContext context) {
[…]
// Require email verification
if (!userModel.isEmailVerified()) {
userModel.addRequiredAction(UserModel.RequiredAction.VERIFY_EMAIL);
}
// Add MFA email credential if not present
if (!getCredentialProvider(context.getSession()).isConfiguredFor(realmModel, userModel, MfaEmailCredentialModel.TYPE)) {
userModel.credentialManager().createStoredCredential(new MfaEmailCredentialModel(new MfaEmailCredentialData()));
}
[…]

- MFA Email Authentication – this is the actual authentication step where a one-time code is sent via email. Marked as Alternative, meaning it can be used instead of other MFA methods like mobile app OTP.

Here, you can see how the configuration of this authenticator could look like in the Keycloak authentication flow.

- Max Cookie Age this setting determines how long the MFA session (cookie) is valid. If the cookie is still valid, the user won’t be prompted for MFA.
- Time-to-live indicates the lifetime of the MFA code.

Now let’s take a look at the code.

The method below handles the MFA process itself. If a valid cookie exists (indicating that the user has already completed MFA), the method immediately returns success, meaning the authentication flow is complete without requiring additional actions.

@Override
public void authenticate(AuthenticationFlowContext context) {
if (hasValidCookie(context)) {
context.success();
return;
}
[…]

If there is no cookie, we should try to retrieve the user’s existing MFA credential from the credential provider. If the user doesn’t have one, a new instance is created using the MfaEmailCredentialModel which just extends the built-in CredentialModel:

[…]
// get existing credential or create a new one
CredentialModel credentialModel = getCredentialProvider(session)
.getDefaultCredential(session, context.getRealm(), user);
if (credentialModel == null) {
credentialModel = user.credentialManager().createStoredCredential(new MfaEmailCredentialModel(new MfaEmailCredentialData()));
}
[…]

Then the authenticate method reads configuration properties like code length and TTL (time-to-live). The code itself can be generated using some utils method and will be stored as the secretData in the credential model.

// generate and store code
int length = Integer.parseInt(configMap.get(CONFIG_CODE_LENGTH));
int ttl = Integer.parseInt(configMap.get(CONFIG_CODE_TTL));
String code = MfaEmailCodesUtils.generateCode(length);
credentialModel.setSecretData(code);
user.credentialManager().updateStoredCredential(credentialModel);
AuthenticationSessionModel authSession = context.getAuthenticationSession();
authSession.setAuthNote("ttl", Long.toString(System.currentTimeMillis() + (ttl * 1000L)));

In the end the sendCode method is called to send the generated code to the user’s email. If the email is sent successfully, the method presents the form where the user can enter the MFA code.

// send email and show input form
try {
MfaEmailCodesUtils.sendCode(session, user, ttl, code, configMap);
context.challenge(context.form().setAttribute("realm", context.getRealm()).createForm(TPL_CODE));
} catch (Exception e) {
context.failureChallenge(AuthenticationFlowError.INTERNAL_ERROR,
context.form().setError("mfaEmailNotSent", e.getMessage())  .createErrorPage(Response.Status.INTERNAL_SERVER_ERROR));
}

The second major part of our Authenticator is the action method which handles the validation of the code entered by the user. It is invoked when the user submits the input form after receiving the email.

The method retrieves the user’s credential from the provider and then the code is validated by checking it against the stored credential using the custom isValid method.

[…]
final MfaEmailCredentialModel credentialModel = getCredentialProvider(session)
        .getDefaultCredential(session, context.getRealm(), user);
boolean isValid = getCredentialProvider(session).isValid(context.getRealm(), user,
     new UserCredentialModel(credentialModel.getId(), getCredentialProvider(context.getSession()).getType(), enteredCode));
[…]

If the code is valid, the next step is to check if it is expired. We can also set a cookie that stores the MFA session to prevent the user from being prompted for MFA again during the cookie’s validity period.

[…]
// valid
HttpResponse response = context.getSession().getContext().getHttpResponse();
response.setCookieIfAbsent(createCookie(context));
context.success();
[…]

Of course, in this post, we will not cover the entire topic, omitting implementation details such as sending the code, generating the code, validation, and creating our custom cookie.

However, we have walked through the major steps of implementing 2FA using email-based codes. On the one hand, this approach offers a simple and accessible solution. Although it has its drawbacks, using it in solutions like Keycloak helps mitigate many of these vulnerabilities. Keycloak also provides the flexibility to combine email-based MFA with other security measures, creating a more layered and resilient authentication process that can help protect against evolving cybersecurity threats.

Do you need help configuring multi-factor authentication?

Schedule a meeting to find out how we can help you.

Schedule a meeting

Artykuł Behind the Scenes #2: Implementing email-based MFA in Keycloak pochodzi z serwisu Inero Software - Software Consulting.

Security Information and Event Management Systems: Why Is It Worth Adding Keycloak?

Marta Kuprasz — Thu, 06 Feb 2025 10:15:42 +0000

Security Information and Event Management (SIEM) systems enable the collection and analysis of data on user activity, system access, and cybersecurity events to detect threats and respond to incidents in real time. Identity and Access Management (IAM) systems, in turn, provide insights into user activity. In this blog, you’ll learn how Keycloak can support your SIEM system.

In the Report on the State of Cybersecurity in Poland for 2023 prepared by CSIRT GOV, it was indicated that among the threats persisting in the Polish cyberspace in 2023, which had a significant impact on risk assessment, social engineering attacks and brute-force attacks were particularly notable. Social engineering attacks involve manipulating users to gain unauthorized access to systems, while brute-force attacks rely on automatically attempting various password combinations to break security measures.

Proper identity management and log monitoring are key elements in protecting against such attacks. This is why integrating Keycloak with a SIEM system allows organizations to detect threats more effectively and respond to them immediately.

Why Is It Worth Integrating SIEM with Keycloak?

Every organization using a SIEM system aims to detect as many threats as possible and respond to incidents as quickly as possible. Information about who attempted to access systems, from where, and when can be crucial in identifying attacks and unauthorized login attempts. This is where Keycloak—a popular open-source IAM platform—can significantly enhance the SIEM ecosystem by providing valuable data on authentication, authorization, and session management processes.

Keycloak, developed by the Red Hat community, offers comprehensive solutions for authenticating and authorizing users in web applications, mobile apps, and backend services. We’ve covered it in detail https://inero-software.com/keycloak-services/

Keycloak can provide data on:

Login attempts – both successful and failed, along with information about the originating IP address.
Forced password resets and changes in access policies – allowing for monitoring of potential account takeover attempts.
User sessions – including unusual logins from new locations or devices.
Detected threats, such as suspicious multiple login attempts (e.g., brute-force attacks, which involve cracking passwords or cryptographic keys by trying all possible combinations).

The SIEM system, in turn, can analyze this data and correlate it with other events, such as:

Login attempts from unusual locations linked to suspicious network activity.
Multiple failed login attempts from a single IP address – a sign of a brute-force attack.
Sudden changes in user privileges associated with suspicious system access.

An example of effective integration can be seen in a situation where a user repeatedly enters an incorrect password within a short period. Keycloak logs this as suspicious activity. A SIEM system can then correlate this data with login attempts from different locations and take action, such as temporarily blocking the account or enforcing additional authentication.

How Do Keycloak and SIEM Work Together?

Keycloak and Security Information and Event Management (SIEM) systems serve different purposes in identity management and IT security, but they complement each other perfectly.

Feature	SIEM (Security Information and Event Management)	IAM (Identity and Access Management – Keycloak)
Main Function	Monitoring and analyzing security events	Managing user identities and access
Scope of Operation	Log collection, incident analysis, threat detection	Authentication, authorization, access control
Types of Data	System logs, network traffic, security alerts	User sessions, authentication logs, authorization requests
Mode of Operation	Aggregation and correlation of events from multiple sources	Verification of user identities and permissions
Primary Uses	Anomaly detection, incident response, compliance	Single Sign-On (SSO), identity federation, MFA
Examples of Threats	DDoS attacks, malware, privilege escalation	Brute-force attacks, account takeover, privilege misuse
Response to Threats	Alert generation, automatic blocking, reporting	Account blocking, enforcing MFA, session management
Integration with Other Systems	Yes – collects logs from SIEM systems, IDS, firewalls	Yes – integrates with LDAP, AD, databases, SIEM

How to Implement Keycloak?

Integrating Keycloak with a SIEM system enhances IT security by providing additional information about users and their activities. This allows organizations to detect threats more effectively and respond to incidents more quickly.

If you’re wondering how to implement and configure Keycloak for your organization, be sure to check out these articles:

These resources provide practical guidance on configuring and integrating Keycloak with various systems. Importantly, one of Keycloak’s key features is its ability to integrate with Lightweight Directory Access Protocol (LDAP) directories, which we covered in detail here: Exporting accounts to federated realms: A guide to Keycloak and LDAP Integration

There are many SIEM solutions available on the market, so it’s worth conducting a security audit within your organization before making a decision. Identifying potential vulnerabilities will help guide the selection and implementation of an appropriate incident management system, enhanced with Keycloak integration, to better monitor threats and strengthen data protection across your organization.

Do You Want to Implement Keycloak?

Benefit from our experience. We have completed numerous implementations for SMEs and large organizations. We’d be happy to discuss potential collaboration opportunities.

Schedule a Meeting

Artykuł Security Information and Event Management Systems: Why Is It Worth Adding Keycloak? pochodzi z serwisu Inero Software - Software Consulting.

Keycloak Migration Made Easy: Tips and Best Practices

Marceli Formela — Tue, 28 Jan 2025 12:57:28 +0000

Here we’ll explore the most significant changes introduced in recent Keycloak releases and how they impact migration efforts. We’ll walk through practical examples to resolve common challenges, ensuring a smooth transition to newer versions. Whether it’s adapting to updated configurations or managing deprecated features, this post should provide additional tips to streamline your Keycloak migration process.

Migrating to Quarkus distribution

One of the most challenging migrations for many users has been the upgrade to Keycloak 17, where the underlying architecture shifted from WildFly to the Quarkus framework. This transition marked a significant departure from the traditional application server model, requiring users to adopt a more modern, lightweight approach tailored to Quarkus. The way Keycloak is configured has fundamentally changed – rather than deploying it on an external application server, it now operates as a standalone application, which simplifies deployment.

For example, custom providers, which were previously packaged dynamically as modules for WildFly, now need to be rebuilt and adapted (as runtime is immutable), involving changes to dependencies, classloading, and packaging methods. This design simplifies deployments in environments like Kubernetes but demands a shift in workflows for teams accustomed to the WildFly solutions. While the move to Quarkus offers performance gains and a more modern development experience, it still requires careful planning and testing to ensure a smooth migration.

Key changes introduced in new releases

Migration introduces important changes that impact configuration, endpoints, and custom provider implementations:

HTTPS requirement for production mode – starting Keycloak with the command [keycloak_quarkus_root]/26.1.0/bin/kc.bat start now requires an HTTPS certificate, as the start option is intended for production use. For local development, the start-dev option should be used instead.
removal of /auth from base path – the /auth segment has been removed from the default base path. Applications relying on Keycloak endpoints must update their configurations to reflect this change.
realm ID changes – in previous versions, the realm ID was identical to the realm name. Starting from Keycloak 21, the realm ID is now a unique, system-generated value. Applications relying on realm IDs should account for this change during migration.
deprecation of userLocalStorage – custom providers using the userLocalStorage method of the KeycloakSession interface must switch to the users method, as userLocalStorage was deprecated starting from Keycloak 19.
transport jdbc-ping as new default – in the latest version of Keycloak (26.1.0), the default method for discovering other nodes within a cluster has shifted to using its database, rather than relying on just multicast. This change eliminates the need for additional network configurations, particularly in cloud environments.

Issues with major migrations

When migrating Keycloak, it’s highly recommended to upgrade version by version, rather than jumping several releases at once. This incremental approach allows you to identify and resolve issues as they arise, minimizing the risk of unexpected complications. Upgrading across multiple versions—especially if spanning a dozen or more releases—can significantly complicate the process due to accumulated changes, deprecated features, and architectural shifts like the move to Quarkus. By addressing compatibility and configuration adjustments one step at a time, you ensure better control over the migration and reduce downtime or disruptions in production environments.

However, in many cases, a large one-time migration—such as moving from Keycloak 12 directly to Keycloak 26—is unavoidable and becomes a challenge that teams must address effectively. This process often involves significant changes to both the Keycloak server and dependent applications, particularly frontend clients that rely on its APIs.

In this guide, we’ll outline a practical step-by-step approach to such a major migration.

Dockerfile configuration

In our example project, all custom themes and SPI (Service Provider Interface) extensions were directly copied into the base Keycloak image without a dedicated build process. So it was done in a standard Wildfly way.

FROM quay.io/keycloak/keycloak:12.0.2

COPY themes/custom-theme /opt/jboss/keycloak/themes/custom-theme
COPY api-extensions/target/spi-resource-0.0.1-SNAPSHOT.jar

ENTRYPOINT /opt/jboss/tools/docker-entrypoint.sh -b 0.0.0.0

The new approach could use a multi-stage process with separate containers like:

FROM eclipse-temurin:17-jdk as spi_builder
[…]
FROM quay.io/keycloak/keycloak:$BASE_IMAGE_TAG as keycloak_builder
[…]
FROM quay.io/keycloak/keycloak:$BASE_IMAGE_TAG

The SPI is built during the container build process using Maven. This approach ensures that the dependencies are fetched and the resulting JAR is optimized for deployment.

### Runtime dependencies build container
FROM registry.access.redhat.com/ubi9 AS runtime_dependencies_builder
RUN mkdir -p /mnt/rootfs

RUN dnf install --installroot /mnt/rootfs curl --releasever 9 --setopt install_weak_deps=false --nodocs -y \
&& dnf --installroot /mnt/rootfs clean all

### SPI build container
FROM eclipse-temurin:17-jdk as spi_builder
ARG BASE_IMAGE_TAG
WORKDIR /workspace/app

COPY api-extensions/mvnw .
COPY api-extensions/.mvn .mvn
COPY api-extensions/pom.xml .

# dos2unix:
RUN sed -i -e 's/\r//g' mvnw
RUN ./mvnw dependency:go-offline
COPY api-extensions/src src
RUN ./mvnw -o package -DskipTests

The new process copies multiple custom themes into the Quarkus-based Keycloak during the build stage, ensuring they are included in the final optimized runtime. So this approach improves startup performance and aligns with immutable container philosophy.

### Build container
FROM quay.io/keycloak/keycloak:$BASE_IMAGE_TAG as keycloak_builder
COPY --from=spi_builder /workspace/app/target/spi-resource-0.0.1-SNAPSHOT-jar-with-dependencies.jar /opt/keycloak/providers/

#Copy custom themes
COPY themes/custom-theme /opt/keycloak/themes/custom-theme

#Build an optimized server runtime
RUN /opt/keycloak/bin/kc.sh build

### Runtime container
FROM quay.io/keycloak/keycloak:$BASE_IMAGE_TAG
COPY --from=keycloak_builder /opt/keycloak/ /opt/keycloak/
WORKDIR /opt/keycloak
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

Basically, by leveraging multi-stage builds and lightweight images, the new process aligns with best practices for containerized deployments. You can find more details about these steps here: https://www.keycloak.org/server/containers.

Default /auth context path changed

With the transition to the Quarkus-based Keycloak distribution, the default context path has been modified—/auth is no longer part of the URL by default. This change aligns with Quarkus’s goal of providing a more streamlined and minimalistic approach to web applications, reducing unnecessary path prefixes.

For users or applications that still require the /auth context path, it can be reintroduced using the http-relative-path build option. For instance, running Keycloak with the following command restores the /auth context:

bin/kc.[sh|bat] start-dev –http-relative-path /auth

Or using a docker-compose way:

KC_HTTP_RELATIVE_PATH: /auth

This allows for compatibility with existing clients or configurations that rely on the /auth prefix. With the relative path specified, Keycloak will still automatically redirect requests from the root (e.g., localhost:8080/) to the /auth path (e.g., localhost:8080/auth). This ensures that applications or users accustomed to the previous URL structure continue to function as expected without requiring major changes.

Changes within provider management

With the shift to the Quarkus-based Keycloak distribution, there are significant changes in how custom providers (SPIs) are deployed and managed. In the WildFly-based distribution, custom providers were deployed by copying them into the standalone/deployments directory, and dependencies were also placed in specific locations within the WildFly server structure. However, in the new Quarkus distribution, this deployment model has been streamlined. Custom providers should now be copied into the /providers directory.

Additionally, Quarkus does not support the EAR packaging format or the jboss-deployment-structure.xml files, which were commonly used in the WildFly distribution to configure deployments and manage dependencies. As a result, the packaging process is simplified, but custom configurations previously made through these files must now be handled differently.

Furthermore, if custom providers utilized JavaEE APIs, such as session or stateless beans, these will no longer be supported in the Quarkus distribution.

Migrating custom themes

Old Keycloak relied on the FreeMarker template engine for rendering dynamic content in themes. This approach is still used in new releases (especially in v1 and v2 themes), but there have been updates to the template syntax and theme structure to align with the new Quarkus architecture. Custom templates may need to be revised to ensure compatibility with newer versions of FreeMarker, as the theme structure may have evolved.

Additionally, certain legacy template functions and macros that were present in, for example Keycloak 12, might have been deprecated or replaced with new, more efficient alternatives.

Custom themes that were previously customized are likely not optimized for dark mode. To avoid complications without having to rewrite them from scratch, the simplest solution is to add the appropriate option darkMode=false in the theme.properties file. Additionally, starting from version 26.1.0, the “Themes” tab now includes switches that allow for enabling dark mode on a per-realm basis.

Making new Keycloak server work with legacy frontend client

checkLoginIframe related issues

In one of our projects, we had to upgrade Keycloak by 14 versions. However, for various reasons, we couldn’t migrate the frontend, which was running on a rather old version of Angular and the keycloak-angular library. Therefore, we will now go through the tweaks we had to apply in order to restore the login process functionality.

Keycloak-angular is a wrapper library for keycloak-js that makes using it easier in Angular applications. It extends the original features with additional functionality and adds new methods to make it easier to use within an Angular app. It also provides a basic implementation of AuthGuard, allowing you to customize your logic by using the authentication logic. It’s also possible to use the HttpClient Interceptor, which adds an authorization header to selected HTTP requests.

"keycloak-angular": "^8.1.0",
"keycloak-js": "^12.0.4",

After integrating the new version of Keycloak (26.1.0) with the old frontend client, we encountered an issue after logging in, which manifested as follows:

This option specifies whether Keycloak should check the login status using an iframe. It should be used with caution, as improper configuration may lead to issues such as continuous page reloads. Newer versions of Keycloak may have improved or changed session management, particularly around cross-site cookies, authentication flows, or iframe handling (setupCheckLoginIframe, check3pCookiesSupported). These changes could affect how the frontend handles login states, especially if it is using deprecated methods for checking login states or processing callbacks.

Given the significant version gap between the frontend and the server, one useful approach might be to disable the setupCheckLoginIframe option, which could also help in situations where infinite redirect loops occur after the upgrade.

Here’s an example of how to disable it in your initialization:

function initializeKeycloak(keycloak: KeycloakService, permissionsService: PermissionsService) 
{
  return () =>
    keycloak.init({

   config: {
     url: environment.keycloakUrl,
     realm: 'test-realm',
     clientId: 'test-realm-web',
   },
   initOptions: {
        checkLoginIframe: false
   }
}).then(() => permissionsService.init());
}

Missing nonce claim

In newer versions of Keycloak, in accordance with the OpenID Connect Core 1.0 specification, the nonce claim is now only added to the ID token if the parameter was included in the authorization request. According to the specification, the nonce claim is mandatory in the ID token but should not be included in tokens after a refresh request. Previously, nonce was added to all tokens (Access, Refresh, and ID) in all responses, including refresh responses.

As a result, using an older version of the keycloak-js adapter may cause login issues, such as “Invalid nonce, clearing token” errors or an infinite redirection loop after login attempts. To resolve this, users can add the predefined “Nonce backwards compatible” mapper via the “By Configuration” button in the dedicated client scope. More information can be found in the official Keycloak documentation (https://www.keycloak.org/docs/latest/upgrading/index.html#nonce-claim-is-only-added-to-the-id-token).

Post-logout redirect URI issues

According to the release notes for version 18, Keycloak no longer supports the redirect_uri parameter for logging out. Instead, you need to use post_logout_redirect_uri along with either the client_id or id_token_hint parameter. In practice, this means when calling the logout function, you must replace redirect_uri with post_logout_redirect_uri. In our case (with legacy keycloak-js), the logout process can be implemented like this:

window.location.replace(this.keycloak['_instance']['endpoints'].logout() +
   '?post_logout_redirect_uri=' + encodeURIComponent(window.location.origin) +
   '&client_id=test-realm-web');

This change should resolve the most common issues with redirects after logging out of the application.

Summary

Over the past few years, Keycloak has undergone significant changes, particularly with the breaking changes introduced during the migration from WildFly to Quarkus. These changes were necessary for performance improvements, more efficient resource usage, and better scalability.

While the migration process can appear challenging, it is generally achievable, even when working with older clients. However, the ease of migration largely depends on the specific use case, especially the level of customization involved. For instance, if themes were highly customized in the previous version of Keycloak, adapting them to newer distributions may require more time and effort, as the structure and templating engines have evolved.

Similarly, integrations with legacy systems might need careful planning to ensure compatibility with newer versions of Keycloak. On the other hand, for standard setups with minimal customization, the transition is often smoother and quicker. The process of migration can also be supported by detailed documentation and a strong community, which has grown significantly in recent years.

Overall, while each migration project has its own challenges, with proper planning and testing, transitioning to a newer version of Keycloak is generally not so complicated, and the long-term benefits of the upgrade, such as improved performance and security features, make it worth the effort.

Are you planning to implement Keycloak in your organization?

If you're looking for a partner to provide comprehensive support in this process, be sure to contact us.

Schedule a conversation

Artykuł Keycloak Migration Made Easy: Tips and Best Practices pochodzi z serwisu Inero Software - Software Consulting.

Step-by-Step Guide to Enabling Multi-Factor Authentication (MFA) in Keycloak

Marceli Formela — Wed, 05 Jun 2024 09:51:42 +0000

In today’s digital age, the importance of securing online resources has never been greater. As these threats continue to evolve, the traditional method of relying on passwords has proven insufficient in protecting sensitive information. This escalation underscored the necessity for more sophisticated security measures, leading to the widespread adoption of Multi-Factor-Authentication (MFA). In this blog post, we will explore still growing online threats and how MFA serves as a defense mechanism for our applications.

What is MFA?

Multi-Factor Authentication (MFA) enhances the security of your applications by requiring users to provide multiple forms of identification before granting access. Of course, tools like Keycloak support MFA and allow administrators to configure it with ease. This guide offers a detailed, step-by-step procedure to enable MFA in Keycloak, ensuring that your user authentication processes are more secure.

MFA is designed to protect users against the vulnerabilities associated with single-factor authentication, where a user only needs to provide one form of authentication, typically a password. MFA adds layers of security by requiring users to present multiple pieces of evidence (factors) that confirm their identity.

Authentication factor user in MFA are typically categorized into three types:

Knowledge Factors (something you know)

- Passwords
- PINs
- Security questions

Possession Factors (something you have)

- OTP (One-Time Password) generated by an authenticator app
- SMS codes
- Email codes
- Hardware tokens

Inherence Factors (something you are)

- Biometric verification (facial recognition, fingerprint etc.)

The first step is always initial authentication, when the user enters username and password (so called knowledge factor). After the initial authentication, the user is prompted to provide a second form of authentication and this could be an OTP sent to the phone, a biometric scan, or another form of possession/inherence factor. If both factors are successfully verified, the user is granted access to the application. Now let’s take a look at a few example types of authentication and their pros/cons.

Email-based OTP

In this method, a temporary code is sent to the user’s registered email address, which they must enter to complete the login process. Users receive the OTP directly in the email and it does not require to install or configure any additional apps. But we should remember that email accounts can be compromised, and intercepted emails could be a significant security risk.

SMS-based OTP

Receiving an OTP via SMS is straightforward and familiar to most users, also requiring no additional app installation. It should work on any mobile phone, making it accessible to a broader range of users. But they can be also vulnerable to interception and SIM swapping attacks, making them less secure compared to other methods. SMS delivery can also be delayed or even fail due to network issues. We’ll take a closer look at its pros and cons in the next post which covers custom authenticator development.

Push notifications

Push notifications involve sending a real-time alert to a user’s registered mobile device, asking them to approve or deny an authentication attempt. Users are instantly notified of any login attempts, allowing them to quickly respond to any unauthorized access attempts. They also do not need to enter a one-time password (OTP), which simplified the authentication process. This method of course requires an active internet connection. But remember that infected devices could potentially compromise the security of this feature and that users basically need to be educated about recognizing legitimate push notifications to avoid accidental approvals of attack attempts.

OTP via Authenticator Apps

OTPs generated by authenticators like Google are highly secure as they are time-based and difficult to predict. They can generate OTPs without an internet connection, making them reliable even when users are offline. In this case, users need to have access to their mobile device to generate the OTP and initial setup very often requires scanning a QR code and configuring authenticator app, which might be challenging for non-technical users.

How to configure OTP (via mobile authenticator) in Keycloak

Now we can go to the Keycloak console and try to set up some basic OTP in our realm. Before attempting to enable MFA in Keycloak, ensure you have a running instance of Keycloak, administrative access to the server, and a basic understanding of realm, client, user management concepts from previous posts.

Step 1: OTP Policy

From the side menu select the realm where you want to enable MFA. In the realm settings, navigate to the Authentication section and select the OTP Policy tab. Configure settings according to your security requirements. You can select default values that are provided by the server.

Step 2: Required actions

In the Authentication settings, go to the Required Actions tab. Now you can activate OTP as default action for every new user.

Therefore, we have already configured MFA and each newly registered user will have to use it. Of course, this configuration could be modified through in-the-app account settings so that users only use MFA if they specifically request it.

As we can see, MFA is a powerful tool for protecting sensitive information and enhancing the security of web applications. By requiring multiple forms of verification, it makes it significantly harder for unauthorized users to access accounts and systems, mitigating risks associated with password-only authentication. Implementing this mechanism is surely helping organizations comply with regulations and protect against still-evolving web threats.

In the next article, we will take a closer look at a custom SMS authenticator for Keycloak, exploring its pros and cons.

Artykuł Step-by-Step Guide to Enabling Multi-Factor Authentication (MFA) in Keycloak pochodzi z serwisu Inero Software - Software Consulting.

Best Practices in Keycloak: Secure Your System in 5 Steps

Marta Kuprasz — Mon, 13 May 2024 13:55:51 +0000

Keycloak is a tool for managing identity and access that ensures the security of applications and web services. To maximally secure your environment using it, it’s important to implement best practices. Here are 5 key steps that will help you in this process.

Enable HTTPS and Use Strong Certificates

The first and most crucial step is to ensure all communication with the Keycloak server is done through the secure HTTPS protocol. Using SSL/TLS certificates from trusted providers protects against data interception and manipulation.

In this step:

- Configure the Keycloak Server: Set the server to use only HTTPS, rejecting all unencrypted HTTP requests.
- Update Certificates: Regularly renew and update SSL/TLS certificates to avoid the risk of exploiting outdated keys.

Implement Multi-Factor Authentication (MFA)

This feature adds a layer of security by simultaneously using multiple methods to verify a user’s identity. 2FA (Two-Factor Authentication) is a popular form of MFA that often requires users to enter a password and confirm their identity with a second factor, such as a code from an authentication app.

In this step:

- Activate Multi-Factor Authentication in Keycloak: Enable MFA for all users, especially those with administrative access and access to sensitive data.
- Choose Authentication Methods: Keycloak supports various MFA methods; commonly used ones include authentication apps (e.g., Microsoft Authenticator).

Read also:

Implement strong password policies and session management

Password and session management are key to protecting user identities and preventing unauthorized access. They are the first line of defense against attacks such as brute force or phishing. Keycloak provides a wide range of configurable password policy settings from the administrative console.

In this step:

- Configure the password policy: Set precise rules for password selection to require specific lengths, complexity (e.g., the presence of special characters, uppercase and lowercase letters), and define the password’s lifespan and history.
- Limit session lifespan: Set short but practical session and token lifespan to minimize the window for potential attacks. Automatically logging out users after a specified period of inactivity is important for preventing accidentally leaving sessions open on shared or public devices.

Read also:

- An introduction to Passkey with Keycloak
- Hands-On Keycloak SSO: From Setup to Integration

Secure API endpoints and use Role-Based Access Control (RBAC)

Role-Based Access Control (RBAC) allows for defining roles, assigning them to users, and managing permissions, enabling control over API operations depending on the role.

In this step:

- Securing API endpoints: To secure API endpoints, it is crucial to apply appropriate authorization and authentication mechanisms:
- Authentication: Implement authentication protocols such as OAuth 2.0 and OpenID Connect, so users and applications must prove their identity before gaining access to the API. Access tokens: Use access tokens, which contain information about user permissions, to verify access rights to various API resources. HTTPS: Ensure that all requests to the API are sent over HTTPS, protecting data from interception and modification. Role-Based Access Control (RBAC): Role-Based Access Control allows for managing user permissions based on their roles in the organization:
- Defining roles: Establish roles that reflect different access levels in the application, e.g., administrator, user, guest, etc. Assigning roles: Assign roles to users that specify which resources and operations they can access. Managing permissions: Configure access policies in Keycloak to control which operations can be performed by users with a given role at specific API endpoints.

Read also:

Regularly update and monitor the environment

Updating and continuously monitoring the Keycloak environment is essential to maintain high protection against new threats and security vulnerabilities. Keycloak updates appear every few months, and information about them can be found on the official project website or in the Keycloak documentation.

In this step:

- Updates: Regularly update Keycloak to the latest stable versions.
- Monitoring and logging: Use monitoring tools to track any unusual behavior and respond quickly to potential security incidents. Set up logging systems to collect key information about system operation. For example, using Kubernetes, you can efficiently manage and scale monitoring and logging tools such as Prometheus and ELK Stack. Kubernetes facilitates the deployment and management of containers with these tools, automating their deployment, scaling, and repair, which is crucial for maintaining continuity of operation and security in distributed systems.
- Choose a proven partner: If implementing Keycloak best practices seems like a labor-intensive process that will heavily burden your team at this stage, seek help from specialists in this field.

Read also:

Inero Software has extensive experience in implementing advanced cybersecurity solutions. We create comprehensive systems for managing users and their roles, tailored to complex IT infrastructures and meeting high corporate standards. Our team, consisting of cybersecurity experts, implements advanced authorization schemes in accordance with renowned security standards. Thanks to our knowledge and experience, we provide effective protection against threats and compliance with corporate security policies.

Artykuł Best Practices in Keycloak: Secure Your System in 5 Steps pochodzi z serwisu Inero Software - Software Consulting.