30 Securing MAF 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:
-
Section 30.3, "Overview of the Authentication Process for Mobile Applications"
-
Section 30.6, "Configuring Security for Mobile Applications"
-
Section 30.8, "Enabling Users to Log Out from Application Features"
30.1 Introduction to MAF 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 30.6.1, "How to Enable Application Features to Require Authentication," and Section 23.2.4, "About User Constraints and Access Control."
A MAF application uses either the default page or a customized login page that is written in HTML. When authentication beyond a login page is required, a knowledge-based authentication (KBA) page can be enabled when knowledge-based authentication is configured on OAM server. KBA screens provide an additional challenge to users by prompting for additional information, such as "mother's maiden name." Like the login page, the KBA screen can be customized.
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 30.5.19, "What You May Need to Know About the Access Control Service."
The developer can elect to containerize the MAF application at the time of deployment. Containerization allows the application to utilize the Secure Networking and Network Tunneling capabilities of the enterprise networking platform configured with Oracle Mobile Security Suite (OMSS). Distribution of containerized applications is managed by OMSS administrators through the Oracle Mobile Security Access Server (MSAS) component App Catalog and Secure Workspace container features. Authentication of users is performed by MSAS configured for the desired authentication type. For more information about developing the MAF application and OMSS containerization, see Section 2.4, "Containerizing a MAF Application for Enterprise Distribution."
30.2 About the User Login Process
From the end-user perspective, the login process is as follows:
Note:
For more information about how containerizing the MAF application changes the login process, see Section 30.4, "Overview of the Authentication Process for Containerized MAF Applications."-
MAF presents a web view of a login page, shown in Figure 30-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.
Note:
As described in Section 30.6.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. -
The user enters a user name and password and then clicks Sign In.
Note:
MAF allows multiple users for the same application. Users may freely log in to an application after a previous user logs out. -
If the user name and password are verified, MAF displays the intended web view, page, or user interface component.
-
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.
-
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.30.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
Note:
For more information about how containerizing the MAF application changes the authentication process, see Section 30.4, "Overview of the Authentication Process for Containerized MAF Applications."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 30-1 summarizes the login configuration options of a MAF application. The connectivity mode depends on the chosen authentication protocol.
Table 30-1 MAF Connectivity Modes and Supported Authentication Protocols
| Connectivity Mode | Support Protocols | Mode Description |
|---|---|---|
|
local |
|
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 30.5.17, "What You May Need to Know about Web Service Security." |
|
remote |
|
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 |
|
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. |
As an example, the following process depicts the flow of security when the MAF application has been configured for the Mobile-Social authentication protocol to verify user credentials against a remote authentication server:
-
MAF presents the user with the login page (similar to the one shown in Figure 30-1) or knowledge-based authentication screen.
-
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.
-
If the login succeeds, MAF receives an OAM token used in the cookie. MAF sets the cookie into each login connection.
-
The OAMMS client SDK APIs cache the credentials in the device's local credential keystore. MAF will clear the local credential keystore when the threshold for the application session timeout or idle timeout is exceeded.
-
If the login fails, the login page or Knowledge Based Authentication screen remains, thereby preventing users from continuing.
30.4 Overview of the Authentication Process for Containerized MAF Applications
When you develop the MAF application, you must define a login connection to develop and test secure features. During testing, the MAF login page will be used to authenticate before accessing the protected resources. At deployment time, you may choose to containerize the MAF application to utilize the Secure Networking and Network Tunneling capabilities of the enterprise networking platform configured with Oracle Mobile Security Suite (OMSS) and thus eliminates the need for mobile VPN.
Post deployment of the containerized MAF application, access to backend resources behind the corporate firewall will rely on the Mobile Security Access Server (MSAS), a component of OMSS, to provide a central access point for securing traffic from mobile devices to corporate resources. In this case, the MSAS instance is configured to enforce an authentication endpoint to use for the initial authentication of the user.
User authentication is handled by container Single Sign-On (SSO) integration provided by MSAS to the registered MAF application. To allow the MAF application to communicate with MSAS, the user installs and registers a Secure Workspace app for the type of authentication that has been configured for the MSAS instance. Then when the user attempts to access a protected resource, the MAF login page will be suppressed and MSAS will present its own login through the Secure Workspace app on the user's mobile device.
Note:
To enable authentication by MSAS and to utilize the AppTunnel, the MSAS instance must be configured to proxy the login URL or authentication endpoint that the MAF application defines. For details about how MSAS is configured for a MAF login connection, see Section 30.5.12, "What You May Need to Know About Login Connections and Containerized MAF Applications."Whether backend resource requests are proxied using the MSAS AppTunnel is determined by a MSAS-generated Proxy Auto-Configuration file used by the MAF application and Secure Workspace app. The AppTunnel is a mutually authenticated SSL tunnel from each Secure Workspace app that provides secure access to the containerized MAF application. The AppTunnel encrypts all data in transit and provides protection from rogue apps on a user's mobile device that device-level mobile VPNs are subject to.
For an overview of OMSS support for containerized MAF applications, see Section 2.4, "Containerizing a MAF Application for Enterprise Distribution."
30.5 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.
30.5.1 How to Create a MAF Login Connection
As Figure 30-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.
To create a login server connection:
-
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 30.5.19, "What You May Need to Know About the Access Control Service." -
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
-
-
In the Mobile Login Server Connection wizard, select Create a new connection and choose the authentication server type, as shown in Figure 30-2. The connection types are described in the following sections.
30.5.2 How to Create a Multi-Tenant Aware MAF Login Connection
As Figure 30-3 shows, you can use the options page of the Mobile Login Server Connection wizard to create a MAF application connection that supports the notion of multi-tenancy, where an 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 configure a multi-tenant aware connection to servers that support the following authentication protocols:
-
HTTP Basic
-
Mobile-Social
As Figure 30-4 shows, the default login page displayed by the MAF application with a multi-tenant aware connection defined, will prompt the user to enter the domain ID to propagate the tenant value on the HTTP Request.
To create a multi-tenant aware login server connection:
-
In the Mobile Login Server Connection wizard, choose an Authentication Server Type that supports multi-tenant login.
-
In the options page, select Multi-Tenant Aware and enter the tenant header name expected by the authentication server. For example, to solicit the tenant ID from the end user during login, enter the multi-tenant header name: X-ID-TENANT-NAME. As Figure 30-4 shows, the default login page will prompt the user to enter the domain name.
-
Optionally, enter the name of additional custom headers required to perform authentication. These may be configured in addition to the multi-tenant header. See also Section 30.5.14, "What You May Need to Know About Custom Headers."
-
If the header value of the custom header is known, enter the value. If the value for the named custom header is to be overridden during login, leave the corresponding Value field empty. When you want to provide the header value at runtime, you must set the value programmatically using the
OverrideConnectionHandlerAPI. For information about using the API to configure headers, see Section 30.5.21, "How to Configure Login Credentials Programmatically Prior to Authentication."
30.5.3 How to Configure Basic Authentication
As Figure 30-5 shows, you can select the HTTP Basic authentication server type in the Mobile Login Server wizard to configure a connection for basic authentication.
To configure basic authentication:
-
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 30.5.1, "How to Create a MAF Login Connection."
-
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 30-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 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 30.5.16, "What You May Need to Know About Injecting Basic Authentication Headers."
-
Realm—If you define an authentication realm for the user name and password, OEPE populates the connections.xml file with a defined
<realm>element which can be reused. For more information, see Section 30.5.16, "What You May Need to Know About Injecting Basic Authentication Headers.". Pages in the same realm share credentials. If your credentials work for a page with the realm "My Realm", the same username and password combination will work for another page with the same realm.
Click Next
-
-
In the HTTP Basic Options page, enter the following, as shown in Figure 30-6.
-
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 30.5.10, "What Happens When You Create a Multi-Tenant Aware Connection."
-
Multi-Tenant Header Name—When Multi-Tenant Aware is selected, provide the header name.
-
Custom Authorization Headers—Enter the name of any custom headers required to perform authentication. See also Section 30.5.14, "What You May Need to Know About Custom Headers."
If the header value of the custom header is known, enter the value. If the value for the named custom header is to be overridden during login, leave the corresponding Value field empty. When you want to provide the header value at runtime, you must set the value programmatically using the
OverrideConnectionHandlerAPI. For information about using the API to configure headers, see < Section 29.5.23, "How to Configure Login Credentials Programmatically Prior to Authentication."
-
-
Click Test to test the connection to the authentication server. The results are displayed on the wizard.
-
Click Next to open the Login Options page and configure the parameters as described in Section 30.5.8, "How to Store Login Credentials."
-
Click Next to open the Authorization Options page and configure the parameters as described in Section 30.5.18, "How to Configure Access Control."
-
Click Finish to create the connection.
30.5.4 How to Configure Authentication Using Oracle Mobile and Social Identity Management
As Figure 30-7 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 plugin that intercepts HTTP requests for resources and forwards them to the OAM server for authentication and authorization).
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 30.6.2, "How to Designate the Login Page."To configure authentication with Oracle Access Management through an Oracle Mobile and Social server:
-
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 30.5.1, "How to Create a MAF Login Connection."
-
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 30-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.
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 30.5.16, "What You May Need to Know About Injecting Basic Authentication Headers."
-
-
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 30-8.
-
Click Next to open the Login Options page where you can and configure the parameters as described in Section 30.5.8, "How to Store Login Credentials."
-
Click Next to open the Authorization Options page where you can configure the parameters as described in Section 30.5.18, "How to Configure Access Control."
30.5.5 How to Configure OAuth Authentication
As Figure 30-9 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.
Configure the server to use the OM_PROP_OAUTH_OAUTH20_SERVER property key.
To configure authentication with an OAuth server:
-
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 30.5.1, "How to Create a MAF Login Connection."
-
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.
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.
-
-
On the OAuth2 page, configure the following, as shown in Figure 30-10, then click Next:
-
Choose the Grant Type to determine where the application obtains the login page. Select Authorization Code when you want the server login page to display. Select Resource Owner Credentials 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.
-
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 30.5.10, "What Happens When You Create a Multi-Tenant Aware Connection."
-
Multi-Tenant Header Name—When Multi-Tenant Aware is selected, provide the header name.
-
Include basic authentication header—Select this option to enable MAF to add a basic authentication header into the HTTP requests made from a web view. See also Section 30.5.16, "What You May Need to Know About Injecting Basic Authentication Headers."
-
Inject Cookies is selected by default.
-
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.
-
-
On the Authorization page, configure the parameters as described in Section 30.5.18, "How to Configure Access Control."
30.5.6 How to Configure Web SSO Authentication
As Figure 30-11 shows, you can use the Mobile Login Server Connection wizard to configure a cross-domain single sign-on.
To configure authentication with a Web SSO server:
-
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 30.5.1, "How to Create a MAF Login Connection."
-
In the General Options page, configure the following, as shown in Figure 30-12:
-
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.
Click Next.
-
-
On the Web Single Sign-on Options page, configure the URLs that enable successful and unsuccessful logins. You can test the URLs by clicking
. -
Click Next, and on the Authorization Options page configure the parameters, as described in Section 30.5.18, "How to Configure Access Control."
30.5.7 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 by 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 oracle.adfmf.framework.api.AdfmfJavaUtilities class and the usage of the configUrlParam parameter, see Java API Reference for Oracle Mobile Application Framework.
30.5.8 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 30-14 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.
30.5.9 What Happens When You Create a Connection for a MAF Application
MAF aggregates all of the connection information in the connections.xml file (located in the assembly project under the adf and META-INF nodes). This file, shown in the following example, 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.
Note:
As a requirement for MAF application authentication, OEPE sets theadfCredentialStoreKey attribute to the same name as the login connection reference (for example, Connection_1). When editing the adfCredentialStoreKey attribute or the login connection name in the connections.xml file be sure to set the value to be identical for each. Failure to maintain identical values will result in a MAF runtime exception.
<?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"/>
<logout url="http://10.0.0.0/SecuredWebServicelogout/logout"/>
<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>
30.5.10 What Happens When You Create a Multi-Tenant Aware Connection
After you complete the MObile Login Server Connection wizard with the Multi-Tenant Aware option enabled, MAF populates the connections.xml file with the <isMultiTenantAware> element set to true. In multi-tenant connections, 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 Create MAF Login Connection, as shown in Figure 30-3. After a successful login (which includes entering the correct tenant ID), MAF stores the tenant ID in the local credential store.
30.5.11 What You May Need to Know About the Login Connection Configuration
When you define the login URL to grant access to secured MAF features, either in the connections.xml file or programmatically, the login URL must not point to a file resource, such as mydocument.txt. The login URL must point to a web resource that does not result in file transfer when requested. If a file resource is used instead, the MAF application may hang or login will fail, thus preventing the user from accessing the secured MAF feature.
30.5.12 What You May Need to Know About Login Connections and Containerized MAF Applications
In order to use the Oracle Mobile Security Suite (OMSS) AppTunnel feature to access corporate resources, the Mobile Security Access Server (MSAS) instance must be configured to proxy the URI or endpoint used by the MAF application to access the resources. For more information, see the "Managing Mobile Security Access Server Applications" chapter and the "Configuring a Mobile Security Access Server Instance" chapter in Administering Oracle Mobile Security Access Server.
Note that HTTP Basic authentication is supported by OMSS but the MAF login page will not be suppressed by the OMSS authentication process and therefore will require the user to authenticate two times.
For more information about authentication in containerized MAF applications, see Section 29.4, "Overview of the Authentication Process for Containerized MAF Applications."
30.5.13 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.30.5.14 What You May Need to Know About Custom Headers
After you complete the Create MAF Login Connection dialog with custom headers defined, MAF populates the connections.xml file with the customAuthHeaders element and individual header subelements.
If the value of the custom headers is to be supplied at runtime, the MAF application can use the OverrideConnectionHandler API in the oracle.adfmf.framework.api.AdfmfJavaUtilities class to configure header values. The oracle.adfmf.framework.api.AdfmfAuthConnection class provides convenience methods to access the connection.xml XML elements and retrieve the most recent value when they have been overridden. See Section 30.5.21, "How to Configure Login Credentials Programmatically Prior to Authentication."
After a successful login (which includes entering the correct header values), MAF stores the header details in the local credential store, and allows secure calls, such as those made to REST services, to include custom headers on the HTTP Request.
30.5.15 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.
30.5.16 What You May Need to Know About Injecting Basic Authentication Headers
MAF enables application features to access secure resources by injecting a basic authentication header into the HTTP requests made by the web view in an application feature. This is useful in situations where a remote web resource is protected by basic authentication and cookies are not sufficient for authentication, or the server does not honor cookies at all. Specify a requesting realm in the Realm input field of the Create MAF Login Connection dialog's Authorization tab if known at the time of development. If not known at the time of development, the requesting realm can be modified using AdfmfJavaUtilities.overrideConnectionProperty at runtime.
The following example shows the entry that appears in the connections.xml file when you specify a value in the Realm input field (realm element).
<?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"/>
<userObjectFilter/>
</Contents>
</XmlRefAddr>
</RefAddresses>
</Reference>
</References>
30.5.17 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 the example in Section 30.5.9, "What Happens When You Create a Connection for a MAF Application."). 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. When editing the adfCredentialStoreKey attribute or the login connection name in the connections.xml file be sure to set the value to be identical for each. Failure to maintain identical values will result in a MAF runtime exception.
Note:
Because there is no overview editor for theconnections.xml file, you can use the Properties window 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 15.6.4, "What You May Need to Know About Credential Injection."
30.5.18 How to Configure Access Control
Access Control Service (ACS) is a RESTful web service with JSON that may be optionally deployed onto an external server that is separate from your MAF application. Typically, you provide the ACS service for your MAF application to consume when your application features contain secured components and you want to allow users to download their user roles and privileges through a single HTTP POST message. If you intend to provide this service with your application, then you must implement and host the ACS service; MAF does not provide this service. Figure 30-15 shows the Authorization page of the Mobile Login Server Connection wizard that you would use to configure the MAF application to support access control.
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 23.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.
-
In the Mobile Login Server Connection wizard, navigate to the Authorization page.
For information about opening the Mobile Login Server Connection wizard, see Section 30.5.1, "How to Create a MAF Login Connection."
-
On the Authorization page, complete the authorization requirements, as shown in Figure 30-15.
-
Access Control Service URL—Enter the URL that is the endpoint for the Access Control Service (ACS).
-
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.
-
30.5.19 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.
The following example 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.
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, andContent-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 theroleFilterarray 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 theprivilegeFilterarray in the request. Otherwise, the response returns an entire list of privileges assigned to the user.
-
The example below illustrates the returned JSON object that contains the user name and the roles and privileges assigned to the user, John Smith.
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 15.6.4, "What You May Need to Know About Credential Injection."Note:
You must implement and host the ACS service; MAF does not provide this service.30.5.20 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 30-15. 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 the example in Section 30.5.16, "What You May Need to Know About Injecting Basic Authentication Headers.". 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 theinvokeACS 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.
30.5.21 How to Configure Login Credentials Programmatically Prior to Authentication
Before the MAF application invokes the login connection to authenticate the user, it is possible to set connection values programmatically. This technique is often required, for example, when custom header names are defined in the Mobile Login Server Connection wizard but the values are to be supplied at runtime. To programmatically configure the connection details, the MAF application can invoke the OverrideConnectionHandler API in the oracle.adfmf.framework.api.AdfmfJavaUtilities class. The API overrides the current connection property value with a new value and allows the application to initiate login with the overridden values.
To override the connection values programmatically, the general process entails:
-
Obtaining the names of the XML elements that define the properties to override from the
connections.xmlfile. -
Obtaining the override value prior to authentication. For example, the MAF application may define an AMX page to solicit the values from the end user for this purpose.
-
Invoking a managed bean that implements the override methods (one for each connection property override) and defines connection property getter and setter methods. For example, in the case of an AMX page, a command button that the end user clicks may submit their entered values on the managed bean.
To specify connection property overrides, examine the connections.xml file to obtain the following XML element definitions:
-
The connection reference name. For example,
ConnWithCustomHeader. -
The XML element name of the property that defines the attribute to override. For example
multiTenantSchemefor the scheme used to propagated a tenant domain name. -
The XML subelement name of the property's attribute to override. In the case of unique connection properties, this is always the
valueelement.
Note:
In the case of custom headers, do not use the XML elementsheader and value since all custom header definitions use the same element names to specify values. Instead, for custom headers use Contents and customAuthHeaders for the property and attribute to pass to the override method, respectively.For example, to override the value of custom headers, in the following connections.xml file you would pass the connection name ConnWithCustomHeader, the Contents element, and the customAuthHeaders subelement, which defines the header name / value pairs.
package mobile; <References xmlns="http://xmlns.oracle.com/adf/jndi"> <Reference name="ConnWithCustomHeader" className="oracle.adf.model.connection.adfmf.LoginConnection" adfCredentialStoreKey="ConnWithCustomHeader" partial="false" manageInOracleEnterpriseManager="true" deployable="true" xmlns=""> <Factory className="oracle.adf.model.connection.adfmf.LoginConnectionFactory"/> <RefAddresses> <XmlRefAddr addrType="adfmfLogin"> <Contents> ... <isMultiTenantAware value="true"/> <multiTenantScheme value="custom_header"/> <multiTenantHeaderName value="X-ID-TENANT-NAME"/> <customAuthHeaders> <header name="State" value="Georgia"/> <header name="City" value="Atlanta"/> </customAuthHeaders> ... </Contents> </XmlRefAddr> </RefAddresses> </Reference>
To perform the connection value override at runtime, the MAF application may solicit the values with a default unsecured feature that invokes an AMX page with prompts for the values and a command button to submit the values. The following sample shows the command button defines an action listener that triggers the override method in a managed bean:
<?xml version="1.0" encoding="UTF-8" ?>
<amx:view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:amx="http://xmlns.oracle.com/adf/mf/amx"
xmlns:dvtm="http://xmlns.oracle.com/adf/mf/amx/dvt">
<amx:panelPage id="pp1">
<amx:facet name="header">
<amx:outputText value="Home" id="ot1"/>
</amx:facet>
<amx:facet name="primary">
<amx:commandButton id="cb1"/>
</amx:facet>
<amx:facet name="secondary">
<amx:commandButton id="cb2"/>
</amx:facet>
<amx:inputText label="Name1" id="it1" value="#{applicationScope.OverrideBean.headerName1}"/>
<amx:inputText label="Value1" id="it2" value="#{applicationScope.OverrideBean.headerValue1}"/>
<amx:inputText label="Name2" id="it3" value="#{applicationScope.OverrideBean.headerName2}"/>
<amx:inputText label="Value1" id="it4" value="#{applicationScope.OverrideBean.headerValue2}"/>
<amx:inputText label="TenantHeader" id="it5"
value="#{applicationScope.TestBean.tenantHeaderName}"/>
<amx:inputText label="Scheme" id="it6" value="#{applicationScope.OverrideBean.scheme}"/>
<amx:commandButton text="Override headers" id="cb3"
actionListener="#{OverrideBean.overrideAndGotoOverrideFeature}"/>
</amx:panelPage>
</amx:view>
To override the connection property values programmatically, the managed bean implements the override method for each connection property override. Note that in the following sample Ova headers HashMap is created to pass in the custom header values. The map is only necessary for custom headers that you want to override since the values of other properties (like MultiTenantHeaderName) are uniquely defined by the XML elements of the connections.xml definition.
package mobile;
import oracle.adfmf.amx.event.ActionEvent;
import oracle.adfmf.framework.api.AdfmfJavaUtilities;
import oracle.adfmf.java.beans.PropertyChangeListener;
import oracle.adfmf.java.beans.PropertyChangeSupport;
import java.util.HashMap;
public class OverrideBean {
private String headerName1 = "", headerName2 = "", headerValue1 = "", headerValue2 = "";
private String tenantHeaderName = "";
private String scheme = "";
// Bean setter and getter methods omitted for brevity
...
// Command button action listener invokes override method implementation
public void overrideAndGotoOverrideFeature(ActionEvent e) {
overrideAndGotoOverrideFeature();
}
// Override method implementation configures custom headers and other connection properties
public void overrideAndGotoOverrideFeature()
{
AdfmfJavaUtilities.clearSecurityConfigOverrides("ConnWithCustomHeader");
HashMap<String, String> headers = new HashMap<String, String>();
headers.put(headerName1, headerValue1);
headers.put(headerName2, headerValue2);
AdfmfJavaUtilities.overrideConnectionProperty("ConnWithCustomHeader", "Contents",
"customAuthHeaders", headers);
AdfmfJavaUtilities.overrideConnectionProperty("ConnWithCustomHeader",
"multiTenantHeaderName", "value",
tenantHeaderName);
AdfmfJavaUtilities.overrideConnectionProperty("ConnWithCustomHeader", "multiTenantScheme",
"value", scheme);
AdfmfJavaUtilities.updateApplicationInformation(false);
}
public void addPropertyChangeListener(PropertyChangeListener l) {
propertyChangeSupport.addPropertyChangeListener(l);
}
public void removePropertyChangeListener(PropertyChangeListener l) {
propertyChangeSupport.removePropertyChangeListener(l);
}
}
30.6 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.
30.6.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 21, "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 30-16.
When you enable security for a feature, the application requires access the network to authenticate the user. For more information, see Section 10.2, "Enabling Core Plugins in Your MAF Application."
To designate user access for an application feature:
-
In the Project Explorer, in the user interface project, expand MAF, and then double-click MAF Feature Editor.
-
In the MAF Feature Editor, select an application feature listed under Features or right-click Features and choose New to add an application feature.
-
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.
30.6.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 30-17, 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 30.6.3, "What You May Need to Know About Login Pages."
Note:
Login servers (connections) are defined on the Security tab. The Registered Features tab allows you to assign them to specific features, or use<default>. If security is not enabled for the feature (done from the feature), login servers are not assignable. A validation problem will occur is a feature requires security, and no login server has been defined for the application
Add constraints for user privileges and roles, as described in Section 23.2.4, "About User Constraints and Access Control."
Provision an Access Control Service (ACS) server. For more information, Section 30.5.19, "What You May Need to Know About the Access Control Service."
The custom login page is defined in the application controller project, as shown in Figure 30-18.
To designate the login page and Knowledge Based Authentication page:
-
In the Project Explorer, expand the assembly project, then expand MAF, and double-click MAF Application Editor.
-
In the outline, click Security.
-
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.
-
-
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 30.6.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 30.6.3.2, "The Custom Login 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.
-
30.6.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 11.1.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.
30.6.3.1 The Default Login Page
The default login page provided by MAF is comprised of a login button, input text fields for the user name, password, and, optionally, multi-tenant name, and an error message section. This is a cross-platform page, one written in HTML. Figure 30-1 shows a default login page with the multi-tenant aware option enabled at design time to solicit the domain name of the tenant, in addition to the user name and password.
30.6.3.2 The Custom Login Page
When you add a custom login page for a selected application feature using MAF Feature Editor, OEPE adds the <adfmf:login> element and populates its child <adfmf:LocalHTML> element, as shown in the next example. 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.
<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 thewww 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.
The example below illustrates the required <input> and <label> elements for a 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"/>
The example below illustrates the 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"/>
30.6.4 What You May Need to Know About Login Page Elements
Every HTML login page should include the user interface elements listed in Table 30-2.
Table 30-2 Login Page Fields and Their Associated IDs
| Page Element | ID |
|---|---|
|
username field |
|
|
password field |
|
|
login button |
|
|
cancel button |
|
|
identity domain/tenant name field |
|
|
Knowledge Based Authentication question field (read-only/label) |
|
|
Knowledge Based Authentication answer field |
|
|
error field |
|
|
auto login check box |
|
|
remember credentials check box |
|
|
remember username check box |
|
Table 30-3 lists the recommended JavaScript code used by the OnClick event.
Table 30-3 JavaScript Used by the OnClick Event
| Button | JavaScript |
|---|---|
|
login button |
|
|
cancel button |
|
|
Knowledge Based Authentication submit button |
|
|
Knowledge Based Authentication cancel button |
|
30.6.5 What Happens in OEPE When You Configure Security for Application Features
After an application feature has been designated to participate in security, OEPE updates the Registered Features with a corresponding feature reference, as shown in Figure 30-17. If each of the referenced application features authenticate against the same login server connection defined in the connections.xml file, OEPE 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 OEPE updates each referenced application feature with a loginConnReference attribute (<adfmf:featureReference id="feature2" loginConnRefId="Connection2"/>). For more information, see Section 30.6.1, "How to Enable Application Features to Require Authentication." See also the Tag Reference for Oracle Mobile Application Framework.
30.7 Allowing Access to Device Capabilities
Access to device capabilities is defined by the Cordova plugins that are included in the MAF application. A set of core plugins are provided by MAF. Enabling one of these plugins will enable any device access permissions that it requires. Any additional Cordova plugins that you include in your MAF application will also enable the device access permissions required.
Because the vast majority of MAF applications require network access, permission to access the network is enabled by default (the only device capability that is enabled by default):
-
Network Information—Allows the application to open network sockets. You must leave the network access capability enabled when security is enabled for at least one device feature.
Because you can enable or restrict device capabilities, the various platform-specific configuration files and manifest files that are updated by the deployment framework list only the device capabilities in use (or rather, the plugins that the MAF application is registered to use). These files enable MAF to share information about the use of these capabilities with other applications. For example, a MAF application can report to the AppStore or to Google Play that it does not use location-based capabilities (even though MAF applications have this capability).
For more information about Cordova plugins in MAF applications, see Chapter 10, "Using Plugins in MAF Applications."
30.8 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 enable users to perform the following the following:
-
Log out of an application feature but continuing to access its unsecured content (that is, MAF does not terminate the application).
-
Authenticate with the login server while in an application to enable its secured content and UI components.
-
Log out of a MAF application or application feature and then logging in again using a different identity.
-
Log out of a MAF 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.
30.9 Supporting SSL
MAF provides a cacerts certificate file, the Java mechanism for HTTPS handshakes between the client application and the server. OEPE 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 the JVM 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.
It may be helpful to have an understanding of the contents of the cacerts file. For more information, see the "Migrating to New cacerts Files for SSL in MAF" section in Installing Oracle Mobile Application Framework.
You may also find it helpful to understand how OEPE creates the cacerts file. For more information, see Section C.2, "About the Assembly-Level Resources."
Refer to Java SE Technical Documentation (https://download.oracle.com/javase/index.html) for information on the cacerts file and how to use the keytool utility.
-
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
cacertsfile (cp cacerts cacerts.org). -
Use the Java SE keytool utility to add certificates to a
cacertsfile. This example illustrates adding certificates to acacertsfile callednew_cert.keytool -importcert -keystore cacerts -file new_cert -storepass changeit -nopromptThe example illustrates how to add a single certificate. Repeat this procedure for each certificate. Table 30-4 lists the keytool options
Table 30-4 Options For Adding Certificates
Option Description -importcertImports a certificate.
-keystorecacerts fileIdentifies the file location of the imported certificate.
-filecertificate fileIdentifies the file containing the new certificate.
-storepass changeitProvides a password for the
cacertsfile. By default, the password is changeit.-
nopromptInstructs the keytool not to ask the user (through
stdin) whether to trust the certificate or not. -
Visually inspect the contents of the new
cacertsfile 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
Securitydirectory (users\workspaces\assembly project\lib\Security) so that it can be read by JVM 1.4.
-
-
Deploy the application.
Note:
During deployment, if a certificate file exists within theSecuritydirectory, MAF copies it into the Android or Xcode template project, replacing any default copies of thecacertsfile. -
Validate that you can access the protected resources over SSL.