17 ADF Mobile Application Security

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

This chapter includes the following sections:

17.1 Introduction to Security for an ADF Mobile Application

The ADF Mobile runtime authenticates end users when a secured application feature has been activated, such as when it is about to be displayed within the web view or when the operating system returns the application feature to the foreground. In these instances, ADF Mobile determines whether access to the application feature requires user authentication and then challenges the user with a login page. Only when the user successfully enters valid credentials does ADF Mobile render the intended web view, UI component, or application page.

ADF Mobile uses JavaScript, a PhoneGap plugin, and native PhoneGap command handlers that collectively handle the interaction with the login page, the navigation between application features, and interactions with the Oracle Identity Connect's IDM Mobile SDK, whose classes and protocols verify user credentials. The native PhoneGap command handler methods are executed through the PhoneGap plugins. The methods' results are sent back to corresponding JavaScript callback functions that navigate to either the requested application feature or to the web view that initiated the authentication process.

Note:

The entire login process is executed within ADF Mobile. Embedded Java is not required.

An ADF Mobile application uses either the default page or a customized login page that is written in HTML.

17.2 Introduction to the User Login Process

Login is required when a credential attribute for the application feature definition (in the adfmf-feature.xml file) is designated as either remote or local and the user has not been authenticated within the timeout period. From the end-user perspective, the login process is as follows:

  1. ADF Mobile presents a web view of a login page, shown in Figure 17-1. The login page illustrates the name of the application feature that requires authentication, feature1.

    Figure 17-1 The Login Page

    The login page (as webview).

    Note:

    As described in Section 17.4.10, "What Happens When You Designate a Custom Login Page," ADF Mobile provides not only a login page, but also supports a custom login page.

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

    Note:

    ADF Mobile does not allow multiple users for the same application without restarting that application. If a user attempts to login to an application after a previous user was logged out because of a timeout, ADF Mobile prompts the user to enter the initial user's name and password or to restart the application. A user can restart an application by logging off, because logging off typically terminates an application automatically. You must enable end users to terminate the application by logging off from the login screen.

    For information on calling methods of the AdfmfJavaUtilities class to enable users to log off of an application without it terminating, see Section 17.4.11, "What You May Need to Know About Login Pages."

  3. If the user name and password are verified, ADF Mobile displays the intended web view, page, or UI component.

  4. ADF Mobile 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.

Note:

Authentication times out when a predefined time period has passed since the last activation of an application feature. ADF Mobile 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.

17.3 Introduction to Authentication

ADF Mobile authenticates against an authentication server, such as Oracle Access Management (OAM) Identity Server.

Note:

ADF Mobile can authenticate against any basic authentication server.

When ADF Mobile handles the authentication against a remote server, the flow of security is as follows:

  1. ADF Mobile presents the user with the default login page, similar to the one shown in Figure 17-1, or with a custom login page. The login page displays for applications that have been deployed because of the security-related parameters configured in the adfmf-application.xml and adfmf-feature.xml files. For more information, see Section 17.4, "Configuring Security for ADF Mobile Applications."

  2. The Oracle Identity Connect IDM Mobile SDK APIs handle the authentication for both remote authentication servers and for authentication against the credential store on the device (which may or may not store a saved user object). Depending on the success or failure of the authentication, the APIs return either a failure or a valid user object to ADF Mobile.

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

    Note:

    When at least one secured application feature includes the user.roles or user.privileges constraints, an end user must authenticate against an application login server when the application starts. Otherwise, the default application feature displays. If a default application feature participates in security, then the end user is prompted for authentication against the login connection associated with the application feature. Instead of authenticating, an end user can also navigate to another application feature. For more information, see Section 14.2.3.1, "User Constraints."

  4. Oracle Identity Connect IDM Mobile SDK APIs save the credentials in the device's credential store.

  5. If the login fails, the login page remains, thereby preventing users from continuing.

17.4 Configuring Security for ADF Mobile Applications

Security is configured both at the application feature and mobile application levels using the overview editors for the adfmf-feature.xml and adfmf-application.xml files. At the application feature level, you designate a security requirement for any application feature that requires authentication against a remote login server, or against a credential store on the device that houses the user's login credentials for a remote login server. In the former case, a mobile application may require user authentication against Oracle Access Manager used by Oracle ADF Fusion web applications. After the user is authenticated against the authentication server within the same application session (that is, within the lifecycle of the application execution), the authentication context is stored locally and subsequent authentication is executed against this local authentication context. A subsequent authentication does not attempt to contact the authentication server if the local authentication context is sufficient to authenticate the user. Although a connection to the remote login server is required for the initial authentication, continual access to the server is not required for local authentication. In addition, authentication against a local credential store can be faster than authentication against a remote login server.

Designating security for an application feature results in JDeveloper populating a credential attribute to the application feature's <adfmf:feature> element. When you embed such an application feature in a mobile application, you then configure login and logout server connection information and designate whether users are presented with the default login page provided by ADF Mobile or with a customized page. These requirements are noted by the attributes for the <adfmf:login> element.

Login is required when the credential attribute for the application feature definition (in the adfmf-feature.xml file) is either designated as remote or local (as described in Section 17.4.1, "How to Enable Application Features to Require Authentication") and when the user has not been authenticated within a timeout period set in the Create ADF Mobile Login Connection dialog, shown in Figure 17-7. See also Section 17.1, "Introduction to Security for an ADF Mobile Application."

Note:

You must define at least one connection to the application login server for an application feature that participates in security remotely through a login server or locally using a stored set of credentials. 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.

17.4.1 How to Enable Application Features to Require Authentication

Configuring security for an ADF Mobile application begins at the application feature level, where you designate which application features require users to authenticate against a login server or to a local credential store. You must define each application feature to participate in security.

The Credentials tab of the adfmf-feature.xml overview editor, shown in Figure 17-2, enables you to designate which application features participate in security and the type of authentication they require.

Figure 17-2 Designating User Credentials Options for an Application Feature

Designating user credentials requirement.

To designate user access for an application feature:

  1. Select an application feature or click Add to add an application feature.

  2. Click Enable Feature Security for any application feature that requires login and then select one of the following authentication options:

    • local—Select if the application will allow users to authenticate against locally stored credentials on the device. After the user's first successful authentication to a remote server, ADF Mobile persists the credentials locally within a credential store in the device. These credentials are used for subsequent access to the application feature. See also Section 17.4.9, "What You May Need to Know about Web Service Security."

    • remote—Select if the application requires authentication with 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.

In addition to the overview editor shown in Figure 17-2, you can configure the security options in the Property Inspector, shown in Figure 17-3.

Figure 17-3 Designating User Credential Options in the Property Inspector

Security options in the Property Inspector.

In addition to the local and remote options available in the overview editor, the Property Inspector also provides the none and <default> (none) options for application features that do not participate in security. Selecting none clears the Enable Feature Security option in the overview editor and updates <adfmf:feature> with credentials="none". Selecting <default> (none) also clears Enable Feature Security and removes the credentials attribute from <admf:feature>, which has no credentials attribute by default.

17.4.2 How to Designate the Login Page

After you designate security for the application features, you use the Security page of the adfmf-application.xml overview editor, shown in Figure 17-4, to configure the login page as well as create and assign a connection to the login server for each of the application features that participate in security. All of the application features listed in this page have been designated in the adfmf-feature.xml file 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 ADF Mobile prompting them for subsequent logins. 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 an ADF Mobile application. In terms of the adfmf-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"/>

ADF Mobile applications can be authenticated against any standard login server that supports basic authentication over HTTP or HTTPS. ADF Mobile also supports authentication against Oracle Identity Management. You can also opt for a custom login page for a specific application feature.

Figure 17-4 The Security Page

Designate the login page for features.

Before you begin:

If the ADF Mobile application uses a custom login page, add the file to the public_html directory of the application controller project (JDeveloper\mywork\Application\ApplicationController\public_html) to make it available from the Web Content node in the Application Navigator, as shown in Figure 17-5. See also Section 5.9.2, "What You May Need to Know About Selecting External Resources."

Figure 17-5 Adding a Custom Login Page

Add the location of the custom login page.

To designate the login page:

  1. Click Security.

  2. Select the login page type:

To set the connection to the remote server:

You must first create the authentication-related connections as follows:

  1. In the Features with Security Enabled table, select the application feature's Server Connection field and then click Add, as shown in Figure 17-6.

    Figure 17-6 Adding a Server Connection

    Click Add to create a login server connection.

    Note:

    You must define the application login server connection and assign it to the default application feature (if the default application feature is secured). Also, the credentials used for the application login server are also used to retrieve user and roles and services through the Access Control Service (ACS). See also Section 17.4.6, "What You May Need to Know About the Access Control Service."

  2. Complete the Authentication tab of the Create ADF Mobile Login Server Connection dialog as follows:

    • Name—Enter a name for the connection.

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

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

    • Idle Timeout—Enter the time for an application feature to remain idle after ADF Mobile 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. ADF Mobile then presents the user with a login page. By default, ADF Mobile presents the user a login page when an application remains idle for 300 seconds (five minutes).

      Note:

      ADF Mobile 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, ADF Mobile 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).

      Note:

      You must edit connections.xml to set the number of failed login attempts allowed to a user. For more information, see Section 17.4.4, "What You May Need to Know About Configuring ADF Mobile to Respond to Unsuccessful Login Attempts."

    • Cookies—Use for a remote login for a secured application feature. Enter a list of cookie names that enable basic authentication after they are stored. Because ADF Mobile stores the cookies in a browser, users need only log in once. These cookies and the credentials stored within them are provided by a system administrator. The cookie names are case-sensitive.

    • Include login server cookie in REST calls—For application features using remote authentication (that is, the <adfmf:feature> element includes credentials="remote" as described in Section 17.4.1, "How to Enable Application Features to Require Authentication"), select to enable a REST web service to retrieve authorized user data stored on a login server by using the login server-generated user session cookie. For more information, see Section 17.4.8, "What You May Need to Know About Injecting Cookies into REST Web Service Calls."

      Note:

      To enable cookies to be injected in the REST web service call:

      • The application feature must use remote authentication; ADF Mobile does not support injecting cookies for application features that store user credentials locally.

      • The domain entered for Login URL must be identical to the domain of the REST web service end point.

      • The cookies entered expected by the REST web service, which are entered into Cookies field, must be identical to the ones returned by the login server when the user logs in to an application feature.

    Figure 17-7 The Create ADF Mobile Login Connection Dialog

    The Create ADF Mobile Login Connection dialog.

    Note:

    Figure 17-7 shows a cookie for JSESSIONID, which is used for HTTP basic authentication against Oracle WebLogic Server. Because other authentication mechanisms require different cookies, you can obtain the cookie name through network tracing or through the HTTP Analyzer, described in the "Monitoring HTTP Using the HTTP Analyzer" in Oracle Fusion Middleware User's Guide for Oracle JDeveloper.

    Tip:

    To authenticate against a resource other than OAM, configure both Login URL and Logout URL as the URL of the authentication resource, and enter JSESSIONID as the cookie.

  3. Complete the Authorization tab, shown in Figure 17-8, of the Create ADF Mobile Login Server Connection dialog if the application feature contains any component that is secured, such as an expense report application that includes a submit button configured with an EL expression that only renders to true if it is clicked by a user who is granted a role of manager. Completing the fields in this tab enables the retrieval of the specific user roles that are checked by an application feature.

    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.3.1, "User Constraints." For example, to allow only a user with manager_role role to access an application feature, you must define the <adfmf:constraints> element adfmf-feature.xml 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. ADF Mobile then challenges the user to login against the application login server connection.

    ADF Mobile 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.

    Complete the authorization requirements as follows:

    • Access Control URL—Enter the URL that is the endpoint for the Access Control Service, as shown in Figure 17-8.

    • Filter List of User 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.

    • Filter List of Privileges—Enter the privileges checked by the application feature.

    Figure 17-8 Configuring Access Control

    Add user roles and privileges.

  4. Click OK.

Note:

By default, all secured application features share the same connection, which, as shown in Figure 17-4, 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 ADF Mobile application using the Create ADF Mobile Login Connection dialog.

17.4.3 What Happens When You Create an ADF Mobile Connection

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

Example 17-1 ADF Mobile Connections Defined in connections.xml

<?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"/>
               <idleTimeout value="300"/>
               <sessionTimeout value="28800"/>
               <cookieNames>
                  <cookie name="JSESSIONID"/>
               </cookieNames>
               <injectCookiesToRESTHttpHeader value="true"/>
               <userObjectFilter>
                  <role name="manager"/>
                  <privilege name="account manager"/>
                  <privilege name="supervisor"/>
                  <privilege name=""/>
               </userObjectFilter>
            </Contents>
         </XmlRefAddr>
      </RefAddresses>
   </Reference>
</References>

For more information, see the "connections.xml" section in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

17.4.4 What You May Need to Know About Configuring ADF Mobile to Respond to Unsuccessful Login Attempts

You can set the maximum number of failed login attempts allowed for a user by adding the max_retries attribute to the connections.xml file, as shown in Example 17-2. If you do not configure this attribute, then ADF Mobile allows ten retries. The application closes automatically after a user exceeds the set number of login attempts.

By default, ADF Mobile grants a user three unsuccessful login attempts before it clears the user's locally stored credentials and contacts the remote login server for subsequent login attempts. By adding the maxFailuresBeforeCredentialCleared attribute to the connections.xml file, as shown in Example 17-2, you can change the number of login attempts that ADF Mobile allows a user before it purges the locally stored credentials.

Note:

ADF Mobile clears locally stored user credentials even when the application feature is configured to use local authentication in the adfmf-feature.xml file.

Example 17-2 Configuring the Maximum Retries in connections.xml

<?xml version = '1.0' encoding = 'UTF-8'?>
<References xmlns="http://xmlns.oracle.com/adf/jndi">
  <Reference name="MyAuth"
           className="oracle.adf.model.connection.adfmf.LoginConnection"
           adfCredentialStoreKey="MyAuth"
           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:7777/SecuredWeb1-ViewController-context-root/
                                  faces/view1.jsf"/>
                      <logout url="http://10.0.0.0:7777/SecuredWeb1-ViewController-context-root/
                                   faces/view1.jsf"/>
                      <accessControl url="http://myhost.us.example.com:7777/
                                          UserObjects/jersey/getUserObjects" />
                      <idleTimeout value="10"/>
                      <sessionTimeout value="36000"/>
                      <cookieNames>
                          <cookie name="JSESSIONID"/>
                      </cookieNames>
                      <max_retries value="6"/>
                      <maxFailuresBeforeCredentialCleared value="3"/>
                 </Contents>
             </XmlRefAddr>
        </RefAddresses>
  </Reference>
</References>

17.4.5 What Happens in JDeveloper When You Configure Security

Selecting the Enable Feature Security option in the adfmf-feature.xml overview editor and then selecting the subsequent type of authentication updates the <adfmf:feature> element with a defined credentials attribute. For example:

<adfmf:feature id="feature1" name="feature1" credentials="remote">
<adfmf:feature id="feature2" name="feature2" credentials="local">

Note:

Application features that do not require security (that this, those for which these security options have not been selected) are available to all users of the ADF Mobile application. These applications either have no credentials attribute defined (the default setting, which is present prior to selecting Enable Feature Security in the adfmf-feature.xml oveview editor, shown in Figure 17-2) or include credentials="none" (an attribute that is populated automatically when you clear Enable Feature Security).

After an application feature has been designated to participate in security, JDeveloper updates the Features With Security Enabled table with a corresponding feature reference, shown in Figure 17-4. If each of the referenced application features authenticate against the same login server connection defined in the connections.xml file, JDeveloper updates the adfmf-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 JDeveloper updates each referenced application feature with a loginConnReference attribute (<adfmf:featureReference id="feature2" loginConnRefId="Connection2"/>). For more information, see Section 17.4.1, "How to Enable Application Features to Require Authentication." See also Oracle Fusion Middleware Tag Reference for Oracle ADF Mobile.

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

The Access Control Service (ACS) is a RESTful web service 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 role or privilege 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 17-3 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 17-3 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-Modfied, 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 17-4 illustrates the returned JSON object that contains the user name and the roles and privileges assigned to the user, John Smith.

Example 17-4 The Returned JSON Object

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

Note:

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

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

Each time an ADF Mobile application requests an REST web service, ADF Mobile'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"/>, shown in Example 17-1.) 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 in to an application feature and returns a string in the form of "<cookie name1>=<cookie value1>;<cookie name2>=<cookie value2>;...<cookie nameN>=<cookie valueN>". The security framework creates a cookie header and injects this string into it only if the domain configured for the login server is identical URL endpoint of the REST web service. Further, the string of stored cookies, which are expected by the REST web service, must match those returned from the login server.

Note:

ADF Mobile constructs the cookie string by calling the IDM Mobile SDK 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.

17.4.8 What You May Need to Know About Injecting Cookies into REST Web Service Calls

After a user has been successfully authenticated by an ADF 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 cookie in REST call option in the Create ADF Mobile Login Connection dialog, shown in Figure 17-2, you instruct ADF Mobile to retrieve this user session cookie sent by the login server and then inject it into the HTTP header of the REST web service that originated from the ADF 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 ADF Mobile application to use the REST web service to access the application data authorized for the user. After the user session cookie expires, ADF Mobile 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.

17.4.9 What You May Need to Know about Web Service Security

There are no login screens for web services; user access is instead enabled by ADF Mobile injecting credentials into the header of the web service. Web services gain access to application data using the locally stored credentials persisted by ADF Mobile after the 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 17-1). To enable a web service to use this credential store, the name defined for the credentialStoreKey attribute of a SOAP or REST web service connection must match the name defined for the login server's adfCredentialStoreKey attribute.

Note:

Because there is no overview editor for the connections.xml file, you can use the Property Editor to update the <Reference> element's credentialStoreKey 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 10.5.3, "What You May Need to Know About Credential Injection."

17.4.10 What Happens When You Designate a Custom Login Page

When you add a custom login page for a selected application feature, JDeveloper adds the <adfmf:login> element and populates its child <adfmf:LocalHTML> element, as shown in Example 17-5. As with all <adfmf:LocalHTML> elements, its url attribute references a location within the public_html directory.

Example 17-5 The Login Element

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

For more information on the <adfmf:localHTML> element, see Oracle Fusion Middleware Tag Reference for Oracle ADF Mobile. See also Section 5.9.2, "What You May Need to Know About Selecting External Resources."

17.4.11 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 5.6.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 ADF Mobile. When authentication succeeds, the login page retrieves the originally intended destination from ADF Mobile and navigates to it.

17.4.11.1 The Default Login Page

The default user interface is an HTML file that provides a login button and input text fields for the user name and password.

17.4.11.2 The Custom Login Page

The custom login user interface can be implemented in a login page specified in the adfmf-application.xml file The user authentication mechanism and navigation control are identical to the default login page.

ADF Mobile provides JavaScript APIs for accessing relevant security features. Because you implement a custom login page as an HTML page, you can enable ADF Mobile to process user commands by adding the call to the adf.mf.api.invokeSecurity method, which is described in Table 17-1.

Table 17-1 The adf.mf.api.invokeSecurityMethod

Security Method Return Value Parameters Passed Function

adf.mf.api.invokeSecurityMethod("login", username, password)

None

username, password

Authenticates the user and provides appropriate program flow execution according to the authentication result.

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

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

You can invalidate the credentials (either remote or stored locally) that are specific to an application using the clearPasswordCredential method of the adfmfJavaUtilities class as illustrated in Example 17-6.

Example 17-6 Clearing User Credentials

import oracle.adfmf.framework.api.AdfmfJavaUtilities;
...
   AdfmfJavaUtilities.clearPasswordCredential(adfCrendentialStorykey, username);

The adfCredentialStorykey parameter is returned as a String from the value defined for the adfCredentialStoreKey parameter in the connections.xml file. The method's username parameter is returned as a String and represents the user whose credentials will be removed from the credential store.

By clearing this set of credentials, users can maintain their sessions in other secured application features or open a non-secured application feature without exiting the ADF Mobile application.

For more information on the AdfmfJavaUtilties class and the usage of the key parameter, see Oracle Fusion Middleware Java API Reference for Oracle ADF Mobile.

17.4.11.3 Creating a Custom Login HTML Page for an iOS-Powered Device

You can create the custom login page using the adf.login.iphone.html page, an artifact that is generated as part of deployment.

Before you begin:

Deploy an ADF Mobile application that uses the default login page.

To create a custom login page:

  1. Copy the default login page, adf.login.iphone.html (located in application_folder/deploy/deployment profile name/temporary_xcode_project/www/adf.login.iphone.html) to a location within the application controller project's public_html directory, such as JDeveloper\mywork\Application Name\ApplicationController\public_html.

  2. Rename the adf.login.iphone.html file.

  3. In the Security page for the overview editor for the adfmf-application.xml file, select Custom and then click Browse to retrieve the location of the login page.

17.5 Adding Private Certificates

As described in Section 4.2.2.1, "About the Application-Level Resources," JDeveloper creates the cacerts certificate file within the Application Resources Security folder (located at JDeveloper\mywork\Mobile Application\resources\Security\cacerts ). This 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 17-7 illustrates adding certificates to a cacerts file called new_cert.

      Example 17-7 Adding a Certificate Using the keytool Utility

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

      Example 17-7 illustrates how to add a single certificate. Repeat this procedure for each certificate. Table 17-2 lists the keytool options

      Table 17-2 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 (JDeveloper\mywork\Mobile Application\resources\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, ADF Mobile 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.