Secure the Application

You can secure access to your application with user credentials and create user roles to secure data stored in your application's business objects.

Security on Web and Mobile Apps

Web and mobile apps created using Visual Builder can use the Oracle Identity Cloud Service (IDCS) for token-based authentication. Token-based authentication protects your business data from unauthorized access, while allowing your app's users to access the app now and again without having to log in each time.

When a user logs in to your deployed web or mobile app, the app authenticates with the IDCS which sends a token to the app. Once authenticated, the user can continue to use the app without having to log back in until the token expires, typically after 8 hours.

Whenever the app makes a call to the REST service, it retrieves the token and attaches it to the request. As long as the token is still valid, the REST service sends the appropriate response. If the token has expired, the service rejects the request (returns a '401') and the user is redirected to the log-in screen.

For mobile hybrid apps, the token is stored internally by Oracle's Cordova Identity Management (IDM) plugin. This token persists even if the user quits the app, reboots the device, or switches networks. This means that the user can relaunch the app while the token is still valid and not have to log back in.

For web and PWAs, the token is stored in the browser session and is discarded when the user closes the browser window, exits the PWA, or reboots the device. When the user relaunches the app following one of these events, they are prompted to log back in.

The following table describes the authentication behavior for mobile, web, and progressive web apps after some common user events such as restarting, rebooting, and going online.

What happens if ... Mobile Hybrid Web PWA

...I quit my app or it crashes and I relaunch it?

...I reboot my device and relaunch the app?

If the token is still valid, I can continue working without having to log in again.

If the token has expired, I am prompted to log back in.

If the device is offline, the app uses a cached user object to allow me to continue working with cached data. I am only prompted to log back in when I reestablish an Internet connection after the token has expired.

I am prompted to log back in.

For web apps, the token is stored in the browser session and is discarded when the browser window or the app is closed.

If the device is online, I am prompted to log back in.

For PWAs, the token is stored in the browser session and is discarded when the browser window or the app is closed.

If the device is offline, the PWA uses a cached user object to allow me to continue working with cached data. I am only prompted to log back in when I reestablish an Internet connection.

...I switch from a data network to a WiFi network or vice versa?

I am not prompted to log in. Changing networks does not affect token behavior or duration.

I am not prompted to log in. Changing networks does not affect token behavior or duration.

I am not prompted to log in. Changing networks does not affect token behavior or duration.

... I lose my network connection or switch to airplane mode?

I can continue to work in offline mode with cached data even after the token expires since I am not connecting to the server.

The app uses the Oracle Offline Persistence Toolkit (OPT) to manage cached data.

See Add Offline Support Using the Oracle Offline Persistence Kit.

I receive a browser error, such as a "No internet" error (Google Chrome).

If my web app uses the cache control HTTP header to manage cached data, I can continue to work in offline mode.

See Add Offline Support Using the Oracle Offline Persistence Kit.

I can continue to work in offline mode with cached data even after the token expires since I am not connecting to the server.

The app uses the Oracle Offline Persistence Toolkit (OPT) to manage cached data.

See Add Offline Support Using the Oracle Offline Persistence Kit.

...My device comes back online?

If the token is still valid, I can continue working as before without having to log in.

If the token has expired, I am prompted to log in again.

If the token is still valid, I can continue working as before without having to log in.

If the token has expired, I am prompted to log in again.

If the token is still valid, I can continue working as before without having to log in.

If the token has expired, I am prompted to log in again.

Authentication Roles Versus User Roles

You use authentication roles to manage access to the pages and data in your application. In addition to the default authentication roles, you can fine tune access to your application's resources by creating user roles and assigning authenticated users to them.

