Set Up an App Gateway
Download the App Gateway binary file, install the App Gateway server, register the App Gateway using Identity Cloud Service console, configure the App Gateway server, assign an enterprise application, start the App Gateway server, and test the access to the application through 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.
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.
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.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.
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.
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.
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
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 is127.0.0.1
.
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
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
- 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 theSTATUS
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.
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.
Assign an Enterprise Application to an App Gateway
Update the App Gateway registration in Oracle Identity Cloud Service console and assign an enterprise application.
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;
, addload_module /scratch/oracle/cloudgate/home/lib/ngx_http_sticky_module.so;
- Below the line
include /usr/local/nginx/conf/agent_conf/*.conf;
, addinclude /usr/local/nginx/conf/origin_conf/*.conf;
- Below the line
- 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.
- 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.
- 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
The default is |
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 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.
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 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 follows Description of Figure 29-2 follows](img/appgateway_workflow.png)
Description of "Figure 29-2 Workflow of protecting an application using App Gateway"
/myapp/private/home
page.