Using JBoss EAP XP 4.0.0

Procedure

1. Enable the microprofile-opentracing-smallrye subsystem using the following management command:

   /subsystem=microprofile-opentracing-smallrye:add()

2. Reload the server for the changes to take effect.

   reload

Procedure

1. Remove the microprofile-opentracing-smallrye subsystem.

   /subsystem=microprofile-opentracing-smallrye:remove()

2. Reload the server for the changes to take effect.

   reload

Procedure

1. Install Jaeger using docker by issuing the following command in CLI:

   $ docker run -d --name jaeger   -p 6831:6831/udp   -p 5778:5778   -p 14268:14268   -p 16686:16686   jaegertracing/all-in-one:1.16

Procedure

1. Create a directory where you want to store the files:

   $ mkdir -p ~/config/prop-files/

2. Navigate to the directory:

   $ cd ~/config/prop-files/

3. Create a file name to store the value for the property name:

   $ touch name

4. Add the value of the property to the file:

   $ echo "jim" > name

5. Create a ConfigSource in which the file name is the property and the file contents the value of the property:

   /subsystem=microprofile-config-smallrye/config-source=file-props:add(dir={path=~/config/prop-files})

   This results in the following XML configuration:

   <subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0">
       <config-source name="file-props">
           <dir path="/etc/config/prop-files"/>
       </config-source>
   </subsystem>

Procedure

1. Add the MicroProfile Fault Tolerance extension using the following management CLI command:

   /extension=org.wildfly.extension.microprofile.fault-tolerance-smallrye:add

2. Enable the microprofile-fault-tolerance-smallrye subsystem using the following managenent command:

   /subsystem=microprofile-fault-tolerance-smallrye:add

3. Reload the server with the following management command:

   reload

Procedure

1. Navigate to the Runtime tab and select the server.
2. In the Monitor column, click MicroProfile Health → View.

Procedure

1. Set the security-enabled attribute to true on the microprofile-health-smallrye subsystem.

   /subsystem=microprofile-health-smallrye:write-attribute(name=security-enabled,value=true)

2. Reload the server for the changes to take effect.

   reload

Procedure

1. Enable the MicroProfile JWT smallrye extension in JBoss EAP:

   /extension=org.wildfly.extension.microprofile.jwt-smallrye:add

2. Enable the microprofile-jwt-smallrye subsystem:

   /subsystem=microprofile-jwt-smallrye:add

3. Reload the server:

   reload

Procedure

1. Set the security-enabled attribute to true on the microprofile-metrics-smallrye subsystem.

   /subsystem=microprofile-metrics-smallrye:write-attribute(name=security-enabled,value=true)

2. Reload the server for the changes to take effect.

   reload

Procedure

1. Enable statistics for the undertow subsystem:

   • Start the standalone server with statistics enabled:

     $ ./standalone.sh -Dwildfly.statistics-enabled=true

   • For an already running server, enable the statistics for the undertow subsystem:

     /subsystem=undertow:write-attribute(name=statistics-enabled,value=true)

2. Deploy the helloworld-rs quickstart:

   • In the root directory of the quickstart, deploy the web application using Maven:

     $ mvn clean install wildfly:deploy

3. Query the HTTP endpoint in the CLI using the curl command and filter for request_count:

   $ curl -v http://localhost:9990/metrics |  grep request_count

   Expected output:

   jboss_undertow_request_count_total{server="default-server",http_listener="default",} 0.0

   The attribute value returned is 0.0.

4. Access the quickstart, located at http://localhost:8080/helloworld-rs/, in a web browser and click any of the links.

5. Query the HTTP endpoint from the CLI again:

   $ curl -v http://localhost:9990/metrics |  grep request_count

   Expected output:

   jboss_undertow_request_count_total{server="default-server",http_listener="default",} 1.0

   The value is updated to 1.0.

   Repeat the last two steps to verify that the request count is updated.

Procedure

1. Enable the MicroProfile OpenAPI smallrye extension in JBoss EAP:

   /extension=org.wildfly.extension.microprofile.openapi-smallrye:add()

2. Enable the microprofile-openapi-smallrye subsystem using the following management command:

   /subsystem=microprofile-openapi-smallrye:add()

3. Reload the server.

   reload

Procedure

1. Create a directory in the application source tree:

   $ mkdir APPLICATION_ROOT/src/main/webapp/META-INF

   APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application.

2. Query the OpenAPI endpoint, redirecting the output to a file:

   $ curl http://localhost:8080/openapi?format=JSON > src/main/webapp/META-INF/openapi.json

   By default, the endpoint serves a YAML document, format=JSON specifies that a JSON document is returned.

3. Configure the application to skip annotation scanning when processing the OpenAPI document model:

   $ echo "mp.openapi.scan.disable=true" > APPLICATION_ROOT/src/main/webapp/META-INF/microprofile-config.properties

4. Rebuild the application:

   $ mvn clean install

5. Deploy the application again using the following management CLI commands:

   1. Undeploy the application:

      undeploy microprofile-openapi.war

   2. Deploy the application:

      deploy APPLICATION_ROOT/target/microprofile-openapi.war

Procedure

1. Open the JBoss EAP management CLI.
2. Enter the following code:

Procedure

1. Run the following CLI script to update the default standalone.xml server configuration file:

   $ EAP_HOME/bin/jboss-cli.sh --file=docs/examples/enable-microprofile.cli

2. Select a standalone server configuration other than the default standalone.xml server configuration file using the following command:

   $ EAP_HOME/bin/jboss-cli.sh --file=docs/examples/enable-microprofile.cli -Dconfig=<standalone-full.xml|standalone-ha.xml|standalone-full-ha.xml>

3. The specified configuration file now includes MicroProfile subsystems and extensions.

Procedure

1. Open a browser and log in to the Red Hat Customer Portal.
2. Select Downloads from the menu at the top of the page.
3. Find the Red Hat JBoss Enterprise Application Platform entry in the list and select it.
4. From the Product drop-down list, select JBoss EAP XP.
5. From the Version drop-down list, select 4.0.0.
6. Click the Releases tab.
7. Find JBoss EAP XP 4.0.0 Incremental Maven Repository in the list, and then click Download.
8. Save the archive file to your local directory.

Procedure

1. Locate the path to your Red Hat JBoss Enterprise Application Platform 7.4.0.GA Maven repository. For example, /path/to/repo/jboss-eap-7.4.0.GA-maven-repository/maven-repository/.

2. Extract the downloaded JBoss EAP XP 4.0.0 Incremental Maven Repository directly into the directory of the Red Hat JBoss Enterprise Application Platform 7.4.0.GA Maven repository. For example, open a terminal and issue the following command, replacing the value for your Red Hat JBoss Enterprise Application Platform 7.4.0.GA Maven repository path:

   $ unzip -o jboss-eap-xp-4.0.0-incremental-maven-repository.zip -d EAP_MAVEN_REPOSITORY_PATH

Procedure

1. Choose a configuration method and configure the JBoss EAP MicroProfile Maven repository.

2. After you have configured the JBoss EAP MicroProfile Maven repository, add the jboss-eap-xp-microprofile BOM to the project POM file. The following example shows how to configure the BOM in the <dependencyManagement> section of the pom.xml file:

   <dependencyManagement>
     <dependencies>
       ...
       <dependency>
         <groupId>org.jboss.bom</groupId>
         <artifactId>jboss-eap-xp-microprofile</artifactId>
         <version>4.0.0.GA</version>
         <type>pom</type>
         <scope>import</scope>
     </dependency>
       ...
     </dependencies>
   </dependencyManagement>

   Note

   If you do not specify a value for the type element in the pom.xml file, Maven specifies a jar value for the element.

Procedure