All app users are automatically assigned either the Anonymous User or Authenticated User authentication role. When access to the app requires authentication (default), all users are granted the Authenticated User role when they sign in. If anonymous access to the app is allowed, users are granted the Anonymous User role. You can use these roles when granting permissions to operations on business objects when role-based security is enabled. Here's a table that describes the two authentication roles.
Authentication Role Description
Anonymous User All users who access Visual Builder applications are assigned this role when anonymous access to the application is enabled. An anonymous user cannot access data stored in the application's business objects or retrieved from services, unless anonymous access is explicitly enabled for the Anonymous User role.
Authenticated User All users who access Visual Builder applications are assigned this role after they sign in. An authenticated user can see all components and manage business objects, unless access to the object is explicitly disabled for the Authenticated User role. All developers are assigned this role by default.

When your app requires authentication, you can further control access to business objects and data in your application through user roles. The application’s user roles ensure that users assigned the same role or group in the Oracle PaaS identity provider are granted equal access in your application. You define the user roles for the visual application in the User Roles tab of the visual application’s Settings editor. The user roles defined for your application are stored in user-roles.json in the visual application's settings folder. See Manage User Roles and Access.

You assign users or groups in the identity domain to a user role in your visual application, but only identity domain administrators can add users to the identity domain, and it is the responsibility of the identity domain administrator to add users to groups and maintain them in the identity provider. Administrators manage groups using Oracle Identity Cloud Service (IDCS), or use Oracle Shared Identity Manager (SIM) to manage roles for services using a Traditional Cloud Account. All user authentication is delegated to the identity provider.

Note:

If you want to federate IDCS with your existing identity provider, see Federating with Identity Providers.

You can also choose to override the default security provider that an app is using by creating your own security provider that maps to a third-party provider. Note that this might affect functionality such as identity propagation to REST service calls. See Security Provider.

When a user attempts to access data in a business object secured by a user role, the roles assigned to the user are authenticated in the identity provider. The user is granted access if one of the user roles securing the business object is mapped to one of the roles or groups the user has been assigned to in the identity provider. Security based on roles is disabled by default. You can set role-based security and privileges for viewing, creating, updating and deleting objects in the Security tab of the business object in the Business Objects editor. See Secure Business Objects.

Note:

By default, Authenticated Users can access all objects and components in your application. To thoroughly enable role-based security, you must explicitly specify authentication or visibility for an object to a user role and disable access for the Authenticated User authentication role.

Allow Anonymous Access

Visual Builder applications, by default, require authentication; all users must sign in with their Oracle Cloud credentials to access your app. If you want users to access your app without signing in, you can enable anonymous access from the app-level Settings editor.

Note:

The service administrator must enable anonymous access in the instance’s Tenant settings. You will not be able to enable anonymous access for your visual applications if anonymous access to applications is not permitted for the instance.

When anonymous access is enabled, users are not required to sign in and are automatically assigned the Anonymous User authentication role. By default, users assigned this role cannot access the data stored in your visual application’s business objects or retrieved from services. You must explicitly allow anonymous users access to this data by configuring the security settings of business objects and services. You also need to allow anonymous access to the Describe endpoint for your business objects.

Changes that you make to authentication and security settings are applied only when you stage or publish the application. The versions of your application that are currently staged or published are unaffected. For example, if your application is already published, you must create a new version of the application, change its settings to allow anonymous access, then stage or publish the application again for the new security settings to take effect.

  1. To enable users to access your visual app without signing in, enable anonymous access in the app's Security tab:
    1. Open your web or mobile application in the Navigator.
    2. Open the application artifact and click Settings, then Security.
    3. Deselect Require authenticated access under Permissions.
    With anonymous access enabled, users don't need to sign in to access the app.
  2. To allow anonymous users access to the visual application's data stored in business objects, enable role-based security in the business object’s Security tab and specify the operations that the Anonymous User authentication role can perform:
    1. Open your business object's Security tab.
    2. Click the Role-based security icon (if not enabled).
    3. Configure the rights granted to users assigned the Anonymous User role.
    With anonymous access enabled, anonymous users can perform operations on business objects based on the permissions granted to the Anonymous User authentication role.
  3. To allow anonymous access to service connection data. enable and specify the authentication mechanism for anonymous access in the service connection's server details:
    1. Open your service connection's Servers tab and edit the server details.
    2. Select Allow anonymous access to the service connection infrastructure under Security.

      If the option is grayed out, click Override Security to override security inherited from the backend, then select Allow anonymous access to the service connection infrastructure.



    3. From the Authentication for Anonymous Users drop-down list, select the authentication mechanism you want to use.

    With anonymous access enabled, anonymous users can access data from the service connections that are configured to allow anonymous access.

  4. Applications that allow anonymous access and have business objects with anonymous access must explicitly allow anonymous access to the business object's Describe endpoint:
    1. Open the Business Objects tab of the visual application's Settings editor.
    2. Select Allow anonymous access to business objects describe end point.


      If you choose to allow anonymous access, access to an endpoint will still require adding the header “Authorization: Public” to the request. This header is injected automatically for requests sent from your visual applications. Here's how you can add the header to the request from external clients:
      • Include auth in the Describe endpoint URL, for example:

        https://servicename-cloudaccount.test.oraclecloud.com/ic/builder/rt/myapp/1.0/resources/auth/data/describe?metadataMode=minimal

      • Add the “Authorization: Public” header to the request, for example, from the cURL command line:

        curl -v https://servicename-cloudaccount.test.oraclecloud.com/ic/builder/rt/myapp/1.0/resources/data/describe?metadataMode=minimal -H 'Authorization: Public'

Manage User Roles and Access

You can create, edit, and remove user roles to secure access to your application's business objects.

In addition to the Authenticated User role granted to users who sign in to your application, users can be assigned a user role based on their credentials and the groups they've been assigned to in Oracle Identity Cloud Service (IDCS). When a user tries to access data in a business object secured by this user role, the roles assigned to the user are authenticated in IDCS. Access is granted if one of the user roles securing the business object is mapped to one of the groups the user has been assigned to in IDCS or if the user was mapped to that user role directly.

Use the User Roles tab in a visual application’s Settings editor to create a user role and assign users and groups in your IDCS account to the user role. Assigning groups to your user role maps the role to IDCS groups and is known as "role mapping". Once you create a user role, the role and any users or groups assigned to it are automatically added to the client application in IDCS.

To create a user role in your visual application:

  1. On the Visual Builder Home page, locate the visual application whose settings you want to change and choose Settings in the Application Options menu. Alternatively, choose Settings in the application’s Menu in the upper right corner.
  2. Open the User Roles tab in the Settings editor.

    If user roles have been defined, you'll see a tile for each user role in your application (along with the groups and users assigned to it).



  3. Click Create Role.
  4. Enter a name for the role in the Create Role dialog box. Click Create.

    This role name is displayed when designing your application, but is not exposed to users.

  5. Before you proceed to assign groups or users, or edit a user role, verify that the application profile selected in the Application Profile drop-down list is the one where you want to make changes.
  6. Click Assign groups or users in the tile if no users or group have been assigned. If you want to edit a user role and some groups or users have already been assigned to it, click Edit icon that appears when you hover your cursor over the tile.
  7. In the Change Assignment... dialog box, click Add icon for each group that you want to assign to the role. In the Users field, enter the name of the user that you want to add, or enter a character to retrieve a list of users. For example, enter a to retrieve all user names that include the character a. Click Add icon to add the user to the role.


    You can assign multiple groups and users to your user role. Keep in mind that the list of groups and users is defined in the identity provider and managed by the identity domain administrator. Click Save Changes when you are done. Saving your changes automatically updates the user roles for your application in IDCS.

After you create a role, you'll need to enable role-based security for the application's business objects by specifying the user roles that can access the object and setting access privileges for the role in the business object’s Security tab.

Besides securing access to the data in your business objects, user roles can help control what a user sees in your application. For example, you can use role-based permissions to limit access to the app, entire pages or flows, even set restrictions on certain components in a page, so only users with certain roles can view that information.

Note:

An application's user role definitions are preserved whenever it is exported and imported—as long as the app is imported to the same IDCS domain it was exported from. When you export an app, its user roles (as defined in user-roles.json) are included in the exported application archive (role-mapping.json), then re-created when you import the application. Once this is done, the role-mapping.json file is deleted from the application's sources. But if you run into errors and this doesn't happen (say, because you're importing an older app whose users and groups no longer exist in IDCS), you'll need to manually set up the user roles again.

Embed a Web Application

Your web application can be embedded in sites in domains associated with your Identity Domain as well as external sites.

You must explicitly allow embedding in your web application’s settings if you want to allow other applications to embed your application. For example, if you know that another site wants to use pages and data from your web app in their site, and they don't want to or can't link to your app, you can allow your app to be embedded in their app.

For security reasons, all embedding is denied by default. You can use the Settings editor in the Designer to edit the metadata of the application artifact. The web application’s security settings are stored in the configuration.json file, which is located in the application’s settings folder when you browse the application’s sources.


Description of settings-embedding.png follows
Description of the illustration settings-embedding.png

To allow your web app to be embedded in another app:

  1. Open the web application in the Navigator.

  2. Select the application artifact to open it in the Designer.

  3. Click Settings in the Designer and open the Security tab in the Settings editor.

  4. Enable Allow embedding in any application domain.

When your app is embedded within another app, the preferred method is for the other app to only embed the content of the page and not display the elements that wrap the content. For example, you might want to prevent a user from opening your app's user menu and logging out when it is embedded in another app. You can edit the shell template page to remove content such as the header and footer elements that you don’t want to appear when the page is embedded.

Configure Basic Authentication for a Mobile Application

Mobile applications that you develop with Visual Builder can use basic authentication rather than the default Oracle Cloud Account authentication mechanism.

To use basic authentication, you specify a login endpoint URL and logout endpoint URL in the input fields that appear when you select Basic as the authentication mechanism in the Security tab of the mobile application's settings. At runtime, the mobile application presents a login screen where the user enters their user name and password (user credentials). These user credentials are converted into a basic authentication header and the login URL is invoked to pass the basic authentication header to the authentication service. On successful authentication, the user is navigated to the home page of the mobile application. If you want to pass additional HTTP headers to the service that you are connecting to through basic authentication, click New Header to display input fields where you enter the HTTP header(s) you want to pass.

The login and logout endpoint URLs can be any third party or Oracle Cloud service URL that supports basic authentication. This contrasts to the Oracle Cloud Account authentication mechanism which requires the user to have a valid account in the Oracle Identity Cloud Service that is associated with Visual Builder.

There are a number of things you need to know if you configure basic authentication for your mobile application. User roles, which secure access to individual page flows or business objects in your application based on the user’s role, can't be used if you configure basic authentication for your mobile application. The built-in variable, user, which accesses information about the current user when the mobile app uses the Oracle Cloud authentication mechanism, doesn't return information when the mobile app uses basic authentication.

Mobile basic authentication is not designed to use any Visual Builder server runtime artifacts like the Visual Builder proxy. Therefore, the connection type that you use must be Dynamic, the service supports CORS. Delegate Authentication and None are the two authentication mechanisms for REST service connections that you can use if your mobile application uses basic authentication. We recommend that you use Delegate Authentication to pass the user credentials entered by the mobile application user to the REST service. Note though that you cannot use Delegate Authentication while you develop and test the mobile application in Visual Builder using the Page Designer’s Live and Design modes or run it in a separate browser tab. For these scenarios, temporarily use one of the following authentication mechanisms for the REST service connection:

  • Basic
  • OAuth 2.0 Client Credentials
  • OAuth 2.0 Resource Owner Password Credentials

Once you complete testing the mobile application in Visual Builder and are ready to install it on a device, switch the authentication mechanism that the REST service connection(s) in the mobile application use back to Delegate Authentication and the connection type to Dynamic, the service supports CORS.

REST services that permit anonymous access can be accessed from a mobile application that uses Basic as its authentication mechanism if the REST service connection in the mobile application is configured to use None as the authentication mechanism.

Basic authentication is not a supported option for mobile apps that enable PWA support.