Friday Oct 25, 2013

Using the OAM Mobile & Social SDK to secure native mobile apps - Part 2 : OAM Mobile & Social Server configuration

Objective 
In the second part of this blog post I'll now cover configuration of OAM to secure our sample native apps developed using the iOS SDK. First, here are some key server side concepts:
  • Application Profiles: An application profile is a logical representation of your application within OAM server. It could be a web (html/javascript) or native (iOS or Android) application. Applications may have different requirements for AuthN/AuthZ, and therefore each application that interacts with OAM Mobile & Social REST services must be uniquely defined.
  • Service Providers: Service providers represent the back end services that are accessed by applications. With OAM Mobile & Social these services are in the areas of authentication, authorization and user profile access. A Service Provider then defines a type or class of service for authentication, authorization or user profiles. For example, the JWTAuthentication provider performs authentication and returns JWT (JSON Web Tokens) to the application. In contrast, the OAMAuthentication also provides authentication but uses OAM SSO tokens

  • Service Profiles:  A Service Profile is a logical envelope that defines a service endpoint URL for a service provider for the OAM Mobile & Social Service. You can create multiple service profiles for a service provider to define token capabilities and service endpoints. Each service provider instance requires atleast one corresponding service profile.The  OAM Mobile & Social Service includes a pre-configured service profile for each pre-configured service provider.

  • Service Domains: Service domains bind together application profiles and service profiles with an optional security handler.

    So now let's configure the OAM server. Additional details are in the OAM Documentation and this post simply provides an outline of configuration tasks required to configure OAM for securing native apps. 

    Configuration 

    Create The Application Profile

    Log on to the Oracle Access Management console and from System Configuration -> Mobile and Social -> Mobile Services, select "Create" under Application Profiles. You would do this  step twice - once for each of the native apps - AvitekInventory and AvitekScheduler. Enter the parameters for the new Application profile:

    • Name:  The application name. In this example we use 'InventoryApp' for the AvitekInventory app and 'SchedulerApp' for the AvitekScheduler app. The application name configured here must match the application name in the settings for the deployed iOS application.
    • BaseSecret: Enter a password here. This does not need to match any existing password. It is used as an encryption key between the client and the OAM server. 
    • Mobile Configuration: Enable this checkbox for any mobile applications. This enables the SDK to collect and send Mobile specific attributes to the OAM server. 
    • Webview: Controls the type of browser that the iOS application will use. The embedded browser (default) will render the browser within the application. External will use the system standalone browser. External can sometimes be preferable for debugging
    • URLScheme: The URL scheme associated with the iOS apps that is also used as a custom URL scheme to register O/S handlers that will take control when OAM transfers control to device. For the AvitekInventory and the AvitekScheduler apps I used osa:// and client:// respectively. You set this scheme in Xcode while developing your iOS Apps under Info->URL Types. 
    • Bundle Identifier : The fully qualified name of your iOS application. You typically set this when you create a new Xcode project or under General->Identity in Xcode. For the AvitekInventory and AvitekScheduler apps these were com.us.oracle.AvitekInventory and com.us.oracle.AvitekScheduler respectively

    Create The Service Domain

    Select create under Service domains. Create a name for your domain (AvitekDomain is what I've used). The name configured must match the service domain set in the iOS application settings. Under "Application Profile Selection" click the browse button. Choose the application profiles that you created in the previous step one by one. Set the InventoryApp as the SSO agent (with an automatic priority of 1) and the SchedulerApp as the SSO client. This associates these applications with this service domain and configures them in a 'circle of trust'. 

    Advance to the next page of the wizard to configure the services for this domain. For this example we will use the following services: 

    • Authentication:   This will use the JWT (JSON Web Token) format authentication provider. The iOS application upon successful authentication will receive a signed JWT token from OAM Mobile & Social service. This token will be used in subsequent calls to OAM. Use 'MobileOAMAuthentication' here.

    • Authorization:  The authorization provider. The SDK makes calls to this provider endpoint to obtain authorization decisions on resource requests. Use 'OAMAuthorization' here.

    • User Profile Service:  This is the service that provides user profile services (attribute lookup, attribute modification). It can be any directory configured as a data source in OAM. 

    And that's it! We're done configuring our native apps. In the next section, let's look at some additional features that were mentioned in the earlier post that are automated by the SDK for the app developer i.e. these are areas that require no additional coding by the app developer when developing with the SDK as they only require server side configuration:

    Additional Configuration 
    Offline Authentication

    Select this option in the service domain configuration to allow users to log in and authenticate to the application locally. Clear the box to block users from authenticating locally.

    Strong Authentication

    By simply selecting the OAAMSecurityHandlerPlugin while configuring mobile related Service Domains, the OAM Mobile&Social service allows sophisticated device and client application registration logic as well as the advanced risk and fraud analysis logic found in OAAM to be applied to mobile authentication. Let's look at some scenarios where the OAAMSecurityHandlerPlugin gets used.

    First, when we configure OAM and OAAM to integrate together using the TAP scheme, then that integration kicks off by selecting the OAAMSecurityHandlerPlugin in the mobile service domain. This is how the mobile device is now prompted for KBA,OTP etc depending on the TAP scheme integration and the OAM users registered in the OAAM database. Second, when we configured the service domain, there were claim attributes there that are already pre-configured in OAM Mobile&Social service and we simply accepted the default values- these are the set of attributes that will be fetched from the device and passed to the server during registration/authentication as device profile attributes. When a mobile application requests a token through the Mobile Client SDK, the SDK logic will send the Device Profile attributes as a part of an HTTP request. This set of Device Profile attributes enhances security by creating an audit trail for devices that assists device identification. When the OAAM Security Plug-in is used, a particular combination of Device Profile attribute values is treated as a device finger print, known as the Digital Finger Print in the OAAM Administration Console. Each finger print is assigned a unique fingerprint number. Each OAAM session is associated with a finger print and the finger print makes it possible to log (and audit) the devices that are performing authentication and token acquisition. Finally, if the jail broken option is selected while configuring an application profile, the SDK detects a device is jail broken based on configured policy and if the OAAM handler is configured the plug-in can allow or block access to client device depending on the OAAM policy as well as detect blacklisted, lost or stolen devices and send a wipeout command that deletes all the mobile &social relevant data and blocks the device from future access.

    Social Logins

    Finally, let's complete this post by adding configuration to configure social logins for mobile applications. Although the Avitek sample apps do not demonstrate social logins this would be an ideal exercise for you based on the sample code provided in the earlier post. I'll cover the server side configuration here (with Facebook as an example) and you can retrofit the code to accommodate social logins by following the steps outlined in "Invoking Authentication Services" and add code in LoginViewController and maybe create a new delegate - AvitekRPDelegate based on the description in the previous post.

    So, here all you will need to do is configure an application profile for social login, configure a new service domain that uses the social login application profile, register the app on Facebook and finally configure the Facebook OAuth provider in OAM with those settings. Navigate to Mobile and Social, click on "Internet Identity Services" and create a new application profile. Here are the relevant parameters for the new application profile (-also we're not registering the social user in OAM with this configuration below, however that is a key feature as well):

    • Name:  The application name. This must match the name of the of mobile application profile created for your application under Mobile Services. We used InventoryApp for this example.

    • SharedSecret: Enter a password here. This does not need to match any existing password. It is used as an encryption key between the client and the OAM Mobile and Social service. 

    • Mobile Application Return URL: After the Relying Party (social) login, the OAM Mobile & Social service will redirect to the iOS application using this URI. This is defined under Info->URL type and we used 'osa', so we define this here as 'osa://'

    • Login Type: Choose to allow only internet identity authentication for this exercise.

    • Authentication Service Endpoint : Make sure that /internetidentityauthentication is selected.

    Login to http://developers.facebook.com using your Facebook account and click on Apps and register the app as InventoryApp. Note that the consumer key and API secret gets generated automatically by the Facebook OAuth server. Navigate back to OAM and under Mobile and Social, click on "Internet Identity Services" and edit the Facebook OAuth Provider. Add the consumer key and API secret from the Facebook developers site to the Facebook OAuth Provider:

    Navigate to Mobile Services. Click on New to create a new service domain. In this example we call the domain "AvitekDomainRP". The type should be 'Mobile Application' and the application credential type 'User Token'. Add the application "InventoryApp" to the domain. Advance the next page of the wizard. Select the  default service profiles but ensure that the Authentication Service is set to 'InternetIdentityAuthentication'. Finish the creation of the service domain.


    Tuesday Oct 15, 2013

    Using the OAM Mobile & Social SDK to secure native mobile apps - Part 1 - iOS SDK

    Introduction

    In this blog post I'll try to demystify a key strategic area for our customers--i.e. securing mobile native apps with Oracle Access Manager using the mobile client SDK. I recently delivered both a session and a HOL (hands on lab) at OOW 2013 here in San Francisco on the same topics and this blog post is an attempt to provide more detail in those areas.

    I have planned this post in two parts. In this first part I'll cover client side development using the SDK and in the second part I'll cover the required server side configuration that needs to be performed in conjunction with using the client side SDK.  Also, while this post uses the iOS SDK to secure native iOS apps, the same concepts apply while securing mobile native apps on the android platform for which we released android SDK support with OAM R2PS1 in the middle of this year. I conducted a workshop for our sales consultants then about using the android SDK and maybe I can figure out a way to release those contents here later as well. Finally, all the source code for the sample apps that we will use in this post is available for download along with an attached viewlet that you can download here: https://www.dropbox.com/sh/6tc7vxyn9zn43an/JloXNybqN_

    Why use the SDK?

    Aside from making your job easier to retrofit your apps with externalizing security to Oracle Access Manager,  the SDK was built to basically help you with automating certain tasks when you're looking to secure your mobile apps specifically:

    • Accessing and sending mobile device context information
    • Managing client side security data (keys, tokens)
    • Single Sign On (Native app - Native app OR  Browser - Native App)
    • Strong Authentication (KBA, OTP)
    • Offline Authentication
    • Social Logins

    Developing with the iOS SDK

    Invoking Authentication Services

    Using the OAM M&S SDK for authentication services listed above is actually quite straightforward and essentially consists of five basic steps that can be divided into two categories:

    1. Methods called on the SDK by the calling application : The calling application invokes three methods on the SDK to perform these three tasks- initialize, setup and authenticate.
    2. Methods called back by the SDK to return control back to the calling application : The calling application implements two methods that are called back by the SDK to return control back to the calling application: for post processing after setup and post processing after authenticate respectively.

    We will now use code snippets from the sample AvitekInventory app throughout the blog post to demonstrate using the SDK. 

    Initialize

    The first step is to create an object of OMMobileSecurityService and initialize the iOS SDK by providing required OAM Mobile and Social server details. This is done by the calling application invoking the initWithProperties:delegate: instance method that returns a MobileSecurityService object initialized using the properties set in a dictionary. 

    LoginViewController.h : 


    @property (strong,nonatomic) OMMobileSecurityService *mss;

    LoginViewController.m: 

    oamDelegate = [[AvitekOAMDelegate allocinit];

    self.mss = [[OMMobileSecurityService allocinitWithProperties:sdkProps delegate:oamDelegate];

    Here, oamDelegate is an instance of AvitekOAMDelegate, the delegate class that implements callback methods that are invoked by the SDK for post processing after setup and authentication respectively. The sdkProps parameter is an NSMutableDictionary object that contains properties that represent OAMMS server side configuration details such as service Domain, application profile and server url.

    Setup

    Next, the calling program invokes setup on the SDK. 

    LoginViewController.m:

    [self.mss setup];

    The setup method downloads and stores the configured server side security policies and application profile for this app from OAM. The iOS client SDK will not download the application profile from the server on subsequent setup invocations until the ProfileCacheDuration setting defined in the application profile on the server has expired.

    The setup invocation is an asynchronous invocation and on completion the iOS client SDK calls the didReceiveApplicationProfile:error: instance method on the delegate which returns an NSDictionary object that contains the application profile details from the server.

    AvitekOAMDelegate.m:

    - (void)didReceiveApplicationProfile: (NSDictionary *)applicationProfile error: (NSError *)error

    Authenticate

    Finally, we are ready to start the authentication process.

    LoginViewController.m:

    authReq = [[OMAuthenticationRequest alloc] init];

    [self.mss startAuthenticationProcess:authReq presenterViewController:self];

    The startAuthenticationProcess:presenterViewController instance method takes an authentication request (OMAuthenticationRequest) object that represents a custom view and the presenterViewController to display the viewcontroller that collects the user's name and password. If the customized login view properties (kbaView and authView) are not passed with the authentication request object, the SDK will throw a default login and KBA view.  The SDK starts the authentication process with OAM server and calls back the delegate's didFinishAuthentication:error: method when it's done.

    AvitekOAMDelegate.m:

    - (void)didFinishAuthentication: (OMAuthenticationContext *)context error: (NSError *)error 

    LoginViewController.m

    // load the next view

    retail = [[RetailStoreViewController alloc]init];

    retail.mss = self.mss;

    [self.navigationController pushViewController:retail animated:true];

     The delegate method returns an OMAuthenticationContext that contains details about the authentication token. On successful authentication, we are now ready --and our sample AvitekInventory app simply loads the next "business login screen" by pushing the RetailStoreViewController on the NavigationController stack.

    Offline Authentication 

    OAM Mobile & Social added support for offline authentication in R2PS1. Using this feature is easy. This feature requires that first the "Offline Authentication" setting is enabled in the Application Profile in the OAM Admin Console. Next, while starting the authentication process with the SDK using the startAuthenticationProcess:presenterViewController: method above, set a property called 'connectivityMode' on the OMAuthenticationRequest object which accepts values from the enum OMConnectivityMode and provides options to basically authenticate locally with cached credentials either always or only if the server is unreachable or simply allow authentication only with the server and fail if the server is unreachable. 

    Single Sign On

    I'll describe Single Sign On in this section as it pertains to native mobile apps participating in single sign on. For Mobile SSO to work, an application installed on the mobile device needs to be designated as the Mobile SSO agent app. The other applications on the mobile device that need to authenticate with OAM are considered as client apps that are configured in a circle of trust in the common Service Domain on the OAM server. The Mobile SSO client apps always authenticate via the agent app that serves as a proxy between OAM and themselves. The Mobile SSO client apps get the benefit  of not having to build authentication/KBA, device registration functionality while getting the benefit of mobile single sign on as the SDK utilized by the agent app automatically handles their sessions including the ability to time-out idle sessions, manage global logout and assist with device selective wipe-outs ( if the OAAM Security Handler plugin is selected in the server side configuration).

    In our case, AvitekInventory is the agent app and AvitekScheduler is the client app. First, let's look at the client app. From our client app perspective, it uses the SDK in the exact same manner as described in the earlier sections - i.e. it simply invokes initialize, setup and authenticate and implements delegates for postprocessing during setup and during authentication. The difference is that since this app is configured as a client on the OAM server, all authentication requests are automatically sent by the SDK to the agent app which makes the necessary acquisitions (access token, registration handle and user token) on behalf of the client app from the OAM server.

    So, the AvitekScheduler's usage of the SDK below should look very familiar and straightforward:

    AvitekScheduler

    LoginViewController.m:

    //initialize and setup

    self.mss = [[OMMobileSecurityService alloc] initWithProperties:sdkProps delegate:self];

    [self.mss setup];

    //authenticate

    authReq = [[OMAuthenticationRequest allocinit];

    [self.mss startAuthenticationProcess:authReq presenterViewController:self];

    //implement delegate for post setup

    -(void) didReceiveApplicationProfile: (NSDictionary *)applicationProfile error: (NSError *)error

    //implement delegate for post authentication processing; load business logic screen

    -(void) didFinishAuthentication: (OMAuthenticationContext *)context error: (NSError *)error

    {

    ...

    scheduler = [[SchedulerViewController alloc]init];

    scheduler.mss = self.mss;

    [self.navigationController pushViewController:scheduler animated:true];

    Now, let's look at our AvitekInventory agent app.  

    AvitekInventory

    LoginViewController.m:

    First, we parse the incoming request URL (i.e. from the client app) and populate a dictionary with query parameter name and values using the parseURL:fromApp: method. We then initialize and setup and instance of the SDK for the agent app that will be later used to process SSO requests from the client.

    (void) handleRequestWithURL: (NSURL *) url bundleID: (NSString *) appBundleID

    {

    NSDictionary *params = [self.mss parseURL:url fromApp:appBundleID];

    if ([self.mss isSSORequest:params]) {

    NSLog(@"SSO request received in class with MSS object");

    ssoURL = url;

    ssoAppID = appBundleID;

    ssoDelegate = [[AvitekSSODelegate alloc]init];

    ...

    self.mss = [[OMMobileSecurityService alloc]initWithProperties:sdkProps delegate:ssoDelegate];

    [self.mss setup];

    }

    Next, when the client app (AvitekScheduler) invokes setup, the SDK invokes the agent app and so here in the agent app we invoke processSSORequest:presenter: on the SDK to process the authentication request.

    //process SSO request i.e start authentication process for SSO client

    -(void) ssoProfileDownloaded

    {

    queryParams = [self.mss parseURL:ssoURL fromApp:ssoAppID];

    [self.mss processSSORequest:queryParams presenter:self];

    }

    The SDK in the agent app starts the authentication process with OAM server on behalf of the client app and calls back the delegate's didFinishAuthentication:error: method when it's done.

    AvitekSSODelegate.m:

    - (void)didFinishAuthentication: (OMAuthenticationContext *)context error: (NSError *)error

    {

    NSLog(@"SSO finish authentication\nUser : %@\n Error : %@",

      context.userName,error.localizedDescription);

      self.ctx = context;

      self.err = error;

      NSNotificationCenter *notificationCenter = [NSNotificationCenter defaultCenter];

     [notificationCenter postNotificationName:@"SSO Finish Authentication" object:nil];

    LoginViewController.m:

    - (void)viewDidLoad

    {

     [super viewDidLoad];

     // Do any additional setup after loading the view from its nib.

      ... 

    NSNotificationCenter *notificationCenter = [NSNotificationCenter defaultCenter];

    [notificationCenter addObserver:self selector:@selector(ssoFinishAuth) name:@"SSO Finish Authentication" object:nil];

    ...

    // dismiss the SDK screen; complete the SSO request and the response is sent to the SSO client

    -(void) ssoFinishAuth

    {

    [self dismissViewControllerAnimated:true completion: nil];

    [self.mss completeSSORequest:queryParams presenter:self error:ssoDelegate.err];

    }

    This delegate implementation above processes the request and via notification allows the SSO agent to invoke the completeSSORequest:presenter:error: on the SDK. The SDK checks whether the client app is registered and sends the response back to the calling client app.

    Social Login

    Relying Party authentication (i.e. the ability to enable your app to use Facebook, LinkedIn, Google etc as OAuth or OpenID providers thus allowing for social logins) is identical to invoking authentication services as outlined above. The configuration for this is done entirely on the server side. There really is only one caveat and that is that if the same app authenticates against different OAM servers or with the same OAM server but different authentication schemes, then one OMMobileSecurityService instance should be created for each server or authentication scheme. So, for example, in this case, since the same AvitekInventory app authenticates against OAM server and Facebook for different use cases, we create separate instances of OMMobileSecurityService to handle each use case.

    Strong Authentication 

    From an app perspective and the perspective of a mobile app developer, there are no additional development tasks that are required to enable your app  for KBA/OTP based strong authentication or collecting and sending mobile device context information for this purpose. The SDK automates all of this and this is enabled via server side configuration.

    About

    Kanishk Mahajan is a Principal Product Manager in Oracle Identity Management with product responsibility within the Oracle Access Management suite

    Search

    Categories
    Archives
    « April 2014
    SunMonTueWedThuFriSat
      
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
       
           
    Today