Configure Applications in Oracle Identity Cloud Service

For authentication to work properly, you must use the same Oracle Identity Cloud Service instance that is securing your Oracle Fusion Applications Cloud Service and Oracle PaaS (Oracle Visual Builder) or custom HTML5 app. Within Oracle Identity Cloud Service you need to create an application to use for the client authentication.

In this scenario, we separate the matters of Oracle Functions plus Oracle API Gateway from the interaction between Oracle Functions and Oracle Fusion Applications Cloud Service entities, by protecting both using Oracle Identity Cloud Service as separate entities instead of using the same Oracle Identity Cloud Service Application for both.

Typically, Oracle SaaS extension applications written by Oracle customers perform some complex logic. For example, a common scenario is to get data from Oracle Fusion Applications Cloud Service, process it in some way, and push data back to Oracle Fusion Applications Cloud Service to to another target such as a database.

Consequently we present here an architecture with two Oracle Identity Cloud Service applications:

One application that protects your Oracle Functions as resource and as a trusted client of Oracle Fusion Applications Cloud Service.
One application that protects your Oracle Fusion Applications Cloud Service instance as a resource.

The instructions in this article will step you through the process of creating and configuring the first of these applications, to protect Oracle Functions. The second of these two applications should already exist: you were required to create and configurean application in order to enable federation between Oracle Fusion Applications Cloud Service and Oracle PaaS.

This setup allows you to configure different rules or policies to access Functions than those rules or policies for a Trusted Client to reach Oracle Fusion Applications Cloud Service. In this configuration, the incoming access token to the API Gateway only requires authorized access to Oracle Functions in order to invoke Function capability, but it does not necessarily have to also have the same grants as are necessary to access the Oracle Fusion Applications Cloud Service instance. The Oracle Visual Builder application requires an associated Oracle Identity Cloud Service Application which will generate the access token to reach API Gateway. This Oracle Identity Cloud Service Application will be the client of the Functions/API Gateway Resource.

The exchanges of tokens shown in the architecture diagram provide an additional protection layer to propagate the identity for the case of a Function being a client of an Oracle Fusion Applications Cloud Service Resource, which is similar to the Oracle WebLogic OAuth assertion process with Oracle Identity Cloud Service used in older supported SaaS extensions, such as those using Oracle Java Cloud Service.

This could mean that in certain use cases, the Oracle Identity Cloud Service application used to generate the token for Oracle Functions could have only resource scopes for Functions but not for Oracle Fusion Applications Cloud Service. In this case, Oracle Functions will not have the capability to re-use the token to invoke Oracle Fusion Applications Cloud Service, but it is valid for reaching Oracle Functions. You can therefore implement logical flows in which some users or Function evocations do not have access, while others do, based on business logic, user roles and privileges, or other criteria.

In other use cases, Oracle Functions can include code to request an access token for Oracle Fusion Applications Cloud Service by using the certificates and user passed in the request from API Gateway.

Create an Application for Oracle Functions in Oracle Identity Cloud Service

Within Oracle Identity Cloud Service you need to create a confidential application to use for the Oracle Functions client authentication.

Within the same Oracle Identity Cloud Service instance that you have federated with your Oracle Fusion Applications Cloud Service instance, create a confidential application and ensure the client configuration is set up so that it enables the Client Credentials, JWT Assertion, and Resource Owner grants.

Sign in to Oracle Cloud My Services, click Users, and then click Identity Console.
Select the Applications tab, and click Add. Then click Confidential Application.
On the Details page of the Add Confidential Application wizard, give the new application a name. If you want, you can set other values such as description, icon, display settings, and tags. Click Next.
On the Client page, select Configure this application as a client now.
Additional options appear on the page. Set them this way:
- Allowed Grant Types: Select Resource Owner, Client Credentials and JWT Assertion.
- Enable Allow non-HTTPS URLs.
- You don't need a redirect URL for this use case.
- Client Type: Leave the Confidential option selected.
Within the Resources section, select Register Resources. Set the Primary Audience value to the API Gateway instance hostname generated in the Oracle Cloud Infrastructure Console when you created your API Gatway instance.
In Oracle Cloud Infrastructure, you can select your gateway, select the Gateway Information tab, and the instance Hostname is displayed on the tab.
Under Scopes, click to add a scope, and add a value for the base url for your deployment that uses the API Gateway JWT authorization policy. For example, /saasextension.
You will use this scope to allow the application to access Oracle Functions resources. You can add additional scopes for additional resources as needed.
You don't need to grant access to admin APIs.
Click Next to go to the Resources page, then click Next again to go to the Authorization page.
On the Authorization page, click Finish.
The Application Added notification appears, with your Client ID and Client Secret. Note these down for use later. When you dismiss the notification, the application is shown.
Click the Activate button to the right of the application name.

