Skip to content

Commit

Permalink
Merge pull request #1994 from theashiot/develop
Browse files Browse the repository at this point in the history 
Add blog post about securing wildfly applications on OpenShift with oidc
  • Loading branch information
@fjuma
fjuma committed Nov 8, 2023
2 parents 14b18c9 + 7750a66 commit 84eebb8
Show file tree
Hide file tree
Showing 2 changed files with 380 additions and 0 deletions.
5 changes: 5 additions & 0 deletions _data/authors.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,8 @@ prarthonapaul:
name: "Prarthona Paul"
emailhash: "6ed81e314d6074bbf734abe812f33b05"
bio: "https://github.com/PrarthonaPaul"
theashiot:
name: "Ashwin Mehendale"
emailhash: "e792a4261507d430e9ac7d1f8abcdcc1"
bio: "https://github.com/theashiot"

375 changes: 375 additions & 0 deletions _posts/2023-11-08-securing-wildfly-apps-oidc-openshift.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,375 @@
---
layout: post
title: 'Securing WildFly Apps with OIDC on OpenShift'
date: 2023-11-08
tags: oidc openshift keycloak adapter galleon-pack
synopsis: Learn how to secure applications deployed to WildFly on OpenShift with OIDC.
author: theashiot
---

:toc: macro
:toc-title:


= Securing WildFly Apps with OIDC on OpenShift

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:

* Roughly 15 minutes
* Access to an OpenShift cluster (try the https://developers.redhat.com/developer-sandbox[Red Hat Developer Sandbox] for free)
* https://docs.openshift.com/container-platform/4.13/cli_reference/openshift_cli/getting-started-cli.html[OpenShift CLI]
* https://helm.sh/docs/intro/install/[Helm Chart]

== Example Application

We will use a simple web application in this guide that consists of a single https://github.com/wildfly-security/elytron-examples/blob/main/simple-webapp-oidc/src/main/java/org/wildfly/security/examples/SecuredServlet.java[servlet]. We will secure this servlet using OIDC.

We will use the example in the https://github.com/wildfly-security-incubator/elytron-examples/tree/main/simple-webapp-oidc[simple-webapp-oidc] directory in this repo.

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

[source]
----
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 https://docs.openshift.com/container-platform/4.13/cli_reference/openshift_cli/getting-started-cli.html[OpenShift CLI]:

[source]
----
oc login -u myUserName
----

Alternatively, you can log in using an API token:

[source]
----
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:

[source]
----
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:

[source]
----
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:

[source]
----
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:

[source]
----
oc get pods
----

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

[source]
----
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:

[source]
----
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

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

. Create a new realm called *myrealm*. For more information, see the Keycloak documentation on how to https://www.keycloak.org/getting-started/getting-started-openshift#_create_a_realm[create a realm].

. 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 https://www.keycloak.org/docs/latest/server_admin/index.html#assigning-permissions-using-roles-and-groups[create a role].

. 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 https://www.keycloak.org/getting-started/getting-started-openshift#_create_a_user[create a user].

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

. From the *Role Mapping* tab, assign *alice* the *user* role. For more information, see the Keycloak documentation on how to https://www.keycloak.org/docs/latest/server_admin/index.html#proc-assigning-role-mappings_server_administration_guide[assign a role] to a user.

. 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 https://www.keycloak.org/docs/latest/server_admin/index.html#_oidc_clients[Managing OpenID Connect clients].

. Click *Save* to save the client.

== Add Helm Configuration

. Obtain the URL for Keycloak.
+
[source]
----
KEYCLOAK_URL=https://$(oc get route keycloak --template='{{ .spec.host }}') &&
echo "" &&
echo "Keycloak URL: $KEYCLOAK_URL" &&
echo ""
----

. Switch to the `charts` directory in the `simple-webapp-oidc` example.
+
[source]
----
cd /PATH/TO/ELYTRON/EXAMPLES/simple-webapp-oidc/charts
----
+
Notice there's a `helm.yaml` file in this directory with the following content:
+
[source]
----
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:

[source]
----
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:

[source]
----
helm repo update
----

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

[source]
----
helm install oidc-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:

[source]
----
oc get build -w
----

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

[source]
----
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 https://github.com/wildfly-security/elytron-examples/blob/main/simple-webapp-oidc/pom.xml[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.
+
[source,xml]
----
<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 https://github.com/wildfly-security-incubator/elytron-examples/blob/main/simple-webapp-oidc/src/main/webapp/WEB-INF/web.xml[web.xml].
+
[source,xml,options="nowrap"]
----
...
<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 https://github.com/wildfly-security-incubator/elytron-examples/blob/main/simple-webapp-oidc/src/main/webapp/WEB-INF/oidc.json[oidc.json] file. The `oidc.json` is used to configure the native OIDC client subsystem.
+
[source,options="nowrap"]
----
{
"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:

[source]
----
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

* https://docs.wildfly.org/30/Getting_Started_on_OpenShift.html[Getting Started with WildFly on OpenShift]
* https://docs.openshift.com/container-platform/4.13/cli_reference/openshift_cli/getting-started-cli.html[OpenShift CLI]
* https://docs.wildfly.org/30/Getting_Started_on_OpenShift.html#helm-charts[WildFly Helm Chart]
* https://www.keycloak.org/getting-started/getting-started-openshift[Getting started with Keycloak on OpenShift]
* https://www.keycloak.org/docs/latest/server_admin/index.html[Keycloak Server Administration Guide]
* https://www.keycloak.org/docs/latest/securing_apps/#_oidc[Using OpenID Connect to secure applications and services]
* https://docs.wildfly.org/30/Getting_Started_on_OpenShift.html#helm-charts[WildFly Helm Chart]

0 comments on commit 84eebb8

Please sign in to comment.