1. Set up the Maven project.

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

   This creates the directory structure for the project and pom.xml configuration file.

2. To let the POM file automatically manage the versions for the MicroProfile Config artifact and the MicroProfile REST Client artifact in the jboss-eap-xp-microprofile BOM, import the BOM to the <dependencyManagement> section of the project POM file.

   <dependencyManagement>
     <dependencies>
       <!-- importing the microprofile BOM adds MicroProfile specs -->
       <dependency>
           <groupId>org.jboss.bom</groupId>
           <artifactId>jboss-eap-xp-microprofile</artifactId>
           <version>4.0.0.GA</version>
           <type>pom</type>
           <scope>import</scope>
       </dependency>
     </dependencies>
   </dependencyManagement>

3. Add the MicroProfile Config artifact and the MicroProfile REST Client artifact and other dependencies, managed by the BOM, to the <dependency> section of the project POM file. The following example demonstrates adding the MicroProfile Config and the MicroProfile REST Client dependencies to the file:

   <!-- Add the MicroProfile REST Client API. Set provided for the <scope> tag, as the API is included in the server. -->
   <dependency>
     <groupId>org.eclipse.microprofile.rest.client</groupId>
     <artifactId>microprofile-rest-client-api</artifactId>
     <scope>provided</scope>
   </dependency>
   <!-- Add the MicroProfile Config API. Set provided for the <scope> tag, as the API is included in the server. -->
   <dependency>
     <groupId>org.eclipse.microprofile.config</groupId>
     <artifactId>microprofile-config-api</artifactId>
     <scope>provided</scope>
   </dependency>
   <!-- Add the {JAX-RS} API. Set provided for the <scope> tag, as the API is included in the server. -->
   <dependency>
     <groupId>org.jboss.spec.javax.ws.rs</groupId>
     <artifactId>jboss-jaxrs-api_2.1_spec</artifactId>
     <scope>provided</scope>
   </dependency>
   <!-- Add the CDI API. Set provided for the <scope> tag, as the API is included in the server. -->
   <dependency>
     <groupId>jakarta.enterprise</groupId>
     <artifactId>jakarta.enterprise.cdi-api</artifactId>
     <scope>provided</scope>
   </dependency>

Procedure

1. Create the directory to store class files:

   $ mkdir -p APPLICATION_ROOT/src/main/java/com/example/microprofile/config/

   Where APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application.

2. Navigate to the new directory:

   $ cd APPLICATION_ROOT/src/main/java/com/example/microprofile/config/

   Create all class files described in this procedure in this directory.

3. Create a class file named HelloApplication.java with the following content:

   package com.example.microprofile.config;
   
   import javax.ws.rs.ApplicationPath;
   import javax.ws.rs.core.Application;
   
   @ApplicationPath("/")
   public class HelloApplication extends Application {
   
   }

   This class defines the application as a Jakarta RESTful Web Services application.

4. Create a class file named HelloService.java with the following content:

   package com.example.microprofile.config;
   
   public class HelloService {
   	String createHelloMessage(String name){
           return "Hello " + name;
       }
   }

5. Create a class file named HelloWorld.java with the following content:

   package com.example.microprofile.config;
   
   import javax.inject.Inject;
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import org.eclipse.microprofile.config.inject.ConfigProperty;
   
   @Path("/config")
   public class HelloWorld {
   
       @Inject
       @ConfigProperty(name="name", defaultValue="jim") 1
       String name;
   
      	@Inject
      	HelloService helloService;
   
      	@GET
      	@Path("/json")
      	@Produces({ "application/json" })
      	public String getHelloWorldJSON() {
           String message = helloService.createHelloMessage(name);
          	return "{\"result\":\"" + message + "\"}";
   	}
   }

   1

   A MicroProfile Config property is injected into the class with the annotation @ConfigProperty(name="name", defaultValue="jim"). If no ConfigSource is configured, the value jim is returned.

6. Create an empty file named beans.xml in the src/main/webapp/WEB-INF/ directory:

   $ touch APPLICATION_ROOT/src/main/webapp/WEB-INF/beans.xml

   Where APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application.

7. Navigate to the root directory of the application:

   $ cd APPLICATION_ROOT

   Where APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application.

8. Build the project:

   $ mvn clean install wildfly:deploy

9. Test the output:

   $ curl http://localhost:8080/microprofile-config/config/json

   The following is the expected output:

   {"result":"Hello jim"}

Procedure

1. Add the MicroProfile Fault Tolerance extension using the following management CLI command:

   /extension=org.wildfly.extension.microprofile.fault-tolerance-smallrye:add

2. Enable the microprofile-fault-tolerance-smallrye subsystem using the following managenent command:

   /subsystem=microprofile-fault-tolerance-smallrye:add

3. Reload the server with the following management command:

   reload

Procedure

1. Set up the Maven project:

   mvn archetype:generate \
       -DgroupId=com.example.microprofile.faulttolerance \
       -DartifactId=microprofile-fault-tolerance \
       -DarchetypeGroupId=org.apache.maven.archetypes \
       -DarchetypeArtifactId=maven-archetype-webapp \
       -DinteractiveMode=false
   cd microprofile-fault-tolerance

   The command creates the directory structure for the project and the pom.xml configuration file.

2. To let the POM file automatically manage the versions for the MicroProfile Fault Tolerance artifact in the jboss-eap-xp-microprofile BOM, import the BOM to the <dependencyManagement> section of the project POM file.

   <dependencyManagement>
     <dependencies>
       <!-- importing the microprofile BOM adds MicroProfile specs -->
       <dependency>
           <groupId>org.jboss.bom</groupId>
           <artifactId>jboss-eap-xp-microprofile</artifactId>
           <version>${version.microprofile.bom}</version>
           <type>pom</type>
           <scope>import</scope>
       </dependency>
     </dependencies>
   </dependencyManagement>

   Replace ${version.microprofile.bom} with the installed version of BOM.

3. Add the MicroProfile Fault Tolerance artifact, managed by the BOM, to the <dependency> section of the project POM file. The following example demonstrates adding the MicroProfile Fault Tolerance dependency to the file:

   <!-- Add the MicroProfile Fault Tolerance API. Set provided for the <scope> tag, as the API is included in the server. -->
   <dependency>
     <groupId>org.eclipse.microprofile.fault.tolerance</groupId>
     <artifactId>microprofile-fault-tolerance-api</artifactId>
     <scope>provided</scope>
   </dependency>

Procedure

1. Create the directory to store class files:

   $ mkdir -p APPLICATION_ROOT/src/main/java/com/example/microprofile/faulttolerance

   APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application.

2. Navigate to the new directory:

   $ cd APPLICATION_ROOT/src/main/java/com/example/microprofile/faulttolerance

   For the following steps, create all class files in the new directory.

3. Create a simple entity representing a coffee sample as Coffee.java with the following content:

   package com.example.microprofile.faulttolerance;
   
   public class Coffee {
   
       public Integer id;
       public String name;
       public String countryOfOrigin;
       public Integer price;
   
       public Coffee() {
       }
   
       public Coffee(Integer id, String name, String countryOfOrigin, Integer price) {
           this.id = id;
           this.name = name;
           this.countryOfOrigin = countryOfOrigin;
           this.price = price;
       }
   }

4. Create a class file CoffeeApplication.java with the following content:

   package com.example.microprofile.faulttolerance;
   
   import javax.ws.rs.ApplicationPath;
   import javax.ws.rs.core.Application;
   
   @ApplicationPath("/")
   public class CoffeeApplication extends Application {
   }

