2 Installing Oracle Advanced Authentication

2.1 About OAA Management Container

OAA provides a docker container called OAA Management Container that includes all the required scripts and tools needed to install OAA on a new or existing Kubernetes cluster.

This container is itself not part of the OAA installation but facilitates installing OAA.

OAA management container has the following binaries also installed based on oraclelinux:slim-7.9 (OELCNE) along with the standard linux utilities such as zip, iputils, net-tools, and vim:
  • kubectl (1.18.4)
  • helm (3.5.2)
  • sqlplus: instantclient_19_10
  • impdp/expdp
  • openssl
  • sslpass
  • openssh

For more information about the Management Container, see the following topics:

2.1.1 Components of Management Container

This section provides an overview of important files and folders in the Management Container.

Table 2-1 Management Container Files and Folder Reference

Files and Folders Description
OAA.sh This script file is used to install OAA. The installOAA.properties file must be given as an argument to the script for installing OAA. An instance of this file must exist in the /u01/oracle/scripts/settings location.

For more information, see Preparing the installOAA.properties file for OAA Installation

runManagementContainer.sh This script is used to run the management container with required docker volumes. The script can be edited to include the required hosts for running OAA installation. For more information, see Running the Management Container (OAA 122140-20210426)
installsettings This folder contains the following files that can be customized and used to install OAA:
  • installOAA.properties: this is given as an argument to the OAA.shscript for installing OAA.
  • oaaoverride.yaml: this can be used to customize the replicaCount for some of the services in OAA.

    To enable this you must set the common.deployment.overridefile property in the installOAA.properties file.

helmcharts This folder contains helm charts and value.yaml for all OAA services.
libs This folder contains the following files:
logs This docker read/write volume stores logs and status of the OAA installation.
scripts/creds This folder contains the following files used during installation:
  • trust.p12
  • cert.p12
  • k8sconfig
  • helmconfig
scripts/settings This docker read/write volume stores installOAA.properties and oaaoverride.yaml configuration files required for installation.
service/store/oaa/ This is a configurable NFS read/write volume that is shared between management container and the OAA deployment.

2.1.2 Preset Environment Variables in Management Container

The Management Container is configured with a predefined set of environment variables.

Table 2-2 Preset Environment Variables

Environment Variable Description
HELM_CONFIG This is set to /u01/oracle/scripts/creds/helmconfig.
KUBECONFIG This is set to /u01/oracle/scripts/creds/k8sconfig.
SCRIPT_PATH This is set to /u01/oracle/scripts. This contains the OAA installation script.
CONFIG_DIR This is a docker volume used to store OAA configuration externally.

It is mounted to the path /u01/oracle/scripts/settings in the container.

Configuration files, such as installOAA.properties file can be created to store the configurations externally.

OAAsettings docker volume is created after running management container, if it does not exist already.

CREDS_DIR This is a docker volume used to store OAA credentials, such as helm config, kube config , and login private keys.

It is mounted to the path /u01/oracle/scripts/creds in the container.

OAAcredentials docker volume is created after running the management container, if it does not exist already.

LOGS_DIR This is a docker volume used to store OAA installation logs and status.

It is mounted to path /u01/oracle/logs in the container.

OAAlogs docker volume is created after running the management container, if it does not exist already.

HELM_CHARTS_PATH This is the path where all the helm charts related to OAA installation exist.
LD_LIBRARY_PATH Set the instant client folder. The variable is required to run the sqlplus and DB-related commands from instant client present in the container.
LIBS_DIR This exists in the path /u01/oracle.

It contains the jar file required for customizing email and SMS providers and OAM Authentication plugin.

It also contains jars that are required for fks vault deployment.

JAR_PATH This contains the following jars required for fks vault to run properly:
  • uas-util.jar
  • javax.json-1.1.jar
  • javax.json-api-1.1.4.jar

2.1.3 Mounted Volumes in Management Container

This section provides details about the mounted volumes in the Management Container

Table 2-3 Mounted Volumes in Management Container

Mount Folder Description Permissions to be Set
/u01/oracle/logs Path not configurable.

Docker volume on the running host is set as OAAlogs

This is used to store installation logs and status

Read-Write

Run the following command on the host to enable write permission on the volume:

sudo chmod 777 `docker inspect OAAlogs | grep "Mountpoint" | cut -d':' -f2 | tr -d "\",\ "`
/u01/oracle/scripts/settings Path not configurable.

Docker volume on the running host is set as OAAsettings

This is used to store the customized configuration file for installing OAA.

Read-Write

Run the following command on the host to make the volume read-only

sudo chmod 777 `docker inspect OAAsettings | grep "Mountpoint" | cut -d':' -f2 | tr -d "\",\ "`
/u01/oracle/scripts/creds Path not configurable.

This is used to store credential files such as k8sconfig, helmconfig, trust.p12 and cert.p2

Read-only

Run the following command on the host to make the volume read-only

sudo chmod 755 `docker inspect OAAcredentials | grep "Mountpoint" | cut -d':' -f2 | tr -d "\",\ "`
/u01/oracle/service/store/oaa Path is configurable.

This is used to store the vault artifacts for file-based vault.

Read-Write

Run the following command on the host to enable write permission on the volume:

sudo chmod 777 `docker inspect OAAvault | grep "Mountpoint" | cut -d':' -f2 | tr -d "\",\ "`

2.2 Prerequisite Configurations for Installing OAA

Before progressing to the installation steps for OAA, ensure you have performed the following:

2.2.1 System Requirements and Certification

Ensure that your environment meets the system requirements such as hardware and software , minimum disk space, memory, required system libraries, packages, or patches before performing any installation.

OAA consists of multiple components that run as microservices on a Kubernetes cluster, managed by Helm charts. To ensure that you are able to install OAA, the following additional operating environment requirements needs to be met.

Cloud Native Environment (CNE)

OAA is designed to be deployed on a CNE, that is composed docker containers running in a Kubernetes Cluster. Specifically, each component (microservice) is composed as a Kubernetes Pod, which is then deployed to a Kubernetes Node.

To realize a CNE, you have the following options:

Container Image Registry (CIR)

OAA container images must be downloaded from My Oracle Support (MOS) and stored in a registry that is accessible to the OAA Management Container, which will be used to create and manage the OAA deployment.

OAA only supports docker images. Docker Registry can be found here: https://hub.docker.com/_/registry/

The following table provides the minimum system requirements for installing OAA:

Hardware Type Minimum Requirements
Standalone Host
  • 16 GB of RAM
  • Disk space of 50 GB
  • 2 CPU
Server
  • 64 GB of RAM
  • Disk space of 150 GB
  • 8 CPU (with Virtualization support. For example, Intel VT)

The certification document covers supported installation types, platforms, operating systems, databases, JDKs, and third-party products:

http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html

2.2.2 Setting Up Groups in the OAM Identity Store

Configure the following groups in the User Identity Store (for example, LDAP server) that OAM uses:

OAA-Admin-Role: this role is used during user login into Admin Console UI. For example, the following LDIF file shows the OAA-Admin-Role group added to the Base DN and also the administrator user oaaadmin added as member of that group:
dn:cn=OAA-Admin-Role,ou=groups,dc=example,dc=com
changetype:add
objectClass: top
objectClass: groupofuniquenames
uniqueMember: uid=oaaadmin,ou=People,dc=example,dc=com
OAA-App-User: this role is used during user login into User Preferences UI to manage preferences. For example, the following LDIF file shows the OAA-App-User group added to the Base DN and the user testuser added as member of that group:
dn:cn=OAA-App-User,ou=groups,dc=example,dc=com
changetype:add
objectClass: top
objectClass: groupofuniquenames
uniqueMember: uid=testuser,ou=People,dc=example,dc=com
Every user who needs OAA access must be a member of the OAA-App-User group, otherwise they will not be able to log in to the User Preferences UI through OAM OAuth. Similarly, for the administrator to be able to access OAA admin console, they must be a member of the OAA-Admin-Role group.

Note:

A User cannot be a member of both the admin and user groups. Therefore, it is recommended that you have a dedicated admin user name.

2.2.3 Prerequisites for Setting Up OAM OAuth for OAA

The User Interface (UI) components of OAA are protected by Oracle Access Management (OAM) OAuth. OAuth can be configured during the OAA installation. However, following are the prerequisites steps to be performed before configuring OAM OAuth:

Note:

You can skip OAuth configuration if the UI components are not required or need to be disabled during OAA installation.
  1. Install Oracle Access Management. For details, see Installing and Configuring Oracle Identity and Access Management
  2. Register WebGates with OAM. For details, see Registering and Managing OAM Agents
  3. Enable OAuth on the Oracle Access Management Console.
    1. Log in to the OAM Console https://OAMAdminHost:OAMAdminPort/oamconsole/
    2. From the Welcome page, click Configuration and then click Available Services
    3. Click Enable Service beside OAuth and OpenIDConnect Service (or confirm that the green status check mark displays).
  4. Open the mod_wl_ohs.conf file located at <OHS_HOME>/user_projects/domains/base_domain/config/fmwconfig/components/OHS/<ohs_instance_name> and add the following:
    <Location /oauth2>
    SetHandler weblogic-handler
    WebLogicHost oam.example.com
    WebLogicPort 14100
    </Location>
    
    <Location /oam>
     SetHandler weblogic-handler
     WebLogicHost oam.example.com
     WebLogicPort 14100
    </Location>
    
    <Location /.well-known/openid-configuration>
     SetHandler weblogic-handler
     WebLogicHost oam.example.com
     WebLogicPort 14100
     PathTrim /.well-known
     PathPrepend /oauth2/rest
    </Location>
    
    <Location /.well-known/oidc-configuration>
    SetHandler weblogic-handler
    WebLogicHost oam.example.com
    WebLogicPort 14100
    PathTrim /.well-known
    PathPrepend /oauth2/rest
    </Location>
    
    <Location /CustomConsent>
    SetHandler weblogic-handler
    WebLogicHost oam.example.com
    WebLogicPort 14100
    </Location>
    
  5. Open the httpd.conf file located at <OHS_HOME>/user_projects/domains/base_domain/config/fmwconfig/components/OHS/<ohs_instance_name>/ and add the following:

    Note:

    Specify an OAuth Identity Domain in <DomainName>. This <DomainName> needs to be provided again during the OAuth setup of the OAA installation.
    
    <IfModule mod_rewrite.c>
    RewriteEngine on
    RewriteRule ^/oauth2/rest/authorize? /oauth2/rest/authorize?domain=<DomainName> [QSA]
    RewriteRule ^/oauth2/rest/token? /oauth2/rest/token?domain=<DomainName> [QSA]
    RewriteRule ^/oauth2/rest/token/info? /oauth2/rest/token/info?domain=<DomainName> [QSA]
    RewriteRule ^/oauth2/rest/authz? /oauth2/rest/authz?domain=<DomainName> [QSA]
    RewriteRule ^/oauth2/rest/userinfo? /oauth2/rest/userinfo?domain=<DomainName> [QSA]
    RewriteRule ^/oauth2/rest/security? /oauth2/rest/security?domain=<DomainName> [QSA]
    RewriteRule ^/oauth2/rest/userlogout? /oauth2/rest/userlogout?domain=<DomainName> [QSA]
    </IfModule>
    
    <IfModule mod_headers.c>
    #Add Identity domain header always for OpenID requests
    RequestHeader set X-OAUTH-IDENTITY-DOMAIN-NAME "<DomainName>"
    </IfModule>
  6. For the OHS WebGate defined in the previous steps, perform the following in the OAM console:
    1. Create each of the following resources and set the Protection Level as Excluded.
      • /oauth2/rest/**
      • /oam/**
      • /.well-known/openid-configuration
    2. Create each of the following resources and set the Protection Level as Protected and set the Authentication Policy and Authorization Policy as Protected Resource Policy
      • /oauth2/rest/approval (this is for POST operation)
      • /oam/pages/consent.jsp (this is for GET operation)

    For more information, see Adding and Managing Policy Resource Definitions

  7. Configure the OHS as reverse proxy in OAM. To do this:
    1. Log in to the OAM Console https://OAMAdminHost:OAMAdminPort/oamconsole/
    2. From the Welcome page, click Configuration and then click Access Manager Settings
    3. Under Load Balancing specify the OAM Server Host and OAM Server Port.

2.3 Downloading OAA Installation Files and Running the Management Container (OAA 122140-20210426)

This section provides steps to download OAA installation files and run the management container for OAA 122140-20210426 only.

To install the latest version of OAA, see Downloading OAA Installation Files and Running the Management Container (OAA 122140_20210721 onwards)

2.3.1 Downloading OAA Installation Files (OAA 122140-20210426)

This section provides steps to download OAA installation files for OAA 122140-20210426 only.

  1. Download the OAA installation V1008873-01.zip files from Oracle eDelivery website
  2. Unzip the V1008873-01.zip file:
    unzip V1008873-01.zip
    Archive: oaa_122140-20210426.zip
    creating: oaa_122140-20210426/
    inflating: oaa_122140-20210426/factor-sms-oaa_122140_20210426.tar
    inflating: oaa_122140-20210426/fido-server-oaa_122140_20210426.tar
    inflating: oaa_122140-20210426/factor-email-oaa_122140_20210426.tar
    inflating: oaa_122140-20210426/oaa-install-oaa_122140_20210426.tar
    inflating: oaa_122140-20210426/factor-totp-oaa_122140_20210426.tar
    inflating: oaa_122140-20210426/oaa-policy-oaa_122140_20210426.tar
    inflating: oaa_122140-20210426/oaa-sp-ui-oaa_122140_20210426.tar
    inflating: oaa_122140-20210426/oaa-admin-oaa_122140_20210426.tar
    inflating: oaa_122140-20210426/oaa-service-oaa_122140_20210426.tar
    inflating: oaa_122140-20210426/factor-yotp-oaa_122140_20210426.tar
  3. Navigate to the oaa_122140-20210426 directory
    cd oaa_122140-20210426
  4. Verify that all the files exist.
    /bin/ls -ls | awk '{print $6,$10}'
    1031650816 factor-email-oaa_122140_20210426.tar
    1031640064 factor-sms-oaa_122140_20210426.tar
    1025819648 factor-totp-oaa_122140_20210426.tar
    1033768448 factor-yotp-oaa_122140_20210426.tar
    1038427136 fido-server-oaa_122140_20210426.tar
    1034390016 oaa-admin-oaa_122140_20210426.tar
    1233283584 oaa-install-oaa_122140_20210426.tar
    1040561664 oaa-policy-oaa_122140_20210426.tar
    1040008704 oaa-service-oaa_122140_20210426.tar
    1042970112 oaa-sp-ui-oaa_122140_20210426.tar
  5. Load each of the tar files into separate docker images:
    docker load --input factor-email-oaa_122140_20210426.tar
    eb346351f655: Loading layer [==================================================>] 138.3MB/138.3MB
    6f1fcc96a5bb: Loading layer [==================================================>] 20.48kB/20.48kB
    a3f146b7711a: Loading layer [==================================================>] 128.5kB/128.5kB
    35bfe6ec4b29: Loading layer [==================================================>] 306.4MB/306.4MB
    8a5edfe4221a: Loading layer [==================================================>] 306.5MB/306.5MB
    01447a20a5df: Loading layer [==================================================>] 209MB/209MB
    20169276b15e: Loading layer [==================================================>] 62.23MB/62.23MB
    152d52bd7b04: Loading layer [==================================================>] 9.01MB/9.01MB
    Loaded image: factor-email:oaa_122140-20210426
    docker load --input factor-sms-oaa_122140_20210426.tar
    a5cbd31c2f64: Loading layer [==================================================>] 62.23MB/62.23MB
    7e5b34e808da: Loading layer [==================================================>] 8.994MB/8.994MB
    Loaded image: factor-sms:oaa_122140-20210426 
    docker load --input factor-totp-oaa_122140_20210426.tar 
    5250b0ae9f3d: Loading layer [==================================================>] 56.42MB/56.42MB
    95b9ee012a4b: Loading layer [==================================================>] 8.987MB/8.987MB
    Loaded image: factor-totp:oaa_122140-20210426
    docker load --input factor-yotp-oaa_122140_20210426.tar
    79a95435be56: Loading layer [==================================================>] 64.38MB/64.38MB
    8294850e46a7: Loading layer [==================================================>] 8.977MB/8.977MB
    Loaded image: factor-yotp:oaa_122140-20210426
    docker load --input fido-server-oaa_122140_20210426.tar
    3f3c8e4c44e5: Loading layer [==================================================>] 59.95MB/59.95MB
    b8e0e52d66d8: Loading layer [==================================================>] 18.06MB/18.06MB
    08a43387f4cb: Loading layer [==================================================>] 3.584kB/3.584kB
    Loaded image: fido:oaa_122140-20210426
    docker load --input oaa-policy-oaa_122140_20210426.tar
    b3075b23b6a2: Loading layer [==================================================>] 79.52MB/79.52MB
    739dd24dfdd9: Loading layer [==================================================>] 627.7kB/627.7kB
    Loaded image: oaa-policy:oaa_122140-20210426
    docker load --input oaa-service-oaa_122140_20210426.tar
    63927b9a2b31: Loading layer [==================================================>] 79.36MB/79.36MB
    437b0fc6f217: Loading layer [==================================================>] 239.6kB/239.6kB
    Loaded image: oaa:oaa_122140-20210426
    docker load --input oaa-sp-ui-oaa_122140_20210426.tar
    f8d34c77faf2: Loading layer [==================================================>] 56.55MB/56.55MB
    1833cdc7eb23: Loading layer [==================================================>] 26MB/26MB
    39b48f6a9d8a: Loading layer [==================================================>] 3.584kB/3.584kB
    Loaded image: spui:oaa_122140-20210426
    docker load --input oaa-install-oaa_122140_20210426.tar
    b291e1fd6f6c: Loading layer [==================================================>] 5.12kB/5.12kB
    61fe452b0c7e: Loading layer [==================================================>] 181.6MB/181.6MB
    ea856c53906b: Loading layer [==================================================>] 510.3MB/510.3MB
    85df8331ff73: Loading layer [==================================================>] 83.21MB/83.21MB
    5bf9028f80bf: Loading layer [==================================================>] 248MB/248MB
    37152c867f8d: Loading layer [==================================================>] 378.4kB/378.4kB
    34e19f66dcbd: Loading layer [==================================================>] 4.608kB/4.608kB
    85880302b32f: Loading layer [==================================================>] 8.704kB/8.704kB
    74163dfa6811: Loading layer [==================================================>] 11.26kB/11.26kB
    b01e89cb1dd8: Loading layer [==================================================>] 34.41MB/34.41MB
    97af6a752bb6: Loading layer [==================================================>] 12.8kB/12.8kB
    4f44002d9af9: Loading layer [==================================================>] 922.6kB/922.6kB
    03a3272efb0f: Loading layer [==================================================>] 340kB/340kB
    a57306d5d004: Loading layer [==================================================>] 35.69MB/35.69MB
    Loaded image: oracle/shared/oaa-mgmt:oaa_122140-20210426
    docker load --input oaa-admin-oaa_122140_20210426.tar
    2368952aef01: Loading layer [==================================================>] 56.54MB/56.54MB
    bb7db7d92730: Loading layer [==================================================>] 17.44MB/17.44MB
    bac855c99419: Loading layer [==================================================>] 3.584kB/3.584kB
    Loaded image: oaa-admin:oaa_122140-20210426
  6. Verify the Images
    docker images
    REPOSITORY TAG IMAGE ID CREATED SIZE
    oaa-admin oaa_122140-20210426 295fb65ec125 50 minutes ago 1.02GB
    oracle/shared/oaa-mgmt oaa_122140-20210426 26b76860ae9c 41 hours ago 1.22GB
    factor-yotp oaa_122140-20210426 5464ea77f29f 2 days ago 1.02GB
    oaa oaa_122140-20210426 8256c09f71be 3 days ago 1.03GB
    spui oaa_122140-20210426 aaaf940c7c99 3 days ago 1.03GB
    fido oaa_122140-20210426 150fe06c0418 3 days ago 1.02GB
    factor-totp oaa_122140-20210426 ced225ffa1bc 3 days ago 1.01GB
    factor-sms oaa_122140-20210426 13041a76a131 3 days ago 1.02GB
    oaa-policy oaa_122140-20210426 ec9ad8401355 3 days ago 1.03GB
    factor-email oaa_122140-20210426 b0a8f2f1bef7 3 days ago 1.02GB
  7. Login into container-registry.oracle.com from your browser and navigate to Middleware and then coherence. On the right-hand side, select the Language from the drop-down menu and click Continue. Read the Oracle Standard Terms and Restrictions and click Accept to agree.
  8. Login into container-registry.oracle.com
    docker login container-registry.oracle.com
  9. Create the docker-registry-secret
    kubectl create secret generic docker-registry-secret --from-file=.dockerconfigjson=<path/to/.docker/config.json> --type=kubernetes.io/dockerconfigjson
  10. Pull the following additional images from container-registry.oracle.com.
    docker pull container-registry.oracle.com/middleware/coherence-operator:3.0.2-utils
    Trying to pull repository container-registry.oracle.com/middleware/coherence-operator ...
    3.0.2-utils: Pulling from container-registry.oracle.com/middleware/coherence-operator
    c6d8078b329d: Pull complete
    2f980b022f6e: Pull complete
    46dcbe043730: Pull complete
    e1327afa46bb: Pull complete
    b9b061e1751d: Pull complete
    e72d834fb2d1: Pull complete
    Digest: sha256:6651fdcf1a97b60fec5159f5e27da11a136cd7d3e31ad1afae2ac921f3cb14ea
    Status: Downloaded newer image for container-registry.oracle.com/middleware/coherence-operator:3.0.2-utils
    container-registry.oracle.com/middleware/coherence-operator:3.0.2-utils
    docker pull container-registry.oracle.com/middleware/coherence-operator:3.0.2
    Trying to pull repository container-registry.oracle.com/middleware/coherence-operator ...
    3.0.2: Pulling from container-registry.oracle.com/middleware/coherence-operator
    50d251969932: Pull complete
    Digest: sha256:389cffa15ed4eea9c76b72efaa52911ee45dbc8bf7ad9f50ec9c6686142e2279
    Status: Downloaded newer image for container-registry.oracle.com/middleware/coherence-operator:3.0.2
    container-registry.oracle.com/middleware/coherence-operator:3.0.2
    
    docker pull container-registry.oracle.com/database/instantclient:12.2.0.1
    12.2.0.1: Pulling from container-registry.oracle.com/database/instantclient
    126d74ea0635: Pull complete
    53db3fa677a5: Pull complete
    Digest: sha256:8d49079c7b30cd8db13470e862602e70beb284973c3998e52836b03ef301d953
    Status: Downloaded newer image for container-registry.oracle.com/database/instantclient:12.2.0.1
    container-registry.oracle.com/database/instantclient:12.2.0.1
    
    docker pull alpine
    Using default tag: latest
    Trying to pull repository docker.io/library/alpine ...
    latest: Pulling from docker.io/library/alpine
    540db60ca938: Pull complete
    Digest: sha256:69e70a79f2d41ab5d637de98c1e0b055206ba40a8145e7bddb55ccc04e13cf8f
    Status: Downloaded newer image for alpine:latest
    alpine:latest
    
  11. Tag and push these images into your docker registry.

    Note:

    The docker registry must be accessible from all the nodes.
    If you do not have a docker registry deployed, see Deploy a registry server
    The following example shows how to tag images with IMAGE_TAG=oaa_122140-20210426 and REGISTRY=container.registry.com/images

    Note:

    Set $IMAGE_TAG and $REGISTRY as environment variables
    docker tag oaa-admin:oaa_122140-20210426 $REGISTRY/oaa-admin:$IMAGE_TAG
    docker tag factor-yotp:oaa_122140-20210426 $REGISTRY/factor-yotp:$IMAGE_TAG
    docker tag oaa:oaa_122140-20210426 $REGISTRY/oaa:$IMAGE_TAG
    docker tag spui:oaa_122140-20210426 $REGISTRY/spui:$IMAGE_TAG
    docker tag fido:oaa_122140-20210426 $REGISTRY/fido:$IMAGE_TAG
    docker tag factor-totp:oaa_122140-20210426 $REGISTRY/factor-totp:$IMAGE_TAG
    docker tag factor-sms:oaa_122140-20210426 $REGISTRY/factor-sms:$IMAGE_TAG
    docker tag oaa-policy:oaa_122140-20210426 $REGISTRY/oaa-policy:$IMAGE_TAG
    docker tag factor-email:oaa_122140-20210426 $REGISTRY/factor-email:$IMAGE_TAG
    docker tag oracle/shared/oaa-mgmt:oaa_122140-20210426 $REGISTRY/oracle/shared/oaa-mgmt:$IMAGE_TAG
    docker tag container-registry.oracle.com/database/instantclient:12.2.0.1 $REGISTRY/shared/oracle/database-instantclient:12.2.0.1
    docker tag container-registry.oracle.com/middleware/coherence-operator:3.0.2-utils $REGISTRY/shared/oracle/coherence-operator:3.0.2-utils
    docker tag container-registry.oracle.com/middleware/coherence-operator:3.0.2 $REGISTRY/shared/oracle/coherence-operator:3.0.2
    docker tag alpine $REGISTRY/shared/alpine:latest

    Push the image to the registry. You may need to login into the registry before you can push.

    docker push $REGISTRY/oaa-admin:$IMAGE_TAG
    docker push $REGISTRY/factor-yotp:$IMAGE_TAG
    docker push $REGISTRY/oaa:$IMAGE_TAG
    docker push $REGISTRY/spui:$IMAGE_TAG
    docker push $REGISTRY/fido:$IMAGE_TAG
    docker push $REGISTRY/factor-totp:$IMAGE_TAG
    docker push $REGISTRY/factor-sms:$IMAGE_TAG
    docker push $REGISTRY/oaa-policy:$IMAGE_TAG
    docker push $REGISTRY/factor-email:$IMAGE_TAG
    docker push $REGISTRY/oracle/shared/oaa-mgmt:$IMAGE_TAG
    docker push $REGISTRY/shared/oracle/database-instantclient:12.2.0.1
    docker push $REGISTRY/shared/oracle/coherence-operator:3.0.2-utils
    docker push $REGISTRY/shared/oracle/coherence-operator:3.0.2
    docker push $REGISTRY/shared/alpine:latest
  12. Use these images to run the Management Container. See Running the Management Container (OAA 122140-20210426)

2.3.2 Running the Management Container (OAA 122140-20210426)

This section provides steps to run the management container for OAA 122140-20210426 only.

To obtain the runManagementContainer.sh script, you must run a docker command to download the oaa-mgmt container. It will start, but the purpose is only to copy the runManagementContainer.sh file from within the container to the host machine. Once it is copied out, you can stop the Docker container and remove it.

  1. Download the Management Container by running the following command:
    docker run -ti -d --name oaadockerrun $REGISTRY/oracle/shared/oaa-mgmt:$IMAGE_TAG

    where oaadockerrun is the docker container name.

  2. Copy the runManagementContainer.sh from the container to a local folder:
    docker cp oaadockerrun:/u01/oracle/runManagementContainer.sh ~/.
    docker stop oaadockerrun
    docker rm oaadockerrun
    
  3. Edit the runManagementContainer.sh file to add or remove hosts required for OAA installation. For example, Proxy Sever, master node, worker nodes, OAuth, Database, and Docker registry.
    HOSTENTRIES="--add-host <ProxyServerHost>:<IP_address> \
    --add-host <Master_Host>:<IP_address> \
    --add-host <Worker1_Host>:<IP_address> \
    --add-host <Worker2_Host>:<IP_address> \
    --add-host <OAM_OAuth_Host>:<IP_address> \
    --add-host <DatabaseHost>:<IP_address> \
    --add-host <DockerRegistryHost>:<IP_address>"
  4. Set the environment variables for the following proxies, in the shell, as necessary:
    • http_proxy
    • https_proxy
    • ftp_proxy
    • no_proxy
  5. Run the runManagementContainer.sh with arguments.
    Arguments Values and Description
    -h Displays help
    -n Specify the name of the container. Default value is oaamgmt
    -t Specify the image tag. Default value is latest
    -s Specify the OAA settings volume to be mounted. Default name of the volume is OAAsettings
    -v Specify the OAA credentials volume to be mounted. Default name of the volume is OAAcredentials
    -l Specify the OAA logs volume to be mounted. Default name of the volume is OAAlogs
    -f Specify the OAA vault volume to be mounted. Default name of the volume is OAAvault
    -r Specify the repository path where the management container image exists.
    -a Specify the IP address of the Network File System (NFS) volume for file-based vault
    -p Specify the path on NFS volume to mount, in the container
    -m Specify the mount path for the NFS volume.
    For example, to run the management container using the default values in the script, run the following command:
    ~/runManagementContainer.sh -r "<docker_registry>"
    For example, to run the management container with the external NFS volume <NFS_PATH>, for a file-based vault, run the following command:
    ~/runManagementContainer.sh -a <NFS_IP_Address> -p "<NFS_PATH>" -r $REGISTRY -t $IMAGE_TAG 
This command creates the OAAcredentials, OAAlogs and OAAsettings volumes in docker. For example:
cd <path_to_docker/volume>
ls -l
drwxr-xr-x 3 root root 4096 Apr 29 01:32 OAAcredentials
drwxr-xr-x 3 root root 4096 Apr 29 01:32 OAAlogs
drwxr-xr-x 3 root root 4096 Apr 29 01:32 OAAsettings
drwxr-xr-x 3 root root 4096 Apr 29 01:32 OAAvault
After the script completes, you are directed into the oaamgmt container. If you exit the OAA management container, you can re-enter it by running the following docker command:
docker exec -it oaamgmt bash
If the oaamgmt container stops, you can restart it by running:
docker start oaamgmt

2.4 Downloading OAA Installation Files and Running the Management Container (OAA 122140_20210721 onwards)

This section provides steps for downloading OAA installation files and running the Management Container for OAA 122140_20210721 onwards.

  1. Download the latest <OAA_Image>.zip file.

    Download the Oracle Advanced Authentication (OAA) Installation Images from My Oracle Support by referring to the document ID 2723908.1.

  2. Create a working directory and copy the image zip file to the working directory:
    mkdir -p /oaaimages
    cd /oaaimages
    cp <download_location>/<OAA_Image>.zip
    unzip <OAA_Image>.zip

    This will give you a <tar_file_name>.tar file.

  3. Load the image from the tar into the local repository
    docker load --input <tar_file_name>.tar
  4. Verify the images
    docker images

    Note the TAG details for the images installed. The TAG value needs to be specified in the subsequent steps.

  5. Download the Management Container by running the following command:
    docker run -ti -d --name oaadockerrun oracle/shared/oaa-mgmt:<TAG>

    where oaadockerrun is the docker container name.

    and <TAG> is the TAG value for the images installed.

  6. Copy the pushImages.sh and runManagementContainer.sh from the running oaadockerrun container to a local directory:
    docker cp oaadockerrun:/u01/oracle/pushImages.sh /oaaimages
    docker cp oaadockerrun:/u01/oracle/runManagementContainer.sh /oaaimages
    docker stop oaadockerrun
    docker rm oaadockerrun
    
  7. Push these images into your docker registry using pushImages.sh

    Note:

    The docker registry must be accessible from all the nodes.

    If you do not have a docker registry deployed, see Deploy a registry server

    cd /oaaimages/
    ./pushImages.sh -r <Docker_Registry_URL>
  8. Edit the runManagementContainer.sh file to add or remove hosts required for OAA installation. For example, Proxy Sever, master node, worker nodes, OAuth, Database, and Docker registry.
    HOSTENTRIES="--add-host <ProxyServerHost>:<IP_address> \
    --add-host <Master_Host>:<IP_address> \
    --add-host <Worker1_Host>:<IP_address> \
    --add-host <Worker2_Host>:<IP_address> \
    --add-host <OAM_OAuth_Host>:<IP_address> \
    --add-host <DatabaseHost>:<IP_address> \
    --add-host <DockerRegistryHost>:<IP_address>"
  9. Set the environment variables for the following proxies, in the shell, as necessary:
    • http_proxy
    • https_proxy
    • ftp_proxy
    • no_proxy
  10. Run the runManagementContainer.sh with arguments.
    Arguments Values and Description
    -h Displays help
    -n Specify the name of the container. Default value is oaamgmt
    -t Specify the image tag. Default value is latest
    -s Specify the OAA settings volume to be mounted. Default name of the volume is OAAsettings
    -v Specify the OAA credentials volume to be mounted. Default name of the volume is OAAcredentials
    -l Specify the OAA logs volume to be mounted. Default name of the volume is OAAlogs
    -f Specify the OAA vault volume to be mounted. Default name of the volume is OAAvault
    -r Specify the repository path where the management container image exists.
    -a Specify the IP address of the Network File System (NFS) volume for file-based vault
    -p Specify the path on NFS volume to mount, in the container
    -m Specify the mount path for the NFS volume.
    For example, to run the management container using the default values in the script, run the following command:
    ./runManagementContainer.sh -r "<docker_registry>"
    For example, to run the management container with the external NFS volume <NFS_PATH>, for a file-based vault, run the following command:
    ./runManagementContainer.sh -a <NFS_IP_Address> -p "<NFS_PATH>" -m "/u01/oracle/service/store/oaa" -r <Docker_Registry> -t <TAG>
    This command creates the OAAcredentials, OAAlogs and OAAsettings volumes in docker. For example:
    cd <path_to_docker/volume>
    ls -l
    drwxr-xr-x 3 root root 4096 Apr 29 01:32 OAAcredentials
    drwxr-xr-x 3 root root 4096 Apr 29 01:32 OAAlogs
    drwxr-xr-x 3 root root 4096 Apr 29 01:32 OAAsettings
    drwxr-xr-x 3 root root 4096 Apr 29 01:32 OAAvault
    
    After the script completes, you are directed into the oaamgmt container. If you exit the OAA management container, you can re-enter it by running the following docker command:
    docker exec -it oaamgmt bash
    If the oaamgmt container stops, you can restart it by running:
    docker start oaamgmt
  11. Outside the container, add the docker secrets in kubernetes in the default namespace and coherence namespace.
    kubectl create secret generic dockersecret \
        --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
        --type=kubernetes.io/dockerconfigjson
    kubectl create ns coherence
    kubectl create secret generic dockersecret -n coherence \
        --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
        --type=kubernetes.io/dockerconfigjson

Next Steps: Perform Post-Container-Script Steps

2.5 Post-Container-Script Steps

You must perform the following steps after running the OAA management container.

  1. Copy installOAA.properties into the docker volume OAAsetting.

    Ensure that you are inside the oaamgmt container

    docker exec -it oaamgmt bash
    cp /u01/oracle/installsettings/installOAA.properties /u01/oracle/scripts/settings/
  2. Exit the container and copy k8sconfig and helmconfig into the volume OAAcreds:
    1. Verify the OAACreds directory
      docker inspect OAAcredentials | grep Mountpoint
      the following is displayed:
      "Mountpoint": "/docker/volumes/OAAcredentials/_data",
    2. Copy the Kubernetes configuration file to the following location:
      sudo cp /etc/kubernetes/admin.conf /docker/volumes/OAAcredentials/_data/k8sconfig
    3. Check where helmconfig points at and copy the helmconfig file to that location.
      env | grep –helm

      If the helmconfig file does not exist then create the file in the same location

      sudo vi /docker/volumes/OAAcredentials/_data/helmconfig
      Populate the file with the following content:
      apiVersion: ""
      generated: "0001-01-01T00:00:00Z"
      repositories:
      - caFile: ""
        certFile: ""
        keyFile: ""
        name: idm-helm
        password: ""
        url: 
        username: ""
      

      Note:

      The URL can point to the helm repository (helm repo ls).
  3. Create the Server Certificate (cert.p12) and Trust Certificate (trust.p12) files.
    1. Create a directory and navigate to that folder. For example:
      mkdir /OAA/oaa_ssl
      cd /OAA/oaa_ssl
    2. Generate a 4096-bit long RSA key for the root CA
      openssl genrsa -out ca.key 4096
    3. Create self-signed root CA certificate ca.crt
      openssl req -new -x509 -days 3650 -key ca.key -out ca.crt

      Add the necessary information

    4. Generate p12 file for CA certificate
      openssl pkcs12 -export -out trust.p12 -nokeys -in ca.crt

      Enter and verify Export Password

    5. Check private key
      openssl rsa -in ca.key -check
    6. Check certificate
      openssl x509 -in ca.crt -text –noout
    7. Generate a 4096 bits Server certificate
      openssl genrsa -out oaa.key 4096
    8. Send a signing request for the server certificate
      openssl req -new -key oaa.key -out cert.csr

      Add the necessary information

    9. Send a CA signing request for the server certificate
      openssl x509 -req -days 1826 -in cert.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out oaa.crt
    10. Convert to PKCS12 format to be used by Server
      openssl pkcs12 -export -out cert.p12 -inkey oaa.key -in oaa.crt -chain -CAfile ca.crt

      Enter and verify Export Password

    11. Convert crt to pem
      openssl x509 -in oaa.crt -out oaa.pem -outform PEM
  4. Place the cert.p12 and trust.p12 files into the volume OAAcreds
    sudo cp *.p12 /docker/volumes/OAAcredentials/_data/
  5. Change permssions on all the mount points as follows:
    sudo chmod 777 `docker inspect OAAlogs | grep "Mountpoint" | cut -d':' -f2 | tr -d "\",\ "`
    sudo chmod 777 `docker inspect OAAsettings | grep "Mountpoint" | cut -d':' -f2 | tr -d "\",\ "`
    sudo chmod 755 `docker inspect OAAcredentials | grep "Mountpoint" | cut -d':' -f2 | tr -d "\",\ "`
    sudo chmod 777 `docker inspect OAAvault | grep "Mountpoint" | cut -d':' -f2 | tr -d "\",\ "`
    If you get a permission denied on the OAAVault, go inside the container and make sure you can access the directories/files
    cd ~/scripts/creds
    ls -l
    total 28
    -rw-r--r-- 1 root root 5525 May  7 10:19 cert.p12
    -rw-r--r-- 1 root root  160 May  7 10:17 helmconfig
    -rw------- 1 root root 5452 May  7 10:15 k8sconfig
    -rw-r--r-- 1 root root 4149 May  7 10:19 trust.p12
    
    If the k8sconfig does not have read permissions like shown then outside the container run
    sudo chmod 644 /docker/volumes/OAAcredentials/_data/k8sconfig

    Inside the container, also check if you are able to create a file in the following paths: /u01/oracle/service/store/oaa, /u01/oracle/scripts/settings, and /u01/oracle.logs

    Also ensure you have added 777 permission to your NFS mount (for example, /OAA/oaa ).

  6. Follow this step only if you are installing the OAA 122140-20210426 release. You can skip this step, if installing OAA 122140_20210721 and later.

    Inside the OAA management container, run the coherence-operator:

    docker exec -it oaamgmt bash
    cd ~/helmcharts/coherence-operator
    helm install --set global.repo="<docker-registry>" --set imagePullSecrets[0].name=docker-registry-secret coherence-operator .
    
    NAME: coherence-operator
    LAST DEPLOYED: Wed May  5 12:40:23 2021
    NAMESPACE: default
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    NOTES:
    Coherence Operator successfully installed
    
  7. Inside the container navigate to /u01/oracle/scripts/settings and prepare the installOAA.properties file. For details, see Preparing the installOAA.properties file for OAA Installation
  8. Create the Database Schema. For details, see Creating Database Schema

2.5.1 Creating Database Schema

OAA uses database schemas to store information. OAA supports Oracle Database 12c, 18c, and 19c.

If you are using Oracle Database19c, the OAA installation supports using SSH keys to copy the required database files directly to the server where the database resides, and automatically install the schema into the database. The SSH key parameters are set in the installOAA.properties file. For details, see Database Configuration.

For all other versions of the Oracle Database, SSH keys are not supported; therefore, you must copy the files manually and run the scripts to create the schemas. The steps for this are as follows:

  1. Outside the container, run:
    mkdir -p ~/OAA/scripts
    docker cp oaamgmt:/u01/oracle/scripts/createOAASchema.sh ~/OAA/scripts/
    docker cp oaamgmt:/u01/oracle/scripts/importDBData.sh ~/OAA/scripts/
    docker cp oaamgmt:/u01/oracle/scripts/validateOAASchema.sh ~/OAA/scripts/
    docker cp oaamgmt:/u01/oracle/scripts/oaa.dat ~/OAA/scripts/
    docker cp oaamgmt:/u01/oracle/scripts/validate.sql ~/OAA/scripts/
    docker cp oaamgmt:/u01/oracle/scripts/settings/installOAA.properties ~/OAA/scripts
    
  2. Transfer the files to the database system
    cd ~/OAA/scripts
    tar cvf oaa_db.tar *
    scp oaa_db.tar oracle@db.example.com:/export/home/oracle/oaascripts

    Note:

    Create the /export/home/oracle/oaascripts directory before copying the tar file. On the database system, unzip the file:
    cd /export/home/oracle/oaascripts
    tar xvf oaa_db.tar
    

    Edit the /export/home/oracle/oaascripts/installOAAproperties.dat and change the path for: database.datafile=/export/home/oracle/oaascripts/oaa.dat

  3. Run the script to create the database schema.

    Note:

    For non-ASM (Automatic Storage Management) databases, run the following command manually before running the createOAASchema.sh script.
    sqlplus sys/pwd as sydba;
    SQL> 
    CREATE TABLESPACE DEV_OAA_TBS DATAFILE 'OAA_TBS.dbf' SIZE 5g AUTOEXTEND ON;
    Tablespace created.

    Ensure the PATH to the DB ORACLE_HOME/bin is on the PATH before running the script so it can find SQLPLUS

    cd /export/home/oracle/oaascripts
    export SCRIPT_PATH=/export/home/oracle/oaascripts
    ./createOAASchema.sh -f installOAA.properties
    

2.6 Preparing the installOAA.properties file for OAA Installation

You can customize OAA installation by setting properties in the installOAA.properties file and passing this file as argument to the OAA.sh script.

The following sections provide description for the customizations allowed in the installOAA.properties file.

2.6.1 Common Deployment Configuration

This section provides details about the common deployment configuration properties that can be set in the installOAA.properties file.

Table 2-4 Common Deployment Configuration

Properties Mandatory/Optional Description
common.dryrun Optional Evaluates the helm chart without actually installing OAA on the Kubernetes cluster.

this is equivalent to --dry-run --debug option in the helm command.

common.deployment.name Mandatory Name of the OAA installation used when the helm install command is run.
common.deployment.name.coherenceoperator Mandatory Name of the coherence operator installed. If you have an existing installation of OAA, ensure that you use the name specified for coherence operator for that installation. Otherwise, it is recommended that you use coherence-operator as the name.

Note:

This parameter is not applicable for oaa_122140-20210426 installation.
common.deployment.overridefile Optional  
common.kube.context Optional Name of the kubernetes context to be used.

If the context is not provided, the default kubernetes context is used.

common.deployment.sslcert Mandatory The server certificate file to be used in the OAA installation

The file is seeded into the vault and downloaded by all OAA microservices

common.deployment.trustcert Mandatory The trust certificate file to be used in the OAA installation.

The file is seeded into the vault and downloaded by all OAA microservices

common.deployment.importtruststore Mandatory If this is enabled then trust certificate is imported in the JRE truststore.

Note:

This parameter is not applicable for oaa_122140-20210426 installation.
common.deployment.keystorepassphrase Mandatory Passphrase for certificate.

If you do not specify the value here, you are prompted for the value during installation

common.deployment.truststorepassphrase Mandatory Passphrase for the truststore file.

If you do not specify the value here, you are prompted for the value during installation

2.6.2 Database Configuration

This section provides details about the database configuration properties that can be set in the installOAA.properties file.

Table 2-5 Database Configuration

Properties Mandatory/Optional Description
database.createschema Mandatory

Enables creation of schema during installation.

If this is set to false, the schema is not created. However, irrespective of this flag, database validation is performed

database.datafile Mandatory Specifies the path to the OAA database snapshot file.

This is included in the container and points to the correct path

If the file is moved, you must change the path accordingly.

database.host Mandatory Specify the database host
database.port Mandatory Specify the database port
database.sysuser Mandatory Specify the sysdba user of the database
database.syspassword Mandatory Specify the sys password.

If you do not specify the value here, you are prompted for value during installation.

database.schema Mandatory Specify the name of the database schema to be used for OAA installation.
database.tablespace Mandatory Specify the tablespace name that needs to be used for the installation.
database.schemapassword Mandatory Specify the schema password.

If you do not specify the value here, you are prompted for value during installation.

database.svc Mandatory Specify the database service name
database.name Mandatory Specify the database name. This can be same as database service name
database.validationfile Mandatory Specifies the path t the SQL validation file.
The following properties are applicable for SSH enabled remote database. The SSH credentials are used to place the oaa.dat file in the tmp folder accessible by running database to run impdp command. The folder inside tmp is created with timestamp information and can be deleted after schema creation. The file oaa.dat contains all the table and views needed for OAA installation.
database.version Optional Specify the database version
database.sshuser Optional Specify the database SSH user
database.sshpass Optional Specify the database SSH password
database.sshkey Optional Specify the database SSH
database.prmpt Optional The prompt presented to user when performing SSH from remote box.

2.6.3 OAM OAuth Configuration

This section provides details about the OAM OAuth configuration properties that can be set in the installOAA.properties file.

Ensure you have followed the prerequisite steps for configuring OAuth. For details, see Prerequisites for Setting Up OAM OAuth for OAA .

Also, for details about OAM OAuth, see Configuring OAuth Services Settings

Table 2-6 OAM OAuth Configuration

Properties Mandatory/Optional Description
oauth.enabled Mandatory

You must set this as true if OAuth needs to be enabled in the OAA installation.

If you set this to false, you must also set the following properties to false, otherwise the installation fails:
  • install.spui.enabled
  • install.oaa-admin-ui.enabled
  • install.fido.enabled
oauth.createdomain Optional if oauth.enabled=false Creates OAuth domain.

OAuth domain is required to create OAuth resource and client

oauth.createresource Optional if oauth.enabled=false Creates OAuth resource.

OAuth resource is required to create OAuth client

oauth.createclient Optional if oauth.enabled=false Creates OAuth client.

OAuth client is required if oauth.enabled is set to true.

oauth.domainname Optional if oauth.enabled=false Specify the OAuth domain name. This must be same as provided in Prerequisites for Setting Up OAM OAuth for OAA
oauth.identityprovider Mandatory if oauth.createdomain is set to true Specify the identity provider for the OAuth Domain.
oauth.clientname Optional if oauth.enabled=false Specify the OAuth client name
oauth.clientgrants Mandatory if oauth.createclient is set to true Specify the client grants for the OAuth client. OAuth client must have CLIENT_CREDENTIALS, which is used during validation stage to check OAuth status. Values must be:

"PASSWORD","CLIENT_CREDENTIALS","JWT_BEARER","REFRESH_TOKEN","AUTHORIZATION_CODE","IMPLICIT"

oauth.clienttype Mandatory if oauth.createclient is set to true Specify the OAuth Client Type.
oauth.clientpassword Mandatory if oauth.enabled=true Specify the OAuth client password
oauth.resourcename Mandatory if oauth.enabled=true Specify the OAuth resource name. Also used for validation of OAuth setup.
oauth.resourcescope Mandatory if oauth.enabled=true Specify the OAuth resource scope. Also used for validation of OAuth setup.
oauth.redirecturl Mandatory if oauth.createclient is set to true Specify the client redirect URL.
oauth.applicationid Mandatory if oauth.createclient is set to true Application ID of OAA to be used when managing preferences and process challenge request of users.
oauth.adminurl Mandatory if oauth.enabled=true Specify the OAuth Administration URL.
oauth.basicauthzheader Mandatory if oauth.enabled=true Base64 encoded authorization header
oauth.identityuri Mandatory if oauth.enabled=true  

2.6.4 Vault configuration

This section provides details about the vault configuration properties that can be set in the installOAA.properties file.

If you are using OCI vault, you can ignore the properties to be set for file-based vault.

Table 2-7 Vault Configuration

Properties Description
vault.deploy.name

Specify the name of vault to be used in OAA installation

vault.create.deploy If the value is set to true, vault creation is performed. However, if a vault with the name provided in vault.deploy.name already exists then vault creation is skipped.
vault.provider Specify if the vault is OCI or file based
Specify one of the following values:
  • fks
  • oci
The following properties are mandatory for OCI-based vault configurations if you have set vault.provider=oci. For for information about creating OCI vault, seeManaging Vaults
vault.oci.uasoperator Specify the base64 encoded private key of the user with read and write permission on OCI vault
vault.oci.tenancyId Speceify the base64 encoded OCI tenancy id.
vault.oci.userId Specify the base64 encoded OCID of the user with read and write permission on OCI vault.
vault.oci.fpId Specify the base64 encoded finger print of the user with read and write permission on OCI vault.
vault.oci.compartmentId Specify the base64 encoded OCID of the compartment where the vault exists in OCI
vault.oci.vaultId Specify the base64 encoded OCID of the vault on OCI.
vault.oci.keyId Specify the base64 encoded OCID of the master secret key in OCI vault used to encrypt the secrets in the vault.
The following properties are mandatory for file-based vault configurations if you have set vault.provider=fks
vault.fks.server Specify the NFS server host name or IP address.
vault.fks.path Specify the NFS path to be mounted on management container and on OAA installed services to store file based vault. For example, /public-uas-dev/stores/oaa
vault.fks.key Specify the Base64 encoded password of the file based vault. The default value is changeit
vault.fks.mountpath Specify the mount path on management container and on OAA installed services where the vault exists. The value in this property must be same as the value passed through the helm chart. For example, /u01/oracle/service/store/oaa

2.6.5 Helm Chart Configuration

This section provides details about the helm chart configuration properties that can be set in the installOAA.properties file.

These properties are passed as input to the helm chart during Installation.

Table 2-8 Helm Chart Configuration

Properties Mandatory/Optional Description
install.global.repo Mandatory

Specify the docker repository where the OAA docker images exists.

install.riskdb.service.type Mandatory You must set the value of this property always to ExternalName, as the database is external to the OAA installation
install.global.imagePullSecret Mandatory Specify the Kubernetes secret reference that needs to be used while pulling the docker images from the protected docker registries.

Note:

This must be set to the kubernetes secret that you set earlier. For details, see the step about adding the docker secrets in kubernetes in the default namespace and coherence namespace under section Downloading OAA Installation Files and Running the Management Container (OAA 122140_20210721 onwards).
install.global.image.tag Mandatory Update docker global image tag to the new image tag.
install.global.oauth.host Optional Specify the OAuth host name. Required only when oauth.enabled is set as true
install.global.oauth.ip Optional Specify the OAM OAuth IP address. Required only when oauth.enabled is set as true
install.global.oauth.logouturl Optional Specify the logout URL for OAuth protected resource. Required only when oauth.enabled is set as true
install.global.uasapikey Mandatory Specify the OAA API key used for protecting rest endpoints in OAA microservice.
install.global.policyapikey Mandatory Specify the OAA Policy API key used for protecting rest endpoints in OAA policy microservice.
install.global.factorsapikey Mandatory Specify the OAA Factor API key used for protecting rest endpoints in OAA factor microservice. For example, email, totp, sms, yotp and fido
In case of OCI vault, the following configurations can be overridden if provided for read-only users during helm installation. If the values are not provided in the following properties then the values are picked from Vault Configuration.
install.global.vault.mapId Optional For a pre-existing vault you can provide the base64 mapId. If the property is set then it validates against the deploy information in the vault.
install.global.vault.oci.uasoperator= Optional Specify the Base64 encoded private key of the user with the read-only permission on the vault.
install.global.vault.oci.tenancyId= Optional Specify the Base64 encoded tenancy id from OCI
install.global.vault.oci.userId= Optional Specify the Base64 encoded user id from OCI.
install.global.vault.oci.fpId= Optional Specify the Base64 encoded finger print id of the user from the OCI.

2.6.6 Optional Configuration

This section provides details about the optional configuration properties can be set in the installOAA.properties file to customize OAA installation using Helm.

Table 2-9 Optional Configuration

Properties
The following properties relate to Ingress configurations
install.ingress.enabled=true
You can specify the Host name to be used for ingress definition. If the value for the following property is missing, ingress definition is created using '*' host.
install.ingress.hosts\[0\].host=oaainstall-host
Optional: Ingress port other than 443, if specified, will be used for access OAA services.
install.ingress.hosts\[0\].port=31281

Note:

This parameter is applicable only for OAA 122140_20210721 and later installations.
Default scheme for ingress is https. If the scheme is HTTP, specify the option -Doaa.ingress.host=oaainstall-host:-Doaa.ingress.scheme=http
OPTIONAL: Add the ingress port in the javaoptions of each service if it is different than 443. For example:
install.spui.javaoptions=-Doaa.ingress.host=oaainstall-host:-Doaa.ingress.port=31281
install.fido.javaoptions=-Doaa.ingress.host=oaainstall-host:-Doaa.ingress.port=31281
install.email.javaoptions=-Doaa.ingress.host=oaainstall-host:-Doaa.ingress.port=31281
install.sms.javaoptions=-Doaa.ingress.host=oaainstall-host:-Doaa.ingress.port=31281
install.totp.javaoptions=-Doaa.ingress.host=oaainstall-host:-Doaa.ingress.port=31281
install.yotp.javaoptions=-Doaa.ingress.host=oaainstall-host:-Doaa.ingress.port=31281
install.oaa-policy.javaoptions=-Doaa.ingress.host=oaainstall-host:-Doaa.ingress.port=31281
install.oaa-admin-ui.javaoptions=-Doaa.ingress.host=oaainstall-host:-Doaa.ingress.port=31281
install.javaoptions=-Doaa.ingress.host=oaainstall-host:-Doaa.ingress.port=31281
The following properties are related to database. If they are not specified here, the values provided in the Database Configuration are used.
install.global.dbhost=
install.global.dbport=
install.global.dscredentials=
install.global.dbservicename=
The following properties are related to OAuth. If they are not specified here, the values provided in the OAuth Configuration are used.
install.global.oauth.oidcidentityuri=
install.global.oauth.oidcaudience=
install.global.oauth.oidcclientid=
Configure the Load Balancer URL in the following property. All UI services will be behind this load balancer.
install.global.oauth.serviceurl=https://oaainstall-host
You can enable or disable UI console using the following properties. If you set the following properties to false, you must also ensure that oauth.enabled is set to false.
install.spui.enabled=false
install.fido.enabled=false
install.oaa-admin-ui.enabled=false
Specify the service type of each service using the following properties. By default, all services are deployed as ClusterIP.
install.service.type=NodePort
install.oaa-admin-ui.service.type=NodePort
install.oaa-policy.service.type=NodePort
install.spui.service.type=NodePort
install.totp.service.type=NodePort
install.fido.service.type=NodePort
install.push.service.type=NodePort
install.email.service.type=NodePort
install.sms.service.type=NodePort
install.yotp.service.type=NodePort

2.7 Deploying OAA

  1. Inside the container edit the /u01/oracle/scripts/settings/installOAA.properties and set database.createschema=false as it has been created earlier. Save the file.
  2. Install OAA by running the OAA.sh script:
    cd ~
    ./OAA.sh -f installOAA.properties

2.8 Post-Installation Steps for NodePort

If you use nodeport, there is no loadbalancer, and therefore you must update the OAuth client with redirect URLs.

  1. Find the URLs
    kubectl get pods | grep spui

    For example:

    NAME                                       READY   STATUS             RESTARTS   AGE
    oaainstall-spui-5675987c9b-9dw7w           1/1     Running            0          11m
    kubectl exec -it oaainstall-spui-5675987c9b-9dw7w -- cat serviceurl.txt 
    
    https://worker1.example.com:32701
    kubectl exec -it oaainstall-oaa-admin-ui-787c76677d-jbdcf -- cat serviceurl.txt 
    
    https://worker1.example.com:32721
    kubectl exec -it oaainstall-fido-88d876975-mp4x2 -- cat serviceurl.txt 
    
    https://worker1.example.com:30414
  2. Update the OAuth Client:
    curl --location --request PUT 'http://<OAuth_Host>:<OAuth_Port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client?name=OAAClient' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic d2VibG9naWM6V2VsY29tZTE=' \
    --data-raw '{
        "id": "OAAClient",
        "clientType": "PUBLIC_CLIENT",
        "idDomain": "OAADomain",
        "name": "OAAClient",
        "redirectURIs": [
            {
                "url": "https://worker1.example.com:32701/oaa/rui",
                "isHttps": true
            },
            {
                "url": "https://worker1.example.com:32701/oaa/rui/oidc/redirect",
                "isHttps": true
            },
            {
                "url": "https://worker1.example.com:32721/oaa-admin",
                "isHttps": true
            },
            {
                "url": "https://worker1.example.com:32721/oaa-admin/oidc/redirect",
                "isHttps": true
            },
            {
                "url": "https://worker1.example.com:30414/fido",
                "isHttps": true
            },
            {
                "url": "https://worker1.example.com:30414/fido/oidc/redirect",
                "isHttps": true
            }
        ]
    }'
    

2.9 Printing Deployment Details on Console

After the deployment completes, the following information is printed on the console

Note:

In cases where ingress controller is enabled, the host is value of property install.ingress.hosts\[0\].host in installOAA.properties.

This is applicable only for installations of OAA 122140_20210721 and later.

In cases where ingress is disabled, the Node host:port information is printed in place of ingress host information.

OAAService=https://oaainstall-host/oaa/runtime
AdminUrl=https://oaainstall-host/oaa-admin
PolicyUrl=https://oaainstall-host/oaa-policy
SpuiUrl=https://oaainstall-host/oaa/rui
Email=https://oaainstall-host/oaa-email-factor
Fido=https://oaainstall-host/fido
SMS=https://oaainstall-host/oaa-sms-factor
TOTP=https://oaainstall-host/oaa-totp-factor
YOTP=https://oaainstall-host/oaa-yotp-factor
RELEASENAME=oaainstall
# Key below is Base64 encoded API key
oaaapikey=YXBpa2V5dG9iZXNldGR1cmluZ2luc3RhbGxhdGlvbgo=
# Key below is Base64 encoded Policy API key
oaapolicyapikey=cG9sYXBpa2V5dG9iZXNldGR1cmluZ2luc3RhbGxhdGlvbgo=
# Key below is Base64 encoded Factor API key
oaafactorapikey=ZmFjdG9yYXBpa2V5dG9iZXNldGR1cmluZ2luc3RhbGxhdGlvbgo=

To reprint the deployment information, rerun the installation command:
./OAA.sh -f installOAA.properties

Note:

All the steps are skipped as they have been completed before and only the deployment information is printed.

The username and password for the Rest API of the various services can be constructed as following:

OAA Svc: <RELEASENAME>-oaa/<Base64Decoded(oaaapikey)>

OAA Policy: <RELEASENAME>-oaa-policy/<Base64Decoded(oaapolicyapikey)>

2.10 Cleaning Up Installation

Perform the following steps to cleanup an OAA installation completely

  1. Run the following in the oaamgmt container
    helm delete oaainstall
    
  2. Perform one of the following steps to delete coherence-operator:
    • If you are on OAA 122140-20210426, run the following command:
      helm delete coherence-operator
    • If you are on OAA 122140_20210721 or later, run the following commands:
      helm delete coherence-operator -n coherence
      kubectl get sts
      kubectl get coherence.coherence.oracle.com
      kubectl delete mutatingwebhookconfigurations coherence-operator-mutating-webhook-configuration
  3. Outside the container, run:
    kubectl get pods

    If you are on OAA 122140_20210721 or later, run the following command:

    kubectl get pods -n coherence
    If any pods remain then run:
    kubectl delete <pod_name>
  4. Delete the OAuth Client. For example:
    curl --location --request DELETE '<OAuth_Host>:<OAuth_port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client?name=OAAClient&identityDomainName=OAADomain' \
    --header 'Authorization: Basic d2VibG9naWM6V2VsY29tZTE='
    
  5. Delete the OAuth Resource Server. For example:
    curl --location --request DELETE '<OAuth_Host>:<OAuth_port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/application?name=OAAResource&identityDomainName=OAADomain' \
    --header 'Authorization: Basic d2VibG9naWM6V2VsY29tZTE='
    
  6. Delete the OAuth Domain. For example:
    curl --location --request DELETE '<OAuth_Host>:<OAuth_port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/oauthidentitydomain?name=OAADomain' \
    --header 'Authorization: Basic d2VibG9naWM6V2VsY29tZTE='
    
  7. Delete the FKS from the NFS mount:
    sudo rm -rf /OAA/oaa/.accessstore.pkcs12
  8. Drop the DB schema:
    SQLPLUS> drop user DEV_OAA cascade;
  9. Clean up docker:
    docker stop oaamgmt
    docker rm oaamgmt
    docker volume rm OAAcredentials OAAlogs OAAsettings OAAvault
    
  10. On master and each worker node, find the docker images downloaded and delete from the local image repository:
    docker images
    docker rmi <$REGISTRY/image>:oaa_122140-20210426
    

2.11 Troubleshooting OAA Installation

This section provides troubleshooting tips for installing OAA.

General Tips for Troubleshooting OAA Installation

  • Docker Mount Points: These mounts are used by docker for OAA. Docker mounts are different from the NFS mounts used between the Kubernetes cluster nodes.
    These Docker mounts mount the directory locations inside the OAA Management Container to the host filesystem. Use the following commands to view them:
    docker inspect OAAsettings | grep Mountpoint
    "Mountpoint": "/docker/volumes/OAAsettings/_data",
    docker inspect OAAcredentials | grep Mountpoint
    "Mountpoint": "/docker/volumes/OAAcredentials/_data",
    docker inspect OAAlogs | grep Mountpoint
    "Mountpoint": "/docker/volumes/OAAlogs/_data",
    docker inspect OAAvault | grep Mountpoint
    "Mountpoint": "/docker/volumes/OAAvault/_data",

    If the host file location is not viewable by the oracle user, but only the root user then you must change the permissons on the hosts location. For details, see Mounted Volumes in Management Container

  • To log in as root user in OAA Management Container, run the following command:
    docker exec -u 0 -ti oaamgmt bash
  • OAA installation can fail because of issues in different sections. If one section fails, you can rerun OAA, skipping the sections that did run successfully. To find which sections failed, inside the OAA Management container, navigate to the /u01/oracle/logs directory and open the status.info file.

Error response from daemon: error while mounting volume

This error occurs if you have specified a wrong IP address for the NFS mount when running the runManagementContainer.sh script.

To fix this you must delete the Docker mounts that were created before running the script and then re-run the runManagementContainer.sh script.

  1. List the docker volumes
    docker volume ls
    
    DRIVER              VOLUME NAME
    local               OAAcredentials
    local               OAAlogs
    local               OAAsettings
    local               OAAvault
    
  2. Delete the mounts. They can be combined on one line as shown in the following example:
    docker volume rm OAAcredentials OAAlogs OAAsettings OAAvault
  3. Re-run the runManagementContainer.sh script with the correct IP address of the NFS server.

Error: timed out waiting for the condition

When running the OAA.sh script, it may timeout pulling the images from the repository. However, you can exit the OAA Management container, or connect to the master node in another ssh window and run the following command to check the status of the pod:
kubectl get pods
You can avoid this timeout by adjusting the values before running the OAA.sh script. Edit the /u01/oracle/helmcharts/oaa/values.yaml, inside the OAA Management container. The section for the times are as follows:
test:
  # test.image -- image name that will be used to test sanity of installation.
  image: shared/alpine
  # test.timeoutsecs time for which sanity tests will run before timing out.
  timeoutsecs: 480
  # test.waitsecs time interval between sanity checks.
  waitsecs: 50

OAuth Creation Fails

During the installation, the OAuth domain, client, and resource server are created. If they fail, check if the parameters for OAuth are correct

OAuth Check Fails

This occurs if the httpd.conf and mod_wl_ohs.conf files are not updated. To update the values, see Prerequisites for Setting Up OAM OAuth for OAA

Pods display Errors about Pulling Images

For example:
NAME                                       READY   STATUS             RESTARTS   AGE
coherence-operator-7f788f5f69-ccz5q        1/1     Running            0          3h24m
oaainstall-cache-proxy-0                   0/1     ImagePullBackOff   0          4m5s
oaainstall-cache-rest-0                    0/1     ImagePullBackOff   0          4m4s
oaainstall-cache-storage-0                 0/1     ErrImagePull       0          4m5s
oaainstall-cache-storage-1                 0/1     ImagePullBackOff   0          4m5s
oaainstall-cache-storage-2                 0/1     ImagePullBackOff   0          4m5s
oaainstall-email-75f4ddbb95-488zt          0/1     ImagePullBackOff   0          4m6s
oaainstall-email-sanity-check              0/1     ImagePullBackOff   0          4m6s
oaainstall-fido-c46f8bf5-9c8sb             0/1     ImagePullBackOff   0          4m6s
oaainstall-oaa-84fd8d48b9-jkh5d            0/1     ImagePullBackOff   0          4m6s
oaainstall-oaa-admin-ui-5496bf55f8-948hm   0/1     ImagePullBackOff   0          4m6s
oaainstall-oaa-policy-757ff9b96-ng5hg      0/1     ImagePullBackOff   0          4m6s
oaainstall-sms-7bd5ffb496-8wjpb            0/1     ImagePullBackOff   0          4m6s
oaainstall-spui-7f6b66fd9b-rf7mz           0/1     ImagePullBackOff   0          4m6s
oaainstall-totp-f888b9586-pdqdq            0/1     ImagePullBackOff   0          4m6s
oaainstall-yotp-87d45689f-58cs6            0/1     ImagePullBackOff   0          4m6s

Check the kubectl logs <pod> to get a description of the problem. However, some of the common reasons for this error are as follows:

  • All the images listed in the setup earlier are not installed in your docker registry, or have been tagged wrong when pushing to the repository.
  • The wrong <hostname:port> is passed for your docker registry in installOAA.properties for install.global.repo.

Installation Fails because of Pods in Container Creating status

Run the following command to check the logs. For example,
kubectl logs oaainstall-email-6fd7c9b9dd-lr5lm
If the logs do not provide the required details about the error, run the describe pod command. For example:
kubectl describe pod oaainstall-email-6fd7c9b9dd-lr5lm

Pods Fail to Start and Shows CrashLoopBackOff

Run the kubectl logs <pod> against the Pods showing the error. Following may be one of the reasons for the error:

Pods were not able to connect to http://www.example.oracle.com:7791/.well-known/openid-configuration because the PathTrim and PathPrepend in the mod_wl_ohs.conf for that entry were not updated. See Prerequisites for Setting Up OAM OAuth for OAA