Configure Connection and Authentication Types for Service Connections

How you configure authentication for connections to services depends on the type of mechanism you want to use, as well as what the external service supports. Depending on the authentication you choose, an administrator might need to configure settings in Visual Builder, the external service and Identity Cloud Service (IDCS).

About Service Connection Authentication and Connection Type

You configure the authentication and connection type that your application uses with external services when you add a server to a service connection, or edit an existing server in a service connection.

The dialogs that allow you to add a server to a service connection, or edit an existing server in a service connection, allow you to:

  • Override authentication settings set at the tenant level
  • Manage the credentials for accessing the service (if credentials are required)
  • Manage identity propagation of the end user logged in to the web or mobile app (if the service supports the standard IDCS OAuth flows)
  • Manage how your application connects to the service (via proxy or via Direct call)
  • Manage how anonymous users can access the application

Note:

In some cases, an administrator might need to configure the Visual Builder tenant-level settings for backend services or the settings of the external service or identity provider before you can connect to the service.

To connect to a service that is available on HTTPS, does not require authentication, and has no special CORS requirement, the default setting of None in the Authentication field is sufficient. In this case, any end user (anonymous or authenticated) of the web or mobile application will be able to access the service. Sending a request to a service that requires authentication will return an error if you do not provide the authentication details. The default connection type is Dynamic, the service supports CORS.



To connect to a service that requires authentication, you need to select the appropriate authentication option from the Authentication drop-down list.



Use additional application profile(s) to configure different authentication mechanisms to access a service during development, testing, and publication. If you use only the base configuration application, you’ll use the same authentication mechanism for all stages of your app development. Some mechanisms are better suited for app development, and in some cases you will want to change the authentication mechanism when you publish the app. You can select authentication mechanisms for logged in users (authenticated users) and non-logged in users (anonymous users). For a description of user roles, see About Authentication Roles and User Roles.

The mechanism you select for authenticating communication with a service will depend on the type of authentication the service supports and the authentication mechanism you use in your web or mobile app. Additionally, whether your external service supports CORS or not can also affect the choice of authentication. The authentication mechanisms can be grouped into two types, grouped by whether the identity of the end user is passed on to the service (Identity Propagation) or not (Fixed Credentials).

Identity Propagation Authentication Mechanisms

Authentication mechanisms that use identity propagation allow the identity of the end user who is signed in to the mobile or web app to be passed on to the service and used for authentication. These types of mechanisms cannot be used to authenticate anonymous access.

To use identity propagation, the service should be able to understand the IDCS identity token coming from Visual Builder and extract the user (or subject) from it. Visual Builder supports only JWT tokens procured using OAuth 2.0 flows.

Tokens are a way of encoding the calling user identity into a string according to different specifications like SAML or JWT format. For example, if the user is John.Doe, then the corresponding JWT token would take the format <header.body.signature> and would look like the following:



Decoding the body of the token yields details about the user identity and possibly the resources which he is authorized to access. The signature part is encrypted by the authority which authenticated the user, and can be easily verified by using the authority's public key. Thus, a valid user's identity is encoded into the token so that the services (namely REST APIs) which receive this token can consider the user as authenticated. The most common way of passing this token to REST services is to send it as a bearer token. i.e. pass "Bearer <token>" in the Authorization header.

The following table describes the authentication mechanisms that use the identity propagation type of mechanism.

Authentication Mechanism – Identity Propagation Description

Propagate Current User Identity

Select this to pass the identity of the user to the service. This is done in one of the two ways:

  1. If the service is called from a native mobile app with application-level Basic authentication, the credentials (username and password) that were used to sign in to the app will be passed to the service as well. Configure Basic Authentication for a Mobile Application provides more details.
  2. If the service is called from a web app, and the web app has the Enable implicit grant checkbox selected, this will pass an authentication token to the service representing the user which is obtained from the implicit grant Oauth type. If the Enable implicit grant checkbox is clear, this will be the same as Oracle Cloud Account.
We recommend that you select this mechanism in the following cases:
  • Mobile apps that use Basic authentication
  • Web apps that can communicate with Oracle Cloud Applications services using implicit OAuth grant type

Oracle Cloud Account

Select this to communicate with Oracle Cloud Applications services or any co-hosted Oracle PaaS Service, for example, Oracle Integration Cloud. When this mechanism is selected, the user must sign in with the credentials of a valid account in the Oracle Identity Cloud Service that is associated with Visual Builder.

User Assertion OAuth 2.0

Select this to call services of external system which can be represented as a Resource app in Oracle Identity Cloud Service (IDCS).

Fixed Credentials Authentication Mechanisms

Authentication mechanisms that use fixed credentials pass a fixed identity to the service and ignore the identity or credentials of the end user who is signed in. All requests sent from the app to the service use the same app id for authentication.

The following table describes the authentication mechanisms that use the fixed credentials type of mechanism.

Authentication Mechanism — Fixed Credentials Description

None

Select this for services that do not accept Authorization headers and no authentication is needed.

Basic

Select this for services where a fixed username and password are required for authentication. The credentials of the signed-in user are not used for authentication. This option uses the Visual Builder authentication proxy irrespective of what you choose in Connection Type.

