Using JBoss EAP on OpenShift Container Platform

Procedure

1. Copy the following Dockerfile contents as provided:

   # Use EAP 8 Builder image to create a JBoss EAP 8 server
   # with its default configuration
   
   FROM registry.redhat.io/jboss-eap-8/eap8-openjdk17-builder-openshift-rhel8:latest AS builder
   
   # Set up environment variables for provisioning. 

   1

   
   ENV GALLEON_PROVISION_FEATURE_PACKS org.jboss.eap:wildfly-ee-galleon-pack,org.jboss.eap.cloud:eap-cloud-galleon-pack
   ENV GALLEON_PROVISION_LAYERS cloud-default-config
   # Specify the JBoss EAP version  

   2

   
   ENV GALLEON_PROVISION_CHANNELS org.jboss.eap.channels:eap-8.0
   
   
   # Run the assemble script to provision the server.
   RUN /usr/local/s2i/assemble
   
   # Copy the JBoss EAP 8 server from the builder image to the runtime image.
   FROM registry.redhat.io/jboss-eap-8/eap8-openjdk17-runtime-openshift-rhel8:latest AS runtime
   
   # Set appropriate ownership and permissions.
   COPY --from=builder --chown=jboss:root $JBOSS_HOME $JBOSS_HOME
   
   # Steps to add:
   # (1) COPY the WAR/EAR to $JBOSS_HOME/standalone/deployments
   #       with the jboss:root user. For example:
   #     COPY --chown=jboss:root my-app.war $JBOSS_HOME/standalone/deployments 

   3

   
   # (2) (optional) server modification. You can modify EAP server configuration:
   #
   #       * invoke management operations. For example
   #
   #        RUN $JBOSS_HOME/bin/jboss-cli.sh --commands="embed-server,/system-property=Foo:add(value=Bar)"
   #
   #        First operation must always be embed-server.
   #
   #       * copy a modified standalone.xml in $JBOSS_HOME/standalone/configuration/
   #          for example
   #
   #      COPY --chown=jboss:root standalone.xml  $JBOSS_HOME/standalone/configuration
   
   # Ensure appropriate permissions for the copied files.
   RUN chmod -R ug+rwX $JBOSS_HOME

   Copy to Clipboard Toggle word wrap

   1

   You can specify the MAVEN_MIRROR_URL environment variable, which is used by the JBoss EAP Maven plugin internally within the image. For more information, see Artifact repository mirrors.

   2

   You do not need to update this Dockerfile for any of the minor releases. Specify the JBoss EAP version in the GALLEON_PROVISION_CHANNELS environment variable if you want to use a specific version. For more information, see Environment variables.

   3

   Modify the copied Dockerfile to include your WAR file in the container. For example:

   COPY --chown=jboss:root <my-app.war> $JBOSS_HOME/standalone/deployments

   Copy to Clipboard Toggle word wrap

   Replace <myapp.war> with the path to the Web archive you want to add to the image.

2. Build the application image using podman:

   $ podman build -t my-app .

   Copy to Clipboard Toggle word wrap

   After the command is executed, the my-app container image is ready to be deployed on OpenShift.

3. Upload your container image to one of the following options:

   • Your internal registry that is accessible from OpenShift.
   • The OpenShift registry by pushing the image directly from the machine where it was built. For more information, see How to push a container image into the image registry in RHOCP 4.
4. When deploying your image from the registry, use deployment strategies such as Helm charts, Operator, or Deployment. Select your preferred method and use either the full image URL or ImageStreams based on your requirements. For more information, see Using Helm charts to build and deploy JBoss EAP applications on OpenShift.

Procedure

1. Set up a Maven project using the mvn command. The command creates the directory structure for the project and the pom.xml configuration file.

   Syntax

   $ mvn archetype:generate \
   -DgroupId=${group-to-which-your-application-belongs} \
   -DartifactId=${name-of-your-application} \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

   Copy to Clipboard Toggle word wrap

   Example

   $ mvn archetype:generate \
   -DgroupId=com.example.app \
   -DartifactId=simple-webapp-example \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

   Copy to Clipboard Toggle word wrap

2. Navigate to the application root directory:

   Syntax

   $ cd <name-of-your-application>

   Copy to Clipboard Toggle word wrap

   Example

   $ cd simple-webapp-example

   Copy to Clipboard Toggle word wrap

