Native support for OpenID Connect

In  elytron

Overview

The ability to secure deployments using OpenID Connect (OIDC) is currently provided by installing a Keycloak client adapter. When Elytron was still in development for WildFly 11, the specifications in use by Keycloak around OIDC were still very much in a state of ongoing development. Thus, at the time, it made sense for Keycloak to handle this integration. Since the OIDC specifications are now stable, it makes sense for individual projects to handle their own OIDC integration. This RFE is to add native support for OIDC to Elytron. This means that the Keycloak client adapter will no longer be needed to secure applications deployed to WildFly using OIDC. This will also greatly simplify other cases where OIDC is used (e.g., bootable JAR).

Issue Metadata

Issue

Dev Contacts

QE Contacts

  • TBD

Testing By

[ ] Engineering

[ ] QE

  • TBD

Affected Projects or Components

  • WildFly Elytron

  • WildFly Core

  • WildFly

Other Interested Projects

Requirements

Hard Requirements

HTTP mechanism implementation

A new HttpServerAuthenticationMechanism implementation, similar to org.keycloak.adapters.elytron.KeycloakHttpServerAuthenticationMechanism, will be added to WildFly Elytron to provide support for OIDC, as specified in the OpenID Connect Core 1.0 spec.

Like the existing Keycloak client adapter, this new HttpServerAuthenticationMechanism implementation will only support the Authorization Code Flow and Authorization Code Flow with Proof Key for Code Exchange (PKCE).

Token storage

The new HTTP mechanism implementation will be able to make use of a session token store and a cookie token store to store account info (i.e., access tokens, ID tokens, and refresh tokens).

The session token store will be used by default but it should be possible to specify that the cookie token store should be used instead.

The new HTTP mechanism implementation will refresh the access token when it is expired. Since the Keycloak client adapter provides an option to refresh the token on every request, we should provide this option as well but make sure to document that the use of this option is discouraged since it can have a significant impact on performance. For more details about what will be documented, see the description of the always-refresh-token option here.

New elytron-oidc-client subsystem

A new subsystem, elytron-oidc-client will be added to WildFly. Its schema will be similar to the existing keycloak-adapter-subsystem. The new subsystem will install a DeploymentUnitProcessor which will detect if OIDC is required for a deployment.

Like with the existing Keycloak client adapter, the OIDC configuration will be specified via the deployment or via subsystem configuration. For the deployment case, the OIDC configuration will be specified in a JSON configuration file in the WEB-INF directory along with the auth-method, OIDC, specified in the web.xml. For the subsystem case, the auth-method won’t need to be specified in the web.xml file, it will be set automatically.

Once a deployment has been processed, if its auth-method is OIDC, the OIDC integration will be activated. Otherwise, no activation will occur and the deployment will continue to use the existing security capabilities provided by WildFly.

If the OIDC integration is activated for a deployment, then appropriate module dependencies will be added to the deployment (e.g., a dependency on the new Elytron OIDC module). This will ensure the activation of the OIDC HTTP mechanism implementation for the deployment. The deployment will make use of a "Virtual Security Domain", similar to what was implemented for Microprofile JWT. This means that it will no longer be necessary to pre-configure SecurityDomains in the Elytron subsystem, as was required with the Keycloak client adapter.

It should be possible to make use of different OpenID providers with WildFly. While working on the implementation for this RFE, we should make sure that we aren’t including Keycloak-specific configuration, if possible.

New galleon layer for OIDC support

A new Galleon layer, oidc, should be added to allow a server to be provisioned with OIDC support.

Nice-to-Have Requirements

  • RP-Initiated Logout is an optional OIDC specification that defines how a relying party (RP) can request that an OpenID provider logs out the end-user. The Keycloak client adapter provides support for this so this is something we should provide as well but we could possibly look at that as a follow-up to this RFE if necessary.

  • The existing Keycloak adapter can also be used to secure the admin console. This requires some additional work so it might be done as a follow-up task.

  • Migration: For the most part, the same subsystem attributes and JSON configuration options that could be used with the keycloak-adapter-subsystem and the keycloak.json file will still work with the elytron-oidc-subsystem and the oidc.json file. The main difference is the actual subsystem name and the name of the JSON configuration file. That means that the migration tool could potentially detect an existing keycloak subsystem configuration and then change its name to the new subsystem name instead (and update any attributes/elements if needed). For the deployment side, the migration tool could detect deployments with auth-method set to KEYCLOAK and with a keycloak.json configuration file and update the auth-method to OIDC and rename the configuration file to oidc.json.

Non-Requirements

This integration will not be supporting the use of pre-configured SecurityDomains. The purpose of OIDC is to allow a client to verify the identity of an end-user based on authentication that is performed by an authorization server. Information about the end-user can be obtained from ID tokens. Scope information (i.e., role information) can be obtained from access tokens. Thus, we do not need pre-configured security resources in the Elytron subsystem.

Support for the following optional OIDC specifications are currently non-requirements. These are also not provided by the Keycloak Java client adapter:

Test Plan

This will require some discussion with QE to determine the best approach for testing. We will need to decide if it is acceptable to add dependencies on Keycloak (or another OIDC provider) to our testsuites or if we need to mock an OIDC provider.

Community Documentation

A new section will be added to the Elytron documentation that describes:

  • How to activate the OIDC integration for a deployment

  • The new elytron-oidc-client subsystem and how to configure it

  • The OIDC configuration properties that can be specified via a JSON file or via subsystem configuration

  • How to use the new Galleon oidc-client layer

It would be good to have a quickstart for this. This can be handled under its own RFE.

Release Note Content

WildFly now provides the ability to secure deployments using OpenID Connect, without needing to make use of the Keycloak client adapter. It is now possible to make use of other OpenID Connect providers in addition to Keycloak.