Set Up an App Gateway

Download and Extract the App Gateway Binary File

The App Gateway binary file you download from Identity Cloud Service console is a compressed (.zip) file. This file contains an Open Virtual Appliance (.ova) file which you use to install the App Gateway server.

Service Change Announcement

App Gateway Replaces App Gate

The software appliance App Gate has been replaced with App Gateway. As of August 2019, App Gate has been replaced with App Gateway. Both the App Gate and the App Gateway solutions are software appliances that you can use to provide Single Sign-On (SSO) and authorization for your on-premises applications. This enables you to use one appliance to provide SSO for multiple applications by allowing external users to access internal applications securely without needing a VPN client. There’s no change in functionality between the old App Gate and the new App Gateway solution. However, as a customer you will need to replace App Gate with App Gateway and reconfigure your supported applications. Technical support for App Gate will end after August 15, 2021. See Manage Oracle Identity Cloud Service App Gateways and see Download and Extract the App Gateway Binary File to download the App Gateway and to ensure that you are using the latest version of App Gateway.

To download and extract the App Gateway binary file:

In the Identity Cloud Service console, expand the Navigation Drawer, click Settings, and then click Downloads.
In the Downloads page, click Download to the right of App Gateway for Identity Cloud Service.
Verify that a Success status appears to the right of App Gateway for Identity Cloud Service.
Extract the content of the zip file you downloaded to a location on your desktop. For Example, c:\temp.
The c:\temp\app-gateway-<version>.ova file will be created.

Note:

The App Gateway for Identity Cloud Service doesn't replace the App Gate for Identity Cloud Service. The App Gateway for Identity Cloud Service software is based on NGINX web server and is used to protect access of enterprise applications. The App Gate for Identity Cloud Service software is an OEM product that has similar but not the same features.

Configuring Cloud Gate CORS Settings in Oracle Identity Cloud Service

Learn how to configure Cloud Gate CORS settings in Oracle Identity Cloud Service.

If you need to configure Cloud Gate CORS settings in Oracle Identity Cloud Service, then you use the Oracle Identity Cloud Service REST API. See Configuring Cloud Gate CORS Settings in Oracle Identity Cloud Service.

Install App Gateway

Use the App Gateway Open Virtual Application (OVA) file or Docker to install the App Gateway server. You can run the server in a compute instance on Oracle Cloud Infrastructureor in a virtual machine hosted in your network environment.

To install the App Gateway server, see the following topics:

Install App Gateway on Oracle Cloud Infrastructure

To install App Gateway on Oracle Cloud Infrastructure, you need to upload the App Gateway virtual disk image file to a Bucket in Oracle Cloud Infrastructure, create a Custom Image using the App Gateway virtual disk image file, and then create a Compute instance based on this custom image.

Upload the App Gateway Virtual Machine Disk Image File to an Object Storage bucket in Oracle Cloud Infrastructure

Before creating a compute instance on Oracle Cloud Infrastructure to run App Gateway, you need create a Virtual Machine Disk Image (VMDK) file using the App Gateway Open Virtual Appliance (OVA) file, and then upload this VMDK file to Oracle Cloud Infrastructure.

To create the VMDK file, follow the procedure to import the App Gateway's Open Virtual Appliance (OVA) file using Oracle VM Virtual Box software, but don't start the machine or configure port forward rule for it. See Import the Open Virtual Appliance Image File in Virtual Machine Software.

Sign in to Oracle Cloud.
In the Oracle Cloud console, expand the Navigation Drawer, move the mouse over Object Storage, and then click Object Storage.
In the Object Storage page, select the compartment where the bucket will be to upload the image. Click Create Bucket, click Create Bucket in the Create Bucket dialog, and then click the name of the bucket you created.

Contact your Oracle Cloud Infrastructure administrator for more information about which compartment to create buckets.
On the Bucket Detail page, click Upload Object in the Objects section.
Click select files to browse and open the App Gateway's VMDK file, and then click Upload Objects.
After the file uploads, click Close.
Click the menu on the right for your object entry, and then record the URL Path (URI) value.

