Create and Configure an App Gateway Client

Create the App Gateway client and start the server.

This requires you to set up the App Gateway client, install the docker, and run the docker image.

Before you begin, review these requirements:

Administrative access to the machine where the App Gateway will be running is required.
Because the App Gateway client will be using ports 7777 and 4443 in this example, stop all processes currently running on those ports. For example, Oracle HTTP Server typically uses these ports by default. Be sure to stop that server or any others that might use those ports before continuing.

Note:
The port numbers used here are only examples. Use whatever valid port numbers are desired. However, be sure the ports selected do not create a port conflict with other listeners on the machine and be sure to use the chosen values throughout the configuration.
Ensure you have the Client ID and Client Secret previously obtained in an earlier step above.
Ensure that Docker is properly installed and running on this machine. If not, do so now. Installation will require “root” access.

Set up the App Gateway Client on the Middle Tier

Create the App Gateway client using the App Gateway Docker Image for Identity Cloud Service as well as a wallet using the App Gateway Wallet Tool.

To set up the App Gateway client:

Navigate to the Identity Domain Overview screen for the domain created in Create an IAM Application.
Click Settings from the menu on the left.
Click Downloads.
Download the latest version of these software packages onto the machine where the App Gateway client will be configured (the middle tier machine).
- App Gateway Docker Image for Identity Cloud Service
- App Gateway Wallet Tool
Create directories for the Docker image, Wallet Tool, and for storing the key and certificate files that will be created in the following steps.
For example, enter the following commands:
```
mkdir /u01/oracle/appgateway/docker 
mkdir /u01/oracle/appgateway/wallettool 
mkdir /u01/oracle/appgateway/keys
```
Extract the contents of the Docker Image downloaded earlier into the ‘docker’ directory and the contents of the Wallet Tool into the ‘wallettool’ directory.
The docker extraction will include a .gz file. Do not extract it. Leave it in the gz format.
Change the current directory to enter the ‘keys’ directory created earlier.
```
cd /u01/oracle/appgateway/keys
```
Create a self-generated certificate with this command. Make changes in the example to accommodate your needs.
```
openssl req -new -newkey rsa:2048 -days 730 -nodes -x509 -subj 
/C=US/ST=CA/L=RedwoodShores/O=OracleUSAInc/OU=Forms/CN=yourserver.com/emailAddress=youradministrator@example.com 
-keyout ssl.key -out ssl.cert
```
Note:
Using a self-generated certificate is not recommended for production use. Further, such a configuration may not work correctly when attempting to run an Oracle Forms application using Forms Standalone Launcher. Using a certificate provided by a known and trusted certificate authority is always recommended.
Change directory to the location of the Wallet Tool:
```
cd /u01/oracle/appgateway/wallettool
```

Execute each of the following one line at a time in the shell:

export CLIENT_ID=<ENTER YOUR CLIENT ID FROM THE EARLIER STEP ABOVE>
export CLIENT_SECRET=<ENTER YOUR CLIENT SECRET FROM THE EARLIER STEP ABOVE>
echo $CLIENT_SECRET | env LD_LIBRARY_PATH=./lib ./cgwallettool --create -i $CLIENT_ID

Move the created wallet to the ‘keys’ directory:
```
mv cwallet.sso ../keys/cwallet.sso
```
Change directories to the ‘appgateway’ directory.
For example:
```
cd /u01/oracle/appgateway
```
In the ‘appgateway’ directory, create a text file and name it appgateway-env (do not include an extension). Add the following contents to the file and save it. Replace < > entries with those that are appropriate for your system.
```
CG_APP_TENANT=<tenant name>
IDCS_INSTANCE_URL=<idcs instance url>
NGINX_DNS_RESOLVER=<resolver ip>
```
CG_APP_TENANT: The tenant name identifier of the Identity Domains instance. This is not your Cloud account/tenancy name. The IAM tenant name is the first portion of the IDCS Instance URL (up to the first dot, but not including the protocol) you will use below. On the Domain Overview page, the “Domain URL” can be found in the Domain Information panel (See Figure 6 below). Copy the first portion of the URL. For example: idcs-1234567890abcdefghijk

IDCS_INSTANCE_URL: The URL required to access the IAM instance. Enter the entire URL. This can be found on the Identity Domain Overview screen in the Domain Information tab.

NGINX_DNS_RESOLVER: Enter the nameserver found in the file /etc/resolv.conf. The default value is 127.0.0.1.