We recommend you only use this mechanism during development due to the limitations of basic authentication. For example, if you have set basic authentication with a particular username and password, and you wish to revoke the basic authentication for one specific application, your only option is to revoke that particular user, which affects all applications using basic authentication. OAuth-based methods use scopes, and client ID secret to limit these scopes and give better control to manage your credentials.

Client Credentials OAuth 2.0

This mechanism is the recommended option if you want to use a Fixed Credentials mechanism and the service supports OAuth 2.0. This mechanism is part of the OAuth 2.0 grant types that are used when you don’t need a specific user’s credentials to connect to the service.

Consult the service’s OAuth 2.0 documentation for the values for the Client Id, Client Secret and token URL fields. If no values are supplied, they will be interpreted as the visual application’s client id and secret, and the token URL will be interpreted as IDCS’s token URL.

Resource Owner OAuth 2.0

This mechanism is part of the OAuth 2.0 grant types and used when you need a specific user’s credentials to connect to the service.

Consult the service’s OAuth 2.0 documentation for the values for the Client Id, Client Secret and token URL fields. If no values are supplied, they will be interpreted as the visual application’s client id and secret, and the token URL will be interpreted as IDCS’s token URL.

Oracle Cloud Infrastructure API Signature 1.0

This mechanism uses a signature method to create an Application ID flow using a single Oracle Cloud Infrastructure (OCI) user to connect to OCI endpoints. All requests go through a proxy because of the requirement to sign the outgoing message.

To use this authentication in Visual Builder, you'll need the following OCI user details from the OCI Console:
  • Fingerprint of the public key associated with your OCI account, available on the Profile > User Settings page. Click API Keys and copy the fingerprint value.
  • User's OCID, available on the Profile > User Settings page. The OCID is shown under User Information; click Copy to copy it to your clipboard.
  • Tenancy's OCID, available on the Administration > Tenancy Details page. The OCID is shown under Tenancy Information; click Copy to copy it to your clipboard.
  • The contents of your certificate's private key in PEM format.
For more information, see Request Signatures in the OCI documentation.
Once you have the details of the OCI user you want to use to connect to OCI endpoints, set up authentication in Visual Builder as follows:
  1. Select Oracle Cloud Infrastructure API Signature 1.0 as the authentication mechanism.
  2. Click Enter the API Key and Private Key (Enter the API key and private key icon).
  3. Construct the API key in the following format, then copy and paste it as the API Key:

    tenancy-ocid/user-ocid/fingerprint

  4. Paste the PEM file contents as the Private Key. Copy the entire file, starting with -----BEGIN PUBLIC KEY----- right up to -----END PUBLIC KEY-----.
  5. Select Always use proxy, irrespective of CORS is selected as the connection type.

What is CORS?

CORS (Cross-origin request sharing) is a mechanism that restricts a web page on one domain calling APIs hosted on another domain from browser-based JavaScript.

To allow such calls, the server hosting the APIs has to allow the domain of the web page to call by enabling CORS for the web page domain. The rules for CORS are built within the browser and are used to secure the user from arbitrary hosted scripts calling any APIs. See the Cross-origin resource sharing Wikipedia page for more details. If the API server has not enabled CORS for the web page, then calling the API via Fetch or AJAX from the browser results in a JavaScript error.

Use an Appropriate Connection Type to Handle CORS for REST Services

Web or mobile apps can call external REST services directly or through the Visual Builder proxy. The value you choose for connection type when you create or modify a service connection determines which option your app uses.

Calling a REST service directly through the browser using the Fetch API allows your REST service call to go directly from your app to the REST service. This method can have a performance benefit, as the REST call is directly routed to the REST service. However, the external REST service that you call must add your app’s domain to its CORS whitelist. A direct call can only be made for the following authentication types:

  • Oracle Cloud Account
  • Propagate Current user Identity
  • OAuth 2.0 (all types)
  • None

The Visual Builder proxy is a trusted server-side component that calls external REST services hosted on external domains on behalf of your app. One benefit is that you, or a system administrator, do not need to configure CORS settings for the external REST service. However, you incur the cost of an extra network call, as each request and response must first go through the Visual Builder proxy. All authentication types can be used with the Visual Builder proxy. When you use some authentication types, such as basic authentication, the REST service call will be always routed through the Visual Builder proxy.

Choose the appropriate type from the Connection type dropdown menu in the dialog where you edit or add a server to a service connection to determine the type of REST service call to make (direct or through Visual Builder proxy):

  • Dynamic, the service supports CORS: Visual Builder decides the best route to connect to the external REST service assuming that the external REST service has enabled CORS for the Visual Builder domain. If the authentication supports direct calls (None, Oracle Cloud Account, Propagate, OAuth 2.0) then the external REST service will be called directly from the app.
  • Dynamic, the service does not support CORS: Visual Builder decides the best route to connect to the external REST service assuming that the external REST service has not enabled CORS for the Visual Builder domain.
    • A call from a native mobile app that uses basic authentication or OCI Infrastructure API Signature 1.0 authentication is routed directly because native mobile apps are exempt from CORS. Web or Progressive Web Apps are not exempt from CORS.
    • All other calls are routed through the Visual Builder proxy.
  • Always use proxy, irrespective of CORS support: REST service calls from your apps always go through the Visual Builder proxy.

