Upgrade the Oracle Identity Cloud Service App Gateway Version

If your Oracle WebLogic Server for OCI domain uses Oracle Identity Cloud Service for authentication, you must upgrade the App Gateway on each compute instance in the domain as an opc user. The latest App Gateway version is 21.2.2.

The upgrade steps are required only if both of these are true:

You selected the Enable Authentication Using Identity Cloud Service option when creating the domain.
The Oracle Identity Cloud Service App Gateway version is later than 19.2.1.

To upgrade the Oracle Identity Cloud Service App Gateway version, perform the following steps:

Note:

You must delete the existing container and recreate the container with a new version of the image.

Download the Oracle Identity Cloud Service App Gateway Docker image.
1. Access the Identity Cloud Service console.
2. Expand the Navigation Drawer, click Settings, and then click Downloads.
3. In the Downloads page, click Download to the right of App Gateway Docker Image for Identity Cloud Service, and download the file, idcs-appgateway-docker<version>.zip to a location on your system.
4. Navigate to the directory where you downloaded the file, and extract the contents of the zip file.
  Example:
```
unzip idcs-appgateway-docker-<version>.zip
```
  After unzip, the file, appgateway-<version>.tar.gz is created.
Download the Oracle Identity Cloud Service App Gateway wallet tool (optional).
1. Repeat steps a and b from step 1.
2. In the Downloads page, download the wallet file. For example, idcs-appgateway-wallet-tool-<version>.zip.
Copy the Oracle Identity Cloud Service App Gateway Docker image and App Gateway wallet tool to one of the virtual machines in the Oracle WebLogic Server for OCI instance.

For example, copy the files, appgateway-<version>.tar.gz and idcs-appgateway-wallet-tool-<version>.zip.
Deploy the Oracle Identity Cloud Service App Gateway Docker image.
1. In the Oracle WebLogic Server for OCI virtual machine (VM) instance, load the .tar.gz file to the local Docker registry.
```
sudo docker load -i <.tar.gz file>
```
  Example:
```
sudo docker load --input /tmp/appgateway-<version>.tar.gz
```
2. Verify that you see the image in the local Docker registry.
```
sudo docker images
```
Deploy the Oracle Identity Cloud Service App Gateway wallet file (optional).
1. Create a new wallet_tool directory, /usr/lib/wallet_tool.
```
sudo mkdir -p /usr/lib/wallettool/
```
2. Extract the idcs-appgateway-wallet-tool zip to /usr/lib/wallet_tool.
```
sudo unzip /tmp/idcs-appgateway-wallet-tool-<version>.zip -d /usr/lib/wallet_tool/
```
Create the cwallet.sso file (optional).
If the wallet file is not deleted, you can use the existing wallet file (cwallet.sso) to upgrade to the latest App Gateway version, or upgrade the App Gateway wallet tool and generate a new cwallet.sso file.

Use one of the following methods to create the cwallet.sso file.
- Manual:
  Retrieve the client ID and client secret of the app_gateway using information in the idcs_artfacts.txt in the /u01/data directory.
  
  cat /u01/data/.idcs_artifacts.txt
  
  Take a note of the displayName of the app_gateway in /u01/data/.idcs_artifacts.txt.
  
  Example:
  
  { "confidential_app": { "meta": { "location": "https://idcs-<GUID>.identity.oraclecloud.com:443/admin/v1/Apps/<confidential_app_ID>" } }, "app_gateway": { "meta": { "location": "https://idcs-<GUID>.identity.oraclecloud.com:443/admin/v1/CloudGates/<app_gateway_ID>" }, "displayName": "idcs0706_app_gateway_2021-06-07T14:57:22.297066", "id": "< app_gateway_ID>" }, "enterprise_app": { "meta": { "location": "https://idcs-<GUID>.identity.oraclecloud.com:443/admin/v1/Apps/<enterprise_app_ID>" } } }
  
  Note:
  
  Note: You must belong to the Administrator group in Oracle Identity Cloud Service to access this information.
  
  In the Oracle Identity Cloud Service console, expand the Navigation Drawer, click Security, and then click App Gateways. In the App Gateways page, search for the App Gateway with the noted displayName and take a note of the client ID and client secret.
  
  Navigate to /u01/data/cloudgate_config/ directory and create the cwallet.sso file.
  
  cd /u01/data/cloudgate_config/ export LD_LIBRARY_PATH=/usr/lib/wallet_tool/lib/ echo <client_secret> | /usr/lib/wallet_tool/cgwallettool --create -i <client_id>