5. Create a Jakarta Contexts and Dependency Injection Bean as CoffeeRepositoryService.java with the following content:

   package com.example.microprofile.faulttolerance;
   
   import java.util.ArrayList;
   import java.util.Collections;
   import java.util.HashMap;
   import java.util.List;
   import java.util.Map;
   import java.util.stream.Collectors;
   import javax.enterprise.context.ApplicationScoped;
   
   @ApplicationScoped
   public class CoffeeRepositoryService {
   
       private Map<Integer, Coffee> coffeeList = new HashMap<>();
   
       public CoffeeRepositoryService() {
           coffeeList.put(1, new Coffee(1, "Fernandez Espresso", "Colombia", 23));
           coffeeList.put(2, new Coffee(2, "La Scala Whole Beans", "Bolivia", 18));
           coffeeList.put(3, new Coffee(3, "Dak Lak Filter", "Vietnam", 25));
       }
   
       public List<Coffee> getAllCoffees() {
           return new ArrayList<>(coffeeList.values());
       }
   
       public Coffee getCoffeeById(Integer id) {
           return coffeeList.get(id);
       }
   
       public List<Coffee> getRecommendations(Integer id) {
           if (id == null) {
               return Collections.emptyList();
           }
           return coffeeList.values().stream()
                   .filter(coffee -> !id.equals(coffee.id))
                   .limit(2)
                   .collect(Collectors.toList());
       }
   }

6. Create a class file CoffeeResource.java with the following content:

   package com.example.microprofile.faulttolerance;
   
   import java.util.List;
   import java.util.Random;
   import java.util.concurrent.atomic.AtomicLong;
   import javax.inject.Inject;
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.ws.rs.core.MediaType;
   import java.util.Collections;
   import javax.ws.rs.PathParam;
   import org.eclipse.microprofile.faulttolerance.Fallback;
   import org.eclipse.microprofile.faulttolerance.Timeout;
   import org.eclipse.microprofile.faulttolerance.Retry;
   
   @Path("/coffee")
   @Produces(MediaType.APPLICATION_JSON)
   public class CoffeeResource {
   
       @Inject
       private CoffeeRepositoryService coffeeRepository;
   
       private AtomicLong counter = new AtomicLong(0);
   
       @GET
       @Retry(maxRetries = 4) 1
       public List<Coffee> coffees() {
           final Long invocationNumber = counter.getAndIncrement();
           return coffeeRepository.getAllCoffees();
       }
   
   
       @GET
       @Path("/{id}/recommendations")
       @Timeout(250) 2
       public List<Coffee> recommendations(@PathParam("id") int id) {
               return coffeeRepository.getRecommendations(id);
           }
   
       @GET
       @Path("fallback/{id}/recommendations")
       @Fallback(fallbackMethod = "fallbackRecommendations") 3
       public List<Coffee> recommendations2(@PathParam("id") int id) {
           return coffeeRepository.getRecommendations(id);
           }
   
       public List<Coffee> fallbackRecommendations(int id) {
           //always return a default coffee
           return Collections.singletonList(coffeeRepository.getCoffeeById(1));
       }
   }

   1

   Define number of re-tries to 4.

   2

   Define the timeout interval in milliseconds.

   3

   Define a fallback method to call when invocation fails.

7. Navigate to the root directory of the application:

   $ cd APPLICATION_ROOT

8. Build the application using the following Maven command:

   $ mvn clean install wildfly:deploy

   Access the application at http://localhost:8080/microprofile-fault-tolerance/coffee.

Procedure

1. Enable the MicroProfile JWT smallrye extension in JBoss EAP:

   /extension=org.wildfly.extension.microprofile.jwt-smallrye:add

2. Enable the microprofile-jwt-smallrye subsystem:

   /subsystem=microprofile-jwt-smallrye:add

3. Reload the server:

   reload

Procedure

1. Set up the maven project:

   $ mvn archetype:generate -DinteractiveMode=false \
       -DarchetypeGroupId=org.apache.maven.archetypes \
       -DarchetypeArtifactId=maven-archetype-webapp \
       -DgroupId=com.example -DartifactId=microprofile-jwt \
       -Dversion=1.0.0.Alpha1-SNAPSHOT
     cd microprofile-jwt

   The command creates the directory structure for the project and the pom.xml configuration file.

2. To let the POM file automatically manage the versions for the MicroProfile JWT artifact in the jboss-eap-xp-microprofile BOM, import the BOM to the <dependencyManagement> section of the project POM file.

   <dependencyManagement>
     <dependencies>
       <!-- importing the microprofile BOM adds MicroProfile specs -->
       <dependency>
           <groupId>org.jboss.bom</groupId>
           <artifactId>jboss-eap-xp-microprofile</artifactId>
           <version>${version.microprofile.bom}</version>
           <type>pom</type>
           <scope>import</scope>
       </dependency>
     </dependencies>
   </dependencyManagement>

   Replace ${version.microprofile.bom} with the installed version of BOM.

3. Add the MicroProfile JWT artifact, managed by the BOM, to the <dependency> section of the project POM file. The following example demonstrates adding the MicroProfile JWT dependency to the file:

   <!-- Add the MicroProfile JWT API. Set provided for the <scope> tag, as the API is included in the server. -->
   <dependency>
     <groupId>org.eclipse.microprofile.jwt</groupId>
     <artifactId>microprofile-jwt-auth-api</artifactId>
     <scope>provided</scope>
   </dependency>

Procedure

1. Create a token generator.

   This step serves as a reference. For a production environment, use an identity provider such as Red Hat SSO.

   1. Create a directory src/test/java for token the generator utility and navigate to it:

      $ mkdir -p src/test/java
      $ cd src/test/java

   2. Create a class file TokenUtil.java with the following content:

      package  com.example.mpjwt;
      
      import java.io.FileInputStream;
      import java.io.InputStream;
      import java.nio.charset.StandardCharsets;
      import java.security.KeyFactory;
      import java.security.PrivateKey;
      import java.security.spec.PKCS8EncodedKeySpec;
      import java.util.Base64;
      import java.util.UUID;
      
      import javax.json.Json;
      import javax.json.JsonArrayBuilder;
      import javax.json.JsonObjectBuilder;
      
      import com.nimbusds.jose.JOSEObjectType;
      import com.nimbusds.jose.JWSAlgorithm;
      import com.nimbusds.jose.JWSHeader;
      import com.nimbusds.jose.JWSObject;
      import com.nimbusds.jose.JWSSigner;
      import com.nimbusds.jose.Payload;
      import com.nimbusds.jose.crypto.RSASSASigner;
      
      public class TokenUtil {
      
          private static PrivateKey loadPrivateKey(final String fileName) throws Exception {
              try (InputStream is = new FileInputStream(fileName)) {
                  byte[] contents = new byte[4096];
                  int length = is.read(contents);
                  String rawKey = new String(contents, 0, length, StandardCharsets.UTF_8)
                          .replaceAll("-----BEGIN (.*)-----", "")
                          .replaceAll("-----END (.*)----", "")
                          .replaceAll("\r\n", "").replaceAll("\n", "").trim();
      
                  PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(Base64.getDecoder().decode(rawKey));
                  KeyFactory keyFactory = KeyFactory.getInstance("RSA");
      
                  return keyFactory.generatePrivate(keySpec);
              }
          }
      
          public static String generateJWT(final String principal, final String birthdate, final String...groups) throws Exception {
          	PrivateKey privateKey = loadPrivateKey("private.pem");
      
              JWSSigner signer = new RSASSASigner(privateKey);
              JsonArrayBuilder groupsBuilder = Json.createArrayBuilder();
              for (String group : groups) { groupsBuilder.add(group); }
      
              long currentTime = System.currentTimeMillis() / 1000;
              JsonObjectBuilder claimsBuilder = Json.createObjectBuilder()
                      .add("sub", principal)
                      .add("upn", principal)
                      .add("iss", "quickstart-jwt-issuer")
                      .add("aud", "jwt-audience")
                      .add("groups", groupsBuilder.build())
                      .add("birthdate", birthdate)
                      .add("jti", UUID.randomUUID().toString())
                      .add("iat", currentTime)
                      .add("exp", currentTime + 14400);
      
              JWSObject jwsObject = new JWSObject(new JWSHeader.Builder(JWSAlgorithm.RS256)
                      .type(new JOSEObjectType("jwt"))
                      .keyID("Test Key").build(),
                      new Payload(claimsBuilder.build().toString()));
      
              jwsObject.sign(signer);
      
              return jwsObject.serialize();
          }
      
          public static void main(String[] args) throws Exception {
              if (args.length < 2) throw new IllegalArgumentException("Usage TokenUtil {principal} {birthdate} {groups}");
              String principal = args[0];
              String birthdate = args[1];
              String[] groups = new String[args.length - 2];
              System.arraycopy(args, 2, groups, 0, groups.length);
      
              String token = generateJWT(principal, birthdate, groups);
              String[] parts = token.split("\\.");
              System.out.println(String.format("\nJWT Header - %s", new String(Base64.getDecoder().decode(parts[0]), StandardCharsets.UTF_8)));
              System.out.println(String.format("\nJWT Claims - %s", new String(Base64.getDecoder().decode(parts[1]), StandardCharsets.UTF_8)));
              System.out.println(String.format("\nGenerated JWT Token \n%s\n", token));
          }
      }

