Friday, 8 September 2017

Using WildFly Elytron with Undertow Standalone

The WildFly Elytron project has been developed to provide the security requirements of the WildFly application server, however the development of WildFly Elytron has produced a security framework which does not depend on the application and can be used outside of the application server.

This means that it is possible to use WildFly Elytron in situations outside of the application server, this blog post demonstrates how WildFly Elytron can be used to secure an embedded Undertow server.

If you visit the main page for Undertow towards the bottom of the page is a code example showing how to start a simple HelloWorld server using Async IO.

This blog post goes one step further and illustrates how WildFly Elytron can be added to the example to secure access to the HttpHandler using HTTP Basic authentication.

The components demonstrated in this example are the same components we use within the application server, the difference being that they are programatically configured and wired together rather than using the subsystem for configuration.

The code for the example can be found in the project called 'undertow-standalone' in the Git repository


The example project has the following key dependencies although these will pull in some additional dependencies.

This is the main dependency on Undertow, this example is only demonstrating with the core Undertow APIs so the servlet dependency is not required.
This is the dependency on the WildFly Elytron security framework.
The Undertow project does not have a dependency on WildFly Elytron and the Elytron project does not have a dependency on Undertow, the Elytron Web project acts as an intermediate project to join the two together.

In future releases of Elytron Web we may also be able to look into integration with other servers following a similar pattern to how we have integrated with Undertow.


