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.

  1. In the Identity Cloud Service console, expand the Navigation Drawer, click Settings, and then click Downloads.
  2. In the Downloads page, click Download to the right of App Gateway for Identity Cloud Service.
  3. Verify that a Success status appears to the right of App Gateway for Identity Cloud Service.
  4. 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.

Install App Gateway

Use the App Gatewway Open Virtual Application (ova) file 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.

  1. Sign in to Oracle Cloud.
  2. In the Oracle Cloud console, expand the Navigation Drawer, move the mouse over Object Storage, and then click Object Storage.
  3. 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.

  4. On the Bucket Detail page, click Upload Object in the Objects section.
  5. Click select files to browse and open the App Gateway's VMDK file, and then click Upload Objects.
  6. After the file uploads, click Close.
  7. 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.
  1. In the Oracle Cloud console, click the top-left menu, mouse over Compute, and then click Custom Images.
  2. In the Images page, select the same compartment where you uploaded your VMDK file, and then click Import Image.
  3. 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.

  1. In the Oracle Cloud console, click the top-left menu, mouse over Compute, and then click Instances.
  2. In the Instances page, click Create Instance.
  3. In the Create Compute Instance page, enter My App Gateway Server in the Name your instance field, and then click Change Image Source.
  4. In the Browse All Images dialog, click Custom Images, select the appropriate compartment, select App Gateway Custom Image, and then click Select Image.
  5. 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.
  6. 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.
  7. Click Create, and wait until your compute instance is provisioned and running.
  8. 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.
  1. 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.
  2. Launch the Oracle VM Virtual Box Manager software, and then select Import Appliance from the File menu.
  3. Locate the OVA file on the Windows server, and then click Next.
  4. In the Import Virtual Appliance window, update the Name field with the value App Gateway Server.
  5. To define a new MAC address to the App Gateway server network component, select Reinitialize the MAC address of all network cards.
  6. Click Import.
  7. 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.

  1. In the Oracle VM Virtual Box Manager software, select the App Gateway server, and then click Settings.
  2. Select Network on the left menu, expand Advanced, and then click Port Forwarding.
  3. In the Port Forwarding Rules window, click Adds new port forwarding rule icon, 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.

  4. In the Port Forwarding Rules window, click Adds new port forwarding rule icon, 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.
  5. In the Port Forwarding Rules dialog box, click OK.
  6. In the App Gateway Settings dialog box, click OK.
  7. Select the App Gateway server, and then click Start.

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

  1. In the Identity Cloud Service console, expand the Navigation Drawer, click Security, click App Gateways, and then click Add.
  2. In the Details pane, specify the name of your App Gateway, and then click Next (>).
  3. In the Hosts pane, click Add.
  4. In the Add Host dialog, provide a name in the Host Identifier field.
  5. 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.
  6. 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.
  7. 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.

  8. In the Add Host dialog, click Save.
  9. In the Hosts pane, click Next >.
  10. 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.
  11. Click Finish.
  12. In the App Gateway Details page, note the value of the Client ID.
  13. 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.

  14. In the Navigation Drawer, click App Gateways.
  15. 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.

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

  2. 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.
  3. Execute the ping <idcs-tenant>.identity.oraclecloud.com command to confirm that the App Gateway server can reach the Oracle Identity Cloud Service instance.
  4. Restart the App Gateway server after applying the updates.
  5. Navigate to the /scratch/oracle/cloudgate/ova/bin/setup folder, and then edit the cloudgate-env file present in this folder (vi cloudgate-env).
  6. 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.

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

  8. In the /scratch/oracle/cloudgate/ova/bin/setup folder, execute ./setup-cloudgate command.
    When prompted, enter y to proceed with the configuration.
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.

  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.
  2. Click the Apps tab, and then click Add.
  3. 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.

    The following figure provides examples of the mappings that you configure between App Gateway and your enterprise application: Description of myappgateway_example.png follows
    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 .

  1. 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;
  2. 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;
    }
  3. 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=.foo.bar] [path=/] [expires=1h] [secure] [httponly];
   or
  sticky [hmac=md5|sha1 hmac_key=<foobar_key>] [no_fallback]
       [name=route] [domain=.foo.bar] [path=/] [expires=1h] [secure] [httponly];
   or
  sticky [text=raw] [no_fallback]
       [name=route] [domain=.foo.bar] [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:
  1. To start App Gateway server.
    /scratch/oracle/cloudgate/home/bin/cg-start
  2. To start App Gateway agent.
    /scratch/oracle/cloudgate/home/bin/agent-start
  3. To stop App Gateway server.
    /scratch/oracle/cloudgate/home/bin/cg-stop
  4. 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.

Login to the App Gateway server and then run the following command:
  1. To start App Gateway server.
    service cloudgate-nginx start
  2. To start App Gateway agent.
    service cloudgate-agent start
  3. To stop App Gateway server.
    service cloudgate-nginx stop
  4. 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 follows
Description of "Figure 29-2 Workflow of protecting an application using App Gateway"
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.