Review the following table to understand the result when you use different combinations of authentication and connection types.

Application type Authentication type Connection type Result
Any Any Always use Proxy Through Visual Builder proxy
Visual Builder Design time environment Any Dynamic – Service doesn’t support CORS Through Visual Builder proxy
Web app running on browser Any Dynamic – Service doesn’t support CORS Through Visual Builder proxy
Progressive Web App Any Dynamic – Service doesn’t support CORS Through Visual Builder proxy
Native mobile app All except basic authentication and OCI Infrastructure API Signature 1.0 Dynamic – Service doesn’t support CORS Direct
Native mobile app Basic authentication or OCI Infrastructure API Signature 1.0 Dynamic – Service doesn’t support CORS Through Visual Builder proxy
Any All except basic authentication and OCI Infrastructure API Signature 1.0 Dynamic – Service supports CORS Direct
Any Basic authentication or OCI Infrastructure API Signature 1.0 Dynamic – Service supports CORS Through Visual Builder proxy

Work with HTTP-based Endpoints

Visual Builder uses HTTPS for its applications, and we recommend also using HTTPS for all service connections to external endpoints.

If you use an HTTP-based URL to create a service connection for development purposes, it will always be routed via the VB Proxy irrespective of the connection type and then to the actual HTTP service. This is because visual applications run on HTTPS and are not allowed to call an HTTP endpoint directly, that is using browser JavaScript. From the VB Proxy to the HTTP endpoint, the call is routed through HTTP. You will get a warning in the Server tab (shown below) when you provide an instance URL that uses HTTP.

Description of visual-app-httpwarning.png follows
Description of the illustration visual-app-httpwarning.png

Use of HTTP is discouraged because the credentials that access the HTTP service are visible over the network. These credentials are not encrypted, as in case of HTTPS). This makes HTTP services vulnerable.

Allow Anonymous Access to the Service Data

Select the Allow anonymous access to the Service Connection Infrastructure checkbox in the Edit Server dialog if you want to allow anonymous users access to the data from services.

If you allow anonymous access to the service data, you must also allow anonymous users access to the app. You enable anonymous access to the app in the Security tab of the app’s Settings editor. See Allow Anonymous Access.

Connect to Oracle Cloud Applications APIs With End User Propagation for Authenticated Flows

To connect to Oracle Cloud Applications APIs and use end- user propagation, the identity provider used by Oracle Cloud Applications and the IDCS used by Visual Builder need to be federated, and two applications representing an Oracle Cloud Applications resource need to be created in IDCS.

Oracle Cloud Applications use their own identity provider (IdP), and Visual Builder uses only IDCS as its identity provider. The identity providers used by each service need to be federated to establish trust between them. The list of users can be maintained in either identity provider, but not both, and it is recommended that you use the Oracle Cloud Applications IdP. The Oracle Cloud Applications IdP can be further integrated via SAML with other identity providers.

Before configuring the connection, an administrator needs to work with Oracle support to federate IDCS and Oracle Cloud Applications. This process will result in creating an application in IDCS that represents the Oracle Cloud Applications resource. The process is described in Enable Oracle Fusion Applications Cloud Service Federation and OAuth Trust with Oracle Identity Cloud Service.

An administrator will then need to perform the following steps:

  1. In IDCS, create a second application representing the Oracle Cloud Applications resource that is identical to the first, except that ":443" is appended to the URL for the primary audience. For example, if the Primary Audience URL for the first IDCS application is https://<your identity provider REST API host name>, the Primary Audience URL for the second IDCS application will be https://<your identity provider REST API host name>:443.
  2. In the Services tab of the Tenant Settings page in Visual Builder, create an Oracle Cloud Applications backend service. See Add a Connection to Oracle Cloud Applications. The instance URL that you use to create the backend service is the same as the Oracle Cloud Applications Base URL.

When creating the service connection, you use the following authentication mechanism:

Authentication mechanism Details
Oracle Cloud Account

The default authentication and connection type for the service connection is determined by the backend service settings from which the service was added from the catalog. For example, if the service was chosen from the Oracle Cloud Applications -> Sales and Service catalog, then the settings will be inherited from the backend representing Sales and Service.

Typically, the backend service settings will be defined in Tenant Settings by your service administrator and can be overridden at the application level (Application Backend Settings). You can view these settings by navigating to Services, then Backends at the instance or application level.

You can choose to override these inherited settings:

  • Add or override headers
  • Allow anonymous access to Service Connection infrastructure. You can either enable or disable this.
  • Authentication for logged-in users.
  • Authentication for anonymous users.
  • Connection type: You see an Inherit from catalog option, which means the value defined at the Backend will be inherited. You choose a different connection type if you decide to override the configuration inherited from the Backend.