2. Create the web.xml file in the src/main/webapp/WEB-INF directory with the following content:

   <context-param>
       <param-name>resteasy.role.based.security</param-name>
       <param-value>true</param-value>
   </context-param>
   
   <security-role>
       <role-name>Subscriber</role-name>
   </security-role>

3. Create a class file SampleEndPoint.java with the following content:

   package com.example.mpjwt;
   
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   
   import java.security.Principal;
   import javax.ws.rs.core.Context;
   import javax.ws.rs.core.SecurityContext;
   
   import javax.annotation.security.RolesAllowed;
   import javax.inject.Inject;
   
   import java.time.LocalDate;
   import java.time.Period;
   import java.util.Optional;
   
   import org.eclipse.microprofile.jwt.Claims;
   import org.eclipse.microprofile.jwt.Claim;
   
   import org.eclipse.microprofile.jwt.JsonWebToken;
   
   @Path("/Sample")
   public class SampleEndPoint {
   
       @GET
       @Path("/helloworld")
       public String helloworld(@Context SecurityContext securityContext) {
           Principal principal = securityContext.getUserPrincipal();
           String caller = principal == null ? "anonymous" : principal.getName();
   
           return "Hello " + caller;
       }
   
       @Inject
   	JsonWebToken jwt;
   
   	@GET()
   	@Path("/subscription")
   	@RolesAllowed({"Subscriber"})
   	public String helloRolesAllowed(@Context SecurityContext ctx) {
       	Principal caller =  ctx.getUserPrincipal();
       	String name = caller == null ? "anonymous" : caller.getName();
       	boolean hasJWT = jwt.getClaimNames() != null;
       	String helloReply = String.format("hello + %s, hasJWT: %s", name, hasJWT);
   
       	return helloReply;
   	}
   
   	@Inject
   	@Claim(standard = Claims.birthdate)
   	Optional<String> birthdate;
   
   	@GET()
   	@Path("/birthday")
   	@RolesAllowed({ "Subscriber" })
   	public String birthday() {
       	if (birthdate.isPresent()) {
           	LocalDate birthdate = LocalDate.parse(this.birthdate.get().toString());
           	LocalDate today = LocalDate.now();
           	LocalDate next = birthdate.withYear(today.getYear());
           	if (today.equals(next)) {
               	return "Happy Birthday";
           }
           if (next.isBefore(today)) {
               next = next.withYear(next.getYear() + 1);
           }
   
           Period wait = today.until(next);
   
           return String.format("%d months and %d days until your next birthday.", wait.getMonths(), wait.getDays());
       }
   
       return "Sorry, we don't know your birthdate.";
   
   	}
   
   }

   The methods annotated with @Path are the Jakarta RESTful Web Services endpoints.

   The annotation @Claim defines a JWT claim.

4. Create a class file App.java to enable Jakarta RESTful Web Services:

   package com.example.mpjwt;
   
   import javax.ws.rs.ApplicationPath;
   import javax.ws.rs.core.Application;
   
   import org.eclipse.microprofile.auth.LoginConfig;
   
   @ApplicationPath("/rest")
   @LoginConfig(authMethod="MP-JWT", realmName="MP JWT Realm")
   public class App extends Application {}

   The annotation @LoginConfig(authMethod="MP-JWT", realmName="MP JWT Realm") enables JWT RBAC during deployment.

5. Compile the application with the following Maven command:

   $ mvn package

6. Generate JWT token using the token generator utility:

   $ mvn exec:java -Dexec.mainClass=org.wildfly.quickstarts.mpjwt.TokenUtil -Dexec.classpathScope=test -Dexec.args="testUser 2017-09-15 Echoer Subscriber"

7. Build and deploy the application using the following Maven command:

   $ mvn package wildfly:deploy

8. Test the application.

   • Call the Sample/subscription endpoint using the bearer token:

     $ curl -H "Authorization: Bearer ey..rg" http://localhost:8080/microprofile-jwt/rest/Sample/subscription

   • Call the Sample/birthday endpoint:

     $ curl -H "Authorization: Bearer ey..rg" http://localhost:8080/microprofile-jwt/rest/Sample/birthday

Procedure

1. Create a class file HelloService.java with the following content:

   package com.example.microprofile.metrics;
   
   public class HelloService {
       String createHelloMessage(String name){
           return "Hello" + name;
       }
   }

2. Create a class file HelloWorld.java with the following content:

   package com.example.microprofile.metrics;
   
   import javax.inject.Inject;
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import org.eclipse.microprofile.metrics.annotation.Counted;
   
   @Path("/")
   public class HelloWorld {
   @Inject
       HelloService helloService;
   
   @GET
   @Path("/json")
       @Produces({ "application/json" })
       @Counted(name = "requestCount",
     		 absolute = true,
   description = "Number of times the getHelloWorldJSON was requested")
       public String getHelloWorldJSON() {
           return "{\"result\":\"" + helloService.createHelloMessage("World") + "\"}";
       }
   }

3. Update the pom.xml file to include the following dependency:

   <dependency>
       <groupId>org.eclipse.microprofile.metrics</groupId>
       <artifactId>microprofile-metrics-api</artifactId>
       <scope>provided</scope>
   </dependency>

4. Build the application using the following Maven command:

   $ mvn clean install wildfly:deploy

5. Test the metrics:

   1. Issue the following command in the CLI:

      $ curl -v http://localhost:9990/metrics |  grep request_count | grep helloworld-rs-metrics

      Expected output:

      jboss_undertow_request_count_total{deployment="helloworld-rs-metrics.war",servlet="org.jboss.as.quickstarts.rshelloworld.JAXActivator",subdeployment="helloworld-rs-metrics.war",microprofile_scope="vendor"} 0.0

   2. In a browser, navigate to the URL http://localhost:8080/helloworld-rs/rest/json.

   3. Re-Issue the following command in the CLI:

      $ curl -v http://localhost:9990/metrics |  grep request_count | grep helloworld-rs-metrics

      Expected output:

      jboss_undertow_request_count_total{deployment="helloworld-rs-metrics.war",servlet="org.jboss.as.quickstarts.rshelloworld.JAXActivator",subdeployment="helloworld-rs-metrics.war",microprofile_scope="vendor"} 1.0

Procedure