The initial example is very similar to the example on, the main difference being the call to a method 'wrap' to wrap the HttpHandler.

    public static void main(String[] args) throws Exception {
        final SecurityDomain securityDomain = createSecurityDomain();

        Undertow server = Undertow.builder()
                .addHttpListener(8080, "localhost")
                .setHandler(wrap(new HttpHandler() {

          public void handleRequest(HttpServerExchange exchange) 
               throws Exception {
  put(Headers.CONTENT_TYPE, "text/plain");                       
  send("Hello " + securityDomain.getCurrentSecurityIdentity().getPrincipal().getName());
                 }, securityDomain)).build();

The first thing to happen during wrapping is an Elytron security domain is assembled, this domain contains a single user 'elytron' with a password of 'Coleoptera'.

    private static SecurityDomain createSecurityDomain() throws Exception {
        PasswordFactory passwordFactory = PasswordFactory.getInstance(ALGORITHM_CLEAR, elytronProvider);

        Map<String, SimpleRealmEntry> passwordMap = new HashMap<>();
        passwordMap.put("elytron", new SimpleRealmEntry(Collections.singletonList(new PasswordCredential(passwordFactory.generatePassword(new ClearPasswordSpec("Coleoptera".toCharArray()))))));

        SimpleMapBackedSecurityRealm simpleRealm = new SimpleMapBackedSecurityRealm(() -> new Provider[] { elytronProvider });

        SecurityDomain.Builder builder = SecurityDomain.builder()

        builder.addRealm("TestRealm", simpleRealm).build();
        builder.setPermissionMapper((principal, roles) -> PermissionVerifier.from(new LoginPermission()));


In this example a simple in memory security realm backed by a Map is used, however any of the other Elytron security realms could be used or even a custom security realm implementation if desired.

After assembling the security domain the next step is creating a HttpAuthenticationFactory, the HttpAuthenticationFactory is the overall authentication policy that makes authentication mechanisms backed by the security domain available.

    private static HttpAuthenticationFactory createHttpAuthenticationFactory(final SecurityDomain securityDomain) {
        HttpServerAuthenticationMechanismFactory providerFactory = new SecurityProviderServerMechanismFactory(() -> new Provider[] {elytronProvider});
        HttpServerAuthenticationMechanismFactory httpServerMechanismFactory = new FilterServerMechanismFactory(providerFactory, true, "BASIC");

        return HttpAuthenticationFactory.builder()
                                .addMechanismRealm(MechanismRealmConfiguration.builder().setRealmName("Elytron Realm").build())

At this stage we can see how the original HttpHandler is wrapped using the resulting HttpAuthenticationFactory and some additional Elytron and Undertow APIs to enable security.

    private static HttpHandler wrap(final HttpHandler toWrap, final SecurityDomain securityDomain) {
        HttpAuthenticationFactory httpAuthenticationFactory = createHttpAuthenticationFactory(securityDomain);

        HttpHandler rootHandler = new ElytronRunAsHandler(toWrap);

        rootHandler = new AuthenticationCallHandler(rootHandler);
        rootHandler = new AuthenticationConstraintHandler(rootHandler);

        return ElytronContextAssociationHandler.builder()
                .setMechanismSupplier(() -> {
                    try {
                        return Collections.singletonList(httpAuthenticationFactory.createMechanism("BASIC"));
                    } catch (HttpAuthenticationException e) {
                        throw new RuntimeException(e);

Build and Run

The example project is a standard Maven project so provided Maven is installed along with Java 8 the project can be built using 'mvn install'.

Once built the server can be started using the exec plug-in 'mvn exec:exec'.  This should result in the server starting and listening on port 8080 for incoming requests.

Note: As an example project there is not a lot of output from the project to the console, feel free to add more output if desired to see each stage as it occurs.

After starting the project you should be able to access the server using curl.

undertow-standalone]$ curl -v
*   Trying
* Connected to ( port 8080 (#0)
> GET / HTTP/1.1
> Host:
> User-Agent: curl/7.53.1
> Accept: */*
< HTTP/1.1 401 Unauthorized
< Connection: keep-alive
< WWW-Authenticate: Basic realm="Elytron Realm"
< Content-Length: 0
< Date: Fri, 08 Sep 2017 15:16:30 GMT
* Connection #0 to host left intact

At this stage curl was not supplied with any user details so we can see the HTTP Basic authentication challenge and the request ends.

If we now provide a username and enter the password when prompted we see a full HTTP exchange.

undertow-standalone]$ curl -v --user elytron
Enter host password for user 'elytron':
*   Trying
* Connected to ( port 8080 (#0)
* Server auth using Basic with user 'elytron'
> GET / HTTP/1.1
> Host:
> Authorization: Basic ZWx5dHJvbjpDb2xlb3B0ZXJh
> User-Agent: curl/7.53.1
> Accept: */*
< HTTP/1.1 200 OK
< Connection: keep-alive
< Content-Type: text/plain
< Content-Length: 13
< Date: Fri, 08 Sep 2017 15:17:45 GMT
* Connection #0 to host left intact
Hello elytron

The 'Hello elytron' returned at the end is the message from the HttpHandler where 'elytron' is the name of the authenticated principal calling the HttpHandler.

Friday, 14 July 2017

WildFly Elytron - Principal Transformers, Realm Mappings, and Principal Decoders

Within the WildFly Elytron configuration it is possible to specify multiple principal transformers, realm mappers, and a principal decoder - this blog post is to describe how they all fit together during the authentication process.

During the authentication process the principal transformers and principal decoders form a very similar function in that they are both used to map principals from one form to another, principal transformers can also be used to validate a principal as an example double check the formatting so authentication can be terminated early if an invalid principal is detected.

At the appropriate state in the process that is being described in this blog post the realm mappers will then operate on the mapped principal to identify which security realm should be used to load the identity.

Here are a couple of diagrams to illustrate how these concepts fit together, the remainder of this blog post will describe the steps in more detail.

The first diagram illustrates the general states the authentication process undergoes to map the Principal used for authentication.

Identity Assignment States 
The next diagram illustrates how the various transformers, decoders, and mappers can be configured for Elytron authentication.

Configuration Relationships

Resolve Mechanism Configuration

When the authentication processes commences for a single authentication mechanism the first step is to resolve the MechanismConfiguration that should be used, this is resolved by taking into account the name of the selected mechanism, the host name, and the protocol.

During this stage the mechanism realm configuration will also be resolved, the authentication mechanism will either request this by name or if the mechanism does not request this then the first one in the list is used.

Note: The mechanism realm is specifically in relation to the realm name negotiated by the authentication mechanism if applicable and is independent of the security realm representing the identity store.

Pre Realm Mapping

The purpose of this state is to take the Principal from the form that was provided by the authentication mechanism and map it to the form that can be used to identify which security realm to use to load the identity.

At the very end of the authentication process the identity is represented by a SecurityIdentity which contains a single Principal, the Principal will be the one created by this mapping stage.

The principal transformers and principal decoder will be called in the following order: -

1. Mechanism Realm - pre-realm principal-transformer
2. Mechanism Configuration - pre-realm principal transformer
3. Security Domain - principal-decoder
4. Security Domain - pre-realm-principal-transformer

If the end result is a null principal and error will be reported and authentication will terminate.

Realm Mapping

The next stage is to take the mapping principal and map it to a realm name to identify the name of the Security Realm to use to load the identity.

Note:  At this stage the realm name is the name of the SecurityRealm as referenced by the SecurityDomain and is not the mechanism realm name.

The configuration will be inspected for the first realm mapper that can be found in the following locations: -

A. Mechanism Realm - realm-mapper
B. Mechanism Configuration - realm-mapper
C. Security Domain - realm-mapper

If a RealmMapper is identified but that mapper returns null when mapping the Principal then the default-realm specified on the Security Domain will be used instead.

If no RealmMapper is available then the default-realm on the SecurityDomain will be used.

Post Realm Mapping

After the realm has been identified a further round of principal transformation happens, this time the following transformers are called: -

5. Mechanism Realm - post-realm principal-transformer
6. Mechanism Configuration - post-realm principal-transformer
7. Security Domain - post-realm principal-transformer

As before if the result is a null principal an error will be reported and authentication will be terminated.

Final Principal Transformation

After the post realm mapping stage one final round of principal transforming takes place, this time the following transformers are called in order.

8. Mechanism Realm - final principal-transformer
9. Mechanism Configuration - final principal-transformer
10. Realm Mapping - principal-transformer

Once again a null principal will result in an error being reported and authentication being terminated.

Having to transformations after the realm has been identified allows for mechanism specific transformations to be applied both before and after domain specific transformations, if this is not required then either the post-realm principal transformers or the final principal-transformers can be used to obtain the same result.

The End

It is only now at the very end of principal transformation that the security realm previously identified will be call to obtain the RealmIdentity that is now used for authentication to continue.

The key points to keep in mind are: -

  • The Principal created by the pre-realm-principal-transformers is: -
    • The Principal used to map the SecurityRealm
    • The Principal that will be associated with the resulting SecurityIdentity.
  • The Principal created after the final principal transformers is: -
    • The Principal that will be passed to the SecurityRealm to obtain the RealmIdentity.