Prepare and Test Your Oracle Identity Cloud Service Application

Configure the Oracle Identity Cloud Service Confidential application to connect to the application corresponding to your Oracle Fusion Applications Cloud Service instance, and then test the application.

In this procedure, you will configure your newly-created Oracle Identity Cloud Service application's Resources to add a Scope for your Oracle Fusion Applications Cloud Service application, and then verify that an authorized user account from your Oracle PaaS system can obtain a token for your Oracle Fusion Applications Cloud Service instance.

Sign in to Oracle Cloud My Services, click Users, and then click Identity Console.
Select the Applications tab, and then locate and select the application you just created for Oracle Functions.
Edit the Token Issuance Policy. Set Authorized Resources to All.
Add a Resource for Oracle Applications Cloud (Fusion), with the Scope of the fusion application (it does not need to be Protected).
Verify that you have a user account that exists in both Oracle PaaS and Oracle Fusion Applications Cloud Service, with sufficient privileges to access the data you will query using a REST API call. For example, the Sales Administrator role may be sufficient.
Test the application by generating an access token using these user credentials. You can generate the access token using the Postman Request Token feature by specifying as the scope, the Oracle Identity Cloud Service Oracle Fusion Applications Cloud Service Application OAuth-protected resource Primary Audience value. For this simple test, use password credentials as the Grant Type in order to use the username as a subject in the generated token. (In a production environment, you would use Client Credentials where the client will provide the user information.) The access token URL is formed by taking the Oracle Identity Cloud Service host URL and appending /oauth2/v1/token. For example, https://<your identity cloud hostname.identity.oraclecloud.com>/oauth2/v1/token.

Description of the illustration postman-test-access-token.png

If everything is working correctly, you should receive a JWT token as a response, which you can then use in an invocation to the Oracle Fusion Applications Cloud Service REST API endpoint and receive the same output. For example:

curl --location --request GET 'https://<your fusion instance>.<domain>.com/fscmRestApi/resources/11.13.18.05/expenses' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <JWT_TOKEN>'

This curl query should return Expenses data.

Configure the Oracle Functions Oracle Identity Cloud Service Application as a Trusted Client

You need a certificate to be used by the Oracle Identity Cloud Service application as a Trusted Client to make OAuth requests to your Oracle Functions. You can generate a self-signed certificate for use during development, if you don't already have a certificate available.

The provided script genSelfSignedKeypair.sh can be used to generate a key if you don't already have one. Execute the script by specifying the tenant and key alias values. In this example, we provided the mytenant as the tenant name and fnassertionkey as the key alias.

If needed, use the script provided with the code samples for this solution playbook to generate a certificate:

$ ./genSelfSignedKeypair.sh --tenant mytenant  --keyalias fnassertionkey
==============================================
Generating Self Signed Certificates in Kesytore
 
 
General Properties:
-------------------------------
==> Workdir: ./genCertsDir
==> Tenant Name: mytenant
==> Key Alias: fnassertionkey
 
Keystore Properties:
-------------------------------
==> Store Type: PKCS12
==> Key Algorithm: RSA
==> Key Size: 2048
==> Validity time(days): 1825
==> Sign Algorithm: SHA256withRSA
==> dname: CN=mytenant FN Assertion, O=mycompany, L=mylocation, ST=mystate, C=mycountry
 
Passwords:
[*] Keystore Password:
[*] PrivateKey Password:
 
Generate keypair in keystore ./genCertsDir/mytenant-keystore.p12 ...
Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA) with a validity of 1,825 days
    for: CN=mytenant FN Assertion, O=mycompany, L=mylocation, ST=mystate, C=mycountry
[Storing ./genCertsDir/mytenant-keystore.p12]
Export public certificate with alias fnassertionkey from generated keystore (openssl) ...
Certificate stored in file <./genCertsDir/mytenant-fnassertionkey-cert.pem>
Extract Private Key in PKCS8 format from generated keystore (openssl) ...
Self Signed certificate generated successfully
==============================================
Files generated:
==> ./genCertsDir/mytenant-keystore.p12
==> ./genCertsDir/mytenant-fnassertionkey-cert.pem [Stored in Keystore]
==> ./genCertsDir/mytenant-fnassertionkey-pkcs8-key.pem [Stored in Keystore]
==============================================