Create a Custom Image in Oracle Cloud Infrastructure Based on the App Gateway Virtual Machine Disk Image File

To create a compute instance on Oracle Cloud Infrastructure to run App Gateway, you need to create a custom image from the App Gateway's Virtual Machine Disk Image (VMDK) file you uploaded to a bucket on Oracle Cloud Infrastructure.

Make sure your Oracle Cloud Infrastructure account has compartments, a virtual cloud network, and subnets previously set up.

Make sure you have selected a compartment in Oracle Cloud console, before proceding.

Note:

The components design should align with your Oracle Cloud Infrastructure operational model. Contact your Oracle Cloud Infrastructure administrator for more information.

In the Oracle Cloud console, click the top-left menu, mouse over Compute, and then click Custom Images.
In the Images page, select the same compartment where you uploaded your VMDK file, and then click Import Image.
In the Import Image dialog box, enter or select the following values, and then click Import Image.
- CREATE IN COMPARTMENT: Select the compartment to import the image. The compartment must be the same where your compute instance will be created.
- NAME: App Gateway Custom Image
- OPERATING SYSTEM: Select Linux.
- OBJECT STORAGE URL: Enter the URL path you recorded after you uploaded the VMDK file.
- IMAGE TYPE: Select VMDK.
- LAUNCH MODE: Select EMULATED MODE.
Wait until the custom image creation finishes.

Create a Compute Instance Using App Gateway's Custom Image

After you uploaded the App Gateway's Virtual Machine Disk Image (VMDK) file to a bucket in Oracle Cloud Infrastructure and created a custom image using this VMDK file, you can create a compute instance to run App Gateway.

In the Oracle Cloud console, click the top-left menu, mouse over Compute, and then click Instances.
In the Instances page, click Create Instance.
In the Create Compute Instance page, enter My App Gateway Server in the Name your instance field, and then click Change Image Source.
In the Browse All Images dialog, click Custom Images, select the appropriate compartment, select App Gateway Custom Image, and then click Select Image.
In the Add SSH Key section, add a public SSH key, by either uploading a public key file or pasting the public key value in the SSH Key field.
See Creating an SSH Key Pair Using PuTTY Key Generator section in Managing Key Pairs on Linux Instances.
In the Configure networking section, select a compartment in Virtual cloud network compartment.

If your compartment doesn't have virtual cloud network configured, then enter App Gateway VNC as Name in the New virtual cloud network section. If your compartment has virtual cloud network configured, then select the values for Virtual cloud network, Subnet compartment, and Subnet in which your compute instance will be created.

Note:
The component design should align with your Oracle Cloud Infrastructure operational model. Contact your Oracle Cloud Infrastructure administrator for more information.
Click Create, and wait until your compute instance is provisioned and running.
Record the value of the Public IP Address assigned to this compute instance.

Make sure that you have a Security List configured so that you can connect to the My App Gateway Server compute instance using a SSH client software such as PuTTY. Contact your Oracle Cloud Infrastructure administrator for more information.

Install App Gateway Using Oracle VM Virtual Box Software

To install App Gateway using Oracle VM Virtual Box, import the App Gateway Open Virtual Appliance (OVA) file in a Oracle VM Virtual Box, and then configure the App Gateway virtual machine to receive HTTP request.

Import the Open Virtual Appliance Image File in Virtual Machine Software

To run App Gateway in a virtual machine, import the App Gateway Open Virtual Appliance (OVA) image file in virtual machine software such as Oracle VM Virtual Box.

The following procedure requires access to a Windows server as administrator. This server must have Oracle VM Virtual Box software installed.

Log in to the Windows server, and upload the App Gateway OVA file from your desktop to a working folder in the server. For example, c:\temp.
See Download and Extract the App Gateway Binary File.
Launch the Oracle VM Virtual Box Manager software, and then select Import Appliance from the File menu.
Locate the OVA file on the Windows server, and then click Next.
In the Import Virtual Appliance window, update the Name field with the value App Gateway Server.
To define a new MAC address to the App Gateway server network component, select Reinitialize the MAC address of all network cards.
Click Import.
Verify App Gateway server is listed in the Oracle VM Virtual Box Manager.