To connect to Oracle Cloud Applications APIs with end-user propagation:

  1. Open Service Connections in the Navigator and click Create Service Connection ( Create Service Connection icon ).
  2. Click Select from Catalog in the Create Service Connection wizard.
  3. Click Oracle Cloud Applications and select a service and endpoint. Click Create.
  4. Test the service connection.
  5. Optional: If you want to make the service connection accessible to anonymous users of the app, select the Override the configuration inherited from the Backend and Allow anonymous access to the Service Connection Infrastructure check boxes in the Edit Server dialog that you invoke from the Servers tab. Use the Authentication for anonymous users drop-down list if you want to configure an authentication type for anonymous users.

Connect to Oracle Cloud Applications APIs Not in the Catalog Using Fixed Credentials

To connect to a service in an Oracle Cloud Applications instance that is not associated with your Visual Builder instance, you can create a connection using the credentials of a fixed user registered in the Oracle Cloud Applications instance.

To create the connection, you need to have the credentials of a fixed Oracle Cloud Applications user of the instance, or an administrator will need to create the Oracle Cloud Applications user with the necessary privileges for you. When you use this user to create the connection, all requests to the Oracle Cloud Applications REST APIs will use the fixed user's credentials. The credentials of the logged-in end-user are not used when communicating with the service.

Oracle Cloud Applications instances are usually associated with your Visual Builder instance in the Tenant Settings. If your instance is already associated with an Oracle Cloud Applications instance and you want to connect to a different instance in your visual application using the Service Catalog, you can open your visual application's Settings editor and override the Tenant Settings to edit the application's Oracle Cloud Applications instance settings. When you override the default instance settings, your application will not be able to access any services provided by the default instance because a visual application can only have one default Oracle Cloud Applications instance that is used to populate the Service Catalog.

If you do not want to change the default Oracle Cloud Applications instance for your application, you can create a service connection by selecting the Define by Endpoint option in the Create Service Connection wizard.

When creating the service connection, you can use the following authentication mechanism for the service connection:

Authentication mechanism Details
Basic

To use this option you need to provide the following details:

  • Username and Password. These can be the valid credentials of any user that has access to the Oracle Cloud Applications REST APIs.

To connect to an Oracle Cloud Applications service that is not in your catalog:

  1. Open the Services tab of the visual application's Settings editor.
  2. Select Oracle Cloud Applications in the Services tab.
  3. Select Override Tenant Settings.
  4. Provide the Instance URL of the Oracle Cloud Applications instance.
  5. Select Basic as the Authentication Mechanism and provide the Username and Password of the fixed user.
  6. Open Service Connections in the Navigator and click Create Service Connection ( Create Service Connection icon ).
  7. Click Select from Catalog in the Create Service Connection wizard.

    If you did not change the default Oracle Cloud Applications instance of your application, you can choose Define by Endpoint and provide the URL of the endpoint.

  8. Click Oracle Cloud Applications and select a service and endpoint. Click Create.
  9. Confirm the connection is working.
  10. Optional: If you want to make the service connection accessible to anonymous users of the app, select the Allow anonymous access to the Service Connection Infrastructure check box in the Edit Server dialog that you invoke from the Servers tab. Use the Authentication for anonymous users drop-down list if you want to configure an authentication type for anonymous users.

Connect to Oracle Integration APIs Using Identity Propagation

To connect to Oracle Integration using identity propagation, the Oracle Integration and Visual Builder instances should be in the same domain. If Visual Builder was provisioned with Oracle Integration, both services are accessible from the Oracle Integration home page and menu.

An administrator will need to confirm that the Oracle Integration URL is correct in the Visual Builder Tenant Settings. The Oracle Integration URL in the Tenant Settings should be similar to https://<Integration Cloud Instance full URL>:443 and the authentication mechanism should be "Oracle Cloud Account". This will appear as the default URL and authentication mechanism in the visual application's Settings editor. Using "Oracle Cloud Account" authentication provides identity propagation from Visual Builder to Oracle Integration without the need for any additional configuration.

When creating the service connection, you use the following authentication mechanism:

Authentication mechanism Details
Oracle Cloud Account

The default authentication for the connection is determined by the authentication set in the Settings editor and in the Tenant Settings. You can view the connection details in the Settings editor.

You can choose to override these inherited settings:
  • Add or override headers
  • Allow anonymous access to Service Connection infrastructure (you can either enable or disable this)
  • Authentication for logged-in users
  • Authentication for anonymous users
  • Connection type: You see an Inherit from catalog option, which means the value defined at the Backend will be inherited. Choose a different connection type if you decide to override the configuration inherited from the Backend.