3. Replace the content of the generated pom.xml file with the following text:

   <?xml version="1.0" encoding="UTF-8"?>
   
   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>com.example.app</groupId>
     <artifactId>simple-webapp-example</artifactId>
     <version>1.0-SNAPSHOT</version>
     <packaging>war</packaging>
   
     <name>simple-webapp-example Maven Webapp</name>
     <!-- FIXME change it to the project's website -->
     <url>http://www.example.com</url>
   
     <properties>
       <maven.compiler.source>11</maven.compiler.source>
       <maven.compiler.target>11</maven.compiler.target>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <version.maven.war.plugin>3.3.2</version.maven.war.plugin>
       <version.eap.plugin>1.0.0.Final-redhat-00014</version.eap.plugin>
       <version.server>8.0.0.GA-redhat-00009</version.server>
       <version.bom.ee>${version.server}</version.bom.ee>
     </properties>
   
   
     <repositories>
       <repository>
           <id>jboss</id>
           <url>https://maven.repository.redhat.com/ga/</url>
           <snapshots>
               <enabled>false</enabled>
           </snapshots>
       </repository>
     </repositories>
   
     <pluginRepositories>
       <pluginRepository>
           <id>jboss</id>
           <url>https://maven.repository.redhat.com/ga/</url>
           <snapshots>
               <enabled>false</enabled>
           </snapshots>
       </pluginRepository>
     </pluginRepositories>
   
     <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>org.jboss.bom</groupId>
           <artifactId>jboss-eap-ee-with-tools</artifactId>
           <version>${version.bom.ee}</version>
           <type>pom</type>
           <scope>import</scope>
         </dependency>
       </dependencies>
     </dependencyManagement>
   
     <dependencies>
       <dependency>
         <groupId>jakarta.servlet</groupId>
         <artifactId>jakarta.servlet-api</artifactId>
         <scope>provided</scope>
       </dependency>
       <dependency>
         <groupId>org.wildfly.security</groupId>
         <artifactId>wildfly-elytron-auth-server</artifactId>
       </dependency>
     </dependencies>
   
   <build>
       <finalName>${project.artifactId}</finalName>
       <plugins>
           <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-war-plugin</artifactId>
               <version>${version.maven.war.plugin}</version>
           </plugin>
           <plugin>
               <groupId>org.jboss.eap.plugins</groupId>
               <artifactId>eap-maven-plugin</artifactId>
               <version>${version.eap.plugin}</version>
               <configuration>
                   <channels>
                       <channel>
                           <manifest>
                               <groupId>org.jboss.eap.channels</groupId>
                               <artifactId>eap-8.0</artifactId>
                           </manifest>
                       </channel>
                   </channels>
                   <feature-packs>
                       <feature-pack>
                           <location>org.jboss.eap:wildfly-ee-galleon-pack</location>
                       </feature-pack>
                       <feature-pack>
                           <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location>
                       </feature-pack>
                   </feature-packs>
                   <layers>
                       <layer>cloud-server</layer>
                       <layer>elytron-oidc-client</layer>
                   </layers>
                   <galleon-options>
                           <jboss-fork-embedded>true</jboss-fork-embedded>
                   </galleon-options>
               </configuration>
               <executions>
                   <execution>
                       <goals>
                           <goal>package</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
       </plugins>
   </build>
   </project>

   Copy to Clipboard Toggle word wrap
   Note
   • <version.eap.plugin>1.0.0.Final-redhat-00014</version.eap.plugin> is an example version of JBoss EAP Maven plugin. See the Red Hat Maven repository for more information on JBoss EAP Maven plugin releases: https://maven.repository.redhat.com/earlyaccess/all/org/jboss/eap/plugins/eap-maven-plugin/.

4. Create a directory to store the Java files.

   Syntax

   $ mkdir -p src/main/java/<path_based_on_artifactID>

   Copy to Clipboard Toggle word wrap

   Example

   $ mkdir -p src/main/java/com/example/app

   Copy to Clipboard Toggle word wrap

5. Navigate to the new directory.

   Syntax

   $ cd src/main/java/<path_based_on_artifactID>

   Copy to Clipboard Toggle word wrap

   Example

   $ cd src/main/java/com/example/app

   Copy to Clipboard Toggle word wrap

