18 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:

Section 18.1, "Introduction to Security for an ADF Mobile Application."
Section 18.2, "Introduction to the User Login Process"
Section 18.3, "Introduction to Authentication"
Section 18.4, "Configuring Security for ADF Mobile Applications"
Section 18.5, "Adding Private Certificates"

18.1 Introduction to Security for an ADF Mobile Application

ADF Mobile presents users with a login page 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. By default, ADF Mobile only presents a login page when it is required, either when an application feature requires security or when it includes constraints based on user roles or user privileges. If either of these conditions exist, then ADF Mobile presents users with the login page at the startup of the ADF Mobile application and displays application features on the navigation bar accordingly. For more information, see Section 18.4.1, "How to Enable Application Features to Require Authentication," and Section 14.2.4, "About User Constraints and Access Control."

ADF Mobile uses JavaScript, an Apache Cordova plugin, and native Cordova command handlers that collectively handle the interaction with the login page, the navigation between application features, and interactions with the Oracle Access Management Mobile and Social (OAMMS) IDM Mobile SDK, whose classes and protocols verifies user credentials. The native Cordova command handler methods are executed through the Cordova 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.

18.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. From the end-user perspective, the login process is as follows:

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

Figure 18-1 The Login Page

Note:

As described in Section 18.4.12.2, "The Custom Login Page," ADF Mobile provides not only a non-platform specific login page, but also supports the use of a custom login page.
The user enters a user name and password and then clicks OK.

Note:

ADF Mobile does not allow multiple users for the same 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 end 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 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 18.4.12, "What You May Need to Know About Login Pages."
If the user name and password are verified, ADF Mobile displays the intended web view, page, or UI component.
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.

18.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:

ADF Mobile presents the user with the default login page, similar to the one shown in Figure 18-1, or with a custom login page.
The APIs of the Oracle Access Management Mobile and Social (OAMMS) IDM Mobile SDK 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.

Note:

Logging into OAMMS populates the roles and privilege collections to the user object.
If the login succeeds, ADF Mobile receives an OAM token used in the cookie. ADF Mobile sets the cookie into each login connection.
The IDM Mobile SDK APIs save the credentials in the device's credential store.
If the login fails, the login page remains, thereby preventing users from continuing.

18.3.1 About Constraint-Dictated Access Control

When at least one secured application feature includes the user.roles or user.privileges constraints, an end user must complete a login page to 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 ADF Mobile uses a login page to prompt the end user to authenticate 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.4, "About User Constraints and Access Control."

18.4 Configuring Security for ADF Mobile Applications

Security is configured using both the overview editors for the adfmf-feature.xml and adfmf-application.xml files. The adfmf-application.xml file's overview editor enables you to designate the type of login page (default or custom) that ADF Mobile presents to users when they select application features that require authentication or to include user role- or user privilege-based constraints. For application features whose content is served from a remote URL, the overview editor enables you to whitelist the domains so that remote URL content can display within the ADF Mobile web view. For more information, see Chapter 12, "Implementing Application Features as Remote URLs."

Using the overview editor for the adfmf-feature.xml file enables you to designate whether an application feature 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 login 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 login 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 18.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 18-7. See also Section 18.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 using a remote login server, or using a locally 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.

18.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 remote login server or to a local credential store. You can define each application feature to participate in security. You perform the remainder of the security configuration using the Security page of the adfmf-application.xml overview editor.

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

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

Designating user credentials requirement.

To designate user access for an application feature:

Select an application feature or click Add to add an application feature.
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 18.4.11, "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 18-2, you can configure the security options in the Property Inspector, shown in Figure 18-3.

Figure 18-3 Designating User Credential 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.

18.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 18-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. For more information, see Section 18.4.12, "What You May Need to Know About Login Pages."

Figure 18-4 The Security Page of the adfmf-application.xml Overview Editor

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 18-5. See also Section 18.4.12.3, "Creating a Custom Login HTML Page" and Section 5.10.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 18.4.7, "What You May Need to Know About the Access Control Service."

Figure 18-5 Adding a Custom Login Page

Add the location of the custom login page.

To designate the login page:

Click Security in the adfmf-application.xml overview editor.
Select the login page type:
- Default—The default, non-platform specific login page used for all of the selected embedded application features. For more information, see Section 18.4.12.1, "The Default Login Page." The default login page is provided by ADF Mobile.
- Custom—Select the format (HTML) and then click Browse to retrieve the path location of the file within the application controller project. Alternatively, click New to create an HTML page within the application controller project. For more information, see Section 18.4.12.2, "The Custom Login Page" and Section 18.4.12.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 Application Navigator into the field.

To set the connection to the remote server:

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

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

Figure 18-6 Adding a 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 18.4.7, "What You May Need to Know About the Access Control Service."
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. In this situation, ADF Mobile prompts users with the login page when they access the feature again. By default, ADF Mobile presents the 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 the connections.xml file to set the number of failed login attempts allowed to a user. For more information, see Section 18.4.5, "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. See also Section 18.4.10, "What You May Need to Know About Injecting Basic Authentication Headers."
- 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 18.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 18.4.9, "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 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 18-7 The Create ADF Mobile Login Connection Dialog

Note:

Figure 18-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.
Complete the Authorization tab, shown in Figure 18-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.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 adfmf-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. 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 18-8.
  
  Note:
  
  ADF Mobile 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 cookie in REST calls and enter identical addresses for Access Control URL and the Login URL parameters. See also Section 18.4.9, "What You May Need to Know About Injecting Cookies into REST Web Service Calls."
- 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 18-8 Configuring Access Control
Click OK.

Note:

By default, all secured application features share the same connection, which, as shown in Figure 18-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.

18.4.3 Enabling Login without the Access Control Service

