Preparing the Environment for Upgrade

General Prerequisites

The following must be met before performing the upgrade:

The Kubernetes cluster must be upgraded to meet the minimum version requirements outlined in Document ID 2723908.1 on My Oracle Support.
The OAA and OARM deployment must be up and running.
Make sure the installation host prerequisites are met as per Installation Host Requirements.
The installation host must have access to the NFS volumes for the existing deployment. See Configuring NFS Volumes.
Backup file system data, runtime data, and policy and configuration data. See, Backing Up OAA/OARM.

Upgrading To Include Oracle Universal Authenticator

If you haven't previously configured Oracle Universal Authenticator (OUA) and want to upgrade OAA to include OUA, you must perform the following steps:

Upgrade Oracle Access Management (OAM) to April 24 Bundle Patch or later.
Follow Oracle Access Management Requirements and perform any prerequisite steps that are required for OUA, for example missing OHS entries, and OUA TAP partner.
Add an additional image registry, oaa-drss, to your repository. See Setting Up a Container Image Registry (CIR).
Add the LDAP attribute obpsftid: true to any user who is to use OUA. See Creating Users and Groups in the LDAP Store.

Push Notification for Android Devices

The following section is only relevant if you are upgrading from any release prior to June 24 and are already using Push Notifications. If you are already using the June 24 release or not using Push Notifications, you can ignore this section.

From June 2024 Google are removing deprecated FCM legacy APIs, see Migrate from legacy FCM APIs to HTTP v1. As a result, if you have push notifications for Android configured in your existing deployment, you need to perform some changes to your existing configuration:

Login to Google Firebase console at https://console.firebase.google.com/.
Click on your existing Firebase project, for example OAAAndroidPUSH.

Note:
If you no longer have access to the account that created the project, you will need to create a new project using the instructions in Creating a Google Firebase Project Enabled for Google Cloud Messaging and then update the senderId parameter as per Configuring OAA Properties for Android Push Notification.
In the left navigation pane of the project window, click the Settings icon, and then select Project settings.
Go to the Service Accounts tab and click Generate new private key. In the Generate new private key window, click Generate key. This will generate a service account json file. Download and save the file, for example service-account.json, and keep it secure.

Create a directory in the NFS volume <NFS_VAULT_PATH> and copy the json file across:

cd <NFS_VAULT_PATH>
$ mkdir -p ChallengeOMAPUSH/gcm
$ cp service-account.json <NFS_VAULT_PATH>/ChallengeOMAPUSH/gcm
$ sudo chmod 444 <NFS_VAULT_PATH>/ChallengeOMAPUSH/gcm/service-account.json

Edit the <NFS_LOG_PATH>/status.info and set the following vault parameters to false, then save the file:
```
VAULTINSTALL=false
VAULTCHECK=false
```

Preparing the Environment for Upgrade

Take a backup of the existing installOAA.properties in case you need to rollback the upgrade:
```
cd <NFS_CONFIG_PATH>
cp installOAA.properties installOAA.properties.<release-date>
```
In the <NFS_LOG_PATH>/status.info make sure SNAPSHOTIMPORT=true.

Note:
This is a very important step. If this value is false make sure you change it to true, otherwise your OAA snapshot will be overwritten during the upgrade!
Download and extract the latest OAA installation files to the installation host as per Obtaining the Installation Software.

Note:
When you unzip the file it will create the oaa-install directory, for example $UPGRADE_WORKDIR/oaa-install. This directory will be used in the steps that follow.
Find the name of the existing OAA Management container:
```
kubectl get pods -n <namespace> | grep oaamgmt
```
For example:
```
kubectl get pods -n oaans | grep oaamgmt
```
The output will look similar to the following:
```
oaamgmt-oaa-mgmt-bf6d5c88-29lrn           1/1     Running   0          64d
```

Copy the installOAA.properties for the current deployment to the $UPGRADE_WORKDIR/oaa-install directory:

kubectl cp <namespace>/<oaamgmt-pod>:/u01/oracle/scripts/settings/installOAA.properties $UPGRADE_WORKDIR/oaa-install/installOAA.properties

For example:

kubectl cp oaans/oaamgmt-oaa-mgmt-bf6d5c88-29lrn:/u01/oracle/scripts/settings/installOAA.properties $UPGRADE_WORKDIR/oaa-install/installOAA.properties