6. Create a file SecuredServlet.java with the following content:

   package com.example.app;
   
   import java.io.IOException;
   import java.io.PrintWriter;
   import java.security.Principal;
   import java.util.ArrayList;
   import java.util.Collection;
   import java.util.Iterator;
   import java.util.List;
   import java.util.Set;
   
   import jakarta.servlet.ServletException;
   import jakarta.servlet.annotation.WebServlet;
   import jakarta.servlet.http.HttpServlet;
   import jakarta.servlet.http.HttpServletRequest;
   import jakarta.servlet.http.HttpServletResponse;
   import org.wildfly.security.auth.server.SecurityDomain;
   import org.wildfly.security.auth.server.SecurityIdentity;
   import org.wildfly.security.authz.Attributes;
   import org.wildfly.security.authz.Attributes.Entry;
   /**
    * A simple secured HTTP servlet. It returns the user name and
    * attributes obtained from the logged-in user's Principal. If
    * there is no logged-in user, it returns the text
    * "NO AUTHENTICATED USER".
    */
   
   @WebServlet("/secured")
   public class SecuredServlet extends HttpServlet {
   
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
           try (PrintWriter writer = resp.getWriter()) {
   
           	Principal user = req.getUserPrincipal();
           	SecurityIdentity identity = SecurityDomain.getCurrent().getCurrentSecurityIdentity();
           	Attributes identityAttributes = identity.getAttributes();
           	Set <String> keys = identityAttributes.keySet();
           	String attributes = "<ul>";
   
           	for (String attr : keys) {
           		attributes += "<li> " +  attr + " : " + identityAttributes.get(attr).toString() + "</li>";
           	}
   
           	attributes+="</ul>";
           	writer.println("<html>");
           	writer.println("  <head><title>Secured Servlet</title></head>");
           	writer.println("  <body>");
           	writer.println("    <h1>Secured Servlet</h1>");
           	writer.println("    <p>");
           	writer.print(" Current Principal '");
           	writer.print(user != null ? user.getName() : "NO AUTHENTICATED USER");
           	writer.print("'");
           	writer.print(user != null ? "\n" + attributes : "");
           	writer.println("    </p>");
           	writer.println("  </body>");
           	writer.println("</html>");
           }
       }
   
   }

   Copy to Clipboard Toggle word wrap

7. Configure the application’s web.xml to protect the application resources.

   Example

   <?xml version="1.0" encoding="UTF-8"?>
   
   <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
       metadata-complete="false">
   
       <security-constraint>
           <web-resource-collection>
               <web-resource-name>secured</web-resource-name>
               <url-pattern>/secured</url-pattern>
           </web-resource-collection>
   
           <auth-constraint>
               <role-name>Users</role-name>
           </auth-constraint>
       </security-constraint>
   
       <login-config>
           <auth-method>OIDC</auth-method>
       </login-config>
   
       <security-role>
           <role-name>*</role-name>
       </security-role>
   </web-app>

   Copy to Clipboard Toggle word wrap

   In this example, only the users with the role Users can access the application.

Procedure

1. Deploy your application code to Git Repository.

2. Create a secret containing the OIDC configuration.

   1. Create a file named oidc-secret.yaml using the following content:

      apiVersion: v1
      kind: Secret
      metadata:
        name: oidc-secret
      type: Opaque
      stringData:
        OIDC_PROVIDER_NAME: rh-sso
        OIDC_USER_NAME: demo
        OIDC_USER_PASSWORD: demo
        OIDC_SECURE_DEPLOYMENT_SECRET: mysecret

      Copy to Clipboard Toggle word wrap

   2. Use the following command to create a secret:

      $ oc apply -f oidc-secret.yaml

      Copy to Clipboard Toggle word wrap

3. Create a file named helm.yaml using the following content:

   build:
     uri: [URL TO YOUR GIT REPOSITORY]
   deploy:
     envFrom:
   	- secretRef:
       	  name: oidc-secret

   Copy to Clipboard Toggle word wrap

4. Deploy the example application using JBoss EAP Helm charts:

   $ helm install eap-oidc-test-app -f helm.yaml jboss-eap/eap8

   Copy to Clipboard Toggle word wrap

5. Add the environment variables to the oidc-secret.yaml file to configure the OIDC provider URL and application hostname.

   yaml
   stringData:
     ...
     OIDC_HOSTNAME_HTTPS: <host of the application>
     OIDC_PROVIDER_URL: https://<host of the SSO provider>/realms/JBossEAP

   Copy to Clipboard Toggle word wrap

   The value for OIDC_HOSTNAME_HTTPS corresponds to the following output:

   echo $(oc get route eap-oidc-test-app --template='{{ .spec.host }}')

   Copy to Clipboard Toggle word wrap

   The value for OIDC_PROVIDER_URL corresponds to the following output:

   echo https://$(oc get route sso --template='{{ .spec.host }}')/realms/JBossEAP

   Copy to Clipboard Toggle word wrap

   A route discovery attempt is made if OIDC_HOSTNAME_HTTP(S) is not set. To enable route discovery, the OpenShift user must be able to list the route resources. For example, to create and associate the routeview role with the view user, use the following oc command:

   $ oc create role <role-name> --verb=list --resource=route
   
   $ oc adm policy add-role-to-user <role-name> <user-name> --role-namespace=<your namespace>

   Copy to Clipboard Toggle word wrap
6. Update the secret with oc apply -f oidc-secret.yaml.

7. Deploy the application again to ensure OpenShift uses the new environment variables:

   $ oc rollout restart deploy eap-oidc-test-app

   Copy to Clipboard Toggle word wrap

Verification

1. In your browser, navigate to https://<eap-oidc-test-app route>/.

   You will be redirected to Red Hat build of Keycloak login page.

2. Access the secured servlet.

3. Log in with the following credentials:

   username: demo
   password: demo

   Copy to Clipboard Toggle word wrap

   A page appears that contains the Principal ID.

