WildFly Elytron

WildFly Elytron

Securing WildFly Apps with OIDC on OpenShift

By Ashwin Mehendale | November 08, 2023
#oidc #openshift #keycloak #adapter #galleon-pack

You can secure your WildFly applications deployed on OpenShift with OpenID Connect (OIDC). By using OIDC to secure applications, you delegate authentication to OIDC providers. This guide shows how to secure an example application deployed to WildFly on OpenShift with OIDC using Keycloak as the OIDC provider.

Prerequisites

To follow along with this guide, you will need:

Example Application

We will use a simple web application in this guide that consists of a single servlet. We will secure this servlet using OIDC.

We will use the example in the simple-webapp-oidc directory in this repo.

To obtain this example, clone the elytron-examples repository to your local machine:

git clone git@github.com:wildfly-security-incubator/elytron-examples.git

Log Into the OpenShift Cluster

Before we can deploy our application, we need to log in to an OpenShift cluster. You can log in via the OpenShift CLI:

oc login -u myUserName

Alternatively, you can log in using an API token:

oc login --token=myToken --server=myServerUrl

You can request the token via the Copy Login Command link in the OpenShift web console.

If you don’t already have a project created, you can create one using:

oc new-project myProjectName

Start Keycloak

We will be using Keycloak as our OIDC identity provider.

To start a Keycloak server in your project on OpenShift, use the following command:

oc process -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/openshift/keycloak.yaml \
    -p KEYCLOAK_ADMIN=admin                  \(1)
    -p KEYCLOAK_ADMIN_PASSWORD=admin         \(2)
    -p NAMESPACE=<PROJECT_NAME>                \(3)
| oc create -f -
1 Replace admin with the user name you would like to use when accessing the Keycloak Administration Console.
2 Replace admin with the password you would like to use when accessing the Keycloak Administration Console.
3 Replace <PROJECT_NAME> with your project name.

After running the above command, you should see the following output:

service/keycloak created
route.route.openshift.io/keycloak created
Warning: apps.openshift.io/v1 DeploymentConfig is deprecated in v4.14+, unavailable in v4.10000+
deploymentconfig.apps.openshift.io/keycloak created.

It will take a few minutes for OpenShift to provision the Keycloak pod and its related resources.

You can use the OpenShift CLI or the OpenShift web console, depending on your preference, to check if your Keycloak server has been provisioned.

OpenShift CLI

To make sure your Keycloak server has been provisioned using the OpenShift CLI, run:

oc get pods

After a little while, check for a message similar to the following message that indicates the pod is ready:

NAME                READY     STATUS      RESTARTS   AGE
keycloak-1-deploy   0/1       Completed   0          1h
keycloak-1-l9kdx    1/1       Running     0          1h

Once the Keycloak server has been provisioned, use the following command to find the URL for your Keycloak instance’s Admin Console:

KEYCLOAK_URL=https://$(oc get route keycloak --template='{{ .spec.host }}') &&
echo "" &&
echo "Keycloak Admin Console:   $KEYCLOAK_URL/admin" &&
echo ""

OpenShift Web Console

To make sure your Keycloak server has been provisioned using the OpenShift web console, navigate to the Topology view in the Developer perspective. You can click on your keycloak app to check its status. Once it is running, you can click on Open URL and then access Keycloak’s Administration Console.

Configure Keycloak

  1. Log into the Keycloak Admin Console using the username and password you specified earlier.

  2. Create a new realm called myrealm. For more information, see the Keycloak documentation on how to create a realm.

  3. Add a role called user. This role will be required to access our simple web application. For more information, see the Keycloak documentation on how to create a role.

  4. Add a new user named alice. Set an email address for this new user, we’ll use alice@example.org. For more information, see the Keycloak documentation on how to create a user.

  5. Once the new user has been created, set a password for this new user from the Credentials tab.

  6. From the Role Mapping tab, assign alice the user role. For more information, see the Keycloak documentation on how to assign a role to a user.

  7. Create a new client as follows:

    • General Settings:

      • Client type (or Client Protocol, depending on your Keycloak version): OpenID Connect

      • Client ID: myclient

    • Capability config:

      • Authentication flow: Standard flow, Direct access grants

    • Login settings: Leave the fields blank for now.

    For more information, see the Keycloak documentation on how to Managing OpenID Connect clients.

  8. Click Save to save the client.

Add Helm Configuration

  1. Obtain the URL for Keycloak.

    KEYCLOAK_URL=https://$(oc get route keycloak --template='{{ .spec.host }}') &&
echo "" &&
echo "Keycloak URL:   $KEYCLOAK_URL" &&
echo ""

  2. Switch to the charts directory in the simple-webapp-oidc example.

    cd /PATH/TO/ELYTRON/EXAMPLES/simple-webapp-oidc/charts

    Notice there’s a helm.yaml file in this directory with the following content:

    build:
  uri: https://github.com/wildfly-security-incubator/elytron-examples.git
  contextDir: simple-webapp-oidc