You can enable users to login without having to provision Access Control Service (ACS) server by adding name=show-application-login-at-startup value=true to the adf-config.xml file (located in ADF META-INF directory in the Application Navigator) as illustrated in Example 18-1. This flag triggers the login page when the ADF Mobile application starts.

Example 18-1 Configuring the Login Page in adf-config.xml

<adf:adf-properties-child xmlns="http://xmlns.oracle.com/adf/config/properties">
    <adf-property name="adfAppUID" value="MobileApplication-3268"/>
    <adf-property name="show-application-login-at-startup" value="true"/>
  </adf:adf-properties-child>

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

18.4.4 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 18-2, can be bundled with the application or can be hosted for the Configuration Service. In the latter case, ADF Mobile checks for the updated configuration information each time an application starts.

Example 18-2 ADF Mobile 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"/>
               <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 "Lookup Defined in the connections.xml File" section in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

18.4.5 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 18-3. 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 element to the connections.xml file, as shown in Example 18-3, 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 18-3 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>

18.4.6 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 is, 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 overview editor, shown in Figure 18-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 18-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 18.4.1, "How to Enable Application Features to Require Authentication." See also Oracle Fusion Middleware Tag Reference for Oracle ADF Mobile.

18.4.7 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 18-4 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 18-4 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 18-5 illustrates the returned JSON object that contains the user name and the roles and privileges assigned to the user, John Smith.

Example 18-5 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 9.5.3, "What You May Need to Know About Credential Injection."

Note:

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

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

Each time an ADF Mobile application requests a 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 18-2.) 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. It then 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 APIs, which return cookies by name from a platform-specific cookie store. The IDM Mobile SDK APIs manage the cookies returned by authentication servers, the names of which are defined in the connections.xml file.

18.4.9 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 18-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 call 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 that is 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.

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

By default, ADF Mobile enables application features to access secure resources from servers that do not honor cookies by injecting a basic authentication header in the HTTP requests made from the web views. Although ADF Mobile injects the basic authentication header when the connections.xml file includes a definition for an authentication realm (the <realm> element) followed by <injectBasicAuthHeader value="true">, as illustrated in Example 18-6, ADF Mobile injects the header regardless of whether the connections.xml file includes these definitions or not. To prevent ADF Mobile from injecting the basic authentication header, set the value attribute to false for the <injectBasicAuthHeader> element.

Note:

You must enter the <realm> and <injectBasicAuthHeader> elements in the Source editor for the connections.xml file.

Example 18-6 Injecting 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=""/>
               <idleTimeout value="300"/>
               <sessionTimeout value="28800"/>
               <cookieNames/>
               <realm value="Secure Area"/>
               <injectBasicAuthHeader value="true"/>
               <userObjectFilter/>
            </Contents>
         </XmlRefAddr>
      </RefAddresses>
   </Reference>
</References>

18.4.11 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 call. Web services gain access to application data using the locally stored credentials persisted by ADF Mobile 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 18-2). 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:

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

18.4.12 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.7.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.

18.4.12.1 The Default Login Page

The default login page provided by ADF Mobile (illustrated in Figure 18-1, "The Login Page") is comprised of a login button and input text fields for the user name and password. This is a cross-platform page, one written in HTML.

18.4.12.2 The Custom Login Page

When you add a custom login page for a selected application feature using the overview editor for the adfmf-application.xml file, JDeveloper adds the <adfmf:login> element and populates its child <adfmf:LocalHTML> element, as shown in Example 18-7. 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 18-7 The Login Element

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

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 a call to the adf.mf.api.invokeSecurity method, which is described in Table 18-1.

Table 18-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 the 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 18-8.

Example 18-8 Clearing User Credentials

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

The adfCredentialStorykey parameter is returned as a String object from the value defined for the adfCredentialStoreKey parameter in the connections.xml file. The method's username parameter is returned as a String object 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.

18.4.12.3 Creating a Custom Login HTML Page

You can create the custom login page using the default login page (adf.login.iphone.html or adf.login.android.html), an artifact generated by the ADF Mobile deployment in the www directory.

Before you begin:

To access the login page within the www directory, deploy an ADF Mobile application and then traverse to the deploy directory. For iOS deployments, the adf.login.iphone.html page is located at:

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

For Android deployments, the adf.login.android.html page is located within the Android application package (.apk) file at

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

To create a custom login page:

Copy the default login page (adf.login.iphone.html or adf.login.android.html) to a location within the application controller project's public_html directory, such as JDeveloper\mywork\application name\ApplicationController\public_html.
Rename the login page.
Update the page as described in Section 5.5.4, "What You May Need to Know About Custom Springboard Application Features with HTML Content" and Section B, "Application Container APIs."
In the Security page for the overview editor of the adfmf-application.xml file, select Custom and then click Browse to retrieve the location of the login page. For more information, see Section 5.5, "Configuring the Springboard and Navigation Bar Behavior."

18.5 Adding Private Certificates

As described in Section 4.2.2.1, "About the Application Controller Project-Level Resources," JDeveloper creates the cacerts certificate file within the Application Resources Security folder (located at JDeveloper\mywork\application name\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:

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

Add the private certificate to the application as follows:

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

Use the Java SE keytool utility to add certificates to a cacerts file. Example 18-9 illustrates adding certificates to a cacerts file called new_cert.

Example 18-9 Adding a Certificate Using the keytool Utility

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

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

Table 18-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.

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
```
Verify that the certificate is for the given hostname.

Note:

The certificate's common name (CN) must match the hostname exactly.
Ensure that the customized certificate file is located within the Security directory (JDeveloper\mywork\application name\resources\Security) so that it can be read by JVM 1.4.

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.
Validate that you can access the protected resources over SSL.