Procedure

1. Create a Single Sign-On realm, users, and roles.

2. Generate the key and certificate by using the Java keytool command:

   keytool -genkeypair -alias saml-app -storetype PKCS12 -keyalg RSA -keysize 2048 -keystore keystore.p12 -storepass password -dname "CN=saml-basic-auth,OU=EAP SAML Client,O=Red Hat EAP QE,L=MB,S=Milan,C=IT" -ext ku:c=dig,keyEncipherment -validity 365

   Copy to Clipboard Toggle word wrap

3. Import the keystore into a Java KeyStore (JKS) format:

   keytool -importkeystore -deststorepass password -destkeystore keystore.jks -srckeystore keystore.p12 -srcstoretype PKCS12 -srcstorepass password

   Copy to Clipboard Toggle word wrap

4. Create a secret in OpenShift for the keystore:

   $ oc create secret generic saml-app-secret --from-file=keystore.jks=./keystore.jks --type=opaque

   Copy to Clipboard Toggle word wrap

Procedure

1. Set up a Maven project by using the mvn command. This command creates both the directory structure for the project and the pom.xml configuration file.

   Syntax

   $ mvn archetype:generate \
   -DgroupId=${group-to-which-your-application-belongs} \
   -DartifactId=${name-of-your-application} \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

   Copy to Clipboard Toggle word wrap

   Example

   $ mvn archetype:generate \
   -DgroupId=com.example.app \
   -DartifactId=simple-webapp-example \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

   Copy to Clipboard Toggle word wrap

2. Navigate to the application root directory:

   Syntax

   $ cd <name-of-your-application>

   Copy to Clipboard Toggle word wrap

   Example

   $ cd simple-webapp-example

   Copy to Clipboard Toggle word wrap

3. Replace the content of the generated pom.xml file with the following text:

   <?xml version="1.0" encoding="UTF-8"?>
   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>com.example.app</groupId>
     <artifactId>simple-webapp-example</artifactId>
     <version>1.0-SNAPSHOT</version>
     <packaging>war</packaging>
   
     <name>simple-webapp-example Maven Webapp</name>
     <!-- FIXME change it to the project's website -->
     <url>http://www.example.com</url>
   
     <properties>
       <maven.compiler.source>11</maven.compiler.source>
       <maven.compiler.target>11</maven.compiler.target>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <version.maven.war.plugin>3.3.2</version.maven.war.plugin>
       <version.eap.plugin>1.0.0.Final-redhat-00014</version.eap.plugin>
       <version.server>8.0.0.GA-redhat-00009</version.server>
       <version.bom.ee>${version.server}</version.bom.ee>
     </properties>
   
     <repositories>
       <repository>
           <id>jboss</id>
           <url>https://maven.repository.redhat.com/ga/</url>
           <snapshots>
               <enabled>false</enabled>
           </snapshots>
       </repository>
     </repositories>
   
     <pluginRepositories>
       <pluginRepository>
           <id>jboss</id>
           <url>https://maven.repository.redhat.com/ga/</url>
           <snapshots>
               <enabled>false</enabled>
           </snapshots>
       </pluginRepository>
     </pluginRepositories>
   
     <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>org.jboss.bom</groupId>
           <artifactId>jboss-eap-ee-with-tools</artifactId>
           <version>${version.bom.ee}</version>
           <type>pom</type>
           <scope>import</scope>
         </dependency>
       </dependencies>
     </dependencyManagement>
   
     <dependencies>
       <dependency>
         <groupId>jakarta.servlet</groupId>
         <artifactId>jakarta.servlet-api</artifactId>
         <scope>provided</scope>
       </dependency>
       <dependency>
         <groupId>org.wildfly.security</groupId>
         <artifactId>wildfly-elytron-auth-server</artifactId>
       </dependency>
     </dependencies>
   
     <build>
       <finalName>${project.artifactId}</finalName>
       <plugins>
           <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-war-plugin</artifactId>
               <version>${version.maven.war.plugin}</version>
           </plugin>
           <plugin>
               <groupId>org.jboss.eap.plugins</groupId>
               <artifactId>eap-maven-plugin</artifactId>
               <version>${version.eap.plugin}</version>
               <configuration>
                   <channels>
                       <channel>
                           <manifest>
                               <groupId>org.jboss.eap.channels</groupId>
                               <artifactId>eap-8.0</artifactId>
                           </manifest>
                       </channel>
                   </channels>
                   <feature-packs>
                       <feature-pack>
                           <location>org.jboss.eap:wildfly-ee-galleon-pack</location>
                       </feature-pack>
                       <feature-pack>
                           <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location>
                       </feature-pack>
                       <feature-pack>
                           <location>org.keycloak:keycloak-saml-adapter-galleon-pack</location>
                       </feature-pack>
                   </feature-packs>
                   <layers>
                       <layer>cloud-server</layer>
                       <layer>keycloak-saml</layer>
                   </layers>
                   <galleon-options>
                       <jboss-fork-embedded>true</jboss-fork-embedded>
                   </galleon-options>
               </configuration>
               <executions>
                   <execution>
                       <goals>
                           <goal>package</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
       </plugins>
     </build>
   </project>

   Copy to Clipboard Toggle word wrap
   Note
   • <version.eap.plugin>1.0.0.Final-redhat-00014</version.eap.plugin> is an example version of JBoss EAP Maven plugin. See the Red Hat Maven repository for more information on JBoss EAP Maven plugin releases: https://maven.repository.redhat.com/earlyaccess/all/org/jboss/eap/plugins/eap-maven-plugin/.