After you import App Gateway, a virtual disk image file (VMDK) will be created in the Windows server.

To locate this file, select App Gateway Server in Oracle VM Virtual Box Manager, click Settings, click Storage, and then click the name that appears under Controller: SATA in the Storage Devices section. The location of the VMDK file appears in the Location field under Information.

Configure Port Forwarding Rules

Create a port forwarding rule to allow the requests received by the Windows server hosting the App Gateway virtual machine to be forwarded to the App Gateway server.

In the Oracle VM Virtual Box Manager software, select the App Gateway server, and then click Settings.
Select Network on the left menu, expand Advanced, and then click Port Forwarding.
In the Port Forwarding Rules window, click , configure a rule to forward the requests from the host port to the guest port, and then click OK.
For example, if your App Gateway is configure to use port 4443, then enter 4443 in both Host Port and Guest Port columns.

The port number must be the same as the port value that you provided during App Gateway registration.
In the Port Forwarding Rules window, click , configure a rule to forward the requests from the host port 22 to the guest port 22, and then click OK.
This enable you to use a SSH client such as PuTTY to login to the App Gateway server later.
In the Port Forwarding Rules dialog box, click OK.
In the App Gateway Settings dialog box, click OK.
Select the App Gateway server, and then click Start.

Deploy the Oracle App Gateway Docker Container

App Gateway can be deployed by using OVA or using Docker. Learn how to deploy the Oracle App Gateway Docker container.

Prerequisites

Download the App Gateway docker image. In the Identity Cloud Service console, expand the Navigation Drawer, click Settings, and then click Downloads.
Create a wallet file containing the Client ID and Client Secret of the App Gateway that was created in the Admin Console. The wallet file should be named cwallet.sso and should be copied to the local folder, so that the container can uptake the file. Note: The wallet tool can be downloaded from the Identity Cloud Service console. In the Identity Cloud Service console, expand the Navigation Drawer, click Settings, and then click Downloads.
Install Docker (Command: $ yum install docker-engine).
Add the current user to the Docker group (Command: $ sudo usermod -a -G docker $USER).

Extract the Docker Image

If the Docker image is in .tar.gz format, then you must use the following commands to extract the image before you can create the container.

Load the .tar.gz file to the local Docker registry. Command: $ docker load -i <.tar.gz file>
Verify that you see the image in the local Docker registry. Command: $ docker images

Create the App Gateway Container

Set the App Gateway Environment Variables

To run the App Gateway Docker container, the following environment variables must be set in the appgateway-env file. Important: No validation is performed on these values. If you configure invalid values, App Gateway Docker container creation will fail.

CG_APP_TENANT=<tenant name>
IDCS_INSTANCE_URL=<idcs instance url>. The URL required to access the Identity Cloud Service instance.
NGINX_DNS_RESOLVER=<resolver ip>. Configure the nameserver found in the file /etc/resolv.conf. The default value is 127.0.0.1.

Run Docker

Use the following command to run Docker.

Note:

The local folder will be mounted as volume and is accessible within the Docker container.

The wallet file (which contains the Client ID and Client Secret) you created as a prerequisite (cwallet.sso) should be copied to the local folder, so that the container can reference the file.

$ docker run -it -d 
--name <container name> 
--env-file <path to env file>  
--env HOST_MACHINE=`hostname -f` 
--volume <local folder>/cwallet.sso:/usr/local/nginx/conf/cwallet.sso
--net=host/<User-defined bridge name> <image name>

Example Container with Host Networking with No Port Mapping

The following is an example of Host Networking with no port mapping. This is only for port numbers greater than 1024.

Note:

If the port number configured for the App Gateway host is less than 1024, then you must use Bridge Networking for the Docker, along with the port mapping. See the Bridge Networking with Port Mapping command example below to run the Docker container.