deploy:
  replicas: 1
  env:
    - name: OIDC_PROVIDER_URL
      value: <KEYCLOAK_URL>    (1)
    1 Replace <KEYCLOAK_URL> with the Keycloak URL obtained in the previous command.

Deploy the Example Application to WildFly on OpenShift

If you haven’t already installed the WildFly Helm chart, install it:

helm repo add wildfly https://docs.wildfly.org/wildfly-charts/

If you’ve already installed the WildFly Helm Chart, be sure to update it to ensure you have the latest one:

helm repo update

We can deploy our example application to WildFly on OpenShift using the WildFly Helm Chart:

helm install oidc-app -f /PATH/TO/ELYTRON/EXAMPLES/simple-webapp-oidc/charts/helm.yaml wildfly/wildfly

Notice that this command specifies the file we updated, helm.yaml, that contains the values needed to build and deploy our application.

The application will now begin to build. This will take a couple of minutes.

The build can be observed using:

oc get build -w

Once complete, you can follow the deployment of the application using:

oc get deployment oidc-app -w

Alternatively, you can check status directly from the OpenShift web console.

Behind the Scenes

While our application is building, let’s take a closer look at our application.

  • Examine the pom.xml file.

    Notice that it contains an openshift profile. A profile in Maven lets you create a set of configuration values to customize your application build for different environments. The openshift profile in this example defines a configuration that will be used by the WildFly Helm Chart when provisioning the WildFly server on OpenShift.

    <profiles>
    <profile>
        <id>openshift</id>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.wildfly.plugins</groupId>
                    <artifactId>wildfly-maven-plugin</artifactId>         (1)
                    <version>${version.wildfly.maven.plugin}</version>
                    <configuration>
                        <feature-packs>
                            <feature-pack>
                                <location>org.wildfly:wildfly-galleon-pack:${version.wildfly}</location>
                            </feature-pack>
                            <feature-pack>
                                <location>org.wildfly.cloud:wildfly-cloud-galleon-pack:${version.wildfly.cloud.galleon.pack}</location>
                            </feature-pack>
                        </feature-packs>
                        <layers>
                            <layer>cloud-server</layer>
                            <layer>elytron-oidc-client</layer>           (2)
                        </layers>
                        <filename>simple-webapp-oidc.war</filename>
                    </configuration>
                    <executions>
                        <execution>
                            <goals>
                                <goal>package</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>
    1 wildfly-maven-plugin provisions a WildFly server with the specified layers with our application deployed.
    2 elytron-oidc-client automatically adds the native OIDC client subsystem to our WildFly installation.

  • Examine the web.xml.

    ...
    <login-config>
        <auth-method>OIDC</auth-method>  (1)
    </login-config>
...
    1 When elytron-oidc-client subsystem sees auth-method is set to OIDC, it enables OIDC authentication mechanism for the application.

  • Examine the oidc.json file. The oidc.json is used to configure the native OIDC client subsystem.

    {
    "client-id" : "myclient",                                                         (1)
    "provider-url" : "${env.OIDC_PROVIDER_URL:http://localhost:8080}/realms/myrealm", (2)
    "public-client" : "true",                                                         (3)
    "principal-attribute" : "preferred_username",                                     (4)
    "ssl-required" : "EXTERNAL"                                                       (5)
}
    1 This is the client we created in Keycloak.
    2 The provider URL, which is the URL for the realm myrealm that we created, is specified as an environment variable. We will set its value in the helm configuration.
    3 When public-client set to true, client credentials are not sent when communicating with the OpenID provider.
    4 We specify that the user name of the identity, which in our case is alice, is to be used as the principal for the identity.
    5 When ssl-required is set to EXTERNAL, only the communication with external clients happens over HTTPs

Get the Application URL

Once the WildFly server has been provisioned, use the following command to find the URL for your example application:

SIMPLE_WEBAPP_OIDC_URL=https://$(oc get route oidc-app --template='{{ .spec.host }}') &&
echo "" &&
echo "Application URL: $SIMPLE_WEBAPP_OIDC_URL/simple-webapp-oidc"  &&
echo "Valid redirect URI: $SIMPLE_WEBAPP_OIDC_URL/simple-webapp-oidc/secured/*" &&
echo ""

We’ll make use of these URLs in the next two sections.

Finish Configuring Keycloak

From your myclient client in the Keycloak Administration Console, in the client settings, set Valid Redirect URI to the Valid redirect URI that was output in the previous section and then click Save.

Access the Application

From your browser, navigate to the Application URL that was output in the previous section.

Click on Access Secured Servlet.

You will be redirected to Keycloak to log in.

Log in using the alice user we created earlier.

Upon successful authentication, you will be redirected back to the example application.

The example application simply outputs the name of the logged in user.

You should see the following output:

Secured Servlet

Current Principal 'alice'

This indicates that we have successfully logged into our application!

Summary

This guide has shown how to secure an application deployed to WildFly on OpenShift with OIDC. For additional information, feel free to check out the resources linked below.

Resources