4. Create a directory to store the Java files.

   Syntax

   $ mkdir -p src/main/java/<path_based_on_artifactID>

   Copy to Clipboard Toggle word wrap

   Example

   $ mkdir -p src/main/java/com/example/app

   Copy to Clipboard Toggle word wrap

5. Navigate to the new directory.

   Syntax

   $ cd src/main/java/<path_based_on_artifactID>

   Copy to Clipboard Toggle word wrap

   Example

   $ cd src/main/java/com/example/app

   Copy to Clipboard Toggle word wrap

6. Create a file named SecuredServlet.java that contains the following settings:

   package com.example.app;
   
   import java.io.IOException;
   import java.io.PrintWriter;
   import java.security.Principal;
   import java.util.Set;
   
   import jakarta.servlet.ServletException;
   import jakarta.servlet.annotation.WebServlet;
   import jakarta.servlet.http.HttpServlet;
   import jakarta.servlet.http.HttpServletRequest;
   import jakarta.servlet.http.HttpServletResponse;
   import org.wildfly.security.auth.server.SecurityDomain;
   import org.wildfly.security.auth.server.SecurityIdentity;
   import org.wildfly.security.authz.Attributes;
   /**
    * A simple secured HTTP servlet. It returns the user name and
    * attributes obtained from the logged-in user's Principal. If
    * there is no logged-in user, it returns the text
    * "NO AUTHENTICATED USER".
    */
   
   @WebServlet("/secured")
   public class SecuredServlet extends HttpServlet {
   
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
           try (PrintWriter writer = resp.getWriter()) {
   
           	Principal user = req.getUserPrincipal();
           	SecurityIdentity identity = SecurityDomain.getCurrent().getCurrentSecurityIdentity();
           	Attributes identityAttributes = identity.getAttributes();
           	Set <String> keys = identityAttributes.keySet();
           	String attributes = "<ul>";
   
           	for (String attr : keys) {
           		attributes += "<li> " +  attr + " : " + identityAttributes.get(attr).toString() + "</li>";
           	}
   
           	attributes+="</ul>";
           	writer.println("<html>");
           	writer.println("  <head><title>Secured Servlet</title></head>");
           	writer.println("  <body>");
           	writer.println("    <h1>Secured Servlet</h1>");
           	writer.println("    <p>");
           	writer.print(" Current Principal '");
           	writer.print(user != null ? user.getName() : "NO AUTHENTICATED USER");
           	writer.print("'");
           	writer.print(user != null ? "\n" + attributes : "");
           	writer.println("    </p>");
           	writer.println("  </body>");
           	writer.println("</html>");
           }
       }
   
   }

   Copy to Clipboard Toggle word wrap

7. Create the directory structure for the web.xml file:

   mkdir -p src/main/webapp/WEB-INF
   cd src/main/webapp/WEB-INF

   Copy to Clipboard Toggle word wrap

8. Configure the application’s web.xml file to protect the application resources.

   Example

   <?xml version="1.0" encoding="UTF-8"?>
   <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
       metadata-complete="false">
   
       <security-constraint>
           <web-resource-collection>
               <web-resource-name>secured</web-resource-name>
               <url-pattern>/secured</url-pattern>
           </web-resource-collection>
   
           <auth-constraint>
               <role-name>user</role-name>
           </auth-constraint>
       </security-constraint>
   
       <login-config>
           <auth-method>KEYCLOAK-SAML</auth-method>
       </login-config>
   
       <security-role>
           <role-name>user</role-name>
       </security-role>
   </web-app>

   Copy to Clipboard Toggle word wrap

   In this example, only users with the user role can access the application.

1. Create a Git repository such as https://github.com/your-username/simple-webapp-example. For more information about remote repositories and Git, see Getting started with Git - About remote repositories.

2. From the root folder of the application, run the following Git commands:

   git init -b main
   git add pom.xml src
   git commit -m "First commit"
   git remote add origin git@github.com:your-username/simple-webapp-example.git
   git remote -v
   git push -u origin main

   Copy to Clipboard Toggle word wrap

Procedure

1. Deploy your application code to the Git Repository.