The generated files will be used in your Function code and in the Oracle Identity Cloud Service Application configuration:

mytenant-keystore.p12: Generated keystore for use in your code to extract the certifites used for assertion process.
mytenant-fnassertionkey-cert.pem: Public certificate for used in Oracle Identity Cloud Service Application configuration.

The third pem file is not immediately needed, but a similar version will be extracted from mytenant-keystore.p12 keystore in your code, and it is exported for reference:

mytenant-fnassertionkey-pkcs8-key.pem: A Private Key in PKCS8 Format

Configure your Oracle Functions Oracle Identity Cloud Service application with the Trusted Client Type and added a certificate using the certificate's key alias. Sign in to Oracle Cloud My Services, click Users, and then click Identity Console.
Select the Applications tab, and select the Oracle Identity Cloud Service application you created earlier for your Oracle Functions access.
In the Client Configuration section, find the Certificate field , enter the alias you used for your certificate (in the example above it was fnassertionkey) and click the Import button to import the mytenant-fnassertionkey-cert.pem file.

Import Keystore Information into Oracle Cloud Infrastructure Vault

The assertion process with Oracle Functions will require the usage of the imported keystore and passwords. For the best security and to avoid using hardcoded passwords and secrets, you can take advantage of Oracle Cloud Infrastructure Vault.

The Oracle Cloud Infrastructure Vault service allows you to encrypt and store sensitive data securely. You can store your key store and public key passwords in a Vault and then reference it using the Oracle Cloud Infrastructure SDK in your Oracle Functions Backend to perform the asssertion. You can also safely encrypt and store the JKS file.

In the Before You Begin section of this solution playbook, you were required to set up your Oracle Functions environment, such as by using the Quick Start Guides. The Quick Start Guide setup asks you to create a Policy for Functions at the root Compartment level. In the following example, that policy is named FnTenancyPolicy. You need to add additional statements to the policy to allow Oracle Functions to access Vaults associated with that policy. The name of the Group for Oracle Functions to be used should be the one you created when configuring the tenancy in the Quick Start Guide. In this example, fnGroup1 is the Group of users able to use Oracle Functions.

In the Oracle Cloud Infrastructure console, under Governance and Administration, go to Identity and click Policies.
A list of the policies in the compartment you're viewing is displayed.
Select the root compartment from the list on the left.
Select the name of your Oracle Functions policy, such as FnTenancyPolicy and click Edit Policy Statements. Add the following statements:
```
allow group fnGroup1 to manage secret-family in tenancy
allow group fnGroup1 to manage vaults in tenancy
allow group fnGroup1 to manage keys in tenancy
```
Select Save Changes.
Create a Vault instance in your compartment.
1. Under the Governance and Administration group, go to Security and select Vault.
2. Under List Scope, in the Compartment list, select the name of the compartment where you want to create the vault, and click Create Vault.
3. In the Create Vault dialog box, click Name, and then enter a display name for the vault. Avoid entering any confidential information in this field.
4. Optionally, make the vault a virtual private vault by selecting the Make it a virtual private vault check box.
5. Select Create.
Create a Key instance associated with the Secrets.
1. Under List Scope, in the Compartment list, select the name of the compartment where you want to create the key, and then click the name of the vault you just created
2. Select Keys, and then select Create Key.
3. In the Create Key dialog box, choose a compartment from the Create in Compartment list. (Keys can exist outside the compartment the vault is in.)
4. Select Name, and then enter a name to identify the key. Avoid entering any confidential information in this field.
5. Specify the key length, in bits, by choosing a length from the Key Shape: Length list.
6. When you are finished, click Create Key.
Create the secrets needed for your Assertion case:
1. Keystore Password
2. PK Password
3. Keystore file
You will need to add a Base64-encoded representation of the content of the Keystore file. You could generate it with the openssl command:

openssl base64 -in <YourKeystoreName>.p12 -out ksBase64Encoded.txt | cat ksBase64Encoded.txt
Copy the content into the value of the key in the Secret. To create a new Secret:
1. Under List Scope, in the Compartment list, select the name of the compartment where you want to create a secret.
2. From the list of vaults in the compartment, select the name of the vault you just created.
3. Select Secrets, and then select Create Secret.
4. In the Create Secret dialog box, choose a compartment from the Create in Compartment list. (Secrets can exist outside the compartment the vault is in.)
5. Select Name, and then enter a name to identify the secret. Avoid entering any confidential information in this field.
6. Select Description, and then enter a brief description of the secret to help identify it. Avoid entering any confidential information in this field.
7. Choose the master encryption key that you want to use to encrypt the secret contents while they're imported to the vault. (The key must belong to the same vault.)
8. Specify the format of the secret contents you're providing by choosing a template type from the Secret Type Template list. (You can provide secret contents in plain-text when you use the Console to create a secret or secret version, but secret contents do need to be base64-encoded before they're sent to the service. The Console automatically encodes plain-text secret contents for you if you choose this format.)
9. Select Secret Contents, and then enter the secret contents. (The maximum allowable size for a secret bundle is 25 KB.)
10. Optionally, you can apply a rule to manage how secrets are used. You can either create a rule regarding the reuse of secret contents across versions of a secret, or you can create a rule specifying when the secret contents expire.
11. When you are finished, select Create Secret.
12. Repeat these steps for each secret you need to create.
Create a Dynamic Group:
1. In the console, select Identity, and then select Dynamic Groups.
  A list of the dynamic groups in your tenancy is displayed.
2. Select Create Dynamic Group.
3. Enter a name for the dynamic group. Record the name for future use. The name must be unique across all groups within your tenancy. You can't change this name later.
4. Enter a description. You can't change the description later using the console, but you can change it by using the API.
5. In the Matching Rules section, enter the following rule (use the OCID of your compartment):
  ALL { resource.type = 'fnfunc', resource.compartment.id = 'ocid1.compartment.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'}
6. Select Create Dynamic Group.
  The matching rule syntax is verified, but the OCIDs are not. Be sure that the OCIDs you enter are correct.
Add a statement to the Policy you created for Oracle Functions at the root Compartment level as part of the Oracle Functions Quick Start Guide, to allow the dynamic group you just created to access your Secrets.
1. Under Governance and Administration, go to Identity and click Policies.
  A list of the policies in the compartment you're viewing is displayed.
2. Select the root compartment from the list.
3. Select the name of your Oracle Functions policy, such as FnTenancyPolicy and click Edit Policy Statements. Add the following statement:
  allow dynamic-group your_fn_group to read secret-family in tenancy

With the Vault Secrets configured, you can use the OCIDs for each secret to access them using the Oracle Cloud Infrastructure SDK. The properties V_KEYSTORE, V_KS_PASS, and V_PK_PASS will be used in the example functions described later in this solution.

Configure the Oracle Visual Builder Application in Oracle Identity Cloud Service

Oracle Visual Builder applications have an associated Oracle Identity Cloud Service Application which is automatically configured as a Trusted Client. You need to configure that application so that it can be used as a client of the Oracle Functions Resource.

As part of the interaction shown in the proposed architecture, an Oracle Visual Builder application associated with an Oracle Identity Cloud Service instance, federated with Oracle Fusion Applications Cloud Service and connected to Oracle Functions, needs to be able to generate an access token that can reach API Gateway and Oracle Functions Resources (as set by Scope). You must configure your Oracle Visual Builder application in Oracle Identity Cloud Service, to set it as a client of the Resource that extends the SaaS functionality by adding the scope of the new Oracle Functions application you created.

When you create a new application in Oracle Visual Builder, an Oracle Identity Cloud Service application is automatically created. For example, if you create an application called TestSaaSExtensionFN, you can navigate to the Oracle Identity Cloud Service console and list applications and you should find an application called TestSaaSExtensionFN.

Create an Oracle Visual Builder application.
In Oracle Identity Cloud Service, navigate to the application corresponding to your new Oracle Visual Builder application.
In the Token Issuance Policy section, set Authorized Resources to Specific, and use the Add Scope button to add a Resource with the Scope of your Oracle Functions API Gateway instance.
If Redirect URL is marked as mandatory in the VBCS IDCS App, it is because in Client Configuration, the Implicit check box in Allowed Grant Types is checked. In that case, you will need to provide a URL for your Oracle Visual Builder web application in this input. You can update these values later depending on your needs.

Repeat this process to add the scope for each additional Oracle Visual Builder application in Oracle Identity Cloud Service that should be able to reach the API Gateway Oracle Functions application.