To connect to Oracle Integration APIs using identity propagation:

  1. Open the Services tab of the visual application's Settings editor.
  2. Select Integration Applications in the Services tab and review its configuration to confirm that "Oracle Cloud Account" is selected as the default Authentication Mechanism.

    You can override the URL coming from Tenant settings of your environment's Visual Builder instance, but keep in mind that the identity propagation will only happen for the co-located Integration instance. No additional CORS configuration is needed when Visual Builder and Oracle Integration are in the same domain.

  3. Open Service Connections in the Navigator and click + Service Connection (or Create Service Connection icon ).
  4. Click Select from Catalog in the Create Service Connection wizard.

    Alternatively, you can click Define by endpoint, provide the URL of the sample Integration endpoint, select Oracle Cloud Account as the authentication mechanism, and select your preferred connection type.

  5. Select the sample integration endpoint from the list of Catalog endpoints. Click Create.
  6. Test the Service Connection.
  7. Optional: If you want to make the service connection accessible to anonymous users of the app, select the Override the configuration inherited from the Backend and Allow anonymous access to the Service Connection Infrastructure check boxes in the Edit Server dialog that you invoke from the Servers tab. Use the Authentication for anonymous users drop-down list if you want to configure an authentication type for anonymous users.

Connect to Oracle Integration APIs Using Fixed Credentials

To connect to Oracle Integration APIs using fixed credentials, you can choose to use either Basic Auth or OAuth 2.0 Resource Owner Password as the authentication mechanism.

To access the Oracle Integration APIs using fixed credentials, the Oracle Integration and Visual Builder instances do not need to be located in the same domain or governed by the same IDCS instance. Configuration is the same in both cases.

When you create the service connection in the Create Service Connection wizard, you choose the service by either selecting it in the Service Catalog or by defining its endpoint or specification. If you want to select a service from the catalog, you will first need to open the Services tab of the visual application's Settings editor and override the tenant-level settings for Integrations and select the authentication mechanism you want to use instead of the default Oracle Cloud Account mechanism.

You do not need to override the tenant-level settings if you are defining the service connection by endpoint or specification in the Create Service Connection wizard. The authentication mechanisms are the same in both cases.

If you want to use OAuth 2.0 Resource Owner Password as the authentication mechanism, a service administrator needs to perform the following steps in the IDCS instance governing the Oracle Integration instance to get its Client ID, Client Secret, and Scope. These details are not needed when using Basic authentication.

  1. Open Applications in IDCS and locate the Oracle Integration application which frontends the Integration instance.
  2. Open the application and copy the Client ID and Client Secret in the General Information panel of the Configuration tab.
  3. Expand the Resources panel of the Configuration tab and copy the Primary Audience and the scope that corresponds to the REST APIs. These are combined to give the full scope, and might be similar to https://<primary-audience-unique-id>.integration.ocp.oraclecloud.com:443/ic/api.

When creating the service connection, you can use either of the following authentication mechanisms:

Authentication mechanism Details
Basic

To use this option you need to provide the following details:

  • Username and Password. These can be the valid credentials of any user that has access to the Integration REST endpoint.
OAuth 2.0 Resource Owner Password

To use this option you need to provide the following details:

  • Client Id and Secret. This is from the IDCS of Oracle Integration
  • Username and Password. These can be the valid credentials of any user that has access to the Integration REST endpoint.
  • Token URL. The URL will be similar to https://<base url of IDCS of Integration Cloud>/oauth2/v1/token
  • Scope. This is from the IDCS of Oracle Integration

If you do not have access to IDCS, you will need to request the connection details from an administrator if you want to use the OAuth 2.0 Resource Owner Password authentication mechanism.

To connect to Oracle Integration APIs using fixed credentials:

  1. Open Service Connections in the Navigator and click Create Service Connection ( Create Service Connection icon ).
  2. Select the source in the Create Service Connection wizard.

    You can choose Select from Catalog if the Integrations service you want to access is in your Service Catalog and you have overridden the tenant-level settings in the application's Settings editor. If it is not in your Service Catalog, choose Define by Specification or Define by Endpoint.

  3. Step through the wizard to define the service connection.
  4. Select one of the supported authentication mechanisms and provide the authentication details.
    If you chose a service from your Service Catalog, you can override the default authentication settings in the Edit Server dialog that you invoke from the Servers tab of the service connection.
  5. Test the service connection.
  6. Optional: If you want to make the service connection accessible to anonymous users of the app, select the Allow anonymous access to the Service Connection Infrastructure check box in the Edit Server dialog that you invoke from the Servers tab. Use the Authentication for anonymous users drop-down list if you want to configure an authentication type for anonymous users.

Connect to Process APIs Using Identity Propagation

To connect to Process APIs using identity propagation, the Process and Visual Builder instances must be located in the same domain and use the same IDCS instance for authentication.

Using "Oracle Cloud Account" authentication provides identity propagation from Visual Builder to Process without the need for any additional configuration. No CORS configuration is required because the instances are in the same domain.

To connect to Process APIs using identity propagation:

  1. Open Service Connections in the Navigator and click + Service Connection (or Create Service Connection icon ).
  2. Click Define by Endpoint in the Create Service Connection wizard.
  3. Provide the full applicable URL.
    For example, the URL might be similar to https://<process cloud instance>/bpm/api/4.0/processes to retrieve a list of processes.
  4. Select Oracle Cloud Account as the authentication mechanisms.
  5. Choose an appropriate connection type, such as Dynamic, the service supports CORS to take advantage of direct flows.
  6. Test the service connection.
  7. Optional: If you want to make the service connection accessible to anonymous users of the app, select the Override the configuration inherited from the Backend and Allow anonymous access to the Service Connection Infrastructure check boxes in the Edit Server dialog that you invoke from the Servers tab. Use the Authentication for anonymous users drop-down list if you want to configure an authentication type for anonymous users.