2. Create an OpenShift secret containing the required environment variables:

   apiVersion: v1
   kind: Secret
   metadata:
     name: saml-secret
   type: Opaque
   stringData:
     SSO_REALM: "saml-basic-auth"
     SSO_USERNAME: "client-admin"
     SSO_PASSWORD: "client-admin"
     SSO_SAML_CERTIFICATE_NAME: "saml-app"
     SSO_SAML_KEYSTORE: "keystore.jks"
     SSO_SAML_KEYSTORE_PASSWORD: "password"
     SSO_SAML_KEYSTORE_DIR: "/etc/sso-saml-secret-volume"
     SSO_SAML_LOGOUT_PAGE: "/simple-webapp-example"
     SSO_DISABLE_SSL_CERTIFICATE_VALIDATION: "true"

   Copy to Clipboard Toggle word wrap
3. Save the provided YAML content to a file, such as saml-secret.yaml.

4. Apply the saved YAML file by using the following command:

   oc apply -f saml-secret.yaml

   Copy to Clipboard Toggle word wrap

5. Create a file named helm.yaml that contains the following settings:

   build:
     uri: [WEB ADDRESS TO YOUR GIT REPOSITORY]
   deploy:
     volumes:
       - name: saml-keystore-volume
         secret:
           secretName: saml-app-secret
     volumeMounts:
       - name: saml-keystore-volume
         mountPath: /etc/sso-saml-secret-volume
         readOnly: true
     envFrom:
       - secretRef:
           name: saml-secret

   Copy to Clipboard Toggle word wrap
   Note

   Specify the web address in the HTTP format, such as http://www.redhat.com. If you are using a maven mirror, specify the web address as follows:

   build:
     uri: [WEB ADDRESS TO YOUR GIT REPOSITORY]
     env:
       - name: "MAVEN_MIRROR_URL"
         value: "http://..."

   Copy to Clipboard Toggle word wrap

6. Deploy the example application by using JBoss EAP Helm charts:

   $ helm install saml-app -f helm.yaml jboss-eap/eap8

   Copy to Clipboard Toggle word wrap

7. Add the environment variables to the saml-secret.yaml file to configure the Keycloak server URL and application route:

   stringData:
     ...
     HOSTNAME_HTTPS: <saml-app application route>
     SSO_URL: https://<host of the Keycloak server>

   Copy to Clipboard Toggle word wrap

   Replace <saml-app application route> and <host of the Keycloak server> with the appropriate values.

   The value for HOSTNAME_HTTPS corresponds to the following output:

   echo $(oc get route saml-app --template='{{ .spec.host }}')

   Copy to Clipboard Toggle word wrap

   The value for SSO_URL corresponds to the following output:

   echo https://$(oc get route sso --template='{{ .spec.host }}')

   Copy to Clipboard Toggle word wrap
   Note

   If you cannot use this command, use oc get routes to list the available routes and select the route to your Red Hat build of Keycloak instance.

8. Update the secret with oc apply -f saml-secret.yaml.

Verification

1. Deploy the application again to ensure that OpenShift uses the new environment variables:

   $ oc rollout restart deploy saml-app

   Copy to Clipboard Toggle word wrap

2. In a browser, navigate to the application URL. For example, https://<saml-app route>/simple-webapp-example.

   You are redirected to the Red Hat build of Keycloak login page.

3. To get the web address, use the following command to access the secured servlet:

   echo https://$(oc get route saml-app --template='{{ .spec.host }}')/simple-webapp-example/secured

   Copy to Clipboard Toggle word wrap

4. Log in with the following credentials:

   username: demo
   password: demo

   Copy to Clipboard Toggle word wrap

   A page is displayed that contains the Principal ID.

Procedure

1. Log in to the Red Hat build of Keycloak admin console using the URL: https://<SSO route>/.

2. Create a realm in Red Hat build of Keycloak; for example, saml-basic-auth. You can subsequently use this realm to create the required users, roles, and a client.

   For more information, see Creating a realm.

3. Create a role within the saml-basic-auth realm. For example, user.

   For more information, see Creating a realm role.

4. Create a user. For example, demo.

   For more information, see Creating users.

5. Create a password for the user. For example, demo.

   Ensure that the password is not temporary. For more information, see Setting a password for a user.

6. Assign the user role to the demo user for login access.

   For more information, see Assigning role mappings.

7. Create a user. For example, client-admin.

   To create the SAML client in the Keycloak server when the JBoss EAP server starts, you can use the client-admin user, which requires additional privileges. For more information, see Creating users.

8. Create a password for the user. For example, client-admin.

   Ensure that the password is not temporary. For more information, see Setting a password for a user.

9. Select realm-management from the Client Roles drop down list.

10. Assign the roles create-client, manage-clients, and manage-realm to the client-admin user.

    For more information, see Assigning role mappings.

Procedure

