Secure the Application

You can secure access to your application with user credentials, and also create user roles to secure data at the level of the business object.

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?

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 reboot my device and relaunch the app?
...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.

About Authentication Roles and User Roles

You use authentication 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 resources by creating user roles and assigning authenticated end users to them.

All app users are automatically assigned either the Anonymous User or Authenticated User authentication role, or both. If access to the app requires authentication, all users are automatically granted the role Authenticated User when they sign in. If anonymous access to the app is also allowed, users that sign in are granted the Authenticated User role AND the Anonymous User role, and users who are not signed in are only granted the Anonymous User role. You can use these roles when granting permissions to operations on business objects when role-based security is enabled. The following table 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.

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.

You use user roles to secure access to business objects and data in your application. 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.

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.

About Anonymous Access

You can enable anonymous access to allow users to access your app without signing in. If anonymous access is not enabled, all users must sign in with the credentials of their Oracle Cloud Account.

All users accessing your app are assigned roles that can be used to secure access to the data and services in the application. By default, your application requires authentication, but you can use the Settings editor of the app artifact to allow anonymous access to the app. When anonymous access is enabled, users that do not sign in are assigned the Anonymous User authentication role. By default, users assigned this role cannot access the data stored in your visual application’s business objects and data retrieved from services. You must explicitly allow anonymous users access to the data by configuring the security settings of business objects and services. See Access and Secure Business Objects and About Authentication and Connection Type.

Changes that you make to authentication and security settings are only applied 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 before you can change the security settings. You then must stage or publish the application when you want the new security settings to take effect.

Note:

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

The following table describes the options for allowing anonymous access to your application and artifacts.

Allow Anonymous Access Options Description Behavior
Web and mobile applications

You enable the Allow Anonymous Access option for a web or mobile app in the Security tab of the Settings editor for the application artifact. Settings for anonymous access must also be set explicitly for business objects and service connections.

This option must be enabled to allow anonymous access to services and business objects.

When enabled, users are not required to sign in. Users that are not signed in are assigned the role Anonymous User. Signed in users are assigned the Anonymous User and Authenticated User roles.

Business objects

You enable anonymous access to business objects by enabling role-based security in the business object’s Security tab and specifying the operations that the Anonymous User authentication role can perform. See Secure Business Objects.

When enabled, anonymous users can perform operations on business objects based on the permissions granted to the Anonymous User authentication role.

Service connections

You enable anonymous access to service connection data by enabling and specifying the authentication mechanism for anonymous access in the Security field of the dialog where you add or modify a server that the service connection uses. See About Authentication and Connection Type.

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

Allow Anonymous Access

To allow anonymous access to an app and its data, you edit the security settings of each app artifact, business object, and service connection. You must also allow anonymous access to the Describe endpoint for business objects in your visual application.

If your application is already published, you must create a new version, change its settings to allow anonymous access, and publish the application again.

Enabling anonymous access in the app artifact's Security tab is required to enable users to access the app without signing in. When anonymous access is enabled for an app, the following property is defined in app-flow.json:

"security":{
      "access":{
          "requiresAuthentication": false
      }
  }

To allow anonymous access to an app and data in its business objects and from services:

  1. Open your web or mobile application in the Navigator.
  2. Open the application artifact and select the Settings editor in the Designer.
  3. Open the Security tab and select Allow anonymous access in the Access pane.
  4. Open the Security tab of the business object.
  5. Enable Role-based Security (if not enabled).
  6. Configure the rights granted to users assigned the Anonymous User role.
  7. Open the Servers tab for the service connection and edit the connection's server details.
  8. Select Allow anonymous access to the service connection infrastructure.

    If the Allow anonymous access option is grayed out, you might need to Override Security inherited from the backend, then select Allow anonymous access to the service connection infrastructure.



  9. Select the authentication mechanism from the Authentication for Anonymous Users drop-down list.
  10. Applications that allow anonymous access and have business objects with anonymous access must explicitly allow anonymous access to the Describe endpoint for business objects in your visual application. To do this, open the Business Objects tab of the visual application's Settings editor.
  11. 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 at the application level to secure access to your application's business objects.

In addition to the Authenticated User role, users who sign in to your application can be assigned a user role based on their user 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. The user is granted access 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.

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.

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.

    Description of toolbar-settings-menu.png follows
    Description of the illustration toolbar-settings-menu.png

    Alternatively, open your web or mobile app and choose Settings in the application’s Menu in the upper right corner.

  2. Open the User Roles tab in the Settings editor.

    The User Roles tab displays a tile for each user role in your application, and the groups and users that have been assigned to it.



  3. Click Create Role.
  4. Type the name in the Create Role dialog box. Click Create.

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

  5. 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 the Edit icon in the tile.

    Before you 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. In the Change Assignments dialog box, click the 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 Save Changes.


    You can assign multiple groups and users to your user role. The list of groups and users is defined in the identity provider and managed by the identity domain administrator. When you save your changes, the user roles for your application is automatically updated 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. See Secure Business Objects.

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 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 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, cannot 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, does not 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. Propagate Current User Identity 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 Propagate Current User Identity to pass the user credentials entered by the mobile application user to the REST service. Note though that you cannot use Propagate Current User Identity 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

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 Propagate Current User Identity 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.