$ docker run -it -d  
--name appgateway 
--env-file appgateway-env 
--env HOST_MACHINE=`hostname -f` 
--volume /opt/appgateway/cwallet.sso:/usr/local/nginx/conf/cwallet.sso  
--net=host opc-delivery.docker.example.com/idcs/appgateway:RELEASE-BUILDNUMBER

Example Bridge Networking with Port Mapping

The following is an example of Bridge Networking with port mapping (ports 80 to 65535).

Prerequisite: Before you use the Bridge Network configuration, add/update iptables to true, in the file /etc/docker/daemon.json. This allows the Docker daemon to edit the iptables filter rules required for port mapping.

$ docker run -it -p 80:9000  -d  
--name appgateway 
--env-file /home/<username>/dev/appgateway_pool/appgateway_env --env HOST_MACHINE=`hostname -f`
--volume /opt/appgateway/cwallet.sso:/usr/local/nginx/conf/cwallet.sso   
--net=bridge-net  idcs.docker.example.com/idcs/appgateway: RELEASE-BUILDNUMBER

Note: Docker internally updates the iptables/firewalld with the routes for the port, when the above command is run.

Post-Requisite Container Step

If the host is configured as HTTPS, the following additional steps are required to copy the certificates to the container.

Configured SSL certificates need to be copied to the location that is specified in Additional Properties. Go to Security, App Gateways, <Gateway>, Hosts, Additional Properties and note the location.

Run commands like the following. Note: The location of the certificate depends on the location you specified in the App Gateways Host.

$ docker cp deploy/docker/nginx/build/test-config/certs/my-appgateway.cert appgateway:/scratch/docker/cloudgate/certs/my-appgateway.cert

$ docker cp deploy/docker/nginx/build/test-config/certs/my-appgateway.key appgateway:/scratch/docker/cloudgate/certs/my-appgateway.key

Upgrade to a New App Gateway Version

To upgrade to a new App Gateway version, delete the existing container and recreate the container with a new version of the image. The wallet files are automatically used by the container, provided the files are not deleted in the local folder, and the same local folder is used for the volume mount.

FAQs

How do I know if my container was created successfully?

Run the command: $ docker ps -a and ensure that the STATUS is Up in the list corresponding to your container name.
If the container STATUS shows exited, how do I check the logs to determine why the container was terminated?

Run the command: $ docker logs <container name>. This command prints the log messages, which will contain the log messages printed by App Gateway.
How to do edit the cloudgate.config file inside the container?

Run the command: $ docker exec -it <container name> bash.

Run this command to access the container if the container is running with a Bash shell. Once inside the container, you can edit the files using Nano editor.

Can we print the access logs in JSON format?

Yes, you can print the access logs in JSON format. Add the lines below to the file /usr/local/nginx/conf/nginx.conf, inside an HTTP block and then restart App Gateway.

log_format jsonf escape=json '{"remote_addr": "$remote_addr", "remote_user":
      "$remote_user", "time": [$time_local], "request": "$request", "status": $status,
      "body_bytes_sent": $body_bytes_sent, "http_referer": "$http_referer", "user_agent":
      "$http_user_agent", "x_forwarded_for": "$http_x_forwarded_for"}'; access_log                    
      /usr/local/nginx/logs/access.log jsonf;

Note: You can edit the JSON fields that you’re interested in by removing or adding the NGINX variable.

Register an App Gateway

Before installing the binary file for App Gateway that appears on the Downloads page, you must register your App Gateway using the Identity Cloud Service console.

To register an App Gateway you must add hosts and associate each host to an enterprise application your App Gateway will protect:

In the Hosts pane, you define host identifiers. Each host identifier represents a domain name and port number App Gateway uses to proxy an enterprise application.
In the Apps pane, you associate an enterprise application with a host identifier.

To register an App Gateway, you must be assigned to either the Identity Domain Administrator role or the Security Administrator role.

