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.

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.

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:

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.

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.

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

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

     Note:

     Starting with App Gateway OVA version 20.4.1-4.0.0, the CG_CALLBACK_PREFIX value must be https(https://%hostid%).
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. 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
9. 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.

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.

     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.

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.

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];

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"

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.