53.7 Configuring Mobile OAuth for SSO Servlet Authentication

The Mobile OAuth SSO Servlet makes it possible to use a device-native app as a single sign-on proxy app when a user signs on to an app running in a mobile browser (external or embedded) in a 2-legged flow.

In this arrangement, the native app implements the login page and uses Mobile and Social Services to authenticate with Oracle Access Management. You can configure this authentication scheme to try multiple native apps on the device. If the first app does not respond within a half second (500ms) the servlet redirects the browser to the next app in the order that the apps are listed. If the servlet gets to the end of the list and there is not an application installed with the specified client ID, the servlet re-directs the user to the OAM login page. Similarly, if the request is received from a desktop browser, the request is forwarded to the OAM login page.

Following is a description of the Mobile SSO Servlet authentication flow:

The user opens a URL in a mobile browser.
The web server hosting the application redirects the browser to OAM.
Access Manager redirects the browser to the native app on the device.
The browser launches the native app in response to the redirect.
The native app displays the user login page.
The user enters a user name and password.
The native app does a 2-legged device registration flow. It collects user credentials, does device registration, and gets the client token. If server-side single sign-on is enabled, the user token is stored on the server and is not returned to the client. If server-side single sign-on is turned off, the user token is returned to the client.
The native app exchanges the client token and user token for the OAM master token (OAM_ID). (If server-side single sign-on is enabled, the user token is exchanged from the server-side keystore.)
The native app directs the browser to the Oracle Access Management Mobile and Social server, which injects the OAM master token as a cookie.
The native app sends the mobile browser a URL redirect and OAM master token as a cookie.
The mobile browser opens the original URL now that the access request includes an OAM master token.
The web server sends the requested pages to the mobile browser.

The following sections contain the configuration steps.

For information about Mobile OAuth SSO options, see Understanding Mobile OAuth Services Server-Side Single Sign-on.

53.7.1 Configuring OAM and Your App to use the Mobile SSO Servlet

You can configure OAM and your App to use the Mobile OAuth Services single sign-on authentication scheme.

You need to complete the following configuration tasks:

In the Oracle Access Management console, protect the Web resource(s) with an OAM WebGate. To learn how, see Registering and Managing OAM 11g Agents.
In Access Manager, create a custom MobileSSOServlet authentication scheme on the OAM server and configure it with a list of mobile application IDs. Then configure the authentication scheme in OAM to protect the Web resource(s). To learn how, see Configuring the MobileSSOServlet Authentication Scheme.
If necessary, register the native mobile app client with Mobile OAuth Services. To register the native mobile app client with OAuth Services see Configuring Clients.
In Mobile OAuth Services, assign the Resource Owner grant type to the native mobile app(s) that will be configured to serve as single sign-on proxies. This grant type is required to be able to perform the 2-legged client registration.

To assign the client the Resource Owner grant type, use the OAuth Services Mobile Clients configuration page. For more information, see Mobile Clients Configuration Page.
To code the device-native app to authenticate with OAM using Mobile and Social Services, refer to the following sections in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management:
- For iOS, see "Invoking Authentication Services With the iOS Client SDK."
- For Android, see "Invoking Authentication Services With the Android Client SDK."
- For the REST API, see "Mobile and Social Services REST Reference: Authentication and Authorization."
When coding the app(s), implement the /authenticate endpoint, which is required to use this feature. This endpoint provides client registration, OAM token exchange, and URL redirection to the MobileSSOServlet. The /authenticate endpoint should accept a resource URL (resource_url) and Return URL (http://<OAM-HOST>:<OAM-PORT>/ms_oauth/mobilesso) as parameters.

Once the app completes registration and the OAM token exchange, it returns control of the authentication process (along with the OAM_ID and resource_url) using the value of the return_url that was sent to /authenticate endpoint. Redirect the app back to the MobileSSOServlet using this URL:
```
/mobilesso?OAM_ID=1234&resource_url=http://<OAM-host>:7777/index.html
```
where:
- OAM_ID = the OAM master token value
- resource_url = URL of the resource
In this case, the redirect URL used to redirect the app back to the MobileSSOServlet will be http://<OAM-HOST>:<OAM-PORT>/ms_oauth/mobilesso?OAM_ID=1234&resource_url=http://<OAM-host>:7777/index.html

53.7.2 Configuring the MobileSSOServlet Authentication Scheme

You can configure a new authentication scheme (MobileSSOServlet authentication scheme) in Access Manager to protect the Web resource(s).

Use these steps to configure a new MobileSSOServlet authentication scheme:

Log on to the Oracle Access Management Administration Console.

The Application Security Launch Pad opens.
Under Access Manager click Authentication Schemes, then click the Create Authentication Scheme button.

The "Create Authentication Scheme" tab opens.
Create a new Authentication Scheme by completing the form as follows:
- Name: MobileSSO-OAuth
- Authentication Level: 2
- Challenge Method: FORM
- Challenge Redirect URL: /oam/server/
- Authentication Module: LDAP
- Challenge URL: /mobilesso
- Context Type: customWar
- Context Value: /ms_oauth/
- Challenge Parameters:
```
applications=TestApp1,TestApp2
serviceEndPoint=oauthservice
```
Description of the illustration GUID-E7EE252F-FD65-4660-9C15-05D2F3058436-default.png
In the Oracle Access Management Administration Console, do the following:
1. Create a new Authentication Policy in an Application Domain and assign it the following Authentication Scheme:
  
  Authentication Scheme: MobileSSO-OAuth
  
  (MobileSSO-OAuth is the scheme that was created in step one.)
2. Create an HTTP Resource, for example /mobileoauthapp, and protect the resource using the created Authentication Scheme (MobileSSO-OAuth). This is the URI that will be accessed from the mobile web browser (mobile Safari for iOS) and protected by a WebGate.