- Using Scripts:
  
  Note:
  
  You can use scripts to create the cwallet.sso file for Oracle WebLogic Server for OCI version 21.2.3 or later; version 21.2.3 has the latest scripts to support Oracle Identity Cloud Service App Gateway version 21.2.2.
  Add the Oracle Identity Cloud Service client ID and client secret to /u01/data/cloudgate_config/appgateway-env.
  
  Run the create_idcs_cloudgate_cwallet.sh script as a root user.
  
  Note:
  Make sure you are using the latest version of the create_idcs_cloudgate_cwallet.sh script.
  
  Example:
  sudo echo "" >> /u01/data/cloudgate_config/appgateway-env sudo echo "CG_APP_NAME=<client_id>" >> /u01/data/cloudgate_config/appgateway-env sudo echo "CG_APP_SECRET=<client_secret>" >> /u01/data/cloudgate_config/appgateway-env sudo sh /opt/scripts/idcs/create_idcs_cloudgate_cwallet.sh

Stop and remove the existing App Gateway container.

sudo docker container stop appgateway
sudo docker container rm appgateway

Create and start the new App Gateway container.
Use one of the following methods to create and start the new App Gateway container:
- Manual:
  Run the update_metadata script to update the metadata for docker_image_version and docker_image_name to point to the latest version.
  
  Example:
  
  sudo python3 /opt/scripts/utils/update_metadata.py -k idcs_cloudgate_docker_image_version -v <version> sudo python3 /opt/scripts/utils/update_metadata.py -k idcs_cloudgate_docker_image_name -v idcs/idcs-appgateway
  
  Note:
  This step to update the metadata script is required if you upgrade the Oracle Identity Cloud Service App Gateway version during scale out.
  
  Navigate to the /u01/data/cloudgate_config/ directory and change the permissions to 777 and the owner to 8000:8000 for this directory.
  
  Example:
  cd /u01/data/cloudgate_config/ sudo chmod -R 777 /u01/data/cloudgate_config/ sudo chown -R 8000:8000 /u01/data/cloudgate_config/*
  
  Start the App Gateway container using the docker run command.
  
  Note:
  
  You must mount the local folder, /u01/data/cloudgate_config volume to the directory, /usr/local/nginx/conf/ inside the container <my-container>.
  
  The cwallet.sso file that contains the client ID and client secret must be copied to the folder, /usr/local/nginx/conf/ in the container so that the container can reference the wallet file.
  
  Example:
  sudo docker run -it -d --name <my-container> --env-file /u01/data/cloudgate_config/appgateway-env / --env HOST_MACHINE=`hostname -f` --env CLOUDGATE_VERSION=<version> / --volume /u01/data/cloudgate_config/:/usr/local/nginx/conf/:z / --net=host idcs/idcs-appgateway:<version>
- Using Scripts:
  
  Note:
  
  You can use scripts to create the cwallet.sso file for Oracle WebLogic Server for OCI version 21.2.3 or later; version 21.2.3 has the latest scripts to support Oracle Identity Cloud Service App Gateway version 21.2.2.
  Run the update_metadata script to update the metadata for docker_image_version and docker_image_name to point to latest version.
  
  Example:
  
  sudo python3 /opt/scripts/utils/update_metadata.py -k idcs_cloudgate_docker_image_version -v <version> sudo python3 /opt/scripts/utils/update_metadata.py -k idcs_cloudgate_docker_image_name -v idcs/idcs-appgateway
  
  Start the App Gateway container using run_cloudgate.sh.
  
  sudo sh /opt/scripts/idcs/run_cloudgate.sh
Verify the upgrade.
1. Check the App Gateway container logs.
```
sudo docker logs appgateway
```
2. Log in and connect to the container using bash.
  Example:
```
sudo docker exec -it appgateway bash
```
3. Navigate to the bin folder in the container, and check the cloudgate-env file.
  Example:
```
cd /usr/local/nginx/logs/
cd /scratch/oracle/idcs-cloudgate/latest/bin/
./cg-env
```

Remove the existing Oracle Identity Cloud Service Docker image.

sudo docker image rm opc-delivery.docker.oraclecorp.com/idcs/<container_name:existing_version>

Repeat from step 3 for all remaining compute instances in this domain.