Use Oracle Identity Cloud Service with Oracle Java Cloud Service

About Oracle Identity Cloud Service

Oracle Identity Cloud Service provides Oracle Cloud administrators with a central security platform to manage the relationships that your users have with your applications, including with other Oracle Cloud services like Oracle Java Cloud Service.

With Oracle Identity Cloud Service you can create custom password policies and email notifications, onboard new users, assign users and groups to applications, and run security reports. See these topics in Administering Oracle Identity Cloud Service:

Manage Service Administrators

If your Oracle Cloud account includes Oracle Identity Cloud Service, use it to create users and groups and to give them access to Oracle Java Cloud Service.

Services in your account can be associated with Oracle Identity Cloud Service security applications. Each security application defines one or more roles. Assign users and groups to these application roles in order to grant them administrative access to these services. For example, in order to create and manage Oracle Java Cloud Service instances, assign users and groups to the JaaS_Administrator role.

In Oracle Cloud Infrastructure Classic regions, you can also assign users and groups to these related roles:

Compute_Operations — Create Oracle Java Cloud Service instances on Oracle Cloud Infrastructure Classic regions.
DBaaS_Administrator (optional) — Create and manage Oracle Database Cloud Service deployments.
Storage_ReadWriteGroup (optional) — Enable backups for an Oracle Java Cloud Service instance, and store the backups in an existing Oracle Cloud Infrastructure Object Storage Classic container.
Storage_Administrator (optional) — Create Oracle Cloud Infrastructure Object Storage Classic containers to use as backup storage locations for Oracle Java Cloud Service instances.

See these topics in Administering Oracle Identity Cloud Service:

To create and manage resources in Oracle Cloud Infrastructure regions like databases and storage, administrators define policies that grant privileges to users and groups. See Securing IAM in the Oracle Cloud Infrastructure documentation.

Create a Service Instance with Oracle Identity Cloud Service

When you create an Oracle Java Cloud Service instance, you have the option to integrate the Oracle WebLogic Server domain in the instance with Oracle Identity Cloud Service.

When you select the Enable Authentication Using Identity Cloud Service option for a service instance, Oracle Java Cloud Service creates a new security application in Oracle Identity Cloud Service that’s integrated with your WebLogic Server domain. For convenience, the Overview page of your service instance includes a link to this security application.

You can also create a service instance within a specific Identity Domain in Oracle Identity Cloud Service (Not available on Oracle Cloud at Customer). Each identity domain has an independent set of users. For example, you might create separate identity domains for test users and production users. By default, the security application for a service instance is created in the primary identity domain in Oracle Identity Cloud Service.

One way to create an Oracle Java Cloud Service instance is to clone an existing service instance. However, you cannot clone a service instance if authentication with Oracle Identity Cloud Service is enabled for the service instance.

Oracle Java Cloud Service provisions and configures an Oracle-managed load balancer for service instances that use Oracle Identity Cloud Service. For instances created in Oracle Cloud Infrastructure regions, you cannot update the default configuration for a load balancer that is provisioned automatically during the creation of the service instance.

Manage WebLogic Server Administrators

An Oracle Java Cloud Service instance includes an Oracle WebLogic Server domain. This domain defines a security realm that controls authentication, authorization, role mapping, credential mapping and security auditing across all of the servers in the domain.

All domains include predefined roles such as Administrators, Operators, Deployers and Monitors. The WebLogic Server administrative user whose credentials you initialize when you create a service instance (the default name is weblogic) is assigned the Administrators role, meaning that this user can perform all WebLogic Server administrative operations through either the WebLogic Server Administration Console, Fusion Middleware Control, WebLogic Scripting Tool (WLST) or WebLogic REST API.

When you create an Oracle Java Cloud Service instance and enable authentication with Oracle Identity Cloud Service:

The WebLogic Server security realm in the service instance is configured to use Oracle Identity Cloud Service for authentication in addition to the default WebLogic Server identity store (embedded LDAP).
A new security application is defined in Oracle Identity Cloud Service and associated with the service instance. This security application includes the same predefined WebLogic Server roles that are also found in the embedded LDAP.
Your Oracle Cloud user name is assigned to the Administrators role in your domain’s security application in Oracle Identity Cloud Service.
An Oracle-managed load balancer is provisioned in Oracle Cloud Infrastructure Load Balancing or Oracle Cloud Infrastructure Load Balancing Classic. Clients access applications on WebLogic Server via this load balancer.

As a result, you can use your Oracle Cloud user name to log into the WebLogic Server Administration Console and other WebLogic tools for your service instance. You can also use Oracle Identity Cloud Service to create additional users or groups, and assign them to the WebLogic Server administrator roles. These users and groups will then be able to perform WebLogic Server administrative operations in the service instance, depending on their assigned roles. For example, users with the Deployer role can deploy Java applications to the domain. See these topics in Administering Oracle Identity Cloud Service:

The default WebLogic Server administrative user that you specify when creating your Oracle Java Cloud Service instance remains in the embedded LDAP. Use standard WebLogic Server tools like the Administration Console in order to modify this user or to change its password. Other users that you create with Oracle Identity Cloud Service are not stored in the embedded LDAP.

Configure Protected Application Contexts for a New Service Instance

When you create an Oracle Java Cloud Service instance with the REST API or CLI, you can configure the application contexts that require authentication via Oracle Identity Cloud Service. This feature is not available in the web console.

Users access Java applications that are deployed to your Oracle WebLogic Server domain through a load balancer hosted on Oracle Cloud Infrastructure Load Balancing or Oracle Cloud Infrastructure Load Balancing Classic. By default, this load balancer is configured to use Oracle Identity Cloud Service for authentication for all requests whose URI begins with /__protected (two underscore characters followed by the word “protected”). For example, a client request to the URL https://lb_host/__protected/myapp/doaction requires authentication, while a request to https://lb_host/myapp/doaction does not.

When you create a service instance by using the REST API or CLI, you can specify additional URL patterns that require authentication. See Create a Service Instance in REST API for Oracle Java Cloud Service. In the request body, use protectedRootContexts to specify one or more URL patterns. Begin each pattern with the / character, use the * character as a wildcard, and separate multiple patterns with a comma.

For example, suppose your existing Java applications are configured to use the context roots store and marketplace. To protect all resources in the marketplace application, and also those resources in /store/cart, use the following URI patterns when creating your service instance:

...
"useIdentityService": "true",
"protectedRootContexts": "/store/cart/*,/marketplace/*"

If you create an Oracle Java Cloud Service instance with multiple WebLogic Server clusters, each cluster is assigned a path prefix. Java applications are deployed to a specific cluster, and clients must access the applications by using the cluster’s path prefix:

https://lb_host/cluster_path_prefix/path

By default, the path prefix for a cluster is the cluster’s name. One cluster in your service instance can be assigned the path prefix /.

When you create a service instance with multiple clusters, be sure to include the path prefix in the URI patterns for protectedRootContexts. For example:

"protectedRootContexts": "/cluster1/store/cart/*,/cluster2/marketplace/*"

Update Protected Application Contexts on an Existing Service Instance

This topic does not apply to Oracle Cloud at Customer.

After creating an Oracle Java Cloud Service service instance, you can use the REST API to replace the current list of protected context roots for your service instance. This feature is not available in the web console or CLI.

See Update the Web Tier Policy in REST API for Oracle Java Cloud Service. In the request body, provide a list of resourceFilters, where each filter is a regular expression that begins with the / character. Set the method of your custom filters to the value oauth.

For example, to protect all resources in the marketplace application, and also those resources in /store/cart, use the following regular expressions in the REST API request body:

...
"resourceFilters":[
  {
    "type":"regex",
    "filter":"/marketplace/.*",
    "method":"oauth"
  },
  {
    "type":"regex",
    "filter":"/store/cart/.*",
    "method":"oauth"
  },
  ...

Secure an Application Using Deployment Descriptors

Use Oracle Identity Cloud Service to protect a Java application running on Oracle Java Cloud Service by updating the application’s context path, security constraints, and role assignments.

In order to test your application’s updated security configuration, create application users and groups in Oracle Identity Cloud Service See these topics in Administering Oracle Identity Cloud Service:

Oracle WebLogic Server supports the Java Enterprise Edition declarative model for securing web applications with XML deployment descriptors.

Update the value of context-root in the application’s weblogic.xml file. Prefix the current value with one of the protected context roots that you configured for your Oracle Java Cloud Service instance.
By default, the only protected context root is /__protected (two underscore characters followed by the word “protected”). For example:
```
<context-root>/__protected/store</context-root>
```
If you created a service instance with multiple WebLogic Server clusters, you must specify the path prefix of the cluster to which the application is targeted. For example:
```
<context-root>/cluster1/__protected/store</context-root>
```
Create one or more security-role elements in the application’s web.xml file.
Simply list the user roles for your application. For example:
```
<security-role>
  <role-name>HRAdmin</role-name>
</security-role>
```

Create one or more security-constraint elements in the application’s web.xml file.

Each security constraint grants access to one or more URL patterns in your application, and to specific roles. For example:

<security-constraint>
  <web-resource-collection>
    <web-resource-name>AdminPages</web-resource-name>
    <url-pattern>/admin/*</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <role-name>HRAdmin</role-name>
  </auth-constraint>
</security-constraint>

Do not include the context root path in the URL patterns.

Create one or more security-role-assignment elements in the application’s weblogic.xml file.
Map your application roles to specific users and/or groups found in Oracle Identity Cloud Service. For example:
```
<security-role-assigment>
  <role-name>HRAdmin</role-name>
  <principal-name>HRManagersGroup</principal-name>
</security-role-assigment>
```
Redeploy your application for these changes to take effect. For example, use the WebLogic Server Administration Console.

For more information on configuring web application security, see these topics in Developing Applications with the WebLogic Security Service:

As an alternative to editing deployment descriptors, you can create a deployment plan file to override the application’s configuration settings.

Oracle Identity Cloud Service Cloudgate Patching on Oracle Java Cloud Service

Learn how to upgrade Oracle Identity Cloud Service Cloudgate on Oracle Java Cloud Service, revert to previous Cloudgate versions, and clean up the old installation.

Topics

Upgrade Cloudgate on Oracle Java Cloud Service

When you create an Oracle Java Cloud Service instance with Oracle Identity Cloud Service, you must upgrade Cloudgate to the latest available version after you update the Oracle Java Cloud Service tools on the OCI Java Cloud Service virtual machine. The upgrade is required only when a new Cloudgate version is released.

To upgrade Cloudgate, you should have enabled authentication with Oracle Identity Cloud Service when creating an Oracle Java Cloud Service instance in Oracle Cloud Infrastructure region.

To upgrade Cloudgate to a new version:

Download the latest available version on the virtual machine of the Oracle Java Cloud Service instance.
The Cloudgate key for JCS blueprint is updated to point to the new Cloudgate location.

Example of JCS Blueprint code for Cloudgate key:
```
"cloudgateZipLocation" : "JAAS/19.2.1-1903110523/cloudgate.zip"
```
After Oracle Java Cloud Service upgrades to the new version of JCS, the cloudgate.zip is downloaded to the /u01/zips/cloudgate/<version>/ folder on the Java Cloud Service virtual machine, where <version> is the current Cloudgate version that is always greater than any previously downloaded Cloudgate versions.
To install the new version on the VM:

Note:

You must perform these steps on each VM in the Oracle Java Cloud Service instance.
1. SSH to the VM in your Oracle Java Cloud Service instance.
  
  ssh -i ~/<private_key opc@<ip address of the VM server>
2. Switch to the oracle user.
  
  sudo u oracle
3. Stop the Clougate service.
  
  export CLOUDGATE_HOME=/u01/data/domains/cloudgate/idcs-cloudgate/
  
  export CLOUDGATE_NGINX_OVERRIDE=/u01/data/domains/cloudgate/nginx
  
  $CLOUDGATE_HOME/bin/cg-stop -p $CLOUDGATE_NGINX_OVERRIDE
4. Create a backup of the old Cloudgate installation.
  
  mv $CLOUDGATE_HOME /u01/data/domains/cloudgate/idcs-cloudgate_original/
5. Extract cloudgate.zip into CLOUDGATE_HOME directory.
  
  unzip /u01/zips/cloudgate/<version>/cloudgate.zip -d /u01/data/domains/cloudgate/
  
  Make sure you select the zip file that has the highest version number.
6. Copy the new nginx library.
  
  cp /u01/data/domains/cloudgate/idcs-cloudgate/bin/nginx /u01/data/domains/cloudgate/nginx/sbin
  
  This step is required when you upgrade Cloudgate versions 19.2.1 to 19.3.3 or 20.4.3, and 19.3.3 to 20.4.3.
7. After upgrade is complete, to update the configuration files for the Cloudgate version, copy the existing Cloudgate config and policy files based on instructions in the README file located in CLOUDGATE_HOME/cfg/examples.
  Note:
  
  If a new nginx entry is added in the configuration file:
  
  Run a diff of each file under /u01/data/domains/cloudgate/idcs-cloudgate/cfg folder (updated version folder) and /u01/data/domains/cloudgate/idcs-cloudgate-original/cfg folder (previous installation folder). If the diff shows changes, replace the configuration element in the updated installation with the previous installation.
  
  Run a diff of each file under /u01/data/domains/cloudgate/idcs-cloudgate/cfg/nginx folder (updated version folder) and /u01/data/domains/cloudgate/idcs-cloudgate-original/nginx folder (previous installation folder). If the diff shows changes, replace the configuration element in the updated installation with the previous installation
8. Start the Cloudgate Service.
  
  export CLOUDGATE_HOME=/u01/data/domains/cloudgate/idcs-cloudgate/
  
  export CLOUDGATE_NGINX_OVERRIDE=/u01/data/domains/cloudgate/nginx
  
  $CLOUDGATE_HOME/bin/cg-start -p $CLOUDGATE_NGINX_OVERRIDE
Verify the upgrade.

cd /u01/data/domains/cloudgate/idcs-cloudgate/bin

./cg-env

This prints the Cloudgate version.

After upgrading Cloudgate to a new version, you can change to the previous Cloudgate Version in case of issue during upgrade. See Change to Previous Cloudgate Version.

Change to Previous Cloudgate Version

If you run into issues during upgrade of Cloudgate, you can revert to the previous Cloudgate version.

Note:

You must perform these steps on each VM in the Oracle Java Cloud Service instance.

Stop the Cloudgate Service.

export CLOUDGATE_HOME=/u01/data/domains/cloudgate/idcs-cloudgate/

export CLOUDGATE_NGINX_OVERRIDE=/u01/data/domains/cloudgate/nginx

$CLOUDGATE_HOME/bin/cg-stop -p $CLOUDGATE_NGINX_OVERRIDE
Remove the current installation.

rm -f $CLOUDGATE_HOME
Change to the previous installation.

mv /u01/data/domains/cloudgate/idcs-cloudgate_original/ $CLOUDGATE_HOME
Start the Cloudgate Service.

export CLOUDGATE_HOME=/u01/data/domains/cloudgate/idcs-cloudgate/

export CLOUDGATE_NGINX_OVERRIDE=/u01/data/domains/cloudgate/nginx

$CLOUDGATE_HOME/bin/cg-start -p $CLOUDGATE_NGINX_OVERRIDE
Verify the upgrade.

cd /u01/data/domains/cloudgate/idcs-cloudgate/bin

./cg-env

This prints the Cloudgate version.

Remove the Old Installations

You can remove the older Cloudgate versions by cleaning the old installation and the downloaded binaries. But, after removing the old installation, you cannot revert to the previous Cloudgate version.

Delete the backed up cloudgate installation.

rm -rf /u01/data/domains/cloudgate/idcs-cloudgate_original/
(Optional) Delete the downloaded binary.

rm -rf /u01/zips/cloudgate/<version>

where <version> corresponds to the old cloudgate version.