1. Enable the MicroProfile OpenAPI smallrye extension in JBoss EAP:

   /extension=org.wildfly.extension.microprofile.openapi-smallrye:add()

2. Enable the microprofile-openapi-smallrye subsystem using the following management command:

   /subsystem=microprofile-openapi-smallrye:add()

3. Reload the server.

   reload

Procedure

1. Initialize the project:

   mvn archetype:generate \
        -DgroupId=com.example.microprofile.openapi \
        -DartifactId=microprofile-openapi\
        -DarchetypeGroupId=org.apache.maven.archetypes \
        -DarchetypeArtifactId=maven-archetype-webapp \
        -DinteractiveMode=false
   cd microprofile-openapi

   The command creates the directory structure for the project and the pom.xml configuration file.

2. Edit the pom.xml configuration file to contain:

   <?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.microprofile.openapi</groupId>
       <artifactId>microprofile-openapi</artifactId>
       <version>1.0-SNAPSHOT</version>
       <packaging>war</packaging>
   
       <name>microprofile-openapi Maven Webapp</name>
       <!-- Update the value with the URL of the project -->
       <url>http://www.example.com</url>
   
       <properties>
           <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
           <maven.compiler.source>1.8</maven.compiler.source>
           <maven.compiler.target>1.8</maven.compiler.target>
           <version.server.bom>4.0.0.GA</version.server.bom>
       </properties>
   
       <dependencyManagement>
           <dependencies>
               <dependency>
                   <groupId>org.jboss.bom</groupId>
                   <artifactId>jboss-eap-xp-microprofile</artifactId>
                   <version>${version.server.bom}</version>
                   <type>pom</type>
                   <scope>import</scope>
               </dependency>
           </dependencies>
       </dependencyManagement>
   
       <dependencies>
           <dependency>
               <groupId>org.jboss.spec.javax.ws.rs</groupId>
               <artifactId>jboss-jaxrs-api_2.1_spec</artifactId>
               <scope>provided</scope>
           </dependency>
       </dependencies>
   
       <build>
           <!-- Set the name of the archive -->
           <finalName>${project.artifactId}</finalName>
           <plugins>
               <plugin>
                   <artifactId>maven-clean-plugin</artifactId>
                   <version>3.1.0</version>
               </plugin>
               <!-- see http://maven.apache.org/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_war_packaging -->
               <plugin>
                   <artifactId>maven-resources-plugin</artifactId>
                   <version>3.0.2</version>
               </plugin>
               <plugin>
                   <artifactId>maven-compiler-plugin</artifactId>
                   <version>3.8.0</version>
               </plugin>
               <plugin>
                   <artifactId>maven-surefire-plugin</artifactId>
                   <version>2.22.1</version>
               </plugin>
               <plugin>
                   <artifactId>maven-war-plugin</artifactId>
                   <version>3.2.2</version>
               </plugin>
               <plugin>
                   <artifactId>maven-install-plugin</artifactId>
                   <version>2.5.2</version>
               </plugin>
               <plugin>
                   <artifactId>maven-deploy-plugin</artifactId>
                   <version>2.8.2</version>
               </plugin>
               <!-- Allows to use mvn wildfly:deploy -->
               <plugin>
                   <groupId>org.wildfly.plugins</groupId>
                   <artifactId>wildfly-maven-plugin</artifactId>
               </plugin>
           </plugins>
       </build>
   </project>

   Use the pom.xml configuration file and directory structure to create an application.

Procedure

1. Create the directory to store class files:

   $ mkdir -p APPLICATION_ROOT/src/main/java/com/example/microprofile/openapi/

   APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application.

2. Navigate to the new directory:

   $ cd APPLICATION_ROOT/src/main/java/com/example/microprofile/openapi/

   All the class files in the following steps must be created in this directory.

3. Create the class file InventoryApplication.java with the following content:

   package com.example.microprofile.openapi;
   
   import javax.ws.rs.ApplicationPath;
   import javax.ws.rs.core.Application;
   
   @ApplicationPath("/inventory")
   public class InventoryApplication extends Application {
   }

   This class serves as the REST endpoint for the application.

4. Create a class file Fruit.java with the following content:

   package com.example.microprofile.openapi;
   
   public class Fruit {
   
       private final String name;
       private final String description;
   
       public Fruit(String name, String description) {
           this.name = name;
           this.description = description;
       }
   
       public String getName() {
           return this.name;
       }
   
       public String getDescription() {
           return this.description;
       }
   }

5. Create a class file FruitResource.java with the following content:

   package com.example.microprofile.openapi;
   
   import java.util.Collections;
   import java.util.LinkedHashMap;
   import java.util.Set;
   
   import javax.ws.rs.Consumes;
   import javax.ws.rs.DELETE;
   import javax.ws.rs.GET;
   import javax.ws.rs.POST;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.ws.rs.core.MediaType;
   
   @Path("/fruit")
   @Produces(MediaType.APPLICATION_JSON)
   @Consumes(MediaType.APPLICATION_JSON)
   public class FruitResource {
   
       private final Set<Fruit> fruits = Collections.newSetFromMap(Collections.synchronizedMap(new LinkedHashMap<>()));
   
       public FruitResource() {
           this.fruits.add(new Fruit("Apple", "Winter fruit"));
           this.fruits.add(new Fruit("Pineapple", "Tropical fruit"));
       }
   
       @GET
       public Set<Fruit> all() {
           return this.fruits;
       }
   
       @POST
       public Set<Fruit> add(Fruit fruit) {
           this.fruits.add(fruit);
           return this.fruits;
       }
   
       @DELETE
       public Set<Fruit> remove(Fruit fruit) {
           this.fruits.removeIf(existingFruit -> existingFruit.getName().contentEquals(fruit.getName()));
           return this.fruits;
       }
   }

6. Navigate to the root directory of the application:

   $ cd APPLICATION_ROOT

7. Build and deploy the application using the following Maven command:

   $ mvn wildfly:deploy

8. Test the application.

   • Access the OpenAPI documentation of the sample application using curl:

     $ curl http://localhost:8080/openapi

   • The following output is returned:

     openapi: 3.0.1
     info:
       title: Archetype Created Web Application
       version: "1.0"
     servers:
     - url: /microprofile-openapi
     paths:
       /inventory/fruit:
         get:
           responses:
             "200":
               description: OK
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       $ref: '#/components/schemas/Fruit'
         post:
           requestBody:
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/Fruit'
           responses:
             "200":
               description: OK
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       $ref: '#/components/schemas/Fruit'
         delete:
           requestBody:
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/Fruit'
           responses:
             "200":
               description: OK
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       $ref: '#/components/schemas/Fruit'
     components:
       schemas:
         Fruit:
           type: object
           properties:
             description:
               type: string
             name:
               type: string

Procedure

1. Create a directory in the application source tree:

   $ mkdir APPLICATION_ROOT/src/main/webapp/META-INF

   APPLICATION_ROOT is the directory containing the pom.xml configuration file for the application.

2. Query the OpenAPI endpoint, redirecting the output to a file:

   $ curl http://localhost:8080/openapi?format=JSON > src/main/webapp/META-INF/openapi.json

   By default, the endpoint serves a YAML document, format=JSON specifies that a JSON document is returned.

3. Configure the application to skip annotation scanning when processing the OpenAPI document model:

   $ echo "mp.openapi.scan.disable=true" > APPLICATION_ROOT/src/main/webapp/META-INF/microprofile-config.properties

4. Rebuild the application:

   $ mvn clean install

5. Deploy the application again using the following management CLI commands:

   1. Undeploy the application:

      undeploy microprofile-openapi.war

   2. Deploy the application:

      deploy APPLICATION_ROOT/target/microprofile-openapi.war

Procedure

