== Get Started === Using the {project_openshift_product_name} Image Streams and Application Templates [IMPORTANT] ==== Red Hat JBoss Middleware for OpenShift images are pulled on demand from the secured Red Hat Registry: link:https://access.redhat.com/containers/[registry.redhat.io], which requires authentication. To retrieve content, you will need to log into the registry using the Red Hat account. To consume container images from *_registry.redhat.io_* in shared environments such as OpenShift, it is recommended for an administrator to use a Registry Service Account, also referred to as authentication tokens, in place of an individual person's Red Hat Customer Portal credentials. To create a Registry Service Account, navigate to the link:https://access.redhat.com/terms-based-registry/[Registry Service Account Management Application], and log in if necessary. . From the *_Registry Service Accounts_* page, click *_Create Service Account_*. . Provide a name for the Service Account, for example *_registry.redhat.io-sa_*. It will be prepended with a fixed, random string. .. Enter a description for the Service Account, for example *_Service account to consume container images from registry.redhat.io._*. .. Click *_Create_*. . After the Service Account was created, click the *_registry.redhat.io-sa_* link in the *_Account name_* column of the table presented on the *_Registry Service Accounts_* page. . Finally, click the *_OpenShift Secret_* tab, and perform all steps listed on that page. See the link:https://access.redhat.com/RegistryAuthentication[Red Hat Container Registry Authentication] article for more information. ==== To update to the latest {project_openshift_product_name} images, run the following commands: . On your master host(s), ensure that you are logged in as a cluster administrator or a user with project administrator access to the global `openshift` project. + [source,bash,subs="attributes+,macros+"] ---- $ oc login -u system:admin ---- . Run the following commands to update the core set of {project_name} {project_version} resources for OpenShift in the `openshift` project: + [source,bash,subs="attributes+,macros+"] ---- $ for resource in {project_templates_version}-image-stream.json \ {project_templates_version}-https.json \ {project_templates_version}-mysql.json \ {project_templates_version}-mysql-persistent.json \ {project_templates_version}-postgresql.json \ {project_templates_version}-postgresql-persistent.json \ {project_templates_version}-x509-https.json \ {project_templates_version}-x509-mysql-persistent.json \ {project_templates_version}-x509-postgresql-persistent.json do oc replace -n openshift --force -f \ \https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/{project_templates_version}-dev/templates/${resource} done ---- . Run the following command to install the {project_name} {project_version} OpenShift image streams in the `openshift` project: + [source,bash,subs="attributes+,macros+"] ---- $ oc -n openshift import-image redhat-{project_templates_version}-openshift:{project_latest_image_tag} ---- === Preparing and Deploying the {project_openshift_product_name} Application Templates [[Configuring-Keystores]] ==== Configuring Keystores The {project_openshift_product_name} image requires two keystores: + - An SSL keystore to provide private and public keys for https traffic encryption. + - A JGroups keystore to provide private and public keys for network traffic encryption between nodes in the cluster. These keystores are expected by the {project_openshift_product_name} image, even if the application uses only http on a single-node OpenShift instance. Self-signed certificates do not provide secure communication and are intended for internal testing purposes. [WARNING] For production environments Red Hat recommends that you use your own SSL certificate purchased from a verified Certificate Authority (CA) for SSL-encrypted connections (HTTPS). See the https://access.redhat.com/documentation/en-us/jboss_enterprise_application_platform/6.1/html-single/security_guide/index#Generate_a_SSL_Encryption_Key_and_Certificate[JBoss Enterprise Application Platform Security Guide] for more information on how to create a keystore with self-signed or purchased SSL certificates. ==== Generating Secrets OpenShift uses objects called `Secrets` to hold sensitive information, such as passwords or keystores. See the https://access.redhat.com/documentation/en-us/openshift_enterprise/3.2/html-single/developer_guide/index#dev-guide-secrets[Secrets chapter] in the OpenShift documentation for more information. The {project_openshift_product_name} image requires one or more secrets that hold the two keystores described earlier. This provides the necessary authorization to applications in the project. Use the SSL and JGroups keystore files to create secrets for the project: [source,bash,subs="attributes+,macros+"] ---- $ oc secret new $ oc secret new ---- //// ==== Creating the Service Account Service accounts are API objects that exist within each project and allow users to associate certain secrets and roles with applications in a project namespace. This provides the application with the necessary authorization to run with all required privileges. The service account that you create must be configured with the correct permissions to view pods in Kubernetes. This is required in order for clustering with the {project_openshift_product_name} image to work. You can view the top of the log files to see whether the correct service account permissions have been configured. . Create a service account to be used for the SSO deployment: + [source,bash,subs="attributes+,macros+"] ---- $ oc create serviceaccount ---- . Add the *view* role to the service account. This enables the service account to view all the resources in the application namespace in OpenShift, which is necessary for managing the cluster. + [source,bash,subs="attributes+,macros+"] ---- $ oc policy add-role-to-user view system:serviceaccount:: -n ---- . Link the secrets created for the project to the service account: + [source,bash,subs="attributes+,macros+"] ---- $ oc secrets link ---- //// [[sso-administrator-setup]] ==== Creating Administrator Account for {project_name} Server {project_name} does not provide any pre-configured management account out of the box. This administrator account is necessary for logging into the `master` realm's management console and perform server maintenance operations such as, creating realms or users, or registering applications intended to be secured by {project_name}. The administrator account can be created: * By providing values for the xref:sso-admin-template-parameters[*_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters], when deploying the {project_name} application template, or * By xref:sso-admin-remote-shell[a remote shell session to particular {project_name} pod], if the {project_openshift_product_name} image is deployed without an application template. [NOTE] ==== {project_name} allows an initial administrator account creation via the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.2/html-single/getting_started_guide/#creating_the_admin_account[Welcome Page] web form. But only if the `Welcome Page` is accessed from a localhost, this method of administrator account creation is not applicable for {project_openshift_product_name} image. ==== [[sso-admin-template-parameters]] ===== Creating {project_name} Administrator Account via Template Parameters When deploying {project_name} application template, *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* parameters denote the username and password of the {project_name} server's administrator account to be created for the `master` realm. [NOTE] ==== *Both of these parameters are required.* If not specified, they are auto generated and displayed as an OpenShift instructional message when the template is instantiated. ==== [IMPORTANT] ==== The lifespan of the {project_name} server's administrator account depends upon the the storage type used to store the {project_name} server's database: * For an in-memory database mode (*_{project_templates_version}-https_* and *_{project_templates_version}-x509-https_* templates) the account exist throughout the lifecycle of the particular {project_name} pod (stored account data is lost upon pod destruction), * For an ephemeral database mode (*_{project_templates_version}-mysql_* and *_{project_templates_version}-postgresql_* templates) the account exist throughout the lifecycle of the database pod (even if {project_name} pod is destructed, the stored account data is preserved under the assumption that the database pod is still running), * For persistent database mode (*_{project_templates_version}-mysql-persistent_*, *_{project_templates_version}-x509-mysql-persistent_*, *_{project_templates_version}-postgresql-persistent_*, and *_{project_templates_version}-x509-postgresql-persistent_* templates) the account exists throughout the lifecycle of the persistent medium used to hold the database data. This means that the stored account data is preserved even when both, the {project_name} and the database pods are destructed. It is a common practice to deploy an {project_name} application template to get the corresponding OpenShift deployment config for the application, and then reuse that deployment config multiple times (every time a new {project_name} application needs to be instantiated). ==== [WARNING] ==== In the case of *ephemeral or persistent database mode*, after creating the RH_SSO server's administrator account, remove the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables from the deployment config before deploying new {project_name} applications. ==== [IMPORTANT] ==== Run the following commands to prepare the previously created deployment config of the {project_name} application for reuse after the administrator account has been created: . Identify the deployment config of the {project_name} application. + [source,bash,subs="attributes+,macros+"] ---- $ oc get dc -o name deploymentconfig/sso deploymentconfig/sso-mysql ---- . Clear the *_SSO_ADMIN_USERNAME_* and *_SSO_ADMIN_PASSWORD_* variables setting. + [source,bash,subs="attributes+,macros+"] ---- $ oc set env dc/sso \ -e SSO_ADMIN_USERNAME="" \ -e SSO_ADMIN_PASSWORD="" ---- ==== [[sso-admin-remote-shell]] ===== Creating {project_name} Administrator Account via Remote Shell Session to {project_name} Pod Run following commands to create administrator account for the `master` realm of the {project_name} server, when deploying the {project_openshift_product_name} image directly from the image stream (without the xref:../introduction/introduction.adoc#sso-templates[template]), after the {project_name} application pod has been started: . Identify the {project_name} application pod. + [source,bash,subs="attributes+,macros+"] ---- $ oc get pods NAME READY STATUS RESTARTS AGE sso-12-pt93n 1/1 Running 0 1m sso-mysql-6-d97pf 1/1 Running 0 2m ---- . Open a remote shell session to {project_openshift_product_name} container. + [source,bash,subs="attributes+,macros+"] ---- $ oc rsh sso-12-pt93n sh-4.2$ ---- . Create the {project_name} server administrator account for the `master` realm at the command line with the `add-user-keycloak.sh` script. + [source,bash,subs="attributes+,macros+"] ---- sh-4.2$ cd /opt/eap/bin/ sh-4.2$ ./add-user-keycloak.sh -r master -u sso_admin -p sso_password Added 'sso_admin' to '/opt/eap/standalone/configuration/keycloak-add-user.json', restart server to load user ---- + [NOTE] ==== The `sso_admin`/`sso_password` credentials in the example above are for demonstration purposes only. Refer to the password policy applicable within your organization for guidance on how to create a secure user name and password. ==== . Restart the underlying JBoss EAP server instance to load the newly added user account. Wait for the server to restart properly. + [source,bash,subs="attributes+,macros+"] ---- sh-4.2$ ./jboss-cli.sh --connect ':reload' { "outcome" => "success", "result" => undefined } ---- + [WARNING] ==== When restarting the server it is important to restart just the JBoss EAP process within the running {project_name} container, and not the whole container. Because restarting the whole container recreates it from scratch, without the {project_name} server administration account for the `master` realm to be created. ==== . Log into the `master` realm's administration console of the {project_name} server using the the credentials created in the steps above. In the browser, navigate to *\http://sso-./auth/admin* for the {project_name} web server, or to *\https://secure-sso-./auth/admin* for the encrypted {project_name} web server, and specify user name and password used to create the administrator user. ==== Using the OpenShift Web Console Log in to the OpenShift web console: . Click *Add to project* to list the default image streams and templates. . Use the *Filter by keyword* search bar to limit the list to those that match _sso_. You may need to click *See all* to show the desired application template. . Select an application template and configure the deployment parameters as required. . Click *Create* to deploy the application template. These are some of the more common variables to configure an {project_name} deployment: [cols="2*", options="header"] |=== |Variable |Description |*_APPLICATION_NAME_* |The name for the {project_name} application. |*_HOSTNAME_HTTPS_* |Custom hostname for https service route. Leave blank for default hostname of _.._ |*_HOSTNAME_HTTP_* |Custom hostname for http service route. Leave blank for default hostname of _.._ |*_HTTPS_KEYSTORE_* |The name of the keystore file within the secret. |*_HTTPS_PASSWORD_* |The password for the keystore and certificate. |*_HTTPS_SECRET_* |The name of the secret containing the keystore file. |*_JGROUPS_ENCRYPT_KEYSTORE_* |The name of the JGroups keystore file within the secret. |*_JGROUPS_ENCRYPT_PASSWORD_* |The password for the JGroups keystore and certificate. |*_JGROUPS_ENCRYPT_SECRET_* |The name of the secret containing the JGroups keystore file. |*_SSO_ADMIN_USERNAME_* |Username of the administrator account for the `master` realm of the {project_name} server. *Required.* If no value is specified, it is auto generated and displayed as an OpenShift instructional message when the template is instantiated. |*_SSO_ADMIN_PASSWORD_* |Password of the administrator account for the `master` realm of the {project_name} server. *Required.* If no value is specified, it is auto generated and displayed as an OpenShift instructional message when the template is instantiated. |*_SSO_REALM_* |The name of an additional {project_name} realm to create during deployment. |*_SSO_SERVICE_USERNAME_* |{project_name} service user name to manage the realm. |*_SSO_SERVICE_PASSWORD_* |{project_name} service user password. |=== See the xref:env_vars[Reference chapter] for a more comprehensive list of the {project_name} environment variables. See the xref:Example-Deploying-SSO[Example Workflow: Preparing and Deploying the {project_openshift_product_name} Image] for an end-to-end example of {project_name} deployment. ==== Routes The {project_openshift_product_name} templates use TLS passthrough termination for routes by default. This means that the destination route receives encrypted traffic without the OpenShift router providing TLS termination. Users do not need the relevant SSL certificate to connect to the {project_name} login page. For more information on OpenShift route types, see the link:https://docs.openshift.com/container-platform/3.7/architecture/networking/routes.html#route-types[Networking chapter] of the OpenShift Architecture Guide. === Binary Builds To deploy existing applications on OpenShift, you can use the link:https://docs.openshift.com/container-platform/latest/dev_guide/builds/build_inputs.html#binary-source[binary source] capability. ==== Deploy Binary Build of EAP 6.4 / 7.1 JSP Service Invocation Application that Authenticates Using {project_name} The following example uses both link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/app-jee-jsp[app-jee-jsp] and link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-jee-jaxrs[service-jee-jaxrs] quickstarts to deploy EAP 6.4 / 7.1 JSP service application that authenticates using the {project_name}. *Prerequisite:* [IMPORTANT] ==== This guide assumes the {project_openshift_product_name} image has been previously link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_single_sign-on_for_openshift/index#Example-Deploying-SSO[deployed using one of the following templates:] * *_{project_templates_version}-mysql_* * *_{project_templates_version}-postgresql_* * *_{project_templates_version}-mysql-persistent_* * *_{project_templates_version}-x509-mysql-persistent_* * *_{project_templates_version}-postgresql-persistent_* * *_{project_templates_version}-x509-postgresql-persistent_* ==== ===== Create {project_name} Realm, Roles, and User for the EAP 6.4 / 7.1 JSP Application The EAP 6.4 / 7.1 JSP service application requires dedicated {project_name} realm, username, and password to be able to authenticate using {project_name}. Perform the following steps after the {project_openshift_product_name} image has been deployed: *Create the {project_name} Realm* . Login to the administration console of the {project_name} server. + *\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin* + Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the {project_name} administrator user]. . Hover your cursor over the realm namespace (default is *Master*) at the top of the sidebar and click *Add Realm*. . Enter a realm name (this example uses `demo`) and click *Create*. [[copy-rsa-public-key]] *Copy the Public Key* In the newly created `demo` realm, click the *Keys* tab, then select *Active* tab, and copy the public key of type *RSA* that has been generated. [NOTE] ==== The {project_openshift_product_name} image version {project_version} generates multiple keys by default, for example *HS256*, *RS256*, or *AES*. To copy the public key information for the {project_openshift_product_name} {project_version} image, click the *Keys* tab, then select *Active* tab, and click the *Public key* button of that row in the keys table, where type of the key matches *RSA*. Then select and copy the content of the pop-up window that appears. ==== The information about the public key is necessary xref:sso-public-key-details[later to deploy] the {project_name}-enabled EAP 6.4 / 7.1 JSP application. *Create {project_name} Roles* [NOTE] ==== The link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-jee-jaxrs[service-jee-jaxrs] quickstart exposes three endpoints by the service: * `public` - Requires no authentication. * `secured` - Can be invoked by users with the `user` role. * `admin` - Can be invoked by users with the `admin` role. ==== Create `user` and `admin` roles in {project_name}. These roles will be assigned to an {project_name} application user to authenticate access to user applications. . Click *Roles* in the *Configure* sidebar to list the roles for this realm. + [NOTE] ==== This is a new realm, so there should only be the default (`offline_access` and `uma_authorization`) roles. ==== . Click *Add Role*. . Enter the role name (`user`) and click *Save*. Repeat these steps for the `admin` role. *Create the {project_name} Realm Management User* . Click *Users* in the *Manage* sidebar to view the user information for the realm. . Click *Add User.* . Enter a valid *Username* (this example uses the user `appuser`) and click *Save*. . Edit the user configuration: .. Click the *Credentials* tab in the user space and enter a password for the user (this example uses the password `apppassword`). .. Ensure the *Temporary Password* option is set to *Off* so that it does not prompt for a password change later on, and click *Reset Password* to set the user password. A pop-up window prompts for additional confirmation. ===== Assign `user` {project_name} Role to the Realm Management User Perform the following steps to tie the previously created `appuser` with the `user` {project_name} role: . Click *Role Mappings* to list the realm and client role configuration. In *Available Roles*, select the `user` role created earlier, and click *Add selected>*. . Click *Client Roles*, select *realm-management* entry from the list, select each record in the *Available Roles* list. + [NOTE] ==== You can select multiple items at once by holding the *Ctrl* key and simultaneously clicking the first `impersonation` entry. While keeping the *Ctrl* key and the left mouse button pressed, move to the end of the list to the `view-clients` entry and ensure each record is selected. ==== . Click *Add selected>* to assign the roles to the client. ===== Prepare {project_name} Authentication for OpenShift Deployment of the EAP 6.4 / 7.1 JSP Application . Create a new project for the EAP 6.4 / 7.1 JSP application. + [source,bash,subs="attributes+,macros+"] ---- $ oc new-project eap-app-demo ---- . Add the `view` role to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`default`] service account. This enables the service account to view all the resources in the `eap-app-demo` namespace, which is necessary for managing the cluster. + [source,bash,subs="attributes+,macros+"] ---- $ oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default ---- . The EAP template requires an link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_single_sign-on_for_openshift/index#Configuring-Keystores[SSL keystore and a JGroups keystore]. This example uses `keytool`, a package included with the Java Development Kit, to generate self-signed certificates for these keystores. .. Generate a secure key for the SSL keystore (this example uses `password` as password for the keystore). + [source,bash,subs="attributes+,macros+"] ---- $ keytool -genkeypair \ -dname "CN=secure-eap-app-eap-app-demo.openshift.example.com" \ -alias https \ -storetype JKS \ -keystore eapkeystore.jks ---- .. Generate a secure key for the JGroups keystore (this example uses `password` as password for the keystore). + [source,bash,subs="attributes+,macros+"] ---- $ keytool -genseckey \ -alias jgroups \ -storetype JCEKS \ -keystore eapjgroups.jceks ---- .. Generate the EAP 6.4 / 7.1 for OpenShift secrets with the SSL and JGroup keystore files. + [source,bash,subs="attributes+,macros+"] ---- $ oc secret new eap-ssl-secret eapkeystore.jks ---- + [source,bash,subs="attributes+,macros+"] ---- $ oc secret new eap-jgroup-secret eapjgroups.jceks ---- .. Add the EAP application secret to the link:https://docs.openshift.com/container-platform/latest/dev_guide/service_accounts.html#default-service-accounts-and-roles[`default`] service account. + [source,bash,subs="attributes+,macros+"] ---- $ oc secrets link default eap-ssl-secret eap-jgroup-secret ---- ===== Deploy Binary Build of the EAP 6.4 / 7.1 JSP Application . Clone the source code. + [source,bash,subs="attributes+,macros+"] ---- $ git clone \https://github.com/keycloak/keycloak-quickstarts.git ---- . link:https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.1/html-single/development_guide/#use_the_maven_repository[Configure] the link:https://access.redhat.com/maven-repository[Red Hat JBoss Middleware Maven repository]. . Build both the link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/service-jee-jaxrs[service-jee-jaxrs] and link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/app-jee-jsp[app-jee-jsp] applications. .. Build the `service-jee-jaxrs` application. + [source,bash,subs="attributes+,macros+"] ---- $ cd keycloak-quickstarts/service-jee-jaxrs/ ---- + [source,bash,subs="attributes+,macros+"] ---- $ mvn clean package -DskipTests [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building Keycloak Quickstart: service-jee-jaxrs 3.1.0.Final [INFO] ------------------------------------------------------------------------ ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.153 s [INFO] Finished at: 2017-06-26T12:06:12+02:00 [INFO] Final Memory: 25M/241M [INFO] ------------------------------------------------------------------------ ---- .. *Comment out* the `app-jee-jsp/config/keycloak.json` requirement of the `maven-enforcer-plugin` plugin and build the `app-jee-jsp` application. + [source,bash,subs="attributes+,macros+"] ---- service-jee-jaxrs]$ cd ../app-jee-jsp/ ---- + [source,bash,subs="attributes+,macros+"] ---- app-jee-jsp]$ sed -i /\/s/^/\<\!--/ pom.xml ---- + [source,bash,subs="attributes+,macros+"] ---- app-jee-jsp]$ sed -i '/\(<\/executions>\)/a\-->' pom.xml ---- + [source,bash,subs="attributes+,macros+"] ---- app-jee-jsp]$ mvn clean package -DskipTests [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building Keycloak Quickstart: app-jee-jsp 3.1.0.Final [INFO] ------------------------------------------------------------------------ ... [INFO] Building war: /tmp/github/keycloak-quickstarts/app-jee-jsp/target/app-jsp.war [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 3.018 s [INFO] Finished at: 2017-06-26T12:22:25+02:00 [INFO] Final Memory: 35M/310M [INFO] ------------------------------------------------------------------------ ---- + [IMPORTANT] ==== The link:https://github.com/keycloak/keycloak-quickstarts/tree/latest/app-jee-jsp[app-jee-jsp] quickstart requires to configure the adapter, and adapter configuration file (`keycloak.json`) to be present at the `config/` directory in the root of the quickstart to successfully build the quickstart. But since this example configures the adapter later via selected environment variables available for the EAP 6.4 / 7.1 for OpenShift image, it is not necessary to specify the form of `keycloak.json` adapter configuration file at this moment. ==== [[directory-structure-binary-builds]] [start=4] . Prepare the directory structure on the local file system. + Application archives in the *deployments/* subdirectory of the main binary build directory are copied directly to the xref:standard-deployments-directory[standard deployments directory] of the image being built on OpenShift. For the application to deploy, the directory hierarchy containing the web application data must be correctly structured. + Create main directory for the binary build on the local file system and *deployments/* subdirectory within it. Copy the previously built WAR archives of both the *service-jee-jaxrs* and *app-jee-jsp* quickstarts to the *deployments/* subdirectory: + [source,bash,subs="attributes+,macros+"] ---- app-jee-jsp]$ ls config pom.xml README.md src target ---- + [source,bash,subs="attributes+,macros+"] ---- app-jee-jsp]$ mkdir -p sso-eap7-bin-demo/deployments ---- + [source,bash,subs="attributes+,macros+"] ---- app-jee-jsp]$ cp target/app-jsp.war sso-eap7-bin-demo/deployments/ ---- + [source,bash,subs="attributes+,macros+"] ---- app-jee-jsp]$ cp ../service-jee-jaxrs/target/service.war sso-eap7-bin-demo/deployments/ ---- + [source,bash,subs="attributes+,macros+"] ---- app-jee-jsp]$ tree sso-eap7-bin-demo/ sso-eap7-bin-demo/ |__ deployments |__ app-jsp.war |__ service.war 1 directory, 2 files ---- + [[standard-deployments-directory]] [NOTE] ==== Location of the standard deployments directory depends on the underlying base image, that was used to deploy the application. See the following table: .Standard Location of the Deployments Directory [cols="2", options="header"] |=== | Name of the Underlying Base Image(s) | Standard Location of the Deployments Directory | EAP for OpenShift 6.4 and 7.1 | *_$JBOSS_HOME/standalone/deployments_* | Java S2I for OpenShift | *_/deployments_* | JWS for OpenShift | *_$JWS_HOME/webapps_* |=== ==== . Identify the image stream for EAP 6.4 / 7.1 image. + [source,bash,subs="attributes+,macros+"] ---- $ oc get is -n openshift | grep eap | cut -d ' ' -f 1 jboss-eap64-openshift jboss-eap71-openshift ---- [[eap-new-binary-build]] [start=6] . Create new binary build, specifying image stream and application name. + [NOTE] ==== Replace `--image-stream=jboss-eap71-openshift` parameter with the `--image-stream=jboss-eap64-openshift` one in the following oc command to deploy the JSP application on top of JBoss EAP 6.4 for OpenShift image. ==== + [source,bash,subs="attributes+,macros+"] ---- $ oc new-build --binary=true \ --image-stream=jboss-eap71-openshift \ --name=eap-app --> Found image 31895a4 (3 months old) in image stream "openshift/jboss-eap71-openshift" under tag "latest" for "jboss-eap71-openshift" JBoss EAP 7.1 ------------- Platform for building and running JavaEE applications on JBoss EAP 7.1 Tags: builder, javaee, eap, eap7 * A source build using binary input will be created * The resulting image will be pushed to image stream "eap-app:latest" * A binary build was created, use 'start-build --from-dir' to trigger a new build --> Creating resources with label build=eap-app ... imagestream "eap-app" created buildconfig "eap-app" created --> Success ---- . Start the binary build. Instruct `oc` executable to use main directory of the binary build we created xref:directory-structure-binary-builds[in previous step] as the directory containing binary input for the OpenShift build. In the working directory of *app-jee-jsp* issue the following command. + [source,bash,subs="attributes+,macros+"] ---- app-jee-jsp]$ oc start-build eap-app \ --from-dir=./sso-eap7-bin-demo/ \ --follow Uploading directory "sso-eap7-bin-demo" as binary input for the build ... build "eap-app-1" started Receiving source from STDIN as archive ... Copying all war artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment... Copying all ear artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment... Copying all rar artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment... Copying all jar artifacts from /home/jboss/source/. directory into /opt/eap/standalone/deployments for later deployment... Copying all war artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment... '/home/jboss/source/deployments/app-jsp.war' -> '/opt/eap/standalone/deployments/app-jsp.war' '/home/jboss/source/deployments/service.war' -> '/opt/eap/standalone/deployments/service.war' Copying all ear artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment... Copying all rar artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment... Copying all jar artifacts from /home/jboss/source/deployments directory into /opt/eap/standalone/deployments for later deployment... Pushing image 172.30.82.129:5000/eap-app-demo/eap-app:latest ... Pushed 6/7 layers, 86% complete Pushed 7/7 layers, 100% complete Push successful ---- . Create a new OpenShift application based on the build. + [source,bash,subs="attributes+,macros+"] ---- $ oc new-app eap-app --> Found image 6b13d36 (2 minutes old) in image stream "eap-app-demo/eap-app" under tag "latest" for "eap-app" eap-app-demo/eap-app-1:aa2574d9 ------------------------------- Platform for building and running JavaEE applications on JBoss EAP 7.1 Tags: builder, javaee, eap, eap7 * This image will be deployed in deployment config "eap-app" * Ports 8080/tcp, 8443/tcp, 8778/tcp will be load balanced by service "eap-app" * Other containers can access this service through the hostname "eap-app" --> Creating resources ... deploymentconfig "eap-app" created service "eap-app" created --> Success Run 'oc status' to view your app. ---- . Stop all running containers of the EAP 6.4 / 7.1 JSP application in the current namespace. + [source,bash,subs="attributes+,macros+"] ---- $ oc get dc -o name deploymentconfig/eap-app ---- + [source,bash,subs="attributes+,macros+"] ---- $ oc scale dc/eap-app --replicas=0 deploymentconfig "eap-app" scaled ---- . Further configure the EAP 6.4 / 7.1 JSP application prior the deployment. [[sso-public-key-details]] .. Configure the application with proper details about the {project_name} server instance. + [WARNING] ==== Ensure to replace the value of *_SSO_PUBLIC_KEY_* variable below with the actual content of the RSA public key for the `demo` realm, that has been xref:copy-rsa-public-key[copied]. ==== + [source,bash,subs="attributes+,macros+"] ---- $ oc set env dc/eap-app \ -e HOSTNAME_HTTP="eap-app-eap-app-demo.openshift.example.com" \ -e HOSTNAME_HTTPS="secure-eap-app-eap-app-demo.openshift.example.com" \ -e SSO_DISABLE_SSL_CERTIFICATE_VALIDATION="true" \ -e SSO_USERNAME="appuser" \ -e SSO_PASSWORD="apppassword" \ -e SSO_REALM="demo" \ -e SSO_URL="https://secure-sso-sso-app-demo.openshift.example.com/auth" \ -e SSO_PUBLIC_KEY="MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkdhXyKx97oIoO6HwnV/MiX2EHO55Sn+ydsPzbjJevI5F31UvUco9uA8dGl6oM8HrnaWWv+i8PvmlaRMhhl6Xs68vJTEc6d0soP+6A+aExw0coNRp2PDwvzsXVWPvPQg3+iytStxu3Icndx+gC0ZYnxoRqL7rY7zKcQBScGEr78Nw6vZDwfe6d/PQ6W4xVErNytX9KyLFVAE1VvhXALyqEM/EqYGLmpjw5bMGVKRXnhmVo9E88CkFDH8E+aPiApb/gFul1GJOv+G8ySLoR1c8Y3L29F7C81odkVBp2yMm3RVFIGSPTjHqjO/nOtqYIfY4Wyw9mRIoY5SyW7044dZXRwIDAQAB" \ -e SSO_SECRET="0bb8c399-2501-4fcd-a183-68ac5132868d" deploymentconfig "eap-app" updated ---- .. Configure the application with details about both the SSL and JGroups keystore. + [source,bash,subs="attributes+,macros+"] ---- $ oc set env dc/eap-app \ -e HTTPS_KEYSTORE_DIR="/etc/eap-secret-volume" \ -e HTTPS_KEYSTORE="eapkeystore.jks" \ -e HTTPS_PASSWORD="password" \ -e JGROUPS_ENCRYPT_SECRET="eap-jgroup-secret" \ -e JGROUPS_ENCRYPT_KEYSTORE_DIR="/etc/jgroups-encrypt-secret-volume" \ -e JGROUPS_ENCRYPT_KEYSTORE="eapjgroups.jceks" \ -e JGROUPS_ENCRYPT_PASSWORD="password" deploymentconfig "eap-app" updated ---- .. Define OpenShift volumes for both the SSL and JGroups secrets created earlier. + [source,bash,subs="attributes+,macros+"] ---- $ oc volume dc/eap-app --add \ --name="eap-keystore-volume" \ --type=secret \ --secret-name="eap-ssl-secret" \ --mount-path="/etc/eap-secret-volume" deploymentconfig "eap-app" updated ---- + [source,bash,subs="attributes+,macros+"] ---- $ oc volume dc/eap-app --add \ --name="eap-jgroups-keystore-volume" \ --type=secret \ --secret-name="eap-jgroup-secret" \ --mount-path="/etc/jgroups-encrypt-secret-volume" deploymentconfig "eap-app" updated ---- .. Configure the deployment config of the application to run application pods under the `default` OpenShift service account (default setting). + [source,bash,subs="attributes+,macros+"] ---- $ oc patch dc/eap-app --type=json \ -p '[{"op": "add", "path": "/spec/template/spec/serviceAccountName", "value": "default"}]' "eap-app" patched ---- . Deploy container of the EAP 6.4 / 7.1 JSP application using the modified deployment config. + [source,bash,subs="attributes+,macros+"] ---- $ oc scale dc/eap-app --replicas=1 deploymentconfig "eap-app" scaled ---- . Expose the service as route. + [source,bash,subs="attributes+,macros+"] ---- $ oc get svc -o name service/eap-app ---- + [source,bash,subs="attributes+,macros+"] ---- $ oc get route No resources found. ---- + [source,bash,subs="attributes+,macros+"] ---- $ oc expose svc/eap-app route "eap-app" exposed ---- + [source,bash,subs="attributes+,macros+"] ---- $ oc get route NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD eap-app eap-app-eap-app-demo.openshift.example.com eap-app 8080-tcp None ---- ===== Access the Application Access the application in your browser using the URL *\http://eap-app-eap-app-demo.openshift.example.com/app-jsp*. You should see output like on the following image: [.text-center] image:images/sso_app_jee_jsp.png[{project_name} Example JSP Application] Perform the following to test the application: * Click the *INVOKE PUBLIC* button to access the `public` endpoint that doesn't require authentication. + You should see the *Message: public* output. * Click the *LOGIN* button to be redirected for user authentication to the {project_name} server instance against the `demo` realm. + Specify username and password of the {project_name} user configured earlier (`appuser` / `apppassword`). Click *Log in*. The look of the application changes as detailed in the following image: + [.text-center] image:images/sso_app_jee_jsp_logged_in.png[] * Click the *INVOKE SECURED* button to access the `secured` endpoint. + You should see the *Message: secured* output. * Click the *INVOKE ADMIN* button to access the `admin` endpoint. + You should see *403 Forbidden* output. + [NOTE] ==== The `admin` endpoint requires users with `admin` {project_name} role to invoke properly. Access for the `appuser` is forbidden because they only have `user` role privilege, which allows them to access the `secured` endpoint. ==== + Perform the following steps to add the `appuser` to the `admin` {project_name} role: + . Access the administration console of the {project_name} server's instance. + *\https://secure-sso-sso-app-demo.openshift.example.com/auth/admin*. + Use the xref:sso_server.adoc#sso-administrator-setup[credentials of the {project_name} administrator user]. . Click *Users* in the *Manage* sidebar to view the user information for the `demo` realm. . Click *View all users* button. . Click the ID link for the *appuser* or alternatively click the *Edit* button in the *Actions* column. . Click the *Role Mappings* tab. . Select `admin` entry from the *Available Roles* list in the *Realm Roles* row. . Click *Add selected>* button to add the `admin` role to the user. . Return to EAP 6.4 / 7.1 JSP service application. + *\http://eap-app-eap-app-demo.openshift.example.com/app-jsp*. . Click the *LOGOUT* button to reload role mappings for the `appuser`. . Click the *LOGIN* button again and provider `appuser` credentials. . Click the *INVOKE ADMIN* button again. + You should see the *Message: admin* output already.