Access and Secure Business Objects

Apps in your visual application and other clients access your business objects through REST endpoints. You can configure the security settings of each business object to control the user roles that can access the endpoints and the types of operations they can perform.

Work with the Endpoints Tab of a Business Object

For each business object, the Visual Builder user interface displays information about the endpoints you can call in code.

The Resource APIs node displays the URIs you can use to retrieve metadata and modify data in the Development, Staging, and Live databases.

The endpoints for business object are displayed in a tabular format. The display includes the HTTP method, the endpoint URI, an endpoint name that you can use in code, and a description of the endpoint.

A filter field at the top of the page allows you to view a subset of the endpoints.

For each custom business object, five default endpoints are created:

  • Two GET endpoints, to retrieve one or all business object instances

  • A POST endpoint, to create a business object instance

  • A PATCH endpoint, to update a business object instance

  • A DELETE endpoint, to delete a business object instance

If the business object refers to other business objects, endpoints are provided that enable you to retrieve, create, delete, and update those business objects. You can control these exposed endpoints for each business object by adding or removing them in a resource editor (see Add or Remove Exposed Endpoints).


Description of bo-endpoints.png follows
Description of the illustration bo-endpoints.png

You can click an endpoint in the list to view the endpoint’s details, for example, details about the endpoint’s settings and the headers sent in the request. The details are displayed in read-only mode, but you can use the Test tab to see the response to requests sent with parameter values that you supply.


Description of bo-endpoints-details.png follows
Description of the illustration bo-endpoints-details.png

Note:

The REST endpoints for business objects support using URL parameters when retrieving resources, for example, to filter payloads using a query parameter to control the behavior of the data retrieved.

For examples of supported URL parameters and some use cases, see Retrieving Business Objects in Accessing Business Objects Using REST APIs.

View the Endpoints of Business Objects

Open the Endpoints tab of a business object to view details about the available endpoints of the business object.

To view the endpoints for your business object:
  1. Select the business object in the Business Objects tab in the Navigator.
  2. Open the Endpoints tab for the business object.

Secure Business Objects

Authentication roles can be used to secure the data stored in business objects.

By default, the business objects in your application are accessible to all users that can access the application. To secure the data stored in objects, you can use authentication roles and user roles to restrict a user’s access to view, create, update and delete operations. For custom business objects, you can configure role-based access for the individual operations. Users can only perform the operations and interact with the business objects associated with the role that the user has been assigned.

To allow anonymous access to the data in a business object, for each operation you must explicitly set the permissions granted to the Anonymous User authentication role.

To enable role-based security for a business object:

  1. Select the business object you want to secure.
  2. Open the Security tab of the business object.
  3. Click the Role-based security icon to enable security for the object.
    When you enable role-based security for a business object, you see a matrix of the existing application roles and the business operations that can be performed. By default, when you enable security all existing application roles are permitted to perform all operations. If you create a new application role, permissions to perform operations are disabled for the new application role and must be enabled manually.
  4. Select the operations that can be performed by each authentication and user role.

    When configuring security for custom business objects, you can enable or disable permission for each operation.


    Description of bo-security-enabled.png follows
    Description of the illustration bo-security-enabled.png

    You can further define security at the row level for View, Update, and Delete operations by using a query builder to define conditions. To specify which users the conditions apply to, select the user role in the table. You can select Allow if user created the row from the action menu to limit an operation to the user who created the row.
    Description of bo-security-condition.png follows
    Description of the illustration bo-security-condition.png

    The action menu has Cut and Copy selections so that you can move conditions from one role or operation to another.
    Description of bo-security-menu.png follows
    Description of the illustration bo-security-menu.png

    When configuring security for business objects exposed by an external service, you can only enable or disable permission for all operations or for none.

About Allowing Access to the Catalog API

You can configure the security settings of your application to allow other applications access to the business objects in your application.

The custom business objects of your application can be consumed through their REST APIs by external clients . You can view the location of each of the catalog APIs in the Business Objects tab of the visual application's Settings editor. In the same tab you can also set the security options for accessing the business object's APIs and generate an access token.

Descriptions of the custom business objects in your application are available at the API URLs in the Catalog API panel. The panel displays separate URLs for the Development, Staged and Live versions of the application. The Catalog API URLs provide a minimal description of just the custom business objects exposed in the application. Though the URLs for the Staged and Live applications are provided for development purposes, they will not provide any results until the applications are staged or published.



Tip:

For each URL, click the Clipboard icon ( Clipboard icon ) to quickly copy the URL to your clipboard.

Each of your Development, Staging and Live versions of your visual application have their own catalog APIs that expose the REST endpoints in the application that can be consumed by other applications. Accessing the catalog using the Catalog API URLs requires authentication. You can access the APIs using an access token and by using Basic Auth.

The Security pane of the Business Objects tab in the Settings editor contains the following options that you can enable for allowing access to the business object APIs:

  • Allow anonymous access to business objects describe endpoint

  • Enable basic authentication for business object REST APIs

If you choose to allow anonymous access to the Describe endpoint, external clients accessing the endpoint will still need to add the header “Authorization: Public” to the request. The header is injected automatically for requests sent from your visual applications.

Access to the data in business objects is based on authentication and user roles. For each business object you need to explicitly enable role-based security and specify the operations that each defined authentication and user role can perform. You configure the security settings in the business object's Security tab. See Allow Anonymous Access.

Note:

Applications in other domains might need to be added to the CORS whitelist of origins permitted to access applications in your domain. An administrator can add domains in Administrator Settings.

Additionally, for requests to access your APIs that are not made through a browser, the request might need to be explicitly modified to include an Origin header that matches the domain in the CORS whitelist. A more advanced alternative would be to add CSRF headers to POST requests that include the current CSRF token value and the session cookie so the server can match the token from the request with the one in the session cache.

Get an Access Token for Authentication

To access the APIs for the catalog or custom business objects from outside Visual Builder, you can get a bearer token to use with various authentication methods.

In the design-time, you can use the token to access any of your app's endpoints. At runtime you can use the token for reading the data in the app's business object.

When authentication is handled by IDCS, you can use the token with connections that are authenticated with OAuth. You cannot use the token with connections to Oracle Cloud Applications.

You can use the token with the following authentication methods:

  • Oracle Cloud Account

  • User Assertion OAuth 2.0

  • Client Credentials OAuth 2.0

  • Resource Owner OAuth 2.0

To generate a bearer token:

  1. Open the Business Objects tab in the visual application’s Settings editor.
  2. Click Get Access Token in the Security pane.

    The access token is generated and is displayed in the Access Token Value field. You can now copy the token and use it when accessing your application's APIs.