1. Specify a volume in the deploy.volumes field and configure the secret to be used. You must provide the name of the volume and the secretName of the secret:

   volumes:
     - name: eap-jgroups-keystore-volume
       secret:
         secretName: eap-app-secret

   Copy to Clipboard Toggle word wrap

2. Mount the volume on the file system using the deploy.volumeMounts in the deployment configuration:

   volumeMounts:
     - name: eap-jgroups-keystore-volume
       mountPath: /etc/jgroups-encrypt-secret-volume
       readOnly: true

   Copy to Clipboard Toggle word wrap

Procedure

1. In the OpenShift Container Platform web console, navigate to Operators→ OperatorHub.
2. Scroll down or type EAP into the Filter by keyword box to find the EAP operator.
3. Select JBoss EAP operator and click Install.

4. On the Create Operator Subscription page:

   1. Select one of the following:

      • All namespaces on the cluster (default) installs the operator in the default openshift-operators namespace to watch and be made available to all namespaces in the cluster. This option is not always available.
      • A specific namespace on the cluster installs the operator in a specific, single namespace that you choose. The operator is made available for use only in this single namespace.
   2. Select an Update Channel.
   3. Select Automatic or Manual approval strategy, as described earlier.

5. Click Subscribe to make the EAP operator available to the selected namespaces on this OpenShift Container Platform cluster.

   1. If you selected a manual approval strategy, the subscription’s upgrade status remains Upgrading until you review and approve its install plan. After you approve the install plan on the Install Plan page, the subscription upgrade status moves to Up to date.
   2. If you selected an automatic approval strategy, the upgrade status moves to Up to date without intervention.

6. After the subscription’s upgrade status is Up to date, select Operators → Installed Operators to verify that the EAP ClusterServiceVersion (CSV) shows up and its Status changes to InstallSucceeded in the relevant namespace.

   Note

   For the All namespaces…​ installation mode, the status displayed is InstallSucceeded in the openshift-operators namespace. In other namespaces the status displayed is Copied. . If the Status field does not change to InstallSucceeded, check the logs in any pod in the openshift-operators project (or other relevant namespace if A specific namespace…​ installation mode was selected) on the Workloads → Pods page that are reporting issues to troubleshoot further.

Procedure

1. View the list of operators available to the cluster from the OperatorHub:

   $ oc get packagemanifests -n openshift-marketplace | grep eap
   NAME        CATALOG               AGE
   ...
   eap         Red Hat Operators     43d
   ...

   Copy to Clipboard Toggle word wrap

2. Create a Subscription object YAML file (for example, eap-operator-sub.yaml) to subscribe a namespace to your EAP operator. The following is an example Subscription object YAML file:

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: eap
     namespace: openshift-operators
   spec:
     channel: stable
     installPlanApproval: Automatic
     name: eap 

   1

   
     source:  redhat-operators 

   2

   
     sourceNamespace: openshift-marketplace

   Copy to Clipboard Toggle word wrap

   1

   Name of the operator to subscribe to.

   2

   The EAP operator is provided by the redhat-operators CatalogSource.

   For information about channels and approval strategy, see the web console version of this procedure.

3. Create the Subscription object from the YAML file:

   $ oc apply -f eap-operator-sub.yaml
   $ oc get csv -n openshift-operators
   NAME                  DISPLAY     VERSION   REPLACES   PHASE
   eap-operator.v1.0.0   JBoss EAP   1.0.0                Succeeded

   Copy to Clipboard Toggle word wrap

   The EAP operator is successfully installed. At this point, the OLM is aware of the EAP operator. A ClusterServiceVersion (CSV) for the operator appears in the target namespace, and APIs provided by the EAP operator is available for creation.

Procedure

1. Open your web browser and log on to OperatorHub.
2. Select the Project or namespace you want to use for your Java application.
3. Navigate to Installed Operator and select JBoss EAP operator.
4. On the Overview tab, click the Create Instance link.

5. Specify the application image details.

   The application image specifies the Docker image that contains the Java application. The image must be built using the JBoss EAP for OpenShift Source-to-Image (S2I) build image. If the applicationImage field corresponds to an imagestreamtag, any change to the image triggers an automatic upgrade of the application.

   You can provide any of the following references of the JBoss EAP for OpenShift application image:

   • The name of the image: mycomp/myapp
   • A tag: mycomp/myapp:1.0
   • A digest: mycomp/myapp:@sha256:0af38bc38be93116b6a1d86a9c78bd14cd527121970899d719baf78e5dc7bfd2
   • An imagestreamtag: my-app:latest

6. Specify the size of the application. For example:

   spec:
     replicas:2

   Copy to Clipboard Toggle word wrap