Connect to Process APIs Using Fixed Credentials

To connect to Process APIs using fixed credentials, you can choose to use Basic Auth, OAuth 2.0 Client Credentials or OAuth 2.0 Resource Owner Password as the authentication mechanism.

For access to Process APIs using fixed credentials, the Process and Visual Builder instances do not need not be located in the same domain or governed by the same IDCS instance. The steps are the same if they use the same IDCS instance. When creating the service connection, you can use one of the following authentication mechanism for the service connection:

Authentication mechanism Details
Basic

To use this option you need to provide the following details:

  • Username and Password. These can be the valid credentials of any user that has access to the Process API.
OAuth 2.0 Client Credentials

To use this option you need to provide the following details:

  • Client Id and Secret. This is from the IDCS of Process
  • Token URL. The instance token URL from IDCS.
  • Scope. This is from the IDCS of Process.
OAuth 2.0 Resource Owner Password

To use this option you need to provide the following details:

  • Client Id and Secret. This is from the IDCS of Process
  • Username and Password. These can be the valid credentials of any user that has access to the Process REST endpoint.
  • Token URL. The instance token URL from IDCS.
  • Scope. This is from the IDCS of Process.

If you do not have access to IDCS, you will need to request the authentication details from an administrator if you want to use the OAuth 2.0 Client Credentials or OAuth 2.0 Resource Owner Password authentication mechanisms.

To connect to Process APIs using fixed credentials:

  1. Open Service Connections in the Navigator and click Create Service Connection ( Create Service Connection icon ).
  2. Click Define by Endpoint in the Create Service Connection wizard.
  3. Provide the full applicable URL.
    For example, the URL might be similar to https://<process cloud instance>/bpm/api/4.0/processes to retrieve a list of processes.
  4. Select one of the supported authentication mechanisms and provide the authentication details.
  5. Test the service connection.
  6. Optional: If you want to make the service connection accessible to anonymous users of the app, select the Allow anonymous access to the Service Connection Infrastructure check box in the Edit Server dialog that you invoke from the Servers tab. Use the Authentication for anonymous users drop-down list if you want to configure an authentication type for anonymous users.

Connect to Content and Experience Cloud APIs Using Identity Propagation

Content and Experience Cloud (CECS) and Visual Builder are not provisioned together, and as a result the service administrator needs to perform the following steps in IDCS to add CECS as a resource of the Visual Builder application.

This adds CECS as a resource to a specific application, so the administrator would need to perform these steps again for each new Visual Builder application, as well as for each new version of an application and duplicate of an application that connects to CECS using identity propagation.

  1. In the Configuration tab for the Visual Builder application in IDCS, expand the Client Configuration panel and click Add Scope in the Token Issuance Policy section.
  2. In the Select Scope dialog box, choose the scope corresponding to the CECS instance "/documents" endpoint and save the application. The added scope should now be visible in the Application in the Resources list.

    If other CECS functionality (for example, Social) is required, the corresponding scope will need to be added.

After the administrator has added the resource in IDCS, you can create a connection to CECS with identity propagation. If you don't have access to IDCS, the administrator will need to provide you with the CECS Scope that you need to enter in the Authentication tab.

When creating the service connection, you use the following authentication mechanism for the service connection:

Authentication mechanism Details
OAuth 2.0 User Assertion

To use this option you need to provide the following details:

  • Client Id and Secret. This is blank.
  • Token URL. This is blank.
  • Scope. This the scope added from IDCS corresponding to the CECS instance. This is the full scope, including "/documents".

To connect to Content and Experience Cloud:

  1. Open Service Connections in the Navigator and click Create Service Connection ( Create Service Connection icon ).
  2. Click Define by Endpoint in the Select Source pane of the Create Service Connection wizard.
  3. Select the HTTP method and type the URL of the endpoint in CECS.
    For example, the URL of your endpoint might be similar to the following: https://<CES_INSTANCE>/documents/api/<VERSION>/folders/{folderId}
  4. In the Authentication section of the Server tab, select OAuth 2.0 User Assertion as the Authentication Mechanism.
  5. In the Scope field, enter the scope corresponding to the CECS instance that was added in IDCS.
    The Client Id, Secret and Token URL fields are blank.
  6. Test the service connection.
  7. Optional: If you want to make the service connection accessible to anonymous user of the app, select the Allow anonymous access to the Service Connection Infrastructure checkbox in the Edit Server dialog that you invoke from the Servers tab. Use the Authentication for anonymous users dropdown list if you want to configure an authentication type for anonymous users.

Connect to Content and Experience Cloud APIs Using Fixed Credentials

To connect to Content and Experience Cloud (CECS) using fixed credentials, the CECS and Visual Builder instances do not need to be located in the same domain or governed by the same IDCS instance. You can use Basic or OAuth 2.0 Resource Owner Password authentication for the service connection.