Run the Oracle App Gateway Docker Container

Install and run Docker and the App Gateway Docker Image.

Because the required App Gateway client is only available as a Docker Image or full Virtual Machine (VM), familiarity with using either Docker or running a Virtual Machine will be helpful. This document will only cover the use of the Docker Image. A similar configuration approach can be used for using the full VM. Refer to the IAM documentation for assistance with configuring and using the full VM.

Install and Start Docker

Install and start Docker.

On newer Linux versions podman may be used in place of docker. However, the command arguments should be the same for both. If necessary, refer to the official Docker or Podman documentation for more guidance on using these utilities.

To install Docker:

If Docker is not already installed on the machine, as the “root” user install Docker with this command:
```
yum install docker-engine
```
Note:
For Linux 8 or newer, use dnf instead of yum.
As the “root” user add the current user to the Docker group. Skip the first command if a “docker” group already exists.
```
groupadd docker
usermod -aG docker oracle
```
Note:
Replace “oracle” above with the user that will own the AppGateway Docker environment.
As the “root” user, start Docker with the following command then return to your user:
```
systemctl start docker
```
Verify that the file /var/run/docker.sock has 766 permissions. If not, as the root user change the permissions on the file using the chmod command.

Note:
If this permission is not set properly, the user (for example, oracle) will not be able to connect to the Docker image or start it.
Exit from the ‘root’ user and verify that Docker is running and can be accessed by the current user (for example, oracle).
The following command should return the contents of the local repository, which will be empty if this is a new installation. Otherwise, it will list the images previously created. No errors should be presented.

It may be necessary to reboot the machine if Docker does not start without error and you just installed it. If any permissions errors are presented, refer to the previous step.
```
docker images
```

Import the App Gateway Docker Image

Import and load the App Gateway Docker Image

To import and load the App Gateway Docker Image:

Open a shell and change directory to the directory where you extracted the App Gateway Docker file (.tar.gz) in Set up the App Gateway Client on the Middle Tier.

Execute the following in order to load the image:

docker load --input appgateway-<VERSION NUMER>.tar.gz

Run the Docker Image

Run the Docker image for the first time.

To run the Docker image for the first time:

List the available images by executing this command. Some of this information will be needed in order to start the image:
```
docker images
```
This will output something similar to the following:
```
REPOSITORY            TAG                  IMAGE ID      CREATED       SIZE
idcs/idcs-appgateway  23.2.101-2304020420  ba1249c25dc3  9 months ago  498MB
```
Execute the following command.
This command is a single line that wraps visually. Be sure to enter it as a single entry, adjusting the values to match your system and desired settings. Replace the idcs-appgateway version with the version you downloaded. The version number is part of the downloaded file name.
```
docker run -it -p 4443:4443 -p 7777:7777 --name appgateway --env-file 
/u01/oracle/appgateway/appgateway-env --env HOST_MACHINE=`hostname -f` --volume 
/u01/oracle/appgateway/keys/cwallet.sso:/usr/local/nginx/conf/cwallet.sso --volume 
/u01/oracle/appgateway/keys:/home/oracle/keys --net=host idcs/idcs-appgateway:23.2.101-2304020420
```
Note:
Refer to the IAM Setup documentation for more information.
Given the above example settings, the App Gateway client listener in the container can be accessed using the hostname:4443 or hostname:7777. For example: https://<hostname>:4443
To verify IAM and the App Gateway are responding, run the following from a browser:
https://<app gateway host>:<port>/cloudgate/v1/about

This will return a JSON page indicating a “RUNNING” status. If you see any other result, likely the App Gateway is not configured correctly and/or is not accessible from the client browser.

If the above is not accessible, verify that the value of “HOST_MACHINE” provided above is an accessible host name by users. If you do not have a registered domain name you can alternatively use the machine’s public facing IP address.

The above command can only be used the first time the contain image is started. Refer to Stop the Docker Container for information on restarting after having stopped previously.

Stop the Docker Container

To stop the running Docker container:

Determine the Container ID by running this command:
```
docker ps
```
The output will resemble the following, although only two columns are shown below:
```
CONTAINER ID    IMAGE
ebe97115c307              idcs/idcs-appgateway:22.2.61-2203221920
```
Using the Container ID from above, execute the “stop” command.
```
docker stop <container ID>
```
You can alternatively use the container name:
```
docker stop <container name>
```

After the container has been stopped, it can be restarted using the same settings previously used, with the following Docker command:

docker start <contain name>