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 25.1.03.

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 on each compute instance in the domain:

Note:

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

Download the App Gateway Docker Image for Oracle Identity Cloud Service .
1. Sign in to the Oracle Cloud Infrastructure Console.
2. Expand the Navigation Drawer, click Identity and Security. From the Identity group, click Domains.
3. Select any domain. If you do not see any domains in your compartment you can navigate to the root compartment.
4. On the menu to the left click Settings and then click Downloads.
5. 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.
6. 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 App Gateway wallet tool (optional).
1. Repeat steps a and b from step 1.
2. From the App Gateway wallet tool tile, click Download to download the wallet file. For example, idcs-appgateway-wallet-tool-<version>.zip.
Copy the App Gateway Docker Image for Identity Cloud Service 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 App Gateway Docker Image for Identity Cloud Service.
1. In the Oracle WebLogic Server for OCI virtual machine (VM) instance, load the .tar.gz file to the local Podman registry.
```
sudo podman load -i <.tar.gz file>
```
  Example:
```
sudo podman load --input /tmp/appgateway-<version>.tar.gz
```
2. Verify that you see the image in the local Docker registry.
```
sudo podman images
```
  For example:
```
REPOSITORY                  TAG                 IMAGE ID      CREATED       SIZE
local.local/idcs-appgateway-docker  25.1.03-2501230623  06cb679d8b32  1 months ago  505 MB
localhost/idcs/idcs-appgateway      21.2.2-2105050509   58ed62ca635c  3 years ago   624 MB
```
3. Record the value from the REPOSITORY column after the first slash for the newly added image. Using the example from above this would be "idcs-appgateway-docker". This will be required in step 8 when setting the "idcs_cloudgate_docker_image_name" metadata value.
4. Record the value from the TAG column for the newly added image. Using the example from above this would be "25.1.03-2501230623". This will be required in step 8 when setting the "idcs_cloudgate_docker_image_version" metadata value
5. Record the value from the REPOSITORY column for the older image. Using the example from above this would be "localhost/idcs/idcs-appgateway". This will be required in step 10 when removing the older docker image.
6. Record the value from the TAG column for the older image. Using the example from above this would be "25.1.03-2501230623". This will be required in step 10 when removing the older docker image.
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/wallet_tool/ 
```
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/:/usr/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 24.3.1 has the latest scripts to support App Gateway Docker Image for Identity Cloud Service 25.1.03.
  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 podman container stop appgateway

sudo podman 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 to the value recorded from step 4d and docker_image_name to point to the values recorded from step 4c.
  
  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-appgateway-docker
  
  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 podman 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 podman run -it -d --name appgateway --log-driver=journald --security-opt label=disable --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 24.3.1 has the latest scripts to support Oracle Identity Cloud Service App Gateway version 25.1.03.
  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 podman logs appgateway
```
2. Log in and connect to the container using bash.
  Example:
```
sudo podman 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 App Gateway Docker Image by executing the following command using the value recorded in step 4e for "existing_repository_name" and the value recorded in step 4f for "existing_version".
```
sudo podman image rm opc-delivery.docker.oraclecorp.com/idcs/<container_name:existing_version>
```
Repeat from step 3 for all remaining compute instances in this domain.