Article

Add security to a Quarkus application using Red Hat's SSO

April 21, 2022
OpenShift Quarkus Security
Olivier Rivat
Principal Engineer
Featured image: Red Hat's single sign-on X509 user certificates

Quarkus applications, like many other Java applications in use today, run on the network and require user authentication. If you are developing a Quarkus application that will run on a Red Hat OpenShift or Red Hat Enterprise Linux platform, you can add security quickly and easily through Red Hat's single sign-on (SSO) technology. This article takes you through the steps, with an example Quarkus application deployed on Red Hat Enterprise Linux.

Create a Quarkus project

The procedure in this article uses a simple example application from the Quarkus guide. You can install the example using Maven:

$ mvn io.quarkus.platform:quarkus-maven-plugin:2.7.1.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=getting-started \
    -Dextensions="resteasy"

This application is deployed in the getting-started directory, so go to that directory:

$ cd getting-started

Start the application in dev mode:

$ mvn quarkus:dev

You can make sure that the application is installed by visiting its URL http://localhost:8080/hello on your local system, either in a browser or from the command line:

$ curl -w "\n" http://localhost:8080/hello
Hello RESTEasy

Prepare Red Hat's SSO

As you saw in that listing, when you visit this URL, the sample Quarkus application will display a message that says "Hello RESTEasy". In the rest of this article, you'll learn how to secure this Quarkus URL using Red Hat's single sign-on technology. To do so, you'll need to register the Quarkus application as a Red Hat single sign-on client.

With single sign-on in place, any browser call to the Quarkus application's URL http://localhost:8080/hello will redirect the user to the single sign-on authentication server at http://localhost:8180/auth. Only after the user authenticates will they be redirected back to the greeting from the Quarkus application.

As you can tell from the URLs, the Quarkus application communicates over the default web port 8080, and Red Hat's SSO therefore has to be started on a different port. The following command starts the SSO on port 8180:

$ sh standalone.sh -Djboss.socket.binding.port-offset=100

Go to the console for Red Hat's SSO at http://localhost:8180/auth/admin/. Create a realm called quarkus and add a user named user1 to this realm (Figure 1).

You can configure a realm and a user in Red Hat's SSO console.
Figure 1. You can configure a realm and a user in Red Hat's SSO console.
Figure 1: You can configure a realm and a user in Red Hat's SSO console.

Configure the Quarkus application to authenticate with Red Hat's SSO

Also within the quarkus realm, create a client named hello (Figure 2). This corresponds to the Quarkus example application you've installed. Configure the client's access type as confidential.

The Hello application should be made confidential in Red Hat's SSO console.
Figure 2. The Hello application should be made confidential in Red Hat's SSO console.
Figure 2: The Hello application should be made confidential in Red Hat's SSO console.

This hello client uses a client ID and secret for authentication. The client secret is generated by Red Hat's SSO (Figure 3), and you need to copy the secret for later use.

Red Hat's SSO console generates a secret for the Hello application.
Figure 3. Red Hat's SSO console generates a secret for the Hello application.
Figure 3: Red Hat's SSO console generates a secret for the Hello application.

Update the Quarkus application and configuration

Your application communicates using OpenID Connect (OICD), so add the OIDC extension to your Quarkus project:

$ ./mvnw quarkus:add-extension -Dextensions="oidc"

Relaunch the application in debug mode:

$ mvn quarkus:dev

Then update the application.properties file to integrate Red Hat's SSO. Supply the appropriate values for your instance of the application when setting the following variables:

  • quarkus.oidc.client-id: Client ID of the application
  • quarkus.oidc.credentials.secret: Client secret of the application
  • quarkus.oidc.auth-server-url: URL of the application

The lines related to authentication and OIDC should look like the following, though you should swap in the proper values for your application:

quarkus.oidc.auth-server-url=http://localhost:8180/auth/realms/quarkus
quarkus.oidc.client-id=hello
quarkus.oidc.credentials.secret=ec7200d9-ccb3-4335-ac72-d2ccd2aab190
quarkus.oidc.application-type=web-app
quarkus.http.auth.permission.authenticated.paths=/*
quarkus.http.auth.permission.authenticated.policy=authenticated

For more information about these properties, see the Quarkus configuration reference.

Any further calls to this Quarkus application will now redirect the user to Red Hat's SSO for authentication.

Test the application with Red Hat's SSO

Now you can visit your application's URL again and see that authentication is in place.

Browser testing

Browser testing invokes Red Hat's SSO standard flow, which uses an OAuth 2.0 authorization code grant.

Just enter http://localhost:8080/hello into a browser window. You should be redirected to the quarkus realm in Red Hat's SSO, where you need to authenticate as user1. The following credentials are used for this example:

  • Username: user1
  • Password: password

REST API testing

When you test the application by issuing REST API queries from the command line, you invoke Red Hat's SSO direct access grant flow, which uses an OAuth 2.0 read-only password grant. It delivers an access token and a refresh token in its response to the query:

$ curl -d "client_id=hello" -d client_secret=ec7200d9-ccb3-4335-ac72-d2ccd2aab190 -d "username=user1" -d "password=password" -d "grant_type=password"  "http://localhost:8180/auth/realms/quarkus/protocol/openid-connect/token" | jq
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJoMHhOVEV1Y3drcWdSNkd3TEkxVXVHcExGLVBjTU1sWnROdDBabGYyM2hnIn0.eyJleHAiOjE2NDcyNjQ5MjIsImlhdCI6MTY0NzI2NDYyMiwianRpIjoiMWQ3MmE2NDYtNzc2NS00MWJkLWFmZmQtZjNhMmEyZGM1MTM0IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MTgwL2F1dGgvcmVhbG1zL3F1YXJrdXMiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiYzkwN2M2N2UtZDc2Ny00ZGRlLWI5N2UtOWVhMmY1NTYzOGVlIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiaGVsbG8iLCJzZXNzaW9uX3N0YXRlIjoiM2NlMWM0YWEtMDE5Yy00MGExLWFkMDEtYWJjYzJmYmNhZTEwIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwiZGVmYXVsdC1yb2xlcy1xdWFya3VzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6ImVtYWlsIHByb2ZpbGUiLCJzaWQiOiIzY2UxYzRhYS0wMTljLTQwYTEtYWQwMS1hYmNjMmZiY2FlMTAiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByZWZlcnJlZF91c2VybmFtZSI6InVzZXIxIn0.SN8xZevRdFba6oB4fWIrde4I75U5osTZsvhw6bZjGnwer-bVcTNEtlokNEk3Ro5LsqtPEQ7by7ZdCKwnWHuPPC0EGqS8p4Kskfh20DdTx1NzboabKujv3d7JnkoEg3QPNsIzhHz3Hx095mZTf9KwAXQrtUwKk50xCtfQCccWLV5RMzuVlQ0z1s4wS0t_9PF-G_aNwK-evpHTuHPUrTV_A71bLcaaRDrUSgG9ux1-yJNGa_pHoT3-au0lOMix3d6DRUesFzLkESrIK6_OIvqk4bFToQCQDq48YvZKZlOnAwDWIv5KJ8m3X3TnmUmXa_YiUugQlYmZC0Jk49tIU0_SPQ",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI0NmViYTE1Ni02ZDgyLTQ1NTMtOWI3Zi1kNjM2Yjk3MjFhYjEifQ.eyJleHAiOjE2NDcyNjY0MjIsImlhdCI6MTY0NzI2NDYyMiwianRpIjoiODY3M2RhNTUtYmNjYi00YjczLWEzYzctZjQ1ZWQyOTkyZTU4IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MTgwL2F1dGgvcmVhbG1zL3F1YXJrdXMiLCJhdWQiOiJodHRwOi8vbG9jYWxob3N0OjgxODAvYXV0aC9yZWFsbXMvcXVhcmt1cyIsInN1YiI6ImM5MDdjNjdlLWQ3NjctNGRkZS1iOTdlLTllYTJmNTU2MzhlZSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJoZWxsbyIsInNlc3Npb25fc3RhdGUiOiIzY2UxYzRhYS0wMTljLTQwYTEtYWQwMS1hYmNjMmZiY2FlMTAiLCJzY29wZSI6ImVtYWlsIHByb2ZpbGUiLCJzaWQiOiIzY2UxYzRhYS0wMTljLTQwYTEtYWQwMS1hYmNjMmZiY2FlMTAifQ.lrrq_toV92cf2mzJoWRrUs7MteCXgF_MFgdNlJ3o82A",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "3ce1c4aa-019c-40a1-ad01-abcc2fbcae10",
  "scope": "email profile"
}

It is also possible to display the details of the access token:

$ access_token=`curl -d "client_id=hello" -d client_secret=ec7200d9-ccb3-4335-ac72-d2ccd2aab190 -d "username=user1" -d "password=password" -d "grant_type=password"  "http://localhost:8180/auth/realms/quarkus/protocol/openid-connect/token" | jq -r .access_token`

 echo $access_token | cut -d"." -f2 | base64 -d | jq
base64: invalid input
{
  "exp": 1647265083,
  "iat": 1647264783,
  "jti": "073295d8-1829-4f01-a58f-0d6497782ddd",
  "iss": "http://localhost:8180/auth/realms/quarkus",
  "aud": "account",
  "sub": "c907c67e-d767-4dde-b97e-9ea2f55638ee",
  "typ": "Bearer",
  "azp": "hello",
  "session_state": "4b15f101-efce-4c8e-8206-beba5e06e7fc",
  "acr": "1",
  "allowed-origins": [
    "http://localhost:8080"
  ],
  "realm_access": {
    "roles": [
      "offline_access",
      "default-roles-quarkus",
      "uma_authorization"
    ]
  },
  "resource_access": {
    "account": {
      "roles": [
        "manage-account",
        "manage-account-links",
        "view-profile"
      ]
    }
  },
  "scope": "email profile",
  "sid": "4b15f101-efce-4c8e-8206-beba5e06e7fc",
  "email_verified": false,
  "preferred_username": "user1"
}

Conclusion

This simple example has shown how easy it is to add security to a Quarkus application with Red Hat's SSO. Quarkus applications can be secured with Red Hat's SSO just as enterprise Java applications can.

For further information about Quarkus application security, please read the security sections of the Quarkus guide. To learn more about using Red Hat's single sign-on technology, check out my earlier articles on Red Hat Developer:

Comments