In the Identity Cloud Service console, expand the Navigation Drawer, click Security, click App Gateways, and then click Add.
In the Details pane, specify the name of your App Gateway, and then click Next (>).
In the Hosts pane, click Add.
In the Add Host dialog, provide a name in the Host Identifier field.
Enter the Host and Port values that the App Gateway server will respond to HTTP requests.
The port number you provide in this step is used by the App Gateway server to respond to HTTP requests.
To have your App Gateway listen to HTTP requests in secure mode (HTTPS), select the SSL Enabled check box. Otherwise, clear this check box and your App Gateway will listen to non-secure HTTP requests only.
If you select the SSL Enabled check box, then populate the Additional Properties text area with the following values to specify the certificate key pair the App Gateway server will use, protocols and ciphers for SSL:
```
ssl_certificate /usr/local/example.com.rsa.crt;
ssl_certificate_key /usr/local/example.com.rsa.key;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers HIGH:!aNULL:!MD5;
```
The /usr/local/example.com.rsa.crt is the full path of a certificate file in the App Gateway server. The /usr/local/example.com.rsa.key is the secret key of that certificate file. You must upload both files to the App Gateway server after you install the App Gateway binary file.
Note:
Starting with App Gateway OVA version 20.4.1-4.0.0, App Gateway will work only in SSL/HTTPS mode. Note the following considerations:
1. If there is no load balancer in front of App Gateway, then populate the Additional Properties as specified above.
2. If App Gateway is configured to be running behind a load balancer, then the load balancer must be listening over SSL/HTTPS.
3. If the load balancer is listening over SSL/HTTPS and SSL is not enabled in the App Gateway settings, then the load balancer must pass the header (Name: is_ssl Value: ssl ) to App Gateway.
In the Add Host dialog, click Save.
In the Hosts pane, click Next >.
If you have previously registered an enterprise application in Oracle Identity Cloud Service, then in the Apps pane, click Add. See Assign an Enterprise Application to an App Gateway.
Click Finish.
In the App Gateway Details page, note the value of the Client ID.
Click Show Secret and note the value of the Client Secret.

The Client ID and Client Secret are equivalent to a credential (for example, an ID and password) that your App Gateway server uses to communicate with Oracle Identity Cloud Service. You'll need these values when you configure the App Gateway server.
In the Navigation Drawer, click App Gateways.
In the App Gateways page, select your App Gateway, click Activate, and then click OK in the Confirmation window to activate your App Gateway.

Configure the App Gateway Server

Before you start the App Gateway server for the first time, you need to configure the server to connect with Oracle Identity Cloud Service.

Use a SSH client such as PuTTY and the following credentials to log in to the App Gateway server.
- Localhost login: oracle
- Password: cloudgateR0X!
  You are required to change the provisioned password on the first login.
Execute the sudo yum updateinfo list security all command and provide sudo password.
This command lists the security errata for your App Gateway Oracle Linux server. To update all packages for which security-related errata are available to the latest versions of the packages enter sudo yum --security update.
Execute the telnet <idcs-tenant>.identity.oraclecloud.com command to confirm that the App Gateway server can reach the Oracle Identity Cloud Service instance.
Restart the App Gateway server after applying the updates.
Navigate to the /scratch/oracle/cloudgate/ova/bin/setup folder, and then edit the cloudgate-env file present in this folder (vi cloudgate-env).
Enter values for the following parameters, and then save the file:
- IDCS_INSTANCE_URL: The URL of your Oracle Identity Cloud Service instance.
  
  For example, https://idcs-123456789.identity.oraclecloud.com
- CG_APP_TENANT: The tenant name of the Oracle Identity Cloud Service instance.
  For example, idcs-123456789