Edit the $UPGRADE_WORKDIR/oaa-install/installOAA.properties and change the install.global.image.tag to the image tag for the latest release.

Note:
You can find the correct value for install.global.image.tag in the $UPGRADE_WORKDIR/oaa-install/installOAA.properties.template.
If you haven't previously installed OUA and want to upgrade your installation to include OUA, you must edit the $UPGRADE_WORKDIR/oaa-install/installOAA.properties and change the following:
- common.deployment.mode=OUA
- install.global.drssapikey=drssapikeytobesetduringinstallation
  
  Note:
  Change drssapikeytobesetduringinstallation to a value of your choice.
- Set the following parameters:
  - oua.tapAgentName=OAM-OUA-TAP
  - oua.tapAgentFilePass=<OUA_TAPFILE_PASSWORD>
  - oua.tapAgentFileLocation=<OUA_TAPFILE_LOCATION>
  - oua.oamRuntimeEndpoint=<WEB_HOST>
  Note:
  See Configuration Checkpoint for more details.
Add the following new section:
```
##################################### OAA Configuration ###########################################
oaa.tapAgentName=<OAA_TAP_PARTNER_NAME>
oaa.tapAgentFilePass=<OAA_TAP_FILE_PASS>
oaa.tapAgentFileLocation=<LOCAL_PATH>/<LOCAL_TAP_AGENT_FILE>
oaa.authFactors=ChallengeEmail,ChallengeSMS,ChallengeOMATOTP,ChallengeYubicoOTP,ChallengeOMAPUSH,ChallengeFIDO2
####################################################################################################
```
Administrators should be aware of the following:
- If you have previously integrated OAM with OAA as per Integrate Oracle Access Management with Oracle Advanced Authentication, then:
  - oaa.tapAgentName must be set to the name of the OAA TAP Partner for your existing deployment. The name can be found by referencing the tutorial above.
  - If the OAA TAP Partner is found during the upgrade then the oaa.tapAgentFilePass, oaa.tapAgentFileLocation, and oaa.authFactors are ignored. However, they must be set to either the default values listed above, or you can copy your TAP Partner keystore to a local directory on the <INSTALL_HOST> and set the parameters correctly.
- If you have not previously integrated OAM with OAA you should follow the Registering OAA as a TAP Partner in OAM section in Registering OAM TAP Partners, and set the parameters accordingly.
If you are upgrading from a release prior to June 24 and have Push notifications for Android configured, you must edit the $UPGRADE_WORKDIR/oaa-install/installOAA.properties file and update the common.deployment.push.gcmjsonfile parameter to point at the service-account.json file downloaded earlier:
```
common.deployment.push.gcmjsonfile=/u01/oracle/service/store/oaa/ChallengeOMAPUSH/gcm/service-account.json
```
Note:
/u01/oracle/service/store/oaa/ChallengeOMAPUSH/gcm/service-account.json is the internal mapping to <NFS_VAULT_PATH>/ChallengeOMAPUSH/gcm/service-account.json.

Add the following new section to the installOAA.properties. For details on these parameters see Creating Users and Groups in the LDAP Store:


##################################### LDAP configuration #########################################
ldap.server=<LDAP_SERVER>
ldap.username=<LDAP_ADMIN_USER>
ldap.password=<LDAP_ADMIN_PWD>
ldap.oaaAdminUser=cn=oaaadmin,<LDAP_USER_SEARCHBASE>
ldap.adminRole=cn=OAA-Admin-Role,<LDAP_GROUP_SEARCHBASE>
ldap.userRole=cn=OAA-App-User,cn=<LDAP_GROUP_SEARCHBASE>
ldap.oaaAdminUserPwd=<password>
ldap.addExistingUsers=no

Ensure that the OAA Management helm chart (oaamgmt) is visible by running the following command:
```
helm ls -n <namespace> | grep oaamgmt
```
For example:
```
helm ls -n oaans | grep oaamgmt
```
The output should look similar to the following:
```
oaamgmt   oaans   1   <DATE> <TIME> +0000 UTC deployed   oaa-mgmt-1.0.0-12.2.1.4.1-<TAG>   0.1.0
```