If you want to use Basic authentication for the connection to CECS, you need to provide a username and password that are valid in IDCS.

If you want to use OAuth flows for authenticating your connection to CECS, you need to retrieve details about the Client Secret, Client Id and the URL associated with the scope that you want to access. Typically, the scope you will want to access will be "/documents", but if you want to access other CECS functionality (for example, Social), you will need the URL that corresponds to its scope. If you do not have access to the IDCS instance used by CECS, you will need to request the details from a user with access to the instance.

To retrieve the details of the CECS application from IDCS:

  1. In the Configuration tab for the CECS application in IDCS that represents the CECS instance, expand the General Information panel and note the Client Id and Client Secret.

    The name of the CECS application will usually be similar to CECSXXX_<instance name>.

  2. Expand the Resources panel in the Configuration tab and note the URL for the scope you want, typically the scope corresponding to the CECS instance "/documents" endpoint. The URL will be similar to https://<primary audience url>/documents.

    If other CECS functionality (for example, Social) is required, you will need to note the URL for the corresponding scope.

When creating the service connection, you can use one of the following authentication mechanisms for the service connection:

Authentication mechanism Details
Basic

To use this option you need to provide the following details:

  • Username and Password. These can be the valid credentials of any user from IDCS.
OAuth 2.0 Resource Owner Password

To use this option you need to provide the following details:

  • Client Id and Secret. You get these from the CECS application in IDCS.
  • Username and Password. These can be the valid credentials of any user that has access to the CECS REST endpoint.
  • Token URL. The URL for the endpoint used to obtain an access token from IDCS. The form of the URL will be similar to <base URL corresponding to CECS in IDCS>/oauth2/v1/token.
  • Scope. You get this from the CECS application in IDCS.

If you do not have access to IDCS you will need to request the CECS application details from an administrator.

To connect to CECS using fixed credentials:

  1. Open Service Connections in the Navigator and click Create Service Connection ( Create Service Connection icon ).
  2. Click Define by Endpoint in the Select Source pane of the Create Service Connection wizard.
  3. Select the HTTP method and type the URL of the endpoint in CECS.
    For example, the URL of your endpoint might be similar to the following: https://<CECS_INSTANCE>/documents/api/<VERSION>/folders/{folderId}
  4. In the Authentication section of the Server tab, select OAuth 2.0 Resource Owner Credentials as the Authentication Mechanism.
  5. Enter the details for the Client Id, Client Secret, Scope and Token URL.
    The Client Id, Client Secret and Scope details are the ones that you noted for the CECS application in IDCS.
  6. Test the service connection.
  7. Optional: If you want to make the service connection accessible to anonymous user of the app, select the Allow anonymous access to the Service Connection Infrastructure checkbox in the Edit Server dialog that you invoke from the Servers tab. Use the Authentication for anonymous users dropdown list to configure an authentication type for anonymous users.

Connect to Oracle Mobile Hub APIs Using Fixed Credentials

To connect to Oracle Mobile Hub using fixed credentials, you can choose to use Basic Auth, OAuth 2.0 Client Credentials or OAuth 2.0 Resource Owner Password as the authentication mechanism.

To access Oracle Mobile Hub from Visual Builder, the settings of the container for the mobile APIs need to be configured to allow connections from your visual application using one of the authentication mechanisms. To use Basic Auth, the mobile backend must have "HTTP Basic" enabled. To use OAuth 2.0, the "OAuth Consumer" option must be enabled.

An administrator will need to perform the following steps to configure the mobile backend:

  1. Open the settings for the Oracle Mobile Hub mobile backend.

    This backend represents the container for the various custom/platform APIs that you will connect to using the service connection.

  2. Enable the connection for the type of authentication you want to use, and note the details for the connection.

    If the connection will use Basic Auth, confirm that the Mobile backend has "HTTP Basic" enabled. If the connection will use OAuth 2.0, confirm that "OAuth Consumer" is enabled. Depending on which you choose, you might need the value of the Anonymous Key, Mobile Backend ID, Client ID and Client Secret.

If Direct flows are needed, then the CORS need to be added to Security_AllowOrigin policy at the OMH backend side.

When creating the service connection, you can use one of the following authentication mechanisms:

Authentication mechanism Details
Basic

To use this option you need to provide the following details:

  • Username and Password. These can be the valid credentials of any user that has access to the Oracle Mobile Hub API.
  • Static header. You need to add a static header named oracle-mobile-backend-id in the Headers tab of your service connection. The value of the header needs to be set to the Mobile Backend ID from Oracle Mobile Hub.
  • Static header. You need to add a static header named oracle-mobile-backend-id when you configure basic authentication in the Security tab of your mobile application’s Settings page. See Configure Basic Authentication for a Mobile Application.

    Note:

    Add oracle-mobile-backend-id in the Headers tab of your service connection if you want to test the service connection from your Visual Builder Designer.
None

To use this option you need to edit the service connection to add the following:

  • Secure static header. You need to add a static header named Authorization in the Headers tab of your service connection. The value of the header needs to be set to Basic<Anonymous key>, where <Anonymous key> is the value from the Oracle Mobile Hub backend.
  • Static header. You need to add a static header named oracle-mobile-backend-id in the Headers tab of your service connection. The value of the header needs to be set to the Mobile Backend ID from Oracle Mobile Hub.

