WildFly Elytron

WildFly Elytron

Securing WildFly Apps with SAML on OpenShift

By Farah Juma | September 06, 2023
#saml #openshift #keycloak #adapter #galleon-pack

Starting with WildFly 29, you can use Galleon to add Keycloak’s SAML adapter to your WildFly installation using the new Keycloak SAML Adapter feature pack. In this guide, we’ll show how to secure an application deployed to WildFly on OpenShift with SAML.

Prerequisites

To follow along with this guide, you will need:

Example Application

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

You’ll need to fork and then clone this Git repository: https://github.com/wildfly-security-incubator/elytron-examples.git

We will be using the example in the simple-webapp-saml directory in this repo.

Log Into the OpenShift Cluster

Before we can deploy our application, we need to log into 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 for our SAML 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=myNameSpace \                (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 myNameSpace with your project name.

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

service/keycloak created
route.route.openshift.io/keycloak created
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:

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

    • Client ID: simple-webapp-saml

      For more information, see the Keycloak documentation on how to create a SAML client.

  8. Once the new client has been created, in the Settings tab, scroll down to the SAML capabilities section and set the Name ID format to email. When accessing our servlet later on, we will see that this results in HttpServletRequest.getUserPrincipal().getName() returning the logged in user’s email address.

  9. Then set Force name ID format to On. Then click on Save.

Download the SAML Keys

  1. From your simple-webapp-saml client in the Keycloak Admin Console, click on the Keys tab.

  2. Click on the Export button in the Signing keys config to export the SAML keys to a keystore.

  3. Set the Key alias to simple-webapp-saml, the Key password to password, the Realm certificate alias to myrealm, and the Store password to password.

    Take note of the aliases and passwords that you specify here since these will be used when updating the keycloak-saml.xml file.

  4. Click on Export to download the corresponding keystore.jks file.

  5. Create an OpenShift secret using this keystore by running the following command:

    oc create secret generic simple-webapp-saml-secret --from-file=/PATH/TO/keystore.jks

Download and Edit the Keycloak Adapter Configuration File

  1. From your simple-webapp-saml client in the Keycloak Admin Console, click on the Action dropdown in the top right corner and select Download Adapter Config.

  2. For the Format option, select the Keycloak SAML Adapter keycloak-saml.xml, and download the file and place it in the example application’s WEB-INF directory, i.e., place the keycloak-saml.xml file in /PATH/TO/ELYTRON/EXAMPLES/simple-webapp-saml/src/main/webapp/WEB-INF.

  3. Update the keycloak-saml.xml file as follows:

    • Set the SP entityID to "simple-webapp-saml"

    • Set the SP logoutPage to "/simple-webapp-saml"

    • Replace the SP Keys configuration with the following configuration, being sure to use the aliases and passwords you specified when exporting the SAML keys to the keystore.jks file:

      <Keys>
    <Key signing="true">
        <KeyStore password="password" file="/etc/keycloak-saml-secret-volume/keystore.jks">
            <PrivateKey alias="simple-webapp-saml" password="password"/>
            <Certificate alias="myrealm"/>
        </KeyStore>
    </Key>
</Keys>

    • Push this new file to the simple-webapp-saml directory in your elytron-examples fork, making sure to push the changes to your fork’s default branch.

      cd /PATH/TO/ELYTRON/EXAMPLES/simple-webapp-saml
git add src/main/webapp/WEB-INF/keycloak-saml.xml
git commit -m "Added Keycloak adapter deployment descriptor file"
git push origin main

Add Helm Configuration

Let’s switch to the charts directory in our simple-webapp-saml example:

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

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

build:
  uri: https://github.com/YOUR_GITHUB_USERNAME/elytron-examples
  contextDir: simple-webapp-saml
deploy:
  volumes:
    - name: saml-keystore-volume
      secret:
        secretName: simple-webapp-saml-secret
  volumeMounts:
    - name: saml-keystore-volume
      mountPath: /etc/keycloak-saml-secret-volume
      readOnly: true

Replace YOUR_GITHUB_USERNAME in the build uri with your own GitHub username.

The helm.yaml file specifies the Git repository that contains our application’s source code.

Because we have modified the application’s source code by adding a keycloak-saml.xml file, you need to set the build uri in the helm.yaml file to point to your own fork.

Notice that our helm.yaml file also refers to the OpenShift secret, simple-webapp-saml-secret we created earlier. This will be used to mount the keystore.jks file on our WildFly server pod.

Deploy the Example Application to WildFly on OpenShift

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

helm install saml-app -f /PATH/TO/ELYTRON/EXAMPLES/simple-webapp-saml/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 saml-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’s pom.xml file. Notice that it contains the following wildfly-maven-plugin configuration:

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>${version.wildfly.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-pack>
                <location>org.keycloak:keycloak-saml-adapter-galleon-pack:${version.keycloak}</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>cloud-server</layer>
            <layer>keycloak-client-saml</layer>
        </layers>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
 </plugin>

This configuration is used to provision a WildFly server with the specified layers and with our application deployed.

The keycloak-client-saml layer automatically adds the Keycloak SAML adapter to our WildFly installation.

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_SAML_URL=https://$(oc get route saml-app --template='{{ .spec.host }}') &&
echo "" &&
echo "Application URL:              $SIMPLE_WEBAPP_SAML_URL/simple-webapp-saml" &&
echo "Master SAML Processing URL:   $SIMPLE_WEBAPP_SAML_URL/simple-webapp-saml/saml" &&
echo ""

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

Finish Configuring Keycloak

From your simple-webapp-saml client in the Keycloak Administration Console, In the client settings, set Master SAML Processing URL to the Master SAML Processing URL that was output in the previous section and then click Save.

Access the Application

From your browser, navigate to the Application URL.

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 email address associated with our logged in user.

You should see the following output:

Current Principal 'alice@example.org'

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 SAML. For additional information, feel free to check out the resources linked below.

Resources