1. Start the Red Hat Single Sign-On server at a port other than 8080 because JBoss EAP default port is 8080.

   Syntax

   $ RH_SSO_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=<offset-number>

   Example

   $ /home/servers/rh-sso-7.4/bin/standalone.sh -Djboss.socket.binding.port-offset=100

2. Log in to the Admin Console at http://localhost:<port>/auth/. For example, http://localhost:8180/auth/.
3. To create a realm, in the Admin Console, hover over Master, and click Add realm.
4. Enter a name for the realm. For example, example_realm. Ensure that Enabled is ON and click Create.
5. Click Users, then click Add user to add a user to the realm.
6. Enter a user name. For example, jane_doe. Ensure that User Enabled is ON and click Save.
7. Click Credentials to add a password to the user.
8. Set a password for the user. For example, janedoep@$$. Toggle Temporary to OFF and click Set Password. In the confirmation prompt, click Set password.
9. Click Clients, then click Create to configure a client connection.
10. Enter a client ID. For example, my_jbeap. Ensure that Client Protocol is set to openid-connect, and click Save.

11. Click Installation, then select Keycloak OIDC JSON as the Format Option to see the connection parameters.

    {
      "realm": "example_realm",
      "auth-server-url": "http://localhost:8180/auth/",
      "ssl-required": "external",
      "resource": "my_jbeap",
      "public-client": true,
      "confidential-port": 0
    }

    When configuring your JBoss EAP application to use Red Hat Single Sign-On as the identity provider, you use the parameters as follows:

    "provider-url" : "http://localhost:8180/auth/realms/example_realm",
    "ssl-required": "external",
    "client-id": "my_jbeap",
    "public-client": true,
    "confidential-port": 0

12. Click Clients, click Edit next to my_jbeap to edit the client settings.

13. In Valid Redirect URIs, enter the URL where the page should redirect after authentication is successful.

    For this example, set this value to http://localhost:8080/simple-oidc-example/secured/*

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

   Example

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

2. Navigate to the application root directory:

   Syntax

   $ cd <name-of-your-application>

   Example

   $ cd simple-oidc-example

3. Update the generated pom.xml file as follows:

   1. Set the following properties:

      <properties>
          <maven.compiler.source>1.8</maven.compiler.source>
          <maven.compiler.target>1.8</maven.compiler.target>
          <failOnMissingWebXml>false</failOnMissingWebXml>
          <version.server.bom>4.0.0.GA</version.server.bom>
          <version.server.bootable-jar>4.0.0.GA</version.server.bootable-jar>
          <version.wildfly-jar.maven.plugin>4.0.0.GA</version.wildfly-jar.maven.plugin>
      </properties>

   2. Set the following dependencies:

      <dependencies>
          <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0.redhat-1</version>
            <scope>provided</scope>
          </dependency>
      </dependencies>

   3. Set the following build configuration to use mvn widlfy:deploy to deploy the application:

      <build>
          <finalName>${project.artifactId}</finalName>
          <plugins>
              <plugin>
                  <groupId>org.wildfly.plugins</groupId>
                  <artifactId>wildfly-maven-plugin</artifactId>
                  <version>2.1.0.Final</version>
              </plugin>
          </plugins>
      </build>

Procedure

1. Create a directory to store the Java files.

   Syntax

   $ mkdir -p <application_root>/src/main/java/com/example/oidc

   Example

   $ mkdir -p simple-oidc-example/src/main/java/com/example/oidc

2. Navigate to the new directory.

   Syntax

   $ cd <application_root>/src/main/java/com/example/oidc

   Example

   $ cd simple-oidc-example/src/main/java/com/example/oidc

3. Create a servlet "SecuredServlet.java" with the following content:

   package com.example.oidc;
   
   import java.io.IOException;
   import java.io.PrintWriter;
   import java.security.Principal;
   
   import javax.servlet.ServletException;
   import javax.servlet.annotation.WebServlet;
   import javax.servlet.http.HttpServlet;
   import javax.servlet.http.HttpServletRequest;
   import javax.servlet.http.HttpServletResponse;
   
   /**
    * A simple secured HTTP servlet.
    *
    */
   @WebServlet("/secured")
   public class SecuredServlet extends HttpServlet {
   
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
           try (PrintWriter writer = resp.getWriter()) {
               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 '");
               Principal user = req.getUserPrincipal();
               writer.print(user != null ? user.getName() : "NO AUTHENTICATED USER");
               writer.print("'");
               writer.println("    </p>");
               writer.println("  </body>");
               writer.println("</html>");
           }
       }
   
   }

4. Add security rules for access to your application in the deployment descriptor web.xml file located in the WEB-INF directory of the application.

   <?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>*</role-name>
           </auth-constraint>
       </security-constraint>
   
       <security-role>
           <role-name>*</role-name>
       </security-role>
   </web-app>