- CG_APP_NAME: The client ID value you made note during the App Gateway registration in Identity Cloud Service console.
- CG_APP_SECRET: The client secret value you made note during the App Gateway registration in Identity Cloud Service console.
- CG_CALLBACK_PREFIX: If App Gateway is configured in SSL mode (HTTPS), then set the value to https://%hostid%. Otherwise, use http://%hostid% as the value for this parameter.
  
  Note:
  Starting with App Gateway OVA version 20.4.1-4.0.0, the CG_CALLBACK_PREFIX value must be https(https://%hostid%).
Confirm that the resolver entry in /usr/local/nginx/conf/nginx-cg-sub.conf has the right DNS server IP address.

Execute the nslookup <your_identity_cloud_service_domain> command, and verify the Server IP Address is the same one of the resolver entry in the /usr/local/nginx/conf/nginx-cg-sub.conf file. If not, then update this file accordingly.
Check the OVA version being installed. If the OVA version is 20.4.1-4.0.0 or 21.2.1-5.0.0, run the following commands.
1. mkdir -m 700 $NGINX_INSTALL/{uwsgi_temp,scgi_temp,proxy_temp,fastcgi_temp,client_body_temp}
2. sed -i '/Starting nginx server successful/a setfacl -Rm u::rwx,d:u::rwx,g::rwx,d:g::rwx ${CLOUDGATE_NGINX}/*_temp' ${CLOUDGATE_HOME}/bin/cg-start; sed -i '/Reloading nginx server successful/a setfacl -Rm u::rwx,d:u::rwx,g::rwx,d:g::rwx ${CLOUDGATE_NGINX}/*_temp' ${CLOUDGATE_HOME}/bin/cg-reload; sed -i 's/NGX_PROCESS_WORKER="^nginx: worker process .+"/NGX_PROCESS_WORKER="^nginx: worker process"/g' $CLOUDGATE_OVA_BIN/jobs/watchdog-cloudgate.sh
In the /scratch/oracle/cloudgate/ova/bin/setup folder, execute ./setup-cloudgate command.

When prompted, enter y to proceed with the configuration.

For OVA version 20.4.1-4.0.0 and greater, after running the ./setup-cloudgate command, the values for CG_APP_NAME and CG_APP_SECRET are automatically deleted for security reasons.

App Gateway service and agent service will start after the configuration finishes.

Assign an Enterprise Application to an App Gateway

Update the App Gateway registration in Oracle Identity Cloud Service console and assign an enterprise application.

In the Identity Cloud Service console, expand the Navigation Drawer, click Security, click App Gateways, and then click the name of your App Gateway.
Click the Apps tab, and then click Add.
In the Assign an App to gate window, map App Gateway to an enterprise application using the values below, and then click Save.
- Application: Select the enterprise application you want to protect using this App Gateway. See About Enterprise Applications.
  
  Note:
  The enterprise application must be in activated status.
- Select a Host: Select the host identifier to which the App Gateway will proxy the enterprise application.
- Resource Prefix: Enter the URL prefix used by App Gateway to proxy the enterprise application.
  
  For example, use / to represent that every request since root path will be forwarded to the enterprise application you've selected.
- Origin Server: This is the actual base URL where the application is hosted. If the application is not directly accessible, but accessible through a web proxy, then enter the URL of the web proxy. See example diagram below.
- Additional Properties: This field is used to provide additional configuration for the application. The values specified into the field are nginx directives or statements which will be part of location block in nginx.conf. Examples when you would do this are:
  1. If protected applications need to do further redirects or to access resources after successful authentication with App Gateway, you can use this field to populate the host header with correct value and pass it to the application.
    
    For example, if a user accesses the application using https://myappgateway.example.com:4443/home, the browser passes the host header to App Gateway with the value set to Host: myappgateway.example.com:4443. This value is passed by App Gateway to the downstream application, and you can achieve this by setting either of the values below in Additional Properties:
    proxy_set_header host "myappgateway.example.com:4443";
    or
    proxy_set_header host $http_host;
    $http_host is a variable and its value is populated with the host header App Gateway receives from the browser or from any client.
    
    Note:
    If the there are load balancers sitting behind App Gateway, then it is the job of the load balancers to forward the actual host header to app gateway so that $http_host is populated with the correct value and App Gateway can forward it to the application.
  2. If the application is accessible through a web proxy, then enter the values below:
    proxy_set_header host "myapp.internal.example.com";
    The "myapp.internal.example.com" domain is the domain name where the application is hosted, also known as origin server.
    
    In this case, App Gateway can't pass the host header received from browser or other client and applications cannot do further redirects via App Gateway.
  3. To pass through the upstream header, enter the following:
    proxy_pass_header Server;
    The App Gateway server header isn't used, and the upstream header is used instead.
The following figure provides examples of the mappings that you configure between App Gateway and your enterprise application:
Description of the illustration myappgateway_example.png

Note:

You can assign multiple enterprise applications to the same App Gateway, and consequently the same App Gateway server will protect these applications.

Make sure for each application, the value of Resource Prefix differs. For example, if you have http://myapp.internal.example.com:3266/myapp1/page.jsp and http://myapp.internal.example.com:6355/myapp2/page.jsp, both accessible through http://myappgateway.example.com:4443/ App Gateway URL, then enter /myapp1 as Resource Prefix when you register application 1, and /myapp2 as Resource Prefix when you register application 2.

After you assign the application to your App Gateway, you may need to restart the App Gateway server for the changes to be effective immediately.

Enable Session Persistence with Sticky Cookies

Follow these steps to enable persistent sessions using cookies in App Gateway. The sticky cookie will always be forwarded to the same backend server.

You only need to use sticky support when you have multiple origins, and you do this by creating a nginx upstream block .

Enable the sticky module in App Gateway by editing the file /usr/local/nginx/conf/nginx.conf.
- Below the line load_module /scratch/oracle/cloudgate/home/lib/idcs_cloudgate_ngx.so;, add
```
load_module /scratch/oracle/cloudgate/home/lib/ngx_http_sticky_module.so;
```
- Below the line include /usr/local/nginx/conf/agent_conf/*.conf;, add
```
include /usr/local/nginx/conf/origin_conf/*.conf;
```

Create a nginx upstream block using

$ vi /usr/local/nginx/conf/origin_conf/myupstream.conf

Add below entry to myupstream.conf
upstream weblogic {
    sticky;
    server 100.111.190.221:7003;
    server 100.111.190.220:7003;
}

Change the origin server.
1. In the Identity Cloud Service console, expand the Navigation Drawer, click Security, click App Gateways, and then click the name of your App Gateway, and in the Apps tab select the App.
2. Change the Origin Server to http://weblogic.

Sticky Parameters

upstream {
  sticky;  
  server 127.0.0.1:9001;
  server 127.0.0.1:9002;
}

  sticky [hash=index|md5|sha1] [no_fallback]
       [name=route] [domain=.example.com] [path=/] [expires=1h] [secure] [httponly];
   or
  sticky [hmac=md5|sha1 hmac_key=<foobar_key>] [no_fallback]
       [name=route] [domain=.example.com] [path=/] [expires=1h] [secure] [httponly];
   or
  sticky [text=raw] [no_fallback]
       [name=route] [domain=.example.com] [path=/] [expires=1h] [secure] [httponly];

Server Selection Algorithm

Algorithm	Description
`hash`	The hash mechanism used to encode upstream server. It can't be used with `hmac` or `text`. `md5\|sha1`. Standard cryptographic hash functions to encode the information. `index`. The information is not hashed and instead an in-memory index is used. This is quicker and the overhead is shorter, but the matching against upstream servers list is inconsistent and if the upstream server has changed index values may not correspond to the same server. Only use `index` if you are certain you want to use it despite this. The default is `md5`.
`hmac`	The HMAC hash mechanism used to encode upstream server It's like the hash mechanism but it uses `hmac_key` to secure the hashing. It can't be used with `hash` or `text`.
`hmac_key`	The cryptographic key to use with `hmac`. You must set a `hmac_key` if you use `hmac`.
`no_fallback`	Set this flag so that if a request comes with a cookie and the corresponding backend is unavailable, a 502 (Bad Gateway or Proxy Error) is returned. You can set it to the upstream block, or set `sticky_no_fallback` in a server or location block.

Cookie Settings

Setting	Description
`name`	The name of the cookie used to track the persistant upstream server. The default is `route`.
`domain`	The domain in which the cookie will be valid. The default is `none` when the browser handles the domain.
`path`	The path in which the cookie is valid. The default is `/`.
`expires`	The validity duration of the cookie. The default is `nothing` which means that it's a session cookie and deleted when the client shuts down. Enter a value to have the cookie expire after the specified time. The value is set relative to the client, and it must be for a period greater than one second.
`secure`	Enable secure cookies (transferred only using https).
`httponly`	Tells the browser that the cookie can only be accessed by the server.

Start and Stop App Gateway

To start and stop App Gateway server and App Gateway agent, you can use scripts or the services installed in the server where your App Gateway runs.

Use Script to Start and Stop App Gateway

You can start and stop the App Gateway server and agent using scripts provided in the server.

Login to the App Gateway server and then run the following command:

To start App Gateway server.

/scratch/oracle/cloudgate/home/bin/cg-start

To start App Gateway agent.

/scratch/oracle/cloudgate/home/bin/agent-start

To stop App Gateway server.

/scratch/oracle/cloudgate/home/bin/cg-stop

To stop App Gateway agent.

/scratch/oracle/cloudgate/home/bin/agent-stop

When you start the App Gateway server, App Gateway contacts Oracle Identity Cloud Service to retrieve the port number you configured during the App Gateway registration in Oracle Identity Cloud Service console. The App Gateway server starts using this port number.

The App Gateway agent is responsible for synchronizing the App Gateway configuration (hosts and applications) from Oracle Identity Cloud Service to the App Gateway server.

To check the running status of the App Gateway server, run the following command: /scratch/oracle/cloudgate/home/bin/cg-status

Use Service to Start and Stop App Gateway

You can start and stop the App Gateway server and agent as services running on the server.

Note:

Starting with App Gateway OVA version 20.4.1-4.0.0, these commands can’t be used. Instead, use the commands listed in Use Script to Start and Stop App Gateway.

Login to the App Gateway server and then run the following command:

To start App Gateway server.
```
service cloudgate-nginx start
```
To start App Gateway agent.
```
service cloudgate-agent start
```
To stop App Gateway server.
```
service cloudgate-nginx stop
```
To stop App Gateway agent.
```
service cloudgate-agent stop
```

To check the running status of the App Gateway server, run the following command: /scratch/oracle/cloudgate/home/bin/cg-status

Test Access to Your Application Using App Gateway

After you configure the App Gateway server to communicate with your Oracle Identity Cloud Service instance, and start the server, test access to your enterprise application.

The following diagram provides an example of how App Gateway and Oracle Identity Cloud Service interact when an HTTP request to an application resource is sent by the user browser through App Gateway.

Because App Gateway proxies your web application, use the App Gateway base URL to access the application instead of the application actual URL.

Figure 29-2 Workflow of protecting an application using App Gateway

Description of "Figure 29-2 Workflow of protecting an application using App Gateway"

Open a new web browser and access your application using the App Gateway URL.

In this example, the URL is: https://myappgateway.example.com:4443/myapp/private/home

The actual application https://myapp.internal.example.com:3266/myapp/private/home isn't accessible by the user browser.
App Gateway intercepts the request and communicates with Oracle Identity Cloud Service to verify if the URL corresponds to an enterprise application.
In this example, My Enteprise Application is registered, and the authentication policy for this enterprise application is Form or Access Token.
App Gateway verifies the request contains a valid Oracle Identity Cloud Service's access token in the Authorization Bearer header or Oracle Identity Cloud Service's session cookie, indicating the user has already signed in to Oracle Identity Cloud Service.
If the user hasn't signed in to Oracle Identity Cloud Service, then App Gateway redirects the user browser to Oracle Identity Cloud Service Sign In page.
If the user has signed in, then App Gateway adds header variables and a cookie to the request, and then forwards the request to the application.

The application receives the request, uses the header variables to identify the user and to present the content of the /myapp/private/home page.