Fusion Middleware Documentation
Advanced Search


Oracle Enterprise Pack for Eclipse Developing Mobile Applications with Oracle Mobile Application Framework (OEPE Edition)
Close Window

Table of Contents

Show All | Collapse

21 Securing Mobile Applications

This chapter provides an overview of the security framework within Oracle Mobile Application Framework and also describes how to configure mobile applications to participate in security.

This chapter includes the following sections:

21.1 About Mobile Application Framework Security

MAF presents users with a login page when a secured application feature has been activated. For example, users are prompted with login pages when an application feature is about to be displayed within the web view or when the operating system returns an application to the foreground. MAF determines whether access to the application feature requires user authentication when an application feature is secured by an authentication server, or when it includes constraints based on user roles or user privileges. Only when the user successfully enters valid credentials does MAF render the intended web view, UI component, or application page.

While the presence of these conditions in any of the application features can prevent users from accessing a mobile application without a successful login, you can enable users to access a mobile application that contains both secured and non-secured application features by including a default application feature that is neither secured nor includes user access-related constraints. In this situation, users can access the MAF application without authentication. The default application feature provides the entrance point to the mobile application for these anonymous users, who can both view non-secured data and authenticate against the remote server when accessing a secured application feature. You can designate a non-secure default application feature by:

  • Allowing anonymous users access to public information through the default application feature, but only enabling authorized users to access secured information.

  • Allowing users to authenticate only when they require access to a secured application feature. Users can otherwise access the mobile application as anonymous users, or login to navigate to secured features.

  • Allowing users to log out of secured application features when secured access is not wanted, thereby explicitly prohibiting access to secured application features by unauthorized users.

Note:

MAF enables anonymous users because the application login process is detached from the application initialization flow; a user can start a mobile application and access unsecured application features as an anonymous user without having to provide authentication credentials. In such a case, MAF limits the user's actions by disabling privileged UI components.

For more information, see Section 21.5.1, "How to Enable Application Features to Require Authentication," and Section 14.2.4, "About User Constraints and Access Control."

The IDM Mobile SDKs provide APIs for authentication, cryptography, user and role management, and secure storage. The SDKs support authentication through Basic Authentication and REST web services exposed by the Mobile and Social server. The Mobile and Social server supports authentication against the Oracle Access Manager (OAM) Server with (or without) strong authentication using Relying Party authentication (that is, authentication against third-party OpenId and OAuth service providers), and authentication against a directory server with (or without) strong authentication.

A mobile application uses either the default page or a customized login page that is written in HTML. When authentication beyond a login page, a knowledge-based authentication page can be enabled when knowledge-based authentication is configured on OAMM server. Knowledge Based Authentication screens provide an additional challenge to users by prompting for additional information, such as ”mother's maiden name.” Like the login page, the Knowledge Based Authentication screen can be customized.

21.1.1 About Constraint-Dictated Access Control

Application features defined with user.roles or user.privileges constraints can be accessed only by users who have been granted the specific role and privileges. When users log into such an application feature, a web service known as the Access Control Service (ACS) returns the user objects that grant them access to this application feature. For more information about ACS, see Section 21.4.15, "What You May Need to Know About the Access Control Service."

21.2 About the User Login Process

From the end-user perspective, the login process is as follows:

  1. MAF presents a web view of a login page, shown in Figure 21-1 whenever the user attempts to access an application feature that is secured. If the secured application feature is the default, then MAF prompts users with the login page when they launch the mobile application.

    Figure 21-1 The Login Page

    This image is described in the surrounding text

    Note:

    As described in Section 21.5.3.2, "The Custom Login Page," MAF provides not only a default login page, but also supports the use of a custom login page and, optionally, a custom knowledge-based authentication screen.

  2. The user enters a user name and password and then clicks OK.

    Note:

    MAF allows multiple users for the same application. Users may freely log in to an application after a previous user logs out.

  3. If the user name and password are verified, MAF displays the intended web view, page, or user interface component.

  4. MAF presents challenges to the user name and password until the user logs in successfully. When users cannot login, they can only navigate to another application feature.

  5. After authenticating their user name and password, the user may be presented with knowledge-based authentication screen to challenge their credentials with additional questions. When Knowledge Based Authentication is configured, the user must correctly reply to the questions in order to complete the login process. Knowledge Based Authentication is an optional configuration that requires the appropriate configuration on OAMM server.

Note:

Authentication times out when a predefined time period has passed since the last activation of an application feature. MAF only renews the timer for the idle timeout when one of the application features that uses the connection to the authentication server has been activated.

21.3 Overview of the Authentication Process for Mobile Applications

Mobile applications may require that user credentials be verified against a remote login server (such as the Oracle Access Manager Identity Server used by Oracle ADF Fusion web applications) or a local credential store that resides on the user's device. To support local and remote connectivity modes, MAF supports these authentication protocols:

  • HTTP Basic

  • Mobile-Social

  • OAuth

  • Web SSO

By default, authentication of the mobile application user is against the remote login server regardless of the authentication protocol chosen at design time. Developers may configure the application, in the case of Oracle Access Management Mobile and Social (OAMMS) and basic authentication to enable local authentication. However, initially, because the local credential store is not populated with credentials, login to access secured application features requires authentication against a remote login server. Successful remote authentication enables the subsequent use of the local credential store, which houses the user's login credentials from the authentication server on the device. Thus, after the user is authenticated against the server within the same application session (that is, within the lifecycle of the application execution), MAF stores this authentication context locally, allowing it to be used for subsequent authentication attempts. In this case, MAF does not contact the server if the local authentication context is sufficient to authenticate the user. Although a connection to the authentication server is required for the initial authentication, continual access to this server is not required for applications using local authentication.

Tip:

While authentication against a local credential store can be faster than authentication against a remote login server, Oracle recommends authentication using OAuth or Web SSO authentication protocols, which only support remote connectivity.

Table 21-1 summarizes the login configuration options of a MAF application. The connectivity mode depends on the chosen authentication protocol.

Table 21-1 MAF Connectivity Modes and Supported Authentication Protocols

Connectivity Mode Support Protocols Mode Description

local

  • HTTP Basic

  • Mobile-Social

Requires the application to authenticate against a remote login server only when locally stored credentials are unavailable on the device. The initial login is always against the remote login server. After the initial successful login, MAF persists the credentials locally within a credential store in the device. These credentials will be used for subsequent access to the application feature. See also Section 21.4.13, "What You May Need to Know about Web Service Security."

remote

  • HTTP Basic

  • Mobile-Social

  • OAuth

  • Web SSO

Requires the application to authentication against a remote login server, such as Oracle Access Manager (OAM) Identity Server or a secured web application. Authentication against the remote server is required each time a user logs in. If the device cannot contact the server, then a user cannot login to the application despite a previously successful authentication.

hybrid

  • HTTP Basic

  • Mobile-Social

Requires the application to authenticate against a remote login server when network connectivity is available, even when local credentials are available on the device. Only when a lack of network connectivity prevents access to the login server will local credentials on the device will be used.


The flow of security is as follows when mobile applications verify user credentials against an authentication server:

  1. MAF presents the user with the login page (similar to the one shown in Figure 21-1) or knowledge-based authentication screen.

  2. The APIs of the Oracle Access Management Mobile and Social (OAMMS) client SDKs handle credential authentication against both the authentication server and the credential store on the device, which may store a saved user object. If the authentication succeeds, the APIs return a valid user object to MAF. Otherwise, they return a failure.

    Note:

    Logging into OAMMS populates the roles and privilege collections to the user object.

  3. If the login succeeds, MAF receives an OAM token used in the cookie. MAF sets the cookie into each login connection.

  4. The OAMMS client SDK APIs save the credentials in the device's credential store.

  5. If the login fails, the login page or Knowledge Based Authentication screen remains, thereby preventing users from continuing.

21.4 Configuring MAF Connections

You must define at least one connection to the application login server for an application feature that participates in security. The absence of a defined connection to an application login server results in an invalid configuration. As a result, the application will not function properly.

21.4.1 How to Create a MAF Login Connection

As Figure 21-2 shows, you can use the Mobile Login Server Connection wizard to select the connection type and, depending on the connection type, enable both local and remote authentication (hybrid). Depending on application requirements, you can configure a connection to servers that support the following authentication protocols:

  • HTTP Basic

  • Mobile-Social

  • OAuth

  • Web SSO

Note:

Oracle recommends that you configure a connection to the login server using the OAuth or Web SSO connection type. OAuth and Web SSO require authentication against a remote login server and do not allow users to authenticate on the device from a local credential store.

Figure 21-2 Configuring Authentication

This image is described in the surrounding text

To create a login server connection:

  1. In the Project Explorer, expand the assembly project, then MAF and double-click MAF Application Editor.

    Note:

    The MAF Application Editor lets you define the application login server connection and assign it to the default application feature (if the default application feature is secured). In this case, credentials specified for the application login server are also used to retrieve user and roles and services through the Access Control Service (ACS). See also Section 21.4.15, "What You May Need to Know About the Access Control Service."

  2. In the editor, select Security in the outline, and then click Create next to one of:

    • Default Login Server

    • Login Page

    • Knowledge Based Authentication Page

  3. In the Mobile Login Server Connection wizard, select Create a new connection and choose the authentication server type, as shown in Figure 21-2. The connection types are described in the following sections.

21.4.2 How to Configure Basic Authentication

As Figure 21-3 shows, you can select the HTTP Basic authentication server type in the Mobile Login Server wizard to configure a connection for basic authentication.

Figure 21-3 Configuring Basic Authentication

This image is described in the surrounding text

To configure basic authentication:

  1. In the Mobile Login Server Connection wizard, choose HTTP Basic as the authentication server type. Click Next.

    For information about opening the Mobile Login Server Connection wizard, see Section 21.4.1, "How to Create a MAF Login Connection."

  2. In the General Options page, define the following:

    • Name—Enter a name for the connection.

    • Authentication Mode—Select the type of authentication, as described in Table 21-1.

    • Idle Timeout—Enter the time for an application feature to remain idle after MAF no longer detects the activation of an application feature. After this period expires, the user is timed-out of all the application features that are secured by the login connection. In this situation, MAF prompts users with the login page when they access the feature again. By default, MAF presents the login page when an application remains idle for 300 seconds (five minutes).

      Note:

      MAF authenticates against the local credential store after an idle timeout, but does not perform this authentication after a session timeout.

    • Session Timeout—Enter the time, in seconds, that a user can remain logged in to an application feature. After the session expires, MAF prompts the user with a login page if the idle timeout period has not expired. By default, a user session lasts for 28,800 seconds (eight hours).

    • Include login server in REST calls—For application features using remote authentication, select this option to enable a REST web service to retrieve the authorized user data that is stored on a login server through a login server-generated user session cookie. For more information, see Section 21.4.10, "What You May Need to Know About Adding Cookies to REST Web Service Calls."

      Note:

      To enable cookies to be injected in the REST web service call, the application feature must use remote authentication (MAF does not support injecting cookies for application features that store user credentials locally) and the domain entered for Login URL must be identical to the domain of the REST web service end point.

    • Include basic authentication header in HTTP requests—Select this option to enable MAF to add a basic authentication header into the HTTP requests made from a web view. Basic authentication is the default request method used by MAF. A basic authentication header is injected only when the login connection type is HTTP Basic. See also Section 21.4.12, "What You May Need to Know About Injecting Basic Authentication Headers."

    • Realm

    Click Next

  3. In the HTTP Basic Options page, enter the following, as shown in Figure 21-4.

    • Login URL—Enter the login URL for the authentication server.

    • Logout URL—Enter the logout URL for the authentication server.

    • Multi-Tenant Aware—MAF supports the notion of multi-tenancy, where a mobile application includes a hosted application feature that can be shared by different organizations (tenants), but can appear as though it is owned by a particular tenant. You can define multi-tenancy awareness for the mobile application connection by selecting this option. See also Section 21.4.17, "What Happens When You Define a Multi-Tenant Connection."

    Figure 21-4 Configuring Basic Authentication

    The surrounding text describes this image.
  4. Click Test to test the connection to the authentication server. The results are displayed on the wizard.

  5. Click Next to open the Login Options page and configure the parameters as described in Section 21.4.7, "How to Store Login Credentials."

  6. Click Next to open the Authorization Options page and configure the parameters as described in Section 21.4.14, "How to Configure Access Control."

  7. Click Finish to create the connection.

21.4.3 How to Configure Web SSO Authentication

As Figure 21-5 shows, you can use the Mobile Login Server Connection wizard to configure a cross-domain single sign-on.

Figure 21-5 Configuring Federated SSO Authentication

The surrounding text describes this image.

To configure authentication with a Web SSO server:

  1. In the Mobile Login Server Connection wizard, choose Web Single Sign-on for the authentication server type and click Next.

    For information about opening the Mobile Login Server Connection wizard, see Section 21.4.1, "How to Create a MAF Login Connection."

  2. In the General Options page, configure the following, as shown in Figure 21-6:

    Figure 21-6 Configuring the Connection

    The surrounding text describes this image.
    • Connection Name—Enter a name for the connection.

    • Session Timeout—Enter the time, in seconds, that a user can remain logged in to an application feature. After the session expires, MAF prompts the user with a login page if the idle timeout period has not expired. By default, a user session lasts for 28,800 seconds (eight hours).

    • Include login server in REST calls—For application features using remote authentication, select this option to enable a REST web service to retrieve the authorized user data that is stored on a login server through a login server-generated user session cookie. For more information, see Section 21.4.10, "What You May Need to Know About Adding Cookies to REST Web Service Calls."

    Click Next.

  3. On the Web Single Sign-on Options page, configure the URLs that enable successful and unsuccessful logins.

    Figure 21-7 Configuring the Authentication URLs

    This image is described in the surrounding text
  4. Click Next, and on the Authorization Options page configure the parameters, as described in Section 21.4.14, "How to Configure Access Control."

21.4.4 How to Configure Authentication Using Oracle Mobile and Social Identity Management

As Figure 21-8 shows, you can select the Oracle Access Management Mobile and Social (OAMMS) authentication server type in the Mobile Login Server Connection wizard to configure a connection for mobile applications to authenticate with the Oracle Access Manager (OAM) server. The OAM backend for this connection type must be running Oracle Mobile and Social server and 10g WebGate (a web server plug-in that intercepts HTTP requests for resources and forwards them to the OAM server for authentication and authorization).

Figure 21-8 Configuring Authentication with Mobile-Social

The surrounding text describes this image.

Before you begin:

Confirm that the OAM backend runs Oracle Mobile and Social Server and 10g Webgate.

Configure the server to use the OM_PROP_OAMMS_URL property key. This URL (including protocol, host name, and port number) is required to reach the Mobile and Social server. Only the HTTP and HTTPS protocols are supported. You must also configure the server to inject an OAM_ID cookie into the web server request header.

Note:

This connection type requires Knowledge Based Authentication (KBA). For more information, see Section 21.5.2, "How to Designate the Login Page."

To configure authentication with Oracle Access Management through an Oracle Mobile and Social server:

  1. In the Mobile Login Server Connection wizard, choose Oracle Access Management Mobile and Social (OAMMS) as the authentication server type, and click Next.

    For information about opening the Mobile Login Server Connection wizard, see Section 21.4.1, "How to Create a MAF Login Connection."

  2. In the General Options page, define the following:

    • Connection Name—Enter a name for the connection.

    • Authentication Mode—Select the type of authentication, as described in Table 21-1.

    • Idle Timeout—Enter the time for an application feature to remain idle after MAF no longer detects the activation of an application feature. After this period expires, the user is timed-out of all the application features that are secured by the login connection. In this situation, MAF prompts users with the login page when they access the feature again. By default, MAF presents the login page when an application remains idle for 300 seconds (five minutes).

      Note:

      MAF authenticates against the local credential store after an idle timeout, but does not perform this authentication after a session timeout.

    • Session Timeout—Enter the time, in seconds, that a user can remain logged in to an application feature. After the session expires, MAF prompts the user with a login page if the idle timeout period has not expired. By default, a user session lasts for 28,800 seconds (eight hours).

    • Include login server in REST calls—For application features using remote authentication, select this option to enable a REST web service to retrieve the authorized user data that is stored on a login server through a login server-generated user session cookie. For more information, see Section 21.4.10, "What You May Need to Know About Adding Cookies to REST Web Service Calls."

      Note:

      To enable cookies to be injected in the REST web service call, the application feature must use remote authentication (MAF does not support injecting cookies for application features that store user credentials locally) and the domain entered for Login URL must be identical to the domain of the REST web service end point.

    • Include basic authentication header in HTTP requests—Select this option to enable MAF to add a basic authentication header into the HTTP requests made from a web view. Basic authentication is the default request method used by MAF. A basic authentication header is injected only when the login connection type is HTTP Basic. See also Section 21.4.12, "What You May Need to Know About Injecting Basic Authentication Headers."

    • Realm

      Click Next.

  3. On the OAMMS page, enter the URL to the Oracle Access Management Mobile and Social server and enter the mobile application service domain.

    You can also configure the connection to enable the server to make location updates on the device, as shown in Figure 21-9.

    Figure 21-9 Configuring the OAM Authentication

    The surrounding text describes this image.
  4. Click Next to open the Login Options page where you can and configure the parameters as described in Section 21.4.7, "How to Store Login Credentials."

  5. Click Next to open the Authorization Options page where you can configure the parameters as described in Section 21.4.14, "How to Configure Access Control."

21.4.5 How to Configure OAuth Authentication

As Figure 21-10 shows, you can use the Mobile Login Server Connection wizard to configure how third-party applications (clients) gain limited access to protected data or services stored on a remote server. The Relying Party authentication provided by Oracle Mobile and Social server enables an application to authenticate against a third-party OAuth provider. Oracle Web Services Manager (OWSM) Lite Mobile ADF Application Agent injects the cookie into the security header of the web service call.

Figure 21-10 Configuring OAuth

This image is described in the surrounding text

Before you begin:

Configure the server to use the OM_PROP_OAUTH_OAUTH20_SERVER property key.

To configure authentication with an OAuth server:

  1. In the Mobile Login Server Connection wizard, choose OAuth2 for Authentication Servers Type, and click Next.

    For information about opening the Mobile Login Server Connection wizard, see Section 21.4.1, "How to Create a MAF Login Connection."

  2. On the General page, configure the following, then click Next.:

    • Connection Name—Enter a name for the connection.

    • Include login server in REST calls—For application features using remote authentication, select this option to enable a REST web service to retrieve the authorized user data that is stored on a login server through a login server-generated user session cookie. For more information, see Section 21.4.10, "What You May Need to Know About Adding Cookies to REST Web Service Calls."

      Note:

      To enable cookies to be injected in the REST web service call, the application feature must use remote authentication (MAF does not support injecting cookies for application features that store user credentials locally) and the domain entered for Login URL must be identical to the domain of the REST web service end point.

  3. On the OAuth2 page, configure the following, as shown in Figure 21-11, then click Next:

    • Choose the Grant Type to determine where the application obtains the login page. Select Code when you want the server login page to display. Select Resource Owner when you want the MAF application to display the default login page, or custom login page, when one is configured.

    • Enter enter the Client ID and, optionally, enter a connection password value in the Client Secret field.

    • Enter the URIs for the endpoints for the Authorization Endpoint itself and the Token Endpoint and the authorization server's Redirect Endpoint.

    • Enter a Logout URL.

    • Select Use Embedded Browser when you want the login page to display within the embedded browser within the application. Deselect to display the login page in an external browser. Note that when single sign-on (SSO) is desired, you must deselect this option to force the application to use the external browser.

    • Enter one or more Scopes.

    Figure 21-11 Configuring the Client ID and Endpoints

    The surrounding text describes this image.
  4. On the Authorization page, configure the parameters as described in Section 21.4.14, "How to Configure Access Control."

21.4.6 How to Update Connection Attributes of a Named Connection at Runtime

Application developers can use the AdfmfJavaUtilities.updateSecurityConfigWithURLParameters API to define or to redefine the connection attributes of a connection that already exists in a fully populated connection definition.

Note:

The typical timing is to call the AdfmfJavaUtilities.updateSecurityConfigWithURLParameters API in a start() method implementation within an application lifecycle listener. You must not call this method from within the feature lifecycle listener.

To update connection attributes associated with the configUrlParam parameter, call the updatedSecurityConfigWithURLParameters method as follows:

import oracle.adfmf.framework.api.AdfmfJavaUtilities;
...
   AdfmfJavaUtilities.updateSecurityConfigWithURLParameters(configUrlParam,
              key, message, showConfirmation);

The key parameter is set as a String object from the value defined for the adfCredentialStoreKey parameter in the connections.xml file. The method may be invoked with the showConfirmation parameter set to true to allow MAF to display a confirmation prompt to the end user once MAF detects a connection configuration change to an existing attribute of the connection.

For more information on the AdfmfJavaUtilties class and the usage of the configUrlParam parameter, see the Java API Reference for Oracle Mobile Application Framework.

21.4.7 How to Store Login Credentials

When security is not critical, MAF supports storing user credentials, which can be replayed to the login server or used to authenticate users locally (depending on the mode defined for the login connection. Storing credentials enhances the user experience by enabling users to access the mobile application without having to login. The IDM Mobile SDKs enable MAF to support the following modes:

  • auto login—MAF caches the user credentials and then replays them to the authentication server during subsequent authentications. In this mode, users can start an application without MAF prompting them to enter or confirm their credentials. MAF can, however, inform users that it has started a new application session.

  • remember credentials—MAF caches the user credentials and populates the login page's username and password fields. After the user confirms these credentials by tapping the login button, MAF replays them to the authentication server.

  • remember username—MAF caches the user name and populates the login page's username field. After the user enters the password and confirms by tapping the login button, MAF replays these credentials to the authentication server.

Note:

Users can decide whether MAF stores their credentials.

As Figure 21-12 shows, you can use the Login Options page of the Mobile Login Server Connection wizard to select credential storing options. Selecting credential options populates the login page with options to remember the user name and password and should not be selected when a device is shared by multiple end users.

Figure 21-12 Caching User Credentials

This image is described in the surrounding text

21.4.8 What You May Need to Know About Multiple Identities for Local and Hybrid Login Connections

Like a remote connection, local and hybrid login connection modes allow a user to log in and log out using any number of identities within an application lifecycle. When you define a login connection to use these connectivity modes, you enable users to log back into a secured application feature using the local credential store if they have previously logged into a secured application feature within the current session timeout duration. In this case, users who have logged out explicitly, or have been logged out because the idle timeout has expired, can log back into a secured application feature (or any other application feature secured by the login server that protects that application feature).

Note:

Local and hybrid connections are only available for basic authentication and authentication to Oracle Access Management Mobile and Social (OAMMS). Because OAuth and Federate SSO use remote authentication, application users cannot log back into an application unless they authenticate successfully.

21.4.9 What Happens When You Enable Cookie Injection into REST Web Service Calls

If you selected the Include login server in REST call option in the Mobile Login Server Connection wizard, shown in Figure 21-14, you instructed MAF to retrieve this user session cookie sent by the login server and then inject it into the HTTP header of the REST web service call that originated from the mobile application.

Each time a mobile application requests a REST web service, MAF's security framework enables the transport layer of the REST web service to check if cookie injection is enabled for the login connection associated with the URL endpoint of the REST web service. That is, the connections.xml file must include <injectCookiesToRESTHttpHeader value="true"/>, as illustrated in Example 21-4.

If the connection allows cookie injection, and if the domains for the login server and the REST web service endpoint are identical, then the security framework retrieves the cookies stored when a user has logged into an application feature. MAF propagates all of the cookies stored for a domain in a REST web service request. MAF stores cookies per the Set-Cookie headers in the Rest web service response. The Set-Cookie headers may add cookies to the store, or replace existing cookies with new ones if they have the same name. The cookies returned by the REST web service response, as well as those returned by the authentication process, are injected into subsequent REST web service requests.

Note:

MAF constructs the cookie string by calling the Oracle Access Management Mobile and Social (OAMMS) API, which returns cookies by name from a platform-specific cookie store. The IDM Mobile SDK manages the cookies returned by authentication servers, the names of which are defined in the connections.xml file.

21.4.10 What You May Need to Know About Adding Cookies to REST Web Service Calls

After a user has been successfully authenticated by a mobile application, the login server creates the security context for the user and generates a cookie that tracks the user session. If you selected the Include login server in REST call option in the Mobile Login Server Connection wizard, shown in Figure 21-14, you instructed MAF to retrieve this user session cookie sent by the login server and then inject it into the HTTP header of the REST web service call that originated from the mobile application.

Propagating the cookie to the web service call enables the retrieval of the user's security context, which is stored on the login server, and enables the mobile application to use the REST web service to access the application data that is authorized for the user. After the user session cookie expires, MAF challenges the user for credentials and then re-authenticates the user. A user that has been re-authenticated can continue to access the authorized application data through the REST web service call.

21.4.11 What Happens at Runtime: When MAF Calls a REST Web Service

After a user is authenticated locally, MAF silently authenticates the user against the login server when the mobile application calls a REST web service. After the user's credentials are authenticated, MAF executes the application's request to the REST web service. If the REST web service returns a 401 status code (Unauthorized), MAF prompts the user to authenticate again. If the REST web service returns a 302 code (Found or temporarily moved), MAF checks the login server to confirm if the user is authenticated. If so, then the code is handled as a 302 redirect.

If the user has not been authenticated against the login server, then MAF prompts the user to authenticate again. In some cases, a login server may prompt users to authenticate using its own web page when it returns a 302 status code. MAF does not support redirection in these instances and instead prompts the user to login again using a MAF login page.

21.4.12 What You May Need to Know About Injecting Basic Authentication Headers

When servers do not honor cookies, MAF enables application features to access secure resources by injecting a basic authentication header into the HTTP requests made from their web views. By default, MAF uses basic authentication. Because the Include basic authentication header in HTTP requests option is selected by default, MAF enables application features to access secure resources by injecting a basic authentication header into the HTTP requests made from their web views.

Note:

To prevent MAF from injecting the basic authentication header, set the value attribute to false for the <injectBasicAuthHeader> element.

Defining an authentication realm for the user name and password populates the connections.xml file with a defined <realm> element. As illustrated in Example 21-1, MAF adds the header regardless of whether the connections.xml file includes these definitions or not.

Example 21-1 Using the connections.xml File to Inject the Basic Authentication Header

<?xml version = '1.0' encoding = 'UTF-8'?>
<References xmlns="http://xmlns.oracle.com/adf/jndi">
   <Reference name="connection1" 
              className="oracle.adf.model.connection.adfmf.LoginConnection" 
              adfCredentialStoreKey="connection1" 
              partial="false" manageInOracleEnterpriseManager="true"
              deployable="true" xmlns="">
      <Factory className=
                     "oracle.adf.model.connection.adfmf.LoginConnectionFactory"/>
      <RefAddresses>
         <XmlRefAddr addrType="adfmfLogin">
            <Contents>
               <login url="http://www.us.example.com/userInfo"/>
               <logout url="http://www.us.example.com/userInfo"/>
               <accessControl url="http://10.0.0.0/identity/authorize"/>
               <idleTimeout value="300"/>
               <sessionTimeout value="28800"/>
               <cookieNames/>
               <realm value="Secure Area"/>
               <injectBasicAuthHeader value="true"/>
               <userObjectFilter/>
            </Contents>
         </XmlRefAddr>
      </RefAddresses>
   </Reference>
</References>

21.4.13 What You May Need to Know about Web Service Security

There are no login pages for web services; user access is instead enabled by MAF injecting credentials into the header of the web service call. Web services gain access to application data using the locally stored credentials persisted by MAF after the user's first successful login to the authentication server. The name of the local credential store is reflected by the adfCredentialStoreKey attribute of the login server connection (such as adfCredentialStoreKey="Connection_1" in Example 21-4). To enable a web service to use this credential store, the name defined for the adfCredentialStoreKey attribute of a SOAP or REST web service connection must match the name defined for the login server's adfCredentialStoreKey attribute.

Note:

When edition connections.xml, you can use the XML Editor's Design tab to update the <Reference> element's adfcredentialStoreKey attribute with the name configured for adfCredentialStoreKey attribute of the login server connection. Alternatively, you can add or update the attribute using the Source editor.

For more information, see Section 8.5.2, "What You May Need to Know About Credential Injection."

21.4.14 How to Configure Access Control

As Figure 21-13 shows, you can use the Authorization page of the Mobile Login Server Connection wizard to configure access control. You will use this page when an application feature contains any component that is secured. For example, an expense report application that includes a submit button may be configured with a EL expression containing a securityContext object defined as disabled to allow only users who log in to this application with the manager privilege to view the submit button. Completing the fields in this Authorization page configures the Access Control Service, a RESTful web service that enables the retrieval of the specific user roles that are checked by an application feature.

Figure 21-13 Configuring Access Control

This image is described in the surrounding text

The access control granted by the application login server is based on the evaluation of the user.roles and user.privileges constraints configured for an application feature, as described in Section 14.2.4, "About User Constraints and Access Control." For example, to allow only a user with manager_role role to access an application feature, you must define the <adfmf:constraints> element in the maf-feature.xml file with the following:

<adfmf:constraint property="user.roles"
                  operator="contains"
                  value="manager_role"/>
</adfmf:constraints>

At the start of application, the RESTful web service known as the Access Control Service (ACS) is invoked for the application login server connection and the roles and privileges assigned to the user are then fetched. MAF then challenges the user to login against the application login server connection.

MAF evaluates the constraints configured for each application against the retrieved user roles and privileges and makes only the application features available to the user that satisfy all of the associated constraints.

To configure access control:

  1. In the Mobile Login Server Connection wizard, navigate to the Authorization page.

    For information about opening the Mobile Login Server Connection wizard, see Section 21.4.1, "How to Create a MAF Login Connection."

  2. On the Authorization page, complete the authorization requirements, as shown in Figure 21-13.

    • Access Control Service URL—Enter the URL that is the endpoint for the Access Control Service (ACS).

      Note:

      MAF injects all cookies issued by the authentication server (that is, the login server) into the HTTP request header when it invokes the ACS. Cookie injection occurs when you select Include login server in REST calls and enter identical domains for Access Control URL and the Login URL parameters. MAF verifies the domains of the ACS URL and login URL are identical before injecting a cookie. Otherwise, a cookie from login server will not be injected in the ACS request and thus authentication against ACS will fail. Ideally, the ACS URL should be protected so user authentication is required for secure access. See also Section 21.4.10, "What You May Need to Know About Adding Cookies to REST Web Service Calls."

    • Roles—Enter the user roles checked by the application feature. Because there may be thousands of user roles and privileges defined in a security system, use the manifest provided by the application feature developer that lists the roles specific to the application feature to create this list.

    • Privileges—Enter the privileges checked by the application feature.

21.4.15 What You May Need to Know About the Access Control Service

The Access Control Service (ACS) is a RESTful web service with JSON that enables users to download their user roles and privileges through a single HTTP POST message. This is a request message, one which returns the roles or privileges (or both) for a given user. It can also return specific roles and privileges by providing lists of required roles and privileges. The request message is comprised of the following:

  • Request header fields: If-Match, Accept-Language, User-Agent, Authorization, Content-Type, Content Length.

  • A request message body (a request for user information).

  • The requested JSON object that contains:

    • userId—The user ID.

    • filterMask—A combination of "role" and "privilege" elements are used to determine if either the filters for user roles, or for privileges, should be used.

    • roleFilter—A list of roles used to filter the user information.

    • privilegeFilter—A list of privileges used to filter the user information.

Note:

If all of the roles should be returned, then do not include the "role" element in the filterMask array.

If all of the privileges should be returned, then do not include the "privilege" element in the filterMask array.

Example 21-2 illustrates an HTTP POST message and identifies a JSON object as the payload, one that requests all of the filters and roles assigned to a user, John Smith.

Example 21-2 The ACS Request for User Roles and Privileges

Protocol: POST
Authoization: Basic xxxxxxxxxxxx
Content-Type: application/json
 
{
        "userId": "johnsmith",
        "filterMask": ["role", "privilege"],
        "roleFilter": [ "role1", "role2" ],
        "privilegeFilter": ["priv1", "priv2", "priv3"] 
}

The response is comprised of the following:

  • A response header with the following fields: Last-Modified, Content-Type, and Content-Length.

  • A response message body that includes the user information details.

  • The returned JSON object, which includes the following:

    • userId—the ID of the user.

    • roles—A list of user roles, which can be filtered by defining the roleFilter array in the request. Otherwise, the response returns an entire list of roles assigned to the user.

    • privileges—A list of the user's privileges, which can be filtered by defining the privilegeFilter array in the request. Otherwise, the response returns an entire list of privileges assigned to the user.

Example 21-3 illustrates the returned JSON object that contains the user name and the roles and privileges assigned to the user, John Smith.

Example 21-3 The Returned JSON Object

Content-Type: application/json
 
{
        "userId": "johnsmith",
        "roles": [ "role1" ],
        "privileges": ["priv1", "priv3"] 
}

Note:

There are no login pages for web services; user access is instead enabled by MAF, which automatically adds credentials to the header of the web service. For more information, see Section 8.5.2, "What You May Need to Know About Credential Injection."

Note:

You must implement and host the ACS service; MAF does not provide this service.

21.4.16 How to Alter the Application Loading Sequence

MAF invokes the Access Control Service (ACS) after a user successfully authenticates against a login connection that defines the ACS endpoint, such as http://10.0.0.0/Identity/Authorize in Figure 21-13. By changing this behavior to prevent the ACS from being called immediately after a successful login, you can insert a custom process between the login and the invocation of the ACS. This additional logic may be a security context called by MAF after a successful login that is based on the specifics of an application, or related to the user's responsibilities, organization, or security group.

You can change the sequence by updating the connections.xml file with <isAcsCalledAutomatically value = "false"/> and through the following method of the AdfmfJavaUtilities class, which enables MAF application features to call the ACS whenever it is required:

invokeACS(String key, String OptionalExtraPayLoad, boolean appLogin)

The invokeACS method enables you to inject extra payload into an ACS request. The key parameter is returned as a String object from the value defined for the adfCredentialStoreKey parameter in the connections.xml file, as illustrated in Example 21-1. The appLogin parameter may be set to true to cause ACS to reevaluate the feature access. The OptionalExtraPayLoad parameter is reserved for future use and is not used.

Invoking ACS through either the invokeACS method or the isAcsCalledAutomatically parameter retrieves the role-based constraints for an application.

Note:

MAF automatically invokes the ACS after a successful login if <isAcsCalledAutomatically value = "false"/> is not included in the connections.xml file.

When a secured application feature calls the invokeACS method, MAF fetches the user constraints for all of the application features associated with the application login connection, including those configured for the secured application feature. When an unsecured application feature calls this method, MAF only retrieves the constraints associated with the login connection.

Note:

In addition to the invokeACS method, the AdfmfJavaUtilities class includes the following lifecycle methods:

  • applicationLogout—Logs out the application login connection.

  • featureLogout(<feature_ID>)—Logs out the login connection associated with the application feature.

For more information, see the Java API Reference for Oracle Mobile Application Framework.

21.4.17 What Happens When You Define a Multi-Tenant Connection

After you complete the Mobile Login Server Connection wizard, MAF populates the connections.xml file with the <isMultiTenantAware> element set to true. In multi-tenant connection, the user name is the aggregation of tenant name and user name.

The login page uses a JavaScript utility to discern if a connection is multi-tenant aware. If the login page detects such a connection, it provides an additional field that requires the user to enter the tenant name configured in the Mobile Login Server Connection. After a successful login (which includes entering the correct tenant ID), MAF stores the tenant ID in the local credential store.

21.4.18 What Happens When You Create a Connection for a Mobile Application

MAF aggregates all of the connection information in the connections.xml file (located in the Project Explorer's Application Resources panel under the Descriptors and ADF META-INF nodes). This file, shown in Example 21-4, can be bundled with the application or can be hosted for the Configuration Service. In the latter case, MAF checks for the updated configuration information each time an application starts.

Example 21-4 MAF Connections Defined in the connections.xml File

<?xml version = '1.0' encoding = 'UTF-8'?>
<References xmlns="http://xmlns.oracle.com/adf/jndi">
  <Reference name="Connection_1"
             className="oracle.adf.model.connection.adfmf.LoginConnection"
             adfCredentialStoreKey="Connection_1"
             partial="false"
             manageInOracleEnterpriseManager="true"
             deployable="true"
             xmlns="">
      <Factory className="oracle.adf.model.connection.adfmf.LoginConnectionFactory"/>
      <RefAddresses>
         <XmlRefAddr addrType="adfmfLogin">
            <Contents>
               <login url="http://10.0.0.0/SecuredWebServicelogin/login.jsf"/>
               <logout url="http://10.0.0.0/SecuredWebServicelogout/logout.jsf"/>
               <accessControl url="http://10.0.0.0/Identity/Authorize"/>
               <isAcsCalledAutomatically value="false"/>
               <idleTimeout value="300"/>
               <sessionTimeout value="28800"/>
               <isMultiTenantAware value="true"/>
               <multiTenantHeaderName value="Oracle_Multi_Tenant"/>
               <injectCookiesToRESTHttpHeader value="true"/>
               <userObjectFilter>
                  <role name="manager"/>
                  <privilege name="account manager"/>
                  <privilege name="supervisor"/>
                  <privilege name=""/>
               </userObjectFilter>
               <rememberCredentials>
                    <enableRememberUserName value="true"/>
                    <rememberUserNameDefault value="true"/>
                    <enableRememberPassword value="true"/>
                    <rememberPasswordDefault value="true"/>
                    <enableStayLoggedIn value="true"/>
                    <stayLoggedInDefault value="true"/>
               </rememberCredentials>
            </Contents>
         </XmlRefAddr>
      </RefAddresses>
   </Reference>
</References>

For more information, see the "Lookup Defined in the connections.xml File" section in Oracle Fusion Middleware Developing Fusion Web Applications with Oracle Application Development Framework.

21.5 Configuring Security for Mobile Applications

You configure security using the MAF Feature Editor and MAF Application Editor, as well as the Mobile Login Server Connection wizard. The editors enable you to designate the type of login page (default or custom) that MAF presents to users when they select application features that require authentication or to include user role- or user privilege-based constraints. They also enable you to select which embedded application features require security.

21.5.1 How to Enable Application Features to Require Authentication

You can define each application feature to participate in security. You perform the remainder of the security configuration using the Security section of the MAF Application Editor. For application features whose content is served from a remote URL, the editor enables you to whitelist the domains so that remote URL content can display within the MAF web view. For more information, see Chapter 12, "Implementing Application Feature Content Using Remote URLs."

You can designate which application features participate in security and the type of authentication they require in the Feature section of the MAF Feature Editor, shown in Figure 21-14.

Figure 21-14 Designating User Credentials Options for an Application Feature

This image is described in the surrounding text

Before you begin:

When you enable security for a feature, the application requires access the network to authenticate the user. For more information about granting the application access to network sockets, see Section 21.6.1, "How to Enable Access to Device Capabilities."

To designate user access for an application feature:

  1. In the Project Explorer, in the user interface project, expand MAF, and then double-click MAF Feature Editor.

  2. In the MAF Feature Editor, select an application feature listed under Features or right-click Features and choose New to add an application feature.

  3. Select Enable security for any application feature that requires login.

    Tip:

    If you do not apply this option to the default application, you enable users to login anonymously (that is, without presenting login credentials). Users can then access unsecured data and features and, when required, login (authenticated users can access both secured and unsecured data). Providing unsecured application features within a mobile application enables users to logout of secured application features, but remain within the mobile application itself and continue to access both unsecured application features and data.

21.5.2 How to Designate the Login Page

After you designate security for the application features, you use the Security page of the MAF Application Editor, shown in Figure 21-15, to configure the login page as well as create a connection to the login server and assign it to each of the application features that participate in security. All of the application features listed in this page have been designated in the MAF Feature Editor as requiring security. Typically, a group of application features are secured with the same login server connection, enabling users to open any of these applications without MAF prompting them to login again. In some cases, however, the credentials required for the application features can vary, with one set of application features secured by one login server and another set secured by a second login server. To accommodate such situations, you can define any number of connections to a login server for a mobile application. In terms of the maf-application.xml file, the authentication server connections associated with the feature references are designated using the loginConnRefId attribute as follows:

<adfmf:featureReference id="feature1" loginConnRefId="Connection_1"/>
<adfmf:featureReference id="feature2" loginConnRefId="Connection2"/>

Mobile applications can be authenticated against any standard login server that supports basic authentication over HTTP or HTTPS. MAF also supports authentication against Oracle Identity Management. You can also opt for a custom login page for a specific application feature. For more information, see Section 21.5.3, "What You May Need to Know About Login Pages."

Note:

By default, all secured application features share the same connection, which, as shown in Figure 21-15, is denoted as <application login server>. The Property Inspector for a Feature Reference notes this default option in its Login Server Connection dropdown menu as <default> application login server. You can select other connections that are defined for the mobile application using the Mobile Login Server Connection wizard.

Figure 21-15 Registered Features in the MAF Application Editor

This image is described in the surrounding text

Before you begin:

If the mobile application uses a custom login page, add the file to the public_html directory of the application controller project (users\workspaces\Application\ApplicationController\public_html) to make it available from the Web Content node in the Project Explorer, as shown in Figure 21-16. See also Section 21.5.3.3, "Creating a Custom Login HTML Page" and Section 4.11.2, "What You May Need to Know About Selecting External Resources."

Add constraints for user privileges and roles, as described in Section 14.2.4, "About User Constraints and Access Control."

Provision an Access Control Service (ACS) server. For more information, Section 21.4.15, "What You May Need to Know About the Access Control Service."

Figure 21-16 Adding a Custom Login Page

This image is described in the surrounding text

To designate the login page and Knowledge Based Authentication page:

  1. In the Project Explorer, expand the assembly project, then expand MAF, and double-click MAF Application Editor.

  2. In the outline, click Security.

  3. On the Security page, designate the type of login page:

    • Choose Login Page for a view that accepts a user name and password.

    • Choose Knowledge Based Authentication Page for a knowledge-based view that presents users with challenges to their credentials and also accepts their answers. Knowledge based authentication can be configured on OAAM server and user can be prompted with another page that asks additional questions such as ”mother's maiden name”. This feature is available for the Mobile-Social authentication type only.

  4. Select the content (or user interface) for the selected login page and, optionally, a Knowledge Based Authentication page:

    • Default—The default login page or Knowledge Based Authentication screen used for all of the selected embedded application features. For more information, see Section 21.5.3.1, "The Default Login Page." The default login page and default Knowledge Based Authentication page is provided by MAF.

    • Custom—Click Browse to retrieve the path location of the file within the application controller project. Alternatively, click New to create a custom HTML page within the application controller project for either the login page or the Knowledge Based Authentication page. For more information, see Section 21.5.3.2, "The Custom Login Page" and Section 21.5.3.3, "Creating a Custom Login HTML Page."

      Tip:

      Rather than retrieve the location of the login page using the Browse function, you can drag the login page from the Project Explorer into the field.

21.5.3 What You May Need to Know About Login Pages

The entry point for the authentication process to an application feature is the activate lifecycle event, described at Section 4.8.2, "Timing for Mobile Application Events." Every time an application feature is activated (that is, the activate event handler for the application feature is called), the application feature login process is executed. This process navigates to the login page (which is either the default or a custom login page) where it determines if user authentication is needed. Before the process navigates to the login page, however, the originally intended application feature must be registered with MAF. When authentication succeeds, the login page retrieves the originally intended destination from MAF and navigates to it.

21.5.3.1 The Default Login Page

The default login page provided by MAF (shown in Figure 21-1, "The Login Page") is comprised of a login button, input text fields for the user name, password, and multi-tenant name, and an error message section. This is a cross-platform page, one written in HTML.

21.5.3.2 The Custom Login Page

When you add a custom login page for a selected application feature using MAF Feature Editor, Oracle Enterprise Pack for Eclipse adds the <adfmf:login> element and populates its child <adfmf:LocalHTML> element, as shown in Example 21-5. As with all <adfmf:LocalHTML> elements, its url attribute references a location within the public_html directory. The user authentication mechanism and navigation control are identical to the default login page.

Example 21-5 The Login Element

<adfmf:login defaultConnRefId="Connection_1">
    <adfmf:localHTML url="newlogin.html"/>
</adfmf:login>

Custom login pages are written in HTML. The fields for both the default login page and the knowledge-based pages must include specifically defined <input> and <label> elements.

Tip:

Use the default the login pages that are generated when you deploy a MAF application as a guide for creating custom login pages. To access the login pages within the www directory, deploy a mobile application and then traverse to the deploy directory.For iOS deployments, the pages are located at the following: application workspace directory/deploy/deployment profile name/temporary_xcode_project/www/adf.login.html and application workspace directory/deploy/deployment profile name/temporary_xcode_project/www/adf.kba.html.

For Android deployments, the pages are located within the Android application package (.apk) file at the following: application workspace directory/application name/deploy/deployment profile name/deployment profile name.apk/assets/www/adf.login.html and application workspace directory/application name/deploy/deployment profile name/deployment profile name.apk/assets/www/adf.kba.html.

Example 21-6 illustrates the required <input> and <label> elements for a default login page.

Example 21-6 Required Elements for the Default Login Page

<input type="text"
       autocorrect="off"
       autocapitalize="none"
       name="oracle_access_user_id"
       id="oracle_access_user_id" value="">
   </input>
 
<input type="text"
       autocorrect="off"'
       autocapitalize="none"
       name="oracle_access_iddomain_id"
       id="oracle_access_iddomain_id" value="">
   </input>
 
<input type="password"
       name="oracle_access_pwd_id"
       id="oracle_access_pwd_id" value="">
   </input>
 
<input type="checkbox"
       class="message-text"
       name="oracle_access_auto_login_id"
       id="oracle_access_auto_login_id">
   </input>Keep me logged in
 
<input type="checkbox"
       class="message-text" 
       name="oracle_access_remember_username_id"
       id="oracle_access_remember_username_id">
   </input>Remember my username
 
<input type="checkbox"
       class="message-text"
       name="oracle_access_remember_credentials_id"
       id="oracle_access_remember_credentials_id">
   </input>Remember my password
 
<label id="oracle_access_error_id"
       class="error-text">
   </label>
 
<input class="commandButton"
       type="button"
       onclick="oracle_access_sendParams(this.id)"
       value="Login" id="oracle_access_submit_id"/>

Example 21-7 illustrates the required elements for a Knowledge Based Authentication login page.

Example 21-7 Required Elements for a Knowledge Based Authentication Login Page

<input type="text"

<label id="oracle_access_kba_ques_id" >Question</label><br>
 
<input class="field-value"
       name="oracle_access_kba_ans_id"
       id="oracle_access_kba_ans_id">
   </input>
 
<label id="oracle_access_error_id"
       class="error-text">
   </label>
 
<label id="message_id"
      class="message-text">
   </label>
 
<input type="button"
       onclick="oracle_access_sendParams(this.id)"
       value="Login"
       id="oracle_access_submit_id"/>

21.5.3.3 Creating a Custom Login HTML Page

You can create the custom login page using the default login page, adf.login.html or adf.kba.html, artifacts generated by the MAF deployment in the www directory.

Before you begin:

To access the login pages within the www directory, deploy a mobile application and then traverse to the deploy directory. For iOS deployments, the pages are located at the following:

application workspace directory/deploy/deployment profile name/temporary_xcode_project/www/adf.login.html

and

application workspace directory/deploy/deployment profile name/temporary_xcode_project/www/adf.kba.html

For Android deployments, the pages are located within the Android application package (.apk) file at the following:

application workspace directory/application name/deploy/deployment profile name/deployment profiile name.apk/assets/www/adf.login.html

and

application workspace directory/application name/deploy/deployment profile name/deployment profiile name.apk/assets/www/adf.kba.html

To create a custom login page:

  1. Copy the default login page to a location within the user interface project's public_html directory, such as users\workspace\application name\ApplicationController\public_html.

  2. Rename the login page.

  3. Update the page.

  4. In the Security section of the MAF Application Editor, select Custom and then click Browse to retrieve the location of the login page. For more information, see Section 4.6, "Configuring the Springboard and Navigation Bar Behavior."

21.5.4 What You May Need to Know About Login Page Elements

Every HTML login page should include the user interface elements listed in Table 21-2.

Table 21-2 Login Page Fields and Their Associated IDs

Page Element ID

username field

oracle_access_user_id

password field

oracle_access_pwd_id

login button

oracle_access_submit_id

cancel button

oracle_access_cancel_id

identity domain/tenant name field

oracle_access_iddomain_id

Knowledge Based Authentication question field (read-only/label)

oracle_access_kba_ques_id

Knowledge Based Authentication answer field

oracle_access_ans_id

error field

oracle_access_error_id

auto login check box

oracle_access_auto_login_id

remember credentials check box

oracle_access_remember_credentials_id

remember username check box

oracle_access_remember_username_id


Table 21-3 lists the recommended JavaScript code used by the OnClick event.

Table 21-3 JavaScript Used by the OnClick Event

Button JavaScript

login button

oracle_access_sendParams(this.id)

cancel button

oracle_access_sendParams(this.id)

Knowledge Based Authentication submit button

oracle_access_sendParams(this.id)

Knowledge Based Authentication cancel button

oracle_access_sendParams(this.id)


21.5.5 What Happens in Oracle Enterprise Pack for Eclipse When You Configure Security for Application Features

After an application feature has been designated to participate in security, Oracle Enterprise Pack for Eclipse updates the Registered Features with a corresponding feature reference, as shown in Figure 21-15. If each of the referenced application features authenticate against the same login server connection defined in the connections.xml file, Oracle Enterprise Pack for Eclipse updates the maf-application.xml file with a single <adfmf:login> element defined with a defaultConnRefId attribute (such as <adfmf:login defaultConnRefId="Connection_1">).

For application features configured to use different login server connections defined in the connections.xml file Oracle Enterprise Pack for Eclipse updates each referenced application feature with a loginConnReference attribute (<adfmf:featureReference id="feature2" loginConnRefId="Connection2"/>). For more information, see Section 21.5.1, "How to Enable Application Features to Require Authentication." See also the Tag Reference for Oracle Mobile Application Framework.

21.6 Allowing Access to Device Capabilities

Access to all of the Apache Cordova-enabled device capabilities is not enabled by default for mobile applications. Instead, MAF ensures security by allowing access to specific capabilities. When you assess the security and privacy requirements for a mobile application, you can select which type of access the application should have. By default, the following functions are not enabled for a mobile application:

  • Network—Allows the application to open network sockets. This capability must be granted to the application when security is enabled for at least one device capability.

  • Location—Covers both fine (GPS) and course (network-based) location services.

  • Camera—Allows the application to use the device's camera.

  • Contacts—Allows the application to access the contacts on the device.

  • E-mails—Allows the application to access and send e-mails.

  • SMS—Allows the application to access and send SMS messages.

  • Phone—Allows the application to access voice services and make phone calls.

  • Push Notifications—Allows the application to receive push notifications. See also Section 17.2, "Enabling Push Notifications for a Mobile Application."

  • Files—Allows the application to access files on device SD Card.

Because you can grant, or restrict, device services, the various platform-specific configuration files and manifest files that are updated by the deployment framework list only the services in use (or rather, the devices services that the mobile application is permitted to use). These files enable MAF to share information about the use of these services with other applications. For example, a mobile application can report to the AppStore or to Google Play that it does not use location-based services (even though mobile applications have this capability).

21.6.1 How to Enable Access to Device Capabilities

Device access for mobile applications is configured at both the application and application-feature level, with the configuration set at the application level taking precedence; an application feature's configuration describes its device requirements, while the permission to use these capabilities is granted through the application configuration.

The MAF Feature Editor and MAF Application Editor enable you designate and manage the device capabilities by creating the <adfmf:deviceFeatureAccess> element. Although both configuration files share this element and its device-specific child elements, the elements in the maf-feature.xml file are defined using requestAccess attribute and those in the maf-application.xml file are defined with the allowAccess attribute.

To specify the required device capabilities for an application feature:

  1. In the Project Explorer, expand the view project, then expand MAF and double-click MAF Feature Editor.

  2. In the MAF Feature Editor, expand the node for the feature and choose Device Access and enable the device capabilities required by the application, as shown in Figure 21-17.

    When you select a feature, you will see a yellow notification icon. If you hover your mouse over the icon you will see a message similar to "Property 'Device Access' of the object 'Email Access'. Access to 'Email Access' is not granted by the application."

    The icon disappears after you grant permission in the MAF Application Editor.

    Figure 21-17 Designating Device Access Requirements

    This image is described in the surrounding text

Note that when you enable security for at least one device feature, as described in Section 21.5.1, "How to Enable Application Features to Require Authentication," you must also enable access to the network. In this case, you can grant permission to the Network capability in the MAF Application Editor, as described below.

To grant permission to a device capability:

  1. In the Project Explorer, expand the assembly project, then expand MAF and double-click MAF Application Editor.

  2. In the MAF Application Editor, click Device Access in the outline and grant permission to the device capabilities required by the application, as shown in Figure 21-18.

    Devices that have one or more feature requiring them are indicated by yellow notification icons. Hover the mouse over the icon to see which feature is requesting the device. The blue icon, which appears once you select a device, allows you to check which feature is using the device by hovering the mouse over icon.

    Figure 21-18 Granting Device Access

    This image is described in the surrounding text

21.6.2 What Happens When You Define Device Capabilities

MAF populates the <adfmf:feature> element with <adfmf:deviceFeatureAccess>, as illustrated in Example 21-8.

Example 21-8 Defining Device Capabilities in the maf-feature.xml File

<adfmf:feature id="feature3" name="feature3">
    <adfmf:content id="feature3.1">
      <adfmf:amx file="feature3/datapage.amx"/>
    </adfmf:content>
    <adfmf:deviceFeatureAccess>
      <adfmf:deviceEmails id="de1" requestAccess="true"/>
    </adfmf:deviceFeatureAccess>
</adfmf:feature>

In the maf-application.xml file, MAF populates the <adfmf:deviceFeatureAccess> element, as illustrated in Example 21-9.

Example 21-9 Adding Device Capability Permissions in the maf-application.xml File

<adfmf:deviceFeatureAccess>
    <adfmf:deviceCamera id="dc1" access="true"/>
    <adfmf:deviceContacts id="dc2" access="true"/>
    <adfmf:deviceEmails id="de1" access="true"/>
    <adfmf:deviceFiles id="df1" access="true"/>
    <adfmf:deviceLocation id="dl1"/>
    <adfmf:deviceNetwork id="dn1"/>
    <adfmf:devicePhone id="dp1"/>
    <adfmf:deviceSMS id="dsms1" access="true"/>
</adfmf:deviceFeatureAccess>

For more information, see the Tag Reference for Oracle Mobile Application Framework.

21.6.3 What You May Need to Know About Device Capability Permissions

If you create a component from a DeviceFeatures data control method that has no related device access permission configured in the maf-application.xml file, then MAF prompts you with a dialog for the method, illustrated in Figure 21-19. The dialog's default option updates the maf-application.xml file with the permission, or enables you to do so manually by opening the file through the Edit device access permissions option.

Figure 21-19 Granting Device Access

This image is described in the surrounding text

Within a MAF AMX page, MAF issues an error in the following format (and illustrated by the alert in Figure 21-20) if device-related methodAction bindings exist, but the applicable device access permissions have been removed (or not defined). Unless the appropriate device access is granted in the maf:application.xml file, the method will not function and cause a runtime error.

Application is not allowed to access device <deviceFeatureName>. Enable Device <deviceFeatureName> access in maf-application.xml for <bindingId> to work

Figure 21-20 The Device Access Permission Warning in a MAF AMX Page

This image is described in the surrounding text

21.6.4 What You May Need to Know About Device Capabilities During Deployment

During each deployment, MAF updates the iOS cordova.plist file as well as the Android config.xml, AndroidManifest.xml and AndroidManifest.template.xml files with the device capabilities permitted by the mobile application. Specifically, the MAF deployment process omits the default Cordova plugin information from these files and maps the child elements defined in the maf-application.xml file's <adfmf:deviceFeatureAccess> element to the permissions defined in the iOS and Android files. Table 21-4 provides an example of the <adfmf:deviceSMS> element maps to elements in the platform specific files. MAF regenerates these files with each deployment.

Table 21-4 Mapping <adfmf:deviceSMS> to Platform-Specific Files

Map to <key> in the cordova.plist File Map to <plugin name> in the config.xml File Map to Permission in the AndroidManifest.xml File
<key>Plugins</key>
<dict>
   <key>AdfmfSMS</key>
   <string>AdfmfSMSAdaptor</string>
</dict>

<plugin name="AdfmfSMS" value="oracle.adfmf.phonegap.AdfmfSMS"/>

<uses-permission android:name="android.permission.RECEIVE_SMS" />


Certain plugins share permissions in the AndroidManifest.xml file, as described in Table 21-5. The deployment process adds these permissions to the file if they did not already exist, or the if permission is required by a device feature that is enabled out-of-the-box.

Table 21-5 Shared Permissions

Device Access Permission
  • Network

  • Push Notifications

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

  • Contacts

  • Push Notifications

<uses-permission android:name="android.permission.GET_ACCOUNTS" />

  • Camera

  • Files

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />


Note:

MAF extracts the AndroidManifest.template.xml file during first deployment of a given deployment profile. This file provides the initial content for the AndroidManifest.xml file.

Similar to the mapping of the <adfmf:deviceSMS> element described in Table 21-4, MAF maps the following elements to the iOS and Android configuration files during deployment:

<adfmf:deviceCamera>

Table 21-6 describes how MAF maps <adfmf:deviceCamera allowAccess="true" /> to platform-specific files.

Table 21-6 Mapping <adfmf:deviceCamera> to Platform-Specific Files

Map to <key> in the cordova.plist File Map to <plugin name> in the config.xml File Map to Permission in the AndroidManifest.xml File
<key>Plugins</key>
<dict>
    <key>Camera</key>
    <string>CDVCamera</string>
    <key>Capture</key>
    <string>CDVCapture</string>
</dict>
<plugin name="Camera" value="org.apache.cordova.CameraLauncher"/>
<plugin name="Capture" value="org.apache.cordova.Capture"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

<adfmf:deviceContacts>

Table 21-7 describes how MAF maps <adfmf:deviceContacts allowAccess="true"/> to platform-specific files.

Table 21-7 Mapping <adfmf:deviceContacts> to Platform-Specific Files

Map to <key> in the cordova.plist File Map to <plugin name> in the config.xml File Map to Permission in the AndroidManifest.xml File
<key>Plugins</key>
<dict>
    <key>Contacts</key>
    <string>CDVContacts</string>
</dict>
<uses-permission android:name="android.permission.READ_CONTACTS"/>
<uses-permission android:name="android.permission.WRITE_CONTACTS"/>
<uses-permission android:name="android.permission.GET_ACCOUNTS"/>
<uses-permission android:name="android.permission.READ_CONTACTS"/>
<uses-permission android:name="android.permission.WRITE_CONTACTS"/>
<uses-permission android:name="android.permission.GET_ACCOUNTS"/>

<adfmf:deviceEmails>

Table 21-8 describes how MAF maps <adfmf:deviceEmails allowAccess="true"/> to platform-specific files.

Table 21-8 Mapping <adfmf:deviceEmails> to Platform-Specific Files

Map to <key> in the cordova.plist File Map to <plugin name> in the config.xml File Map to Permission in the AndroidManifest.xml File
<key>Plugins</key>
<dict>
    <key>AdfmfEmail</key>
<plugin name="AdfmfEmail" value="oracle.adfmf.phonegap.AdfmfEmail"/>

Not applicable because there is no e-mail entry in the AndroidManifest.xml file.


<adfmf:deviceNetwork>

Table 21-9 describes how MAF maps <adfmf:deviceNetwork allowAccess="true"/> to platform-specific files.

Table 21-9 Mapping <adfmf:deviceNetwork> to Platform-Specific Files

Map to <key> in the cordova.plist File Map to <plugin name> in the config.xml File Map to Permission in the AndroidManifest.xml File
<key>Plugins</key>
<dict>
  <key>NetworkStatus</key>
  <string>CDVConnection</string>
</dict>
<plugin name="NetworkStatus" value="org.apache.cordova.NetworkManager"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

<adfmf:deviceFiles>

Table 21-10 describes how MAF maps <adfmf:deviceFiles allowAccess="true"/> to platform-specific files.

Table 21-10 Mapping <adfmf:deviceFiles> to Platform-Specific Files

Map to <key> in the cordova.plist File Map to <plugin name> in the config.xml File Map to Permission in the AndroidManifest.xml File
<key>Plugins</key>
<dict>
    <key>File</key>
    <string>CDVFile</string>
</dict>
 
<key>Plugins</key>
<dict>
    <key>FileTransfer</key>
    <string>CDVFileTransfer</string>
</dict>
<plugin name="File" value="org.apache.cordova.FileUtils"/>
<plugin name="FileTransfer" value="org.apache.cordova.FileTransfer"/>
<plugin name="Storage" value="org.apache.cordova.Storage"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

<adfmf:deviceLocation>

Table 21-11 describes how MAF maps <adfmf:deviceLocation allowAccess="true"/> to platform-specific files.

Table 21-11 Mapping <adfmf:deviceLocation> to Platform-Specific Files

Map to <key> in the cordova.plist File Map to <plugin name> in the config.xml File Map to Permission in the AndroidManifest.xml File
<dict>
  <key>Plugins</key>
  <dict>
    <key>Geolocation</key>
    <string>CDVLocation</string>
    <key>Compass</key>
    <string>CDVLocation</string>
  </dict>
</dict>
<plugin name="Geolocation" value="org.apache.cordova.GeoBroker"/>
<plugin name="Compass" value="org.apache.cordova.CompassListener"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS"/>

<adfmf:devicePushNotifications>

Table 21-12 describes how MAF maps <adfmf:deviceSMS allowAccess="true"/> to platform-specific files.

Table 21-12 Mapping <adfmf:devicePushNotifications> to Platform-Specific Files

Map to <key> in the cordova.plist File Map to <plugin name> in the config.xml File Map to Permission in the AndroidManifest.xml File
<key>Plugins</key>
<dict>
    <key>PushPlugin</key>
    <string>PushPlugin</string>
</dict>
<plugin name="PushPlugin" value="com.plugin.gcm.PushPlugin"/>

Not applicable.


21.7 Enabling Users to Log Out from Application Features

MAF does not terminate application features when a user logs out of one that contains secured content or is restricted through constraints; a user can remain within the application and access its unsecured content and features as an anonymous user. Because MAF enables constraints to be re-initialized, it allows a user to login to an application repeatedly using the same identity. It also enables multiple identities to share the access to the application by allowing the user to login using different identities.

The logoutFeature and logout methods of the AdfmfJavaUtilities class, described in the Java API Reference for Oracle Mobile Application Framework, enable users to explicitly login and logout from the authentication server after launching an application. In addition, they enable a user to login to the authentication server after the user invokes a secured application feature. Although a user can log out from individual application features, a user will be simultaneously logged out of application features secured by the same connection.

These methods enables users to perform the following the following:

  • Logging out of an application feature but continuing to access its unsecured content (that is, MAF does not terminate the application).

  • Authenticating with the login server while in an application to enable its secured content and UI components.

  • Logging out of a mobile application or application feature and then logging in again using a different identity.

  • Logging out of a mobile application or application feature and then logging in again using the same identity but with updated roles and privileges.

To enable logging out of the current authentication server, call the logout method of the AdfmfJavaUtilities class as follows. For example:

import oracle.adfmf.framework.api.AdfmfJavaUtilities;
...
   AdfmfJavaUtilities.logout();

To enable logging from the authentication server associated with the key parameter, call the logoutFeature method as follows:

import oracle.adfmf.framework.api.AdfmfJavaUtilities;
...
   AdfmfJavaUtilities.logoutFeature(adfCrendentialStorykey);

The adfCredentialStorykey parameter is returned as a String object from the value defined for the adfCredentialStoreKey parameter in the connections.xml file. For more information on the AdfmfJavaUtilties class and the usage of the key parameter, see the Java API Reference for Oracle Mobile Application Framework.

21.8 Supporting SSL

MAF provides a cacerts certificate file, the Java mechanism for HTTPS handshakes between the client application and the server. As described in Section 3.2.2, "What Happens When You Create an MAF Application," Oracle Enterprise Pack for Eclipse creates this file within the Application Resources Security folder (located at users\workspaces\application name\resources\Security\cacerts ). The MAF cacerts file identifies a set of certificates from well-known and trusted sources to JVM 1.4 and enables deployment. For an application that requires custom certificates (such as in cases where RSA cryptography is not used), you must add private certificates before deploying the application.

Before you begin:

Refer to Java SE Technical Documentation (http://download.oracle.com/javase/index.html) for information on the cacerts file and how to use the keytool utility.

To add private certificates:

  1. Create a private certificate. For example, create a certificate file called new_cert.

  2. Add the private certificate to the application as follows:

    1. Create a copy of the seeded cacerts file (cp cacerts cacerts.org).

    2. Use the Java SE keytool utility to add certificates to a cacerts file. Example 21-10 illustrates adding certificates to a cacerts file called new_cert.

      Example 21-10 Adding a Certificate Using the keytool Utility

      keytool -importcert              
              -keystore cacerts 
              -file new_cert
              -storepass changeit
              -noprompt
      

      Example 21-10 illustrates how to add a single certificate. Repeat this procedure for each certificate. Table 21-13 lists the keytool options

      Table 21-13 Options For Adding Certificates

      Option Description

      -importcert

      Imports a certificate.

      -keystore cacerts file

      Identifies the file location of the imported certificate.

      -file certificate file

      Identifies the file containing the new certificate.

      -storepass changeit

      Provides a password for the cacerts file. By default, the password is changeit.

      -noprompt

      Instructs the keytool not to ask the user (through stdin) whether to trust the certificate or not.


    3. Visually inspect the contents of the new cacerts file to ensure that all of the fields are correct. Use the following command:

      keytool -list -v -keystore cacerts | more
      
    4. Verify that the certificate is for the given hostname.

      Note:

      The certificate's common name (CN) must match the hostname exactly.

    5. Ensure that the customized certificate file is located within the Security directory (users\workspaces\assembly project\lib\Security) so that it can be read by JVM 1.4.

  3. Deploy the application.

    Note:

    During deployment, if a certificate file exists within the Security directory, MAF copies it into the Android or Xcode template project, replacing any default copies of the cacerts file.

  4. Validate that you can access the protected resources over SSL.