7. Configure the application environment using the env spec. The Environment variables can come directly from values, such as POSTGRESQL_SERVICE_HOST or from Secret objects, such as POSTGRESQL_USER. For example:

   spec:
     env:
     - name: POSTGRESQL_SERVICE_HOST
       value: postgresql
     - name: POSTGRESQL_SERVICE_PORT
       value: '5432'
     - name: POSTGRESQL_DATABASE
       valueFrom:
         secretKeyRef:
           key: database-name
           name: postgresql
     - name: POSTGRESQL_USER
       valueFrom:
         secretKeyRef:
           key: database-user
           name: postgresql
     - name: POSTGRESQL_PASSWORD
       valueFrom:
         secretKeyRef:
           key: database-password
           name: postgresql

   Copy to Clipboard Toggle word wrap

8. Complete the following optional configurations that are relevant to your application deployment:

   • Specify the storage requirements for the server data directory. For more information, see Configuring Persistent Storage for Applications.

   • Specify the name of the Secret you created in WildFlyServerSpec to mount it as a volume in the pods running the application. For example:

     spec:
       secrets:
         - my-secret

     Copy to Clipboard Toggle word wrap

     The Secret is mounted at /etc/secrets/<secret name> and each key/value is stored as a file. The name of the file is the key and the content is the value. The Secret is mounted as a volume inside the pod. The following example demonstrates commands that you can use to find key values:

     $ ls /etc/secrets/my-secret/
     my-key  my-password
     $ cat /etc/secrets/my-secret/my-key
     devuser
     $ cat /etc/secrets/my-secret/my-password
     my-very-secure-pasword

     Copy to Clipboard Toggle word wrap
     Note

     Modifying a Secret object might lead to project inconsistencies. Instead of modifying an existing Secret object, Red Hat recommends creating a new object with the same content as that of the old one. You can then update the content as required and change the reference in operator custom resource (CR) from old to new. This is considered a new CR update and the pods are reloaded.

   • Specify the name of the ConfigMap you created in WildFlyServerSpec to mount it as a volume in the pods running the application. For example:

     spec:
       configMaps:
       - my-config

     Copy to Clipboard Toggle word wrap

     The ConfigMap is mounted at /etc/configmaps/<configmap name> and each key/value is stored as a file. The name of the file is the key and the content is the value. The ConfigMap is mounted as a volume inside the pod. To find the key values:

     $ ls /etc/configmaps/my-config/
     key1 key2
     $ cat /etc/configmaps/my-config/key1
     value1
     $ cat /etc/configmaps/my-config/key2
     value2

     Copy to Clipboard Toggle word wrap
     Note

     Modifying a ConfigMap might lead to project inconsistencies. Instead of modifying an existing ConfigMap, Red Hat recommends creating a new ConfigMap with the same content as that of the old one. You can then update the content as required and change the reference in operator custom resource (CR) from old to new. This is considered a new CR update and the pods are reloaded.

   • If you choose to have your own standalone ConfigMap, provide the name of the ConfigMap as well as the key for the standalone.xml file:

       standaloneConfigMap:
         name: clusterbench-config-map
         key: standalone.xml

     Copy to Clipboard Toggle word wrap
     Note

     Creating a ConfigMap from the standalone.xml file is not supported in JBoss EAP 8.0.

   • If you want to disable the default HTTP route creation in OpenShift, set disableHTTPRoute to true:

     spec:
       disableHTTPRoute: true

     Copy to Clipboard Toggle word wrap

Procedure

1. In the OpenShift Container Platform web console, navigate to Monitoring→ Metrics.
2. On the Metrics screen, type the name of your application in the text box to select your application. The metrics for your application appear on the screen.

Procedure

1. From the Operators→ Installed Operators page, select JBoss EAP.
2. On the right-hand side of the Operator Details page, select Uninstall Operator from the Actions drop-down menu.
3. When prompted by the Remove Operator Subscription window, optionally select the Also completely remove the Operator from the selected namespace check box if you want all components related to the installation to be removed. This removes the CSV, which in turn removes the pods, deployments, custom resource definitions (CRDs), and custom resources (CRs) associated with the operator.
4. Click Remove. The EAP operator stops running and no longer receives updates.

Procedure

1. Check the current version of the EAP operator subscription in the currentCSV field:

   $ oc get subscription eap-operator -n openshift-operators -o yaml | grep currentCSV
     currentCSV: eap-operator.v1.0.0

   Copy to Clipboard Toggle word wrap

2. Delete the EAP operator’s subscription:

   $ oc delete subscription eap-operator -n openshift-operators
   subscription.operators.coreos.com "eap-operator" deleted

   Copy to Clipboard Toggle word wrap

3. Delete the CSV for the EAP operator in the target namespace using the currentCSV value from the previous step:

   $ oc delete clusterserviceversion eap-operator.v1.0.0 -n openshift-operators
   clusterserviceversion.operators.coreos.com "eap-operator.v1.0.0" deleted

   Copy to Clipboard Toggle word wrap