OAuth 2.0 Client Credentials

To use this option you need to provide the following details:

  • Client Id and Secret. This is from the Oracle Mobile Hub backend.
  • Token URL. This is the OAuth Token endpoint from the Oracle Mobile Hub backend.
  • Scope. See Authenticate with OAuth in Direct REST Calls in Developing Applications for Oracle Mobile Hub. The format will be similar to https://<baseURL>urn:opc:resource:consumer::all. For example, if the baseURL given in the Oracle Mobile Hub settings is https://abcdef.mobile.ocp.oraclecloud.com:443, the scope would be https://abcdef.mobile.ocp.oraclecloud.com:443urn:opc:resource:consumer::all.
OAuth 2.0 Resource Owner Password

To use this option you need to provide the following details:

  • Username and Password. These can be the valid credentials of any user that has access to the Oracle Mobile Hub API.
  • Client Id and Secret. This is from the Oracle Mobile Hub backend.
  • Token URL. This is the OAuth Token endpoint from the Oracle Mobile Hub backend.
  • Scope. See Authenticate with OAuth in Direct REST Calls in Developing Applications for Oracle Mobile Hub. The format will be similar to https://<baseURL>urn:opc:resource:consumer::all. For example, if the baseURL given in the Oracle Mobile Hub settings is https://abcdef.mobile.ocp.oraclecloud.com:443, the scope would be https://abcdef.mobile.ocp.oraclecloud.com:443urn:opc:resource:consumer::all.

If you do not have access to the Oracle Mobile Hub mobile backend, you will need to request the connection details from an administrator.

To connect to Oracle Mobile Hub using fixed credentials:

  1. Open Service Connections in the Navigator and click Create Service Connection ( Create Service Connection icon ).
  2. Click Define by Endpoint in the Select Source pane of the Create Service Connection wizard.
  3. Select the HTTP method and type the URL of the endpoint in Oracle Mobile Hub.
  4. In the Authentication section of the Server tab, select the Authentication Mechanism you want to use.
  5. Enter the required details based on the Authentication Mechanism you are using.
  6. Test the service connection.
  7. Optional: If you want to make the service connection accessible to anonymous user of the app, select the Allow anonymous access to the Service Connection Infrastructure checkbox in the Edit Server dialog that you invoke from the Servers tab. Use the Authentication for anonymous users dropdown list to configure an authentication type for anonymous users.

Connect to ORDS APIs Using Fixed Credentials

To connect to Oracle REST Data Services (ORDS) using fixed credentials, you can use OAuth 2.0 Client Credentials for authentication. Visual Builder

Before creating a connection to ORDS, a role and privilege to protect your REST service need to be created and the OAuth client needs to be registered in the ORDS service. The following steps briefly describe this process. See Protecting and Accessing Resources.

When creating the service connection, you can use the following authentication mechanism for the service connection:

Authentication mechanism Details
OAuth 2.0 Client Credentials

This is the recommended authentication option.

To use this option you need to provide the following details:

  • Client Id and Secret. From ORDS
  • Token URL. From ORDS, for example, https://example.com/ords/ordstest/oauth/token
  • Scope. This is blank.
  1. Create a role and privilege to protect your REST service in ORDS
    begin  ords.create_role('HR Administrator');
            ords.create_privilege(
          p_name => 'example.employees',
          p_role_name => 'HR Administrator',
          p_label => 'Employee Data',
          p_description => 'Provide access to employee HR data');
      commit;end;
  2. Associate the privilege with resources (i.e. your ORDS REST APIs)
    begin ords.create_privilege_mapping(
          p_privilege_name => 'example.employees',
          p_pattern => '/examples/employees/*');
          commit;end;

    Accessing the /example/employees REST resource should now result in a 401 unauthorized as below

    curl -i https://example.com/ords/ordstest/examples/employees/
    HTTP/1.1 401 Unauthorized
    Content-Type: text/html
    Transfer-Encoding: chunked
      
    <!DOCTYPE html>
    <html>
    ...
    </html>
  3. Register the OAuth client with grant type Client Credentials
    begin oauth.create_client(
          p_name => 'Client Credentials Example',
          p_grant_type => 'client_credentials',
          p_privilege_names => 'example.employees',
          p_support_email => 'support@example.com');
     commit;end;

    Check the registered client id and secret

    select client_id,client_secret from user_ords_clients where name = 'Client Credentials Example';

To create a connection to ORDS using fixed credentials:

  1. Open Service Connections in the Navigator and click Create Service Connection ( Create Service Connection icon ).
  2. Click Define by Endpoint in the Select Source pane of the Create Service Connection wizard.
  3. Select the HTTP method and type the URL of the endpoint in ORDS.
  4. In the Authentication section of the Server tab, select OAuth 2.0 Client Credentials as the authentication mechanism.
  5. Provide the details for the Client Id, Secret and Token URL fields based on your ORDS configuration.
  6. Test the service connection.