5. To secure the application with OpenID Connect, either update the deployment configuration or configure the elytron-oidc-client subsystem.

   Note

   If you configure OpenID Connect in both the deployment configuration and the elytron-oidc-client subsystem, the configuration in the elytron-oidc-client subsystem secure-deployment attribute takes precedence over the configuration in the application deployment descriptor.

   • Updating the deployment configuration:

     1. Create a file oidc.json in the WEB-INF directory, like this:

        {
          "provider-url" : "http://localhost:8180/auth/realms/example_realm",
          "ssl-required": "external",
          "client-id": "my_jbeap",
          "public-client": true,
          "confidential-port": 0
        }

     2. Update the deployment descriptor web.xml file with the following text to declare that this application uses OIDC:

        <login-config>
            <auth-method>OIDC</auth-method>
        </login-config>

   • Configuring the elytron-oidc-client subsystem:

     • To secure your application, use the following management CLI command:

       /subsystem=elytron-oidc-client/secure-deployment=simple-oidc-example.war/:add(client-id=my_jbeap,provider-url=http://localhost:8180/auth/realms/example_realm,public-client=true,ssl-required=external)

6. In the application root directory, compile your application with the following command:

   $ mvn package

7. Deploy the application.

   $ mvn wildfly:deploy

Verification

1. In a browser, navigate to http://localhost:8080/simple-oidc-example/secured.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Secured Servlet
   Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'

   You can now log in to the application using the credentials you configured in the Red Hat Single Sign-On as the OpenID provider.

Procedure

1. Update the deployment descriptor web.xml file with the following text:

   Syntax

   <security-constraint>
       ...
       <auth-constraint>
           <role-name><allowed_role></role-name>
       </auth-constraint>
   </security-constraint>

   Example

   <security-constraint>
       ...
       <auth-constraint>
           <role-name>example_role</role-name> 1
       </auth-constraint>
   </security-constraint>

   1

   Allow only those users with the role example_role to access your application.

2. In the application root directory, recompile your application with the following command:

   $ mvn package

3. Deploy the application.

   $ mvn wildfly:deploy

Verification

1. In a browser, navigate to http://localhost:8080/simple-oidc-example/secured.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Forbidden

   Because you have not assigned the required role to the user "jane_doe," jane_doe can’t log in to your application. Only the users with the required role can log in.

Procedure

1. Log in to the admin console at http://localhost:<port>/auth/. For example, http://localhost:8180/auth/.
2. Click the realm you use to connect with JBoss EAP. For example, example_realm.
3. Click Clients, then click the client-name you configured for JBoss EAP. For example, my_jbeap.
4. Click Roles, then Add Role.
5. Enter a role name, such as example_role, then click Save. This is the role name you configure in JBoss EAP for authorization.
6. Click Users, then View all users.
7. Click an ID to assign the role you created. For example, click the ID for jane_doe.
8. Click Role Mappings. In the Client Roles field, select the client-name you configured for JBoss EAP. For example, my_jbeap.
9. In Available Roles, select a role to assign. For example, example_role. Click Add selected.

Verification

1. In a browser, navigate to the application URL.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Secured Servlet
   Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'

   Users with the required role can log in to your application.

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

   Example

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

2. Navigate to the application root directory.

   Syntax

   $ cd <name-of-your-application>

   Example

   $ cd simple-oidc-layer-example

3. Update the generated pom.xml file as follows:

   1. Set the following repositories:

      <repositories>
          <repository>
              <id>jboss</id>
              <url>https://maven.repository.redhat.com/ga</url>
              <snapshots>
                  <enabled>false</enabled>
              </snapshots>
          </repository>
      </repositories>

   2. Set the following plugin repositories:

      <pluginRepositories>
          <pluginRepository>
              <id>jboss</id>
              <url>https://maven.repository.redhat.com/ga</url>
              <snapshots>
                  <enabled>false</enabled>
              </snapshots>
          </pluginRepository>
      </pluginRepositories>

   3. Set the following properties:

      <properties>
          <maven.compiler.source>1.8</maven.compiler.source>
          <maven.compiler.target>1.8</maven.compiler.target>
          <bootable.jar.maven.plugin.version>6.1.2.Final-redhat-00001</bootable.jar.maven.plugin.version>
          <jboss.xp.galleon.feature.pack.version>4.0.0.GA-redhat-00002</jboss.xp.galleon.feature.pack.version>
      </properties>

   4. Set the following dependencies:

      <dependencies>
          <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0.redhat-1</version>
            <scope>provided</scope>
          </dependency>
      </dependencies>
      
      <dependencyManagement>
          <dependencies>
              <dependency>
                  <groupId>org.jboss.bom</groupId>
                  <artifactId>jboss-eap-jakartaee8</artifactId>
                  <version>7.3.4.GA</version>
                  <type>pom</type>
                  <scope>import</scope>
              </dependency>
              <dependency>
                  <groupId>org.jboss.spec.javax.servlet</groupId>
                  <artifactId>jboss-servlet-api_4.0_spec</artifactId>
                  <scope>provided</scope>
              </dependency>
          </dependencies>
      </dependencyManagement>

   5. Set the following build configuration in the <build> element of the pom.xml file:

      <finalName>${project.artifactId}</finalName>
      <plugins>
          <plugin>
              <groupId>org.wildfly.plugins</groupId>
              <artifactId>wildfly-jar-maven-plugin</artifactId>   1
              <version>${bootable.jar.maven.plugin.version}</version>
              <configuration>
                  <feature-pack-location>org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</feature-pack-location>
                  <layers>
                      <layer>jaxrs-server</layer>
                      <layer>elytron-oidc-client</layer>    2
                  </layers>
                  <context-root>false</context-root>   3
              </configuration>
              <executions>
                  <execution>
                      <goals>
                          <goal>package</goal>
                      </goals>
                  </execution>
              </executions>
          </plugin>
      </plugins>

      1

      JBoss EAP Maven plug-in to build the application as a bootable JAR

      2

      The elytron-oidc-client layer provides a native OpenID Connect (OIDC) client to connect with external OpenID providers.

      3

      Register the application in the simple-oidc-layer-example resource path. The servlet is then available at the URL http://server-url/application_name/servlet_path, for example: http://localhost:8080/simple-oidc-layer-example/secured. By default, the application WAR file is registered under the root-context path, like http://server-url/servlet_path, for example: http://localhost:8080/secured.

   6. Set the application name, for example "simple-oidc-layer-example" in the <build> element of the pom.xml file.

      <finalName>simple-oidc-layer-example</finalName>

Procedure

1. Create a directory to store the Java files.

   Syntax

   $ mkdir -p <application_root>/src/main/java/com/example/oidc

   Example

   $ mkdir -p simple-oidc-layer-example/src/main/java/com/example/oidc

2. Navigate to the new directory.

   Syntax

   $ cd <application_root>/src/main/java/com/example/oidc

   Example

   $ cd simple-oidc-layer-example/src/main/java/com/example/oidc

3. Create a servlet "SecuredServlet.java" with the following content:

   package com.example.oidc;
   
   import java.io.IOException;
   import java.io.PrintWriter;
   import java.security.Principal;
   
   import javax.servlet.ServletException;
   import javax.servlet.annotation.WebServlet;
   import javax.servlet.http.HttpServlet;
   import javax.servlet.http.HttpServletRequest;
   import javax.servlet.http.HttpServletResponse;
   
   /**
    * A simple secured HTTP servlet.
    *
    */
   @WebServlet("/secured")
   public class SecuredServlet extends HttpServlet {
   
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
           try (PrintWriter writer = resp.getWriter()) {
               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 '");
               Principal user = req.getUserPrincipal();
               writer.print(user != null ? user.getName() : "NO AUTHENTICATED USER");
               writer.print("'");
               writer.println("    </p>");
               writer.println("  </body>");
               writer.println("</html>");
           }
       }
   
   }

4. Add security rules for access to your application in the deployment descriptor web.xml file located in the WEB-INF directory of the application.

   <?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>*</role-name>
           </auth-constraint>
       </security-constraint>
   
       <security-role>
           <role-name>*</role-name>
       </security-role>
   </web-app>

5. To secure the application with OpenID Connect, either update the deployment configuration or configure the elytron-oidc-client subsystem.

   Note

   If you configure OpenID Connect in both the deployment configuration and the elytron-oidc-client subsystem, the configuration in the elytron-oidc-client subsystem secure-deployment attribute takes precedence over the configuration in the application deployment descriptor.

   • Updating the deployment configuration:

     1. Create a file oidc.json in the WEB-INF directory, like this:

        {
          "provider-url" : "http://localhost:8180/auth/realms/example_realm",
          "ssl-required": "external",
          "client-id": "my_jbeap",
          "public-client": true,
          "confidential-port": 0
        }

     2. Update the deployment descriptor web.xml file with the following text to declare that this application uses OIDC:

        <login-config>
            <auth-method>OIDC</auth-method>
        </login-config>

   • Configuring the elytron-oidc-client subsystem:

     1. Create a directory to store a CLI script in the application root directory:

        Syntax

        $ mkdir <application_root>/<cli_script_directory>

        Example

        $ mkdir simple-oidc-layer-example/scripts/

        You can create the directory at any place that Maven can access, inside the application root directory.

     2. Create a CLI script, such as configure-oidc.cli, with the following content:

        /subsystem=elytron-oidc-client/secure-deployment=simple-oidc-layer-example.war:add(client-id=my_jbeap,provider-url=http://localhost:8180/auth/realms/example_realm,public-client=true,ssl-required=external)

        The subsystem command defines the simple-oidc-layer-example.war resource as the deployment to secure in elytron-oidc-client subsystem.

     3. In the project pom.xml file, add the following configuration extract to the existing plug-in <configuration> element:

        <cli-sessions>
            <cli-session>
                <script-files>
                    <script>scripts/configure-oidc.cli</script>
                </script-files>
            </cli-session>
        </cli-sessions>

6. In the application root directory, compile your application with the following command:

   $ mvn package

7. Deploy the bootable jar application using the following command:

   Syntax

   $ java -jar <application_root>/target/simple-oidc-layer-example-bootable.jar

   Example

   $ java -jar simple-oidc-layer-example/target/simple-oidc-layer-example-bootable.jar

   This starts JBoss EAP and deploys the application.

Verification

1. In a browser, navigate to http://localhost:8080/simple-oidc-layer-example/secured.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Secured Servlet
   Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'

   You can now log in to the application using the credentials you configured in the Red Hat Single Sign-On as the OpenID provider.

Procedure

1. Update the deployment descriptor web.xml file with the following text:

   Syntax

   <security-constraint>
       ...
       <auth-constraint>
           <role-name><allowed_role></role-name>
       </auth-constraint>
   </security-constraint>

   Example

   <security-constraint>
       ...
       <auth-constraint>
           <role-name>example_role</role-name> 1
       </auth-constraint>
   </security-constraint>

   1

   Allow only those users with the role example_role to access your application.

2. In the application root directory, recompile your application with the following command:

   $ mvn package

3. Deploy the application.

   $ java -jar simple-oidc-layer-example/target/simple-oidc-layer-example-bootable.jar

   This starts JBoss EAP and deploys the application.

Verification

1. In a browser, navigate to \localhost:8080/simple-oidc-layer-example/secured.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Forbidden

   Because you have not assigned the required role to the user "jane_doe," jane_doe can’t log in to your application. Only the users with the required role can log in.

Procedure

1. Log in to the admin console at http://localhost:<port>/auth/. For example, http://localhost:8180/auth/.
2. Click the realm you use to connect with JBoss EAP. For example, example_realm.
3. Click Clients, then click the client-name you configured for JBoss EAP. For example, my_jbeap.
4. Click Roles, then Add Role.
5. Enter a role name, such as example_role, then click Save. This is the role name you configure in JBoss EAP for authorization.
6. Click Users, then View all users.
7. Click an ID to assign the role you created. For example, click the ID for jane_doe.
8. Click Role Mappings. In the Client Roles field, select the client-name you configured for JBoss EAP. For example, my_jbeap.
9. In Available Roles, select a role to assign. For example, example_role. Click Add selected.

Verification

1. In a browser, navigate to the application URL.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Secured Servlet
   Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'

   Users with the required role can log in to your application.

Procedure

1. In the CLI, use the mvn command to set up a Maven project. This 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

   Example

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

2. Navigate to the application root directory.

   Syntax

   $ cd <name-of-your-application>

   Example

   $ cd simple-tracing-example

3. Update the generated pom.xml file.

   1. Set the following properties:

      <properties>
          <maven.compiler.source>1.8</maven.compiler.source>
          <maven.compiler.target>1.8</maven.compiler.target>
          <failOnMissingWebXml>false</failOnMissingWebXml>
          <version.server.bom>4.0.0.GA</version.server.bom>
          <version.wildfly-jar.maven.plugin>6.1.1.Final</version.wildfly-jar.maven.plugin>
      </properties>

   2. Set the following dependencies:

      <dependencies>
          <dependency>
              <groupId>jakarta.enterprise</groupId>
              <artifactId>jakarta.enterprise.cdi-api</artifactId>
              <version>2.0.2</version>
              <scope>provided</scope>
          </dependency>
      
          <dependency>
              <groupId>org.jboss.spec.javax.ws.rs</groupId>
              <artifactId>jboss-jaxrs-api_2.1_spec</artifactId>
              <version>2.0.2.Final</version>
              <scope>provided</scope>
          </dependency>
      
          <dependency>
              <groupId>io.opentelemetry</groupId>
              <artifactId>opentelemetry-api</artifactId>
              <version>1.5.0</version>
              <scope>provided</scope>
          </dependency>
      </dependencies>

   3. Set the following build configuration to use mvn widlfy:deploy to deploy the application:

      <build>
        <!-- Set the name of the archive -->
        <finalName>${project.artifactId}</finalName>
        <plugins>
          <!-- Allows to use mvn wildfly:deploy -->
          <plugin>
            <groupId>org.wildfly.plugins</groupId>
            <artifactId>wildfly-maven-plugin</artifactId>
          </plugin>
        </plugins>
      </build>

Procedure

1. In the <application_root>, create a directory to store the Java files.

   Syntax

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

   Example

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

2. Navigate to the new directory.

   Syntax

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

   Example

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

3. Create a JakartaRestApplication.java file with the following content. This JakartaRestApplication class declares the application as a Jakarta RESTful Web Services application.

   package com.example.opentelemetry;
   
   import javax.ws.rs.ApplicationPath;
   import javax.ws.rs.core.Application;
   
   @ApplicationPath("/")
   public class JakartaRestApplication extends Application {
   }

4. Create an ExplicitlyTracedBean.java file with the following content for the class ExplicitlyTracedBean. This class creates custom spans by injecting a Tracer class.

   package com.example.opentelemetry;
   
   import javax.enterprise.context.RequestScoped;
   import javax.inject.Inject;
   import io.opentelemetry.api.trace.Span;
   import io.opentelemetry.api.trace.Tracer;
   
   @RequestScoped
   public class ExplicitlyTracedBean {
   
       @Inject
       private Tracer tracer; 1
   
       public String getHello() {
           Span prepareHelloSpan = tracer.spanBuilder("prepare-hello").startSpan(); 2
           prepareHelloSpan.makeCurrent();
   
           String hello = "hello";
   
           Span processHelloSpan = tracer.spanBuilder("process-hello").startSpan(); 3
           processHelloSpan.makeCurrent();
   
           hello = hello.toUpperCase();
   
           processHelloSpan.end();
           prepareHelloSpan.end();
   
           return hello;
       }
   }

   1

   Inject a Tracer class to create custom spans.

   2

   Create a span called prepare-hello to indicate that the method getHello() was called.

   3

   Create a span called process-hello to indicate that the value hello was assigned to a new String object called hello.

5. Create a TracedResource.java file with the following content for TracedResource class. This file injects the ExplicitlyTracedBean class and declares two endpoints: traced and cdi-trace.

   package com.example.opentelemetry;
   
   import javax.enterprise.context.RequestScoped;
   import javax.inject.Inject;
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.ws.rs.core.MediaType;
   
   @Path("/hello")
   @RequestScoped
   public class TracedResource {
       @Inject
       private ExplicitlyTracedBean tracedBean;
   
       @GET
       @Path("/traced")
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return "hello";
       }
   
       @GET
       @Path("/cdi-trace")
       @Produces(MediaType.TEXT_PLAIN)
       public String cdiHello() {
           return tracedBean.getHello();
       }
   }

6. Navigate to the application root directory.

   Syntax

   $ cd <path_to_application_root>/<application_root>

   Example

   $ cd ~/applications/simple-tracing-example

7. Compile and deploy the application with the following command:

   $ mvn clean package wildfly:deploy

8. Start the Jaeger console.

   $ docker run -d --name jaeger \
     -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
     -p 5775:5775/udp \
     -p 6831:6831/udp \
     -p 6832:6832/udp \
     -p 5778:5778 \
     -p 16686:16686 \
     -p 14268:14268 \
     -p 14250:14250 \
     -p 9411:9411 \
     jaegertracing/all-in-one:1.29

9. In a browser, navigate to \localhost:8080/simple-tracing-example/hello/cdi-trace.
10. In a browser, open the Jaeger console at http://localhost:16686/search.
11. In the Jaeger console, select JBoss EAP XP and click Find Traces.
12. Click 3 Spans.

13. The Jaeger console displays the following traces:

    |GET /hello/cdi-trace 1
    -
     | prepare-hello 2
      -
       | process-hello 3

    1

    This is the span for the automatic implicit trace.

    2

    The custom span prepare-hello indicates that the method getHello() was called. It is the child of span for the automatic implicit trace.

    3

    The custom span process-hello indicates that the value hello was assigned to a new String object hello. It is the child of the prepare-hello span.

1. There must be an active subscription on the channel before you call Emitter.send(). In this example, notice that the subscribeAndAllowMultipleSubscriptions() method called by the constructor ensures that there’s an active subscription by the time the bean is available for user code calls.
2. You can have only one Subscription on the injected Publisher. If you want to expose the receiving publisher with a REST call, where each call to the poll() method results in a new subscription to the dest publisher, you have to implement your own publisher to broadcast data from the injected to each client.