27 Securing MAF Applications
This chapter includes the following sections:
Introduction to MAF Security
MAF provides a number of ready-to-use features that facilitate the development of secure MAF applications. These include a default login page for secured application features, support for anonymous users, and constraints to restrict access to users with specific roles or privileges.
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 MAF application without a successful login, you can enable users to access a MAF 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 MAF 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 MAF 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 MAF 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. See How to Enable Application Features to Require Authentication and About User Constraints and Access Control.
A MAF application uses either the default page or a customized login page that is written in HTML.
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. See What You May Need to Know About the Access Control Service.
About the User Login Process
MAF displays the web view, page, or user interface component that a user wants to access after the user has logged in on the web login page and has been authenticated. MAF presents challenges until a login is effected, and the login times out after the configured interval.
From the end-user perspective, the login process is as follows:
-
MAF presents a web view of a login page 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 default login page when they launch the application.
Note:
As described in The Custom Login Page, MAF provides not only a default login page, but also supports the use of a custom login page.
-
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.
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 time-out when one of the application features that use the connection to the authentication server has been activated.
Overview of the Authentication Process for MAF Applications
MAF applications may require that user credentials be verified against a remote login server 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
-
OAuth
-
OpenID
-
Web SSO
By default, authentication of the MAF application user is against the remote login server regardless of the authentication protocol chosen at design time. Developers may configure the application, if using 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 an authentication protocol that only supports remote connectivity.
Table 27-1 summarizes the login configuration options of a MAF application. The connectivity mode depends on the selected authentication protocol.
Table 27-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 What You May Need to Know About Web Service Security. |
|
remote |
|
Requires the application to authenticate 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 access the secured MAF feature 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. |
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 and the application will not function properly.
How to Create a MAF Login Connection
Use the Create MAF Connection dialog 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
-
OAuth
-
OpenID
-
Web SSO
Note:
Oracle recommends that you use a connection type that requires authentication against a remote login server and does not allow users to authenticate on the device from a local credential store.
To create a login server connection:
- Perform one of the following actions.
-
In the Navigator, expand the Descriptors node and then ADF META-INF, and double-click maf-application.xml. Then, in the overview editor for the
maf-application.xmlfile, expand the Security - Authentication and Access Control section and click Create. -
Alternatively, select Connections in the New Gallery and then MAF Login Server Connection.
-
How to Create a Multi-Tenant Aware MAF Login Connection
A MAF application connection can support a hosted application feature that can be shared by different organizations or tenants.
Figure 27-4 Configuring a Multi-Tenant Aware Connection
Description of "Figure 27-4 Configuring a Multi-Tenant Aware Connection"
As the figure 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:
Figure 27-5 Default Login Page for Multi-Tenant Aware Connection
Description of "Figure 27-5 Default Login Page for Multi-Tenant Aware Connection"
- Perform one of the following actions.
- In the Navigator, expand the Descriptors node and then ADF META-INF, and double-click maf-application.xml. Then, in the overview editor for the
maf-application.xmlfile, expand the Security - Authentication and Access Control section and click Create. - Alternatively, select Connections in the New Gallery and then MAF Login Server Connection.
- In the Navigator, expand the Descriptors node and then ADF META-INF, and double-click maf-application.xml. Then, in the overview editor for the
How to Configure Basic Authentication
Select the HTTP Basic authentication server type in the Create MAF Login Connection dialog to configure a connection for basic authentication.
Figure 27-7 Configuring Basic Authentication
Description of "Figure 27-7 Configuring Basic Authentication"
To configure basic authentication:
- Click the HTTP Basic tab and configure the following, as shown in the figure below.
-
Login URL—Enter the login URL for the login page.
The login URL should not be a login page on the remote server, but rather a page that is secured and presents the HTTP Basic user name/password challenge. The login URL must point to a web resource that does not result in file transfer when requested; it must not point to a file resource.
-
Logout URL—Enter the logout URL for the authentication server.
The logout URL may be the same as the login URL, but alternatively may be a URL to the remote server that performs additional actions on the session, such as invalidating it. The logout URL must point to a web resource that does not result in file transfer when requested; it must not point to a file resource.
Figure 27-8 Configuring Basic Authentication
Description of "Figure 27-8 Configuring Basic Authentication" -
How to Configure OAuth Authentication
Use the Create MAF Login Connection dialog to configure the access of an application to protected data or services stored on a remote server.
Before you begin:
Configure the server to use the OM_PROP_OAUTH_OAUTH20_SERVER property key.
To configure authentication with an OAuth server:
- Click the OAuth tab and configure the following, as shown in the figure below:
-
Select the appropriate grant type from the Grant Type drop-down list.
-
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.
-
Select Client Credentials when you want the MAF application to access resources anonymously without requiring a user ID or user credentials.
-
-
Enter the Client Id and, optionally, enter a connection password value in the Client Secret field.
-
Enter the Redirect Endpoint of the authorization server and the URIs for the endpoints for the Authorization Server Endpoint itself and the Token Endpoint.
-
Enter the Logout URL to redirect to upon user logout. This field is mandatory and the URL parameters are determined by the specific authentication provider.
-
Select Enable Embedded Browser Mode 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 SSO is desired, you must deselect this option to force the application to use the external browser.
Figure 27-10 Configuring the Client ID and Endpoints
Description of "Figure 27-10 Configuring the Client ID and Endpoints" -
How to Configure OpenID Authentication
Use the Create MAF Login Connection dialog to configure a connection that uses the OpenID authentication protocol to allow the MAF application access to protected data or services stored on a remote server.
To configure authentication with the OpenID authentication protocol:
- Click the OpenID tab and configure the following, as shown in the figure below:
-
Select the appropriate grant type from the Grant Type dropdown list.
-
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.
-
Select Client Credentials when you want the MAF application to access resources anonymously without requiring a user ID or user credentials.
-
-
Enter the Client Id and, optionally, enter a connection password value in the Client Secret field.
-
Enter the Connect Discovery URL provided by your identity provider that retrieves the information, such as authorization endpoint and token endpoint, that the MAF application requires to authenticate using the OpenID protocol.
-
Enter the Redirect Endpoint provided by your identity provider.
-
Select Enable Embedded Browser Mode 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 SSO is desired, you must deselect this option to force the application to use the external browser.
Figure 27-11 Configuring a MAF Login Connection Using OpenID
-
How to Configure Single Sign-On in a MAF Application
MAF supports single-sign on (SSO) and federated SSO in MAF applications deployed to all platforms (Android, iOS, and the Universal Windows Platform).
The identity provider that you use to configure SSO can be a third-party identity provider hosted in your corporate domain, such as an instance of Azure Active Directory, or whatever identity provider has already been configured for the backend service that your MAF application connects to such as, for example, Oracle Mobile Cloud Service (MCS).
For MAF applications that you deploy to the Universal Windows Platform that need to support MCS SSO, you need to register a Cordova plugin in your application that allows access to MCS SSO. Configure entries in the plugin’s plugin.xml file that allow this access, as demonstrated by the following example:
<config-file target="package.appxmanifest" parent="/Package/Applications/Application/uap:ApplicationContentUriRules">
<!-- Allow Webviews access to server so the token relay header can be injected -->
<uap:Rule Match="http://*.oracle.com:7777/*/*/*/*" Type="include"/>
</config-file>
For information about creating Cordova plugins and using them in your MAF application, see Introduction to Using Plugins in MAF Applications and Registering Additional Plugins in Your MAF Application.
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"example",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value"
}
Note:
If you select the Parse Token Relay Response checkbox, MAF includes “format=JSON” as a query parameter in the login URLs. You do not need to specify this query parameter in the URL.
If you use the identity provider configured for MCS, you provide the client ID for the OAuth Consumer issued by the MCS mobile backend ID that your MAF application connects to as a query parameter in the connection URL that you configure in your MAF application. The following example shows a subset of the entries generated in MAF application’s connections.xml file for a connection that enables the application to use SSO that is configured in an MCS mobile backend.
<Contents>
<login url="http://yourmcsinstance.com/sso/token?clientID=C490B55...FO51"/>
<logout url="http://yourmcsinstance.com/sso/appLogout"/>
<loginSuccessUrl url="http://yourmcsinstance.com/sso/success/token?clientID=C490B55...FO51">
<parseTokenRelayResponse value="true"/>
</loginSuccessUrl>
<loginFailureUrl url="http://yourmcsinstance.com/sso/appError"/>
…
</Contents>To configure single sign-on authentication:
- Click the Web SSO tab and configure the following URLs that enable successful and unsuccessful logins, as shown in the figure below:
-
Login URL—Enter the URL that prompts the user to enter credentials when the MAF application navigates to it. The login URL must point to a web resource that does not result in file transfer when requested; it must not point to a file resource. If creating a login connection to MCS, the login URL must include a query parameter set to the client ID specified by the MCS MBE that your MAF application connects to. Obtain the value of this client from MCS.
-
Logout URL—Enter a server side URL that logs out the user by terminating the server session. The logout URL must point to a web resource that does not result in file transfer when requested; it must not point to a file resource.
If configuring a connection to MCS, make sure that the logout URL conforms to the following format so that redirect works as expected after logout.
//A production instance of MCS https://{hostname}/logout.html?end_url=/mobileui //A development instance of MCS https://{hostname}/oam/server/logout -
Login Success URL—Enter a target URL to redirect the user to after the user successfully authenticates.
The login success URL can be the same as the login URL. For example, if the login URL and login success URL is
http://www.mysite.com, then when the user points the browser tohttp://www.mysite.com, the browser will redirect to the login page for the site before it redirects upon successful authentication back tohttp://www.mysite.com. Then, when MAF detects the page named by the login success URL, MAF completes the login process and activates the requested feature. Thus, the contents of the login success URL page will not be displayed to the user and user will have access to the MAF feature. As with the URL you enter for Login URL, include a query parameter set to the client ID specified by the MCS MBE if you want create a login connection to an MCS MBE.-
Parse Token Relay Response – Select this checkbox to parse the login success URL JSON response for the OAuth token. Your MAF application uses the retrieved OAuth token to access secured services. Selecting this checkbox generates
<parseTokenRelayResponse value="true"/>in your application’sconnections.xmlfile.
-
-
Login Failure URL—Enter a URL to redirect the user to after unsuccessful authentication. Alternatively, when no failure URL exists, enter any URL.
As the browser loads the login failure URL, MAF first detects the error and returns control to the application. This is useful when the MAF application limits the number of user login attempts. In this case, MAF will redirect the user to the login failure URL after the user fails to authenticate by the last allowed attempt.
In the case where no failure URL exists, it is permissible to enter any URL. In this case, authentication will be terminated either when the user clicks Cancel on the login page or when login times out due to no user action for a given period of time (the inactivity timeout is two minutes).
Figure 27-12 Configuring the Authentication URLs
Description of "Figure 27-12 Configuring the Authentication URLs"
-
- Optionally, configure the connection that you just created so that the MAF application does not display the login URL to the end user when it renders the login page on Android or iOS devices. The following image shows two instances of the same login page where the display of the login URL is configured differently in each instance.
Add
<hideAddressBar value="true"/>to theconnections.xmlfile in theapplicationRootDir\.adf\META-INFdirectory for the connection, as shown by the following example, to hide the login URL.<Reference name="connectionName" className="oracle... ... <Contents> <login url="http://login.url.com:7777/fed_auth.html"/> ... <hideAddressBar value="true"/>Alternatively, you can update the connection at runtime by adding
&HideAddressBar::=trueto the configuration URL you pass as a parameter to theupdateSecurityConfigWithURLParametersmethod described in How to Update Connection Attributes of a Named Connection at Runtime.
How to Configure a Placeholder Connection for MAF Application Login
If all connection attributes for a MAF application login are not known at design time, use the AdfmfJavaUtilities.updateSecurityConfigWithURLParameters API to define a placeholder connection. Follow the steps in the task to configure a placeholder connection for definition at runtime.
As the figure shows, you can use the Create MAF Login Connection dialog to create a named connection during development and populate the login attributes to fully define the connection at runtime. This connection type is particularly useful when the connection attributes are not all known at design time.
Application developers must use AdfmfJavaUtilities.updateSecurityConfigWithURLParameters API to fully define the placeholder connection created at design time, as described in How to Update Connection Attributes of a Named Connection at Runtime.
Figure 27-13 Configuring a Placeholder Connection
Description of "Figure 27-13 Configuring a Placeholder Connection"
To configure a placeholder connection for definition at runtime:
How to Update Connection Attributes of a Named Connection at Runtime
The AdfmfJavaUtilities class provides the overrideConnectionProperty and updateSecurityConfigWithURLParameters methods to define or redefine the connection attributes of a connection that already exists: either by placeholder (when you select Specify Values at Runtime in the Create MAF Login Connection dialog) or by a fully populated connection definition.
Both methods must be invoked in conjunction with the clearSecurityConfigOverrides and updateApplicationInformation APIs that the AdfmfJavaUtilities class also provides. The updateSecurityConfigWithURLParameters method updates parameters required for authentication only. Additional parameters that a connection in connections.xml may specify cannot be updated using the updateSecurityConfigWithURLParameters method. Use overrideConnectionProperty to update all the non-authentication parameters as well as all the parameters that can be updated with updateSecurityConfigWithURLParameters.
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 in conjunction with the other methods shown in the following example:
AdfmfJavaUtilities.clearSecurityConfigOverrides(loginConnectionName);
AdfmfJavaUtilities.updateSecurityConfigWithURLParameters(configUrlParam, key, message, showConfirmation);
// Final step to apply the changes
AdfmfJavaUtilities.updateApplicationInformation(false);
The key parameter is set as a String object from the value defined for the adfCredentialStoreKey parameter in the connections.xml file. Use this key parameter in all references to the configuration, such as subsequent updates. 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.
The string value that you pass to the configUrlParam parameter must be UTF-8 encoded and formatted as follows:
String parameterString = "http://settings?" +
"&<Parameter Name1>::=<Parameter Value1>" +
"&<Parameter Name2>::=<Parameter Value2>" +
...
"&<Parameter NameN>::=<Parameter ValueN>";
For example, passing the following values to the configUrlParam parameter:
http://settings?AuthServerType::=HTTPBasicAuthentication
&ApplicationName::=Approvals
&LoginURL::=http://hostname.com:8008/OA_HTML/RF.jsp?function_id=mLogin
&LogoutURL::=http://hostname.com:8008/OA_HTML/RF.jsp?function_id=mLogout
&SessionTimeOutValue::=28800
&IdleTimeOutValue::=7200
&CryptoScheme::=PlainText
Requires you to create a URL as follows:
http://settings?AuthServerType::=HTTPBasicAuthentication&ApplicationName::=Approvals&LoginURL::=http%3A%2F%2Fhostname.com%
3A8008%2FOA_HTML%2FRF.jsp%3Ffunction_id%3DmLogin&LogoutURL::=http%3A%2F%2Fhostname.com%3A8008%2FOA_HTML%2FRF.jsp%3
Ffunction_id%3DmLogout&SessionTimeOutValue::=28800&IdleTimeOutValue::=7200&CryptoScheme::=PlainTextThe following examples demonstrates how you can override the default behavior of a specified connection used by the MAF application at runtime.
…
import oracle.adfmf.framework.api.AdfmfJavaUtilities;
import oracle.adfmf.framework.api.OverrideConstants;
…
// MAF applications on Android declare the default hostname verification process as STRICT. Override
// the default hostname verification process by passing a value of ALLOW_ALL.
AdfmfJavaUtilities.overrideConnectionProperty("connectionId", OverrideConstants.HOSTNAME_VERIFICATION_NODE,
OverrideConstants.HOSTNAME_VERIFICATION_ATTRIBUTE, "ALLOW_ALL");
// By default, MAF applications on Android remove all session cookies when a user logs out. To retain session cookies
// for a named connection, set REMOVE_ALL_SESSION_COOKIES_NODE to false, as demonstrated in the following example.
AdfmfJavaUtilities.overrideConnectionProperty("connectionId", OverrideConstants.REMOVE_ALL_SESSION_COOKIES_NODE,
OverrideConstants.REMOVE_ALL_SESSION_COOKIES_ATTRIBUTE, "false");
…
Note the following additional points about the updateSecurityConfigWithURLParameters and overrideConnectionProperty methods:
-
The
updateSecurityConfigWithURLParametersmethod persists the new configuration immediately whileoverrideConnectionPropertydoes not persist the configuration change until the next time the MAF application uses the login connection. For example, an end user navigates to a feature that is protected by the login connection and MAF shows the login view. -
You can use
overrideConnectionPropertyto reconfigure any top-level properties in a connection reference and connection references not limited to login connections in theconnections.xmlfile. TheupdateSecurityConfigWithURLParametersmethod can be only used to update login connections. -
Calls to
overrideConnectionPropertycalls are cumulative while calls toupdateSecurityConfigWithURLParametersreconfigure previous calls toupdateSecurityConfigWithURLParametersand result in a new login URL each timeupdateSecurityConfigWithURLParametersis called. The following example demonstrates how a sequence ofoverrideConnectionPropertycalls overrides the values of thelogin,logout, andaccessControlproperties for a connection namedMyLoginConnection.AdfmfJavaUtilities.clearSecurityConfigOverrides("MyLoginConnection"); AdfmfJavaUtilities.overrideConnectionProperty("MyLoginConnection", "login", "url", newLoginUrl); AdfmfJavaUtilities.overrideConnectionProperty("MyLoginConnection", "logout", "url", newLogoutUrl); AdfmfJavaUtilities.overrideConnectionProperty("MyLoginConnection", "accessControl", "url", newAccessControlUrl); AdfmfJavaUtilities.updateApplicationInformation(false); -
The second parameter value in
overrideConnectionProperty (String node)is the parameter named used in theconnections.xmlfile. For example, to update the following connection:<Reference name="remotePage" className="oracle.adf.model.connection.url.HttpURLConnection" xmlns=""> <Factory className="oracle.adf.model.connection.url.URLConnectionFactory"/> <RefAddresses> <XmlRefAddr addrType="remotePage"> <Contents> <urlconnection name=" remotePage_urlconnectionName " url="http://www.google.com"/> </Contents> </XmlRefAddr> </RefAddresses> </Reference>You call
overrideConnectionPropertyto change the URL as follows:overrideConnectionProperty("remotePage", "urlconnection", "url", "http://www.oracle.com");This is not the same parameter name as in
updateSecurityConfigWithURLParameters. Follow the URL construction pattern described above when usingupdateSecurityConfigWithURLParameters. Knowledge of the contents of theconnections.xmlfile is not required.
For 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.
For information about how to override a connection property value using overrideConnectionProperty, see How to Configure Login Credentials Programmatically Prior to Authentication. The ConfigServiceHandler.java in the ConfigServiceDemo sample application demonstrates how to invoke the overrideConnectionProperty method to override a number of connection properties. For information about the ConfigServiceDemo sample application, see MAF Sample Applications.
How to Store Login Credentials
Opt to have MAF store credentials, user name, and auto login so as to access the MAF application without having to log in. Use the AutoLogin option of the Create MAF Login Connection dialog to select credential storing options.
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 MAF application without having to login. The IDM Mobile SDKs enable MAF to support the following modes:
-
remember user name—MAF caches the user name and populates the username field of the login page. After the user enters the password and confirms by tapping the login button, MAF replays these credentials to the authentication server.
-
remember credentials—MAF caches the user credentials and populates the user name and password fields of the login page. After the user confirms these credentials by tapping the login button, MAF replays them to the authentication server.
-
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.
Note:
Users can decide whether MAF stores their credentials.
As the figure shows, you can use the AutoLogin page of the Create MAF Login Connection dialog 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 users.
What Happens When You Create a Connection for a MAF Application
Application connection information is available in the connections.xml file which can be bundled with the application. If the file is hosted for the Configuration Service, MAF checks for updated configuration information every time the application starts.
MAF aggregates all of the connection information in the connections.xml file (located in the Application Resources panel of the Applications window under the Descriptors and ADF 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, JDeveloper sets the adfCredentialStoreKey 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>
See Lookup Defined in the connections.xml File in Developing Fusion Web Applications with Oracle Application Development Framework.
What Happens When You Create a Multi-Tenant Aware Connection
When you create a multi-tenant aware connection, MAF sets the value of the <isMultiTenantAware> element to true in the connections.xml file.
After you complete the Create MAF Login Connection dialog with the Multi-Tenant Aware option enabled, MAF populates the connections.xml file with the <isMultiTenantAware> element set to true. In multi-tenant connection, the user name is the aggregation of tenant name and user name.
The login page uses a JavaScript utility to discern if a connection is multi-tenant aware. If the login page detects such a connection, it provides an additional field that requires the user to enter the tenant name configured in the Create MAF Login Connection, as shown in Figure 27-5. After a successful login (which includes entering the correct tenant ID), MAF stores the tenant ID in the local credential store.
What You May Need to Know About the Login Connection Configuration
When the login URL is defined in the connections.xml file or in a program, the URL must point to a web resource that
does not result in file transfer upon a request.
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.
What You May Need to Know About Multiple Identities for Local and Hybrid Login Connections
Within an application lifecycle, users can log in and log out using multiple identities in the local and hybrid login connection modes.
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. Because OAuth and Federate SSO use remote authentication, application users cannot log back into an application unless they authenticate successfully.
What You May Need to Know About Migrating a MAF Application and Authentication Modes
When a MAF application is migrated, ensure that the authentication mode
defined in the maf-feature.xml file is defined by the authenticationMode attribute in the connections.xml file.
When you migrate a MAF application, you must verify that the authentication mode defined in maf-feature.xml (such as <adfmf:feature id="feature1" name="feature1" credentials="remote">) is defined by the authenticationMode attribute in the connections.xml file. Use the audit rules of JDeveloper, which detect the presence of the credentials attribute, to assist you in removing it from maf-feature.xml.
Because the authenticationMode attribute in the connections.xml file can only be defined as either remote or local, do not migrate the value of none (<adfmf:feature id="feature1" name="feature1" credentials="none">), as doing so causes the deployment to fail.
What You May Need to Know About Custom Headers
When a MAF login connection is created and custom headers have been defined, the connections.xml file is populated with the customAuthHeaders element and individual header subelements. You can configure header values at runtime using the OverrideConnectionHandler API.
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 overrideConnectionProperty 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. For information about using the API to configure headers, see 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.
What Happens at Runtime: When MAF Calls a REST Web Service
When a MAF application calls a REST web service, MAF authenticates the user against the login server if the user has been authenticated locally. MAF executes the application request to the REST web service if the user is authenticated.
After a user is authenticated locally, MAF silently authenticates the user against the login server when the MAF application calls a REST web service. After the user's credentials are authenticated, MAF executes the application 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.
What You May Need to Know About Injecting Basic Authentication Headers
MAF injects a basic authentication header into HTTP requests to enable application features to access secure resources.
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 Authorization tab of the Create MAF Login Connection dialog 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>What You May Need to Know About Web Service Security
Although web services have no login pages, MAF injects the required credentials for access into the header of a web service call. The credentials injected are the credentials that MAF persists after they are used to log in to the authentication server.
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 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 REST web service connection must match the name defined for the adfCredentialStoreKey attribute of the login server. 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 the connections.xml file, you can use the Properties window to update the adfcredentialStoreKey attribute of the <Reference> element with the name configured for adfCredentialStoreKey attribute of the login server connection. Alternatively, you can add or update the attribute using the Source editor.
How to Configure Access Control
If an application contains secured components, configure it to implement and host Access Control Service. Follow the steps in the task to configure access control so that only the application features for which the user has authorization becomes available.
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. The figure shows the Authorization page of the Create MAF Login Connection dialog 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 About User Constraints and Access Control. For example, to allow only a user with manager_role role to access an application feature, you must define the <adfmf:constraints> element in the maf-feature.xml file with the following:
<adfmf:constraint property="user.roles" operator="contains" value="manager_role"/> </adfmf:constraints>
At the start of application, the RESTful web service known as the Access Control Service (ACS) is invoked for the application login server connection and the roles and privileges assigned to the user are then fetched. MAF then challenges the user to login against the application login server connection.
MAF evaluates the constraints configured for each application against the retrieved user roles and privileges and makes only the application features available to the user that satisfy all of the associated constraints.
To configure access control:
What You May Need to Know About the Access Control Service
The Access Control Service (ACS) is a REST 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 following example 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, as described in What You May Need to Know About Credential Injection.
You must implement and host the ACS service; MAF does not provide this service.
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 . 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 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 the invokeACS method, the AdfmfJavaUtilities class includes the following lifecycle methods:
-
applicationLogout—Logs out the application login connection. -
featureLogout(<feature_ID>)—Logs out the login connection associated with the application feature.
For information, see Java API Reference for Oracle Mobile Application Framework.
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 Create MAF Login Connection dialog but the values are to be supplied at runtime. To programmatically configure the connection details, the MAF application can invoke the overrideConnectionProperty 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 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 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 value element.
Note:
In the case of custom headers, do not use the XML elements header 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 a 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);
}
}Configuring Security for MAF Applications
Use the overview editors for the maf-feature.xml, and maf-application.xml files, and the Create MAF Login Connection dialog to configure security for MAF applications.
You configure security using the overview editors for the maf-feature.xml and maf-application.xml files, as well as the Create MAF Login Connection dialog. The overview 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.
How to Enable Application Features to Require Authentication
You can define each application feature to participate in security. You perform the security configuration using the Security page of the maf-application.xml overview editor.
The maf-feature.xml overview editor enables you to designate which application features participate in security.
Figure 27-16 Designating User Credentials Options for an Application Feature
Description of "Figure 27-16 Designating User Credentials Options for an Application Feature"
Before you begin:
When you enable security for a feature, the application requires access the network to authenticate the user. For information about granting the application access to network sockets, see Enabling a Core Plugin in Your MAF Application.
To designate user access for an application feature:
How to Designate the Login Page
After defining security for application features, use the Security page of the maf-application.xml overview editor to configure the login page, create a connection to the login server, and assign it to the application features for which security is enabled. Follow the steps in the task to designate the login page.
After you designate security for the application features, you use the Security page of the maf-application.xml overview editor, shown in the figure below, 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.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 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 MAF 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 refId="feature1" loginConnRefId="BasicAuthentication"/> <adfmf:featureReference refId="feature2" loginConnRefId="WebSSO"/>
MAF 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. See What You May Need to Know About Login Pages.
Note:
By default, all secured application features share the same connection, which, is denoted as <application login server>. The Properties window for a Feature Reference notes this default option in its Login Server Connection drop-down menu as <default> (application login server). You can select other connections that are defined for the MAF application using the Create MAF Login Connection dialog.
Figure 27-17 The Security Page of the maf-application.xml Overview Editor
Description of "Figure 27-17 The Security Page of the maf-application.xml Overview Editor"
Before you begin:
If the MAF 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 the figure below. See also How to Create a Custom Login HTML Page and What You May Need to Know About Selecting External Resources .
Add constraints for user privileges and roles, as described in About User Constraints and Access Control.
Provision an Access Control Service (ACS) server. See What You May Need to Know About the Access Control Service.
To designate the login page:
How to Create a Custom Login HTML Page
Modifying the default login page, adf.login.html, and artifacts generated by the MAF deployment in the www directory creates a custom login page.
Follow the steps in the task to create a custom login page, and to retrieve its location.
You can create the custom login page by modifying the default login page, adf.login.html, artifacts generated by the MAF deployment in the www directory.
Before you begin:
To access the login page within the www directory, deploy a MAF 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
For Android deployments, the page is 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
To create a custom login page:
- Copy the default login page to a location within the
public_htmldirectory of the user interface project, such asJDeveloper\mywork\application name\ApplicationController\public_html. - Rename the login page.
- Update the page.
- In the Security page for the overview editor of the
maf-application.xmlfile, select Custom and then click Browse to retrieve the location of the login page.
What You May Need to Know About Login Pages
When a feature registered with MAF is activated, the login process is executed. Upon successful authentication, the login page retrieves and navigates to the indicated destination.
The entry point for the authentication process to an application feature is the activate lifecycle event, described at Using Lifecycle Listeners in MAF Applications . 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.
If you want to use Java classes or resources, such as resource bundles, from your login page using the built-in Cordova support, you must place these classes and resources in the ApplicationController project.
The Default Login Page
The default login page provided by MAF is a cross-platform page, written in HTML, with fields for credentials.
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. The figure 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.
Figure 27-19 The Default Login Page with Multi-Tenant Domain Field
Description of "Figure 27-19 The Default Login Page with Multi-Tenant Domain Field"
The Custom Login Page
A custom login page has the authentication mechanism and navigation control that is identical to the default login
page. When a custom login page is added, JDeveloper adds the <adfmf:login> element and populates its child <adfmf:LocalHTML> element.
When you add a custom login page for a selected application feature using the overview editor for the maf-application.xml file, JDeveloper adds the <adfmf:login> element and populates its child <adfmf:LocalHTML> element, as shown in the following 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 the login page must include specifically defined <input> and <label> elements.
Tip:
Use the default login pages that are generated when you deploy a MAF application as a guide for creating custom login pages. To access the login pages within the www directory, deploy a MAF application and then traverse to the deploy directory, as described in How to Create a Custom Login HTML Page.
The following example 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"/>
What You May Need to Know About Login Page Elements
Every HTML login page should include the user interface elements listed in Table 27-2.
Table 27-2 Login Page Fields and Their Associated IDs
| Page Element | ID |
|---|---|
|
username field |
|
|
password field |
|
|
login button |
|
|
cancel button |
|
|
identity domain/tenant name field |
|
|
error field |
|
|
auto login checkbox |
|
|
remember credentials checkbox |
|
|
remember username checkbox |
|
Table 27-3 lists the recommended JavaScript code used by the OnClick event.
Table 27-3 JavaScript Used by the OnClick Event
| Button | JavaScript |
|---|---|
|
login button |
|
|
cancel button |
|
What Happens in JDeveloper When You Configure Security for Application Features
For every application feature with security enabled, JDeveloper adds a corresponding feature reference in the Features With Security Enabled table.
After an application feature has been designated to participate in security, JDeveloper updates the Features With Security Enabled table with a corresponding feature reference. If each of the referenced application features authenticate against the same login server connection defined in the connections.xml file, JDeveloper 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 JDeveloper updates each referenced application feature with a loginConnReference attribute (<adfmf:featureReference refId="feature2" loginConnRefId="Connection2"/>). See How to Enable Application Features to Require Authentication. See also Tag Reference for Oracle Mobile Application Framework.
Allowing Access to Device Capabilities
Access to device capabilities is defined by the Cordova plugins that are included in the MAF application. Enabling one of the core plugins provided by MAF enables any device access permissions that the application 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).
You can prevent selected application features within a MAF application from accessing the native container, and by extension, the device capabilities that the MAF application can access. For example, your MAF application includes an application feature that references remote content from a web application that you do not trust (Remote URL content application feature). In this scenario, you prevent this specific application feature from accessing the native container, as shown in the following example:
<adfmf:featureReference refId="remoteAppfeature1" id="fr1" allowNativeAccess="false"/>The default value of the allowNativeAccess property is true.
For information about Cordova plugins in MAF applications, see Using Plugins in MAF Applications .
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 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:
-
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 information about the AdfmfJavaUtilties class and the usage of the key parameter, see Java API Reference for Oracle Mobile Application Framework.
Using MAF Authentication APIs
MAF provides a number of authentication classes that include APIs to assist you with authentication-related tasks in your MAF application.
These APIs reside in the authentication classes of the oracle.maf.api.authentication package. Examples include the AuthenticationHandler, AuthenticationPlatform, and AuthenticationUtility classes.
Tasks that you can perform by implementing these APIs include processing for a logged-in user before the user accesses a secured application. You can, for example, retrieve authorization header information and use the information to determine what content an end user navigates to upon a successful login. AuthenticationPlatform also provides an addLogoutCallback API that you can implement to perform some processing once an end user logs out from a secured application feature. Use of this callback API may be useful in scenarios where your end users share a device.
The following example shows snippets of code from an implementation class where an instance of AuthenticationPlatform gets the authorization header information using its getToken() API.
Example 27-1 Getting the Authorization Header from the Authentication Platform
import oracle.maf.api.authentication.AuthenticationPlatform;
import oracle.maf.api.authentication.AuthenticationUtility;
…
AuthenticationPlatform ap = AuthenticationUtility.getInstance().lookupByCredentialStoreKey("credentialStoreKey");
String authorization = ap.getToken("Authorization");
…
For information about these authentication classes, see the Java API Reference for Oracle Mobile Application Framework.
Creating Certificates to Access Servers That Use Self-Signed Certificates for SSL
A cacerts file in MAF enables deployment by identifying certificates from trusted sources. Follow the steps in the task to add private certificates to the MAF cacerts file when an application needs access to resources in a server that uses a self-signed certificate, or when an application needs custom certificates.
MAF provides a cacerts certificate file, the Java mechanism for HTTPS handshakes between the client application and the server. JDeveloper creates this file within the Application Resources Security folder (located at JDeveloper\mywork\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.
You need to add private certificates to the MAF cacerts file when your application has to access server resources where the server uses a self-signed certificate. You also need to add a private certificate if your application requires custom certificates, such as cases where RSA cryptography is not used. Add a private certificate before you deploy the application. Users of your MAF application can install certificates if you configure your MAF application to facilitate the installation of certificates, as described in Registering SSL Certificate File Extensions in a MAF Application.
Before you begin:
It may be helpful to have an understanding of the contents of the cacerts file. See Migrating to New cacerts Files for SSL in MAF in Installing Oracle Mobile Application Framework.
You may also find it helpful to understand how JDeveloper creates the cacerts file. See About the Application Controller Project-Level Resources.
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
cacertsfile (cp cacerts cacerts.org). -
Use the Java SE keytool utility to add certificates to a
cacertsfile. The following example illustrates adding a single certificate to acacertsfile callednew_cert.keytool -importcert -keystore cacerts -file new_cert -storepass changeit -nopromptRepeat this procedure for each certificate. Table 27-4 lists the keytool options
Table 27-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 common name (CN) of the certificate must match the hostname exactly.
-
Ensure that the customized certificate file is located within the
Securitydirectory (JDeveloper\mywork\application name\resources\Security) so that it can be read by the JVM.
-
-
Deploy the application.
Note:
During deployment, if a certificate file exists within the
Securitydirectory, 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.
Registering SSL Certificate File Extensions in a MAF Application
MAF application end users can install digital certificates into their application’s keystore for use in SSL communication. You register file extensions to facilitate the installation of these certificate(s).
If the MAF application is the only application on the device to register the file extension, it will be the application that the device’s operating system proposes to the end user to open a certificate file that is distributed to the end user (by email attachment or download URL). If other applications register the file extension, the device’s operating system presents a list of applications from which your end user must choose the MAF application to install the certificate into their application’s keystore.
Note that some versions of supported platforms where the MAF application runs may treat certificate files as text files if the files are saved in a Base64 text format (for example, .PEM) and open the files as text files instead of prompting the end user to install the certificate. We recommend that you use a binary format (for example, .DER) instead of a Base64 text format to avoid this issue.
MAF supports the registration of file extensions for both server SSL and client SSL certificates. Users may need to restart their MAF application after installing a certificate.
Server SSL Certificate Extension
A server SSL certificate identifies the remote HTTPS server that your MAF application connects to. Register a server SSL certificate file extension to facilitate the installation of a certificate that is not in the cacerts file that MAF provides when you create a MAF application. This scenario frequently occurs when the HTTPS server that your MAF application connects to uses a self-signed certificate rather than a certificate issued by a root certificate authority. MAF currently supports the installation of server SSL certificates in MAF applications deployed to the Android and iOS platforms. This is not supported in MAF applications deployed to the Universal Windows Platform. For this platform, add the certificate to the cacerts file of the MAF application, as described in Creating Certificates to Access Servers That Use Self-Signed Certificates for SSL.
Client SSL Certificate Extension
A client certificate identifies a MAF application to a remote server. Register a client SSL certificate extension when you want users to install a client certificate into the keystore of the MAF application to enable authentication using a process known variously as two-way SSL, mutual authentication or two-way authentication. Once the user installs the client certificate, the MAF application can present it to a server so that a two-way SSL communication session performs authentication between the client and the server.
The iOS platform does not permit third party applications to open files with the default extension for client certificates (.p12). To work around this restriction, you (the application developer) must register an alternative certificate extension (for example, .cert). Administrators who distribute the certificates can rename the client certificate files to use the alternative extension so that the MAF application user can open the client certificate directly from the email attachment or URL used to distribute the client certificate.
How to Register an SSL Certificate File Extension
You register a certificate file extension in your application by entering the file extension in the appropriate field (depending on your use case) on the Application page of the overview editor of the maf-application.xml file.
To configure a MAF application to enable two-way SSL:
-
In the Applications window, expand the Application Resources panel.
-
In the Application Resources panel, expand Descriptors and then ADF META-INF.
-
Double-click the maf-application.xml file and in the overview editor that appears, click the Application navigation tab.
-
In the Application page, select the appropriate option:
-
Enter the file extension in the Client SSL Certificate Extension field if you want to facilitate the installation of a client certificate for use in a two-way SSL session.
-
Enter the file extension in the Server SSL Certificate Extension field if you want to facilitate the installation of a server certificate that your MAF application uses to connect to a HTTPS server.
-
What Happens When You Register an SSL Certificate File Extension
JDeveloper writes the value that you enter in the input fields to the maf-application.xml file, as shown in Example 27-2.
At runtime, the user downloads the certificate(s) to the device from the location where the administrator put the certificate or opens it automatically from an email attachment. The download behavior from a server location depends on the operating system of the user’s device. For example, a MAF application user with an Android device downloads the certificate to the Android Download directory. Once downloaded, the user extracts (opens) the certificate in order to install it to the keystore of the MAF application. To complete this step for a client certificate, the user must enter a password provided by the administrator who distributed the client certificate. After the user has installed a client certificate in the keystore of the application, the MAF application can present it to a server to establish a two-way SSL session. A server certificate that an user installs can be used by the MAF application to establish an SSL session with a HTTPS server.
Example 27-2 Certificate File Extensions in maf-application.xml File
<adfmf:application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:adfmf="http://xmlns.oracle.com/adf/mf"
version="1.0" name="ssltest" id="com.company.ssltest"
appControllerFolder="ApplicationController" listener-class="application.LifeCycleListenerImpl"
client-ssl-certificate-extension="clientcert"
server-ssl-certificate-extension="servercert">
….