Skip to Content

This guide describes how to use HttpConversationManager and HttpConvAuthFlows libraries for implementing request, response, and challenge filters when developing native iOS OData apps with the SAP Mobile Platform SDK version 3.0 SP07 and later.

The iOS HttpConversationManager is an iOS networking library that enables sending and receiving of HTTP requests and responses between an iOS app and server securely, and is built on top of NSURLSession and related classes, extending the high-level abstractions built into CocoaTouch to meet SAP OData framework and corporate standards for security, traceability, and logging. The HttpConversationManager operates with native CocoaTouch constructs (for example NSURL and NSMutableURLRequest); however, it also uses some specific classes, protocols, and properties that comply with the special requirements for which it was built.

Getting Started with Conversation Manager for iOS

Requirements

Installing the Libraries

If you do not use the CocoaPod master spec file to set up the project, you must manually add the libraries to your project: after installing the SAP Mobile Platform SDK for iOS and the libraries and resources are extracted, locate and add these libraries, which is usually enough to write your first Conversation Manager based app:

  • libHTTPConversation.a
  • libHTTPConvAuthFlows.a
  • libMobilePlace.a
  • libE2ETrace2.a
  • libSupportability.a
  • libPerformanceLib.a
  • (iOS) Foundation.framework
  • (iOS) UIKit.framework
  • (iOS) CoreGraphics.framework
  • (iOS) libsqlite3.dylib (required by libSupportability)
  • (iOS) Security.framework

Note: Beginning with SAP Mobile Platform SDK version SP08, a CocoaPod master spec file will be provided which automatically sets up the project dependencies.

Architecture

Exposed protocols:

RequestFilterProtocol – defines the delegate which is called before a request is triggered; this allows modification of the request (adding request header, set POST body, and so on) prior to execution.

ResponseFilterProtocol – defines the delegate which is called after a request is triggered; this allows modification of the NSURLResponse and the response data before it reaches the request executor.

ChallengeFilterProtocol – defines the interface for the ChallengeFilter delegate, which is called whenever authentication is required for request execution.

ManagerConfiguratorProtocol – defines the interface for holding a view controller reference which can be used by filters to display views with additional information on top of it.Filters are basically providers that communicate with conversation manager values such as user credentials; there are various typesof filters: authentication challenge filters, configuration filters, and response filters.

RedirectWhitelistProtocol – defines the interface for a class that handles redirects; it is called whenever a redirect to a new URL is going to occur.

Public interfaces:

HttpConversationManager – request execution manager class, supports request, response, and challenge filtering.

HttpConversationObserverProtocol – defines the HttpConversationObserver interface. Observers are notified when a specific event occurs.

SupportabilityUploader – SupportabilityUploader implementation, used by E2ETrace and ClientLog uploading.

Categories:

NSURLResponse+HttpConversation – extension that adds batch response handling support.

NSMutableURLRequest+HttpConversation – extension that adds batch request handling support.

Conversation Manager API Usage for iOS

After adding the required dependencies to your project, add the #import “HttpConversationManager.h” statement to your source file. Instantiate the conversation manager with:

HttpConversationManager* manager = [HttpConversationManager new];

The Conversation Manager exposes a single block-based API to execute network requests. The API expects an NSMutableURLRequest as input, and returns response data, an URL response, and an NSError in its completion block, which is non-nil after successful execution.

samplecode:
-(void) executeRequest:(NSMutableURLRequest*)urlRequest completionHandler:(void
(^)(NSData* data, NSURLResponse* response, NSError* error))completionHandler;

NSURL* url = [NSURL URLWithString:@“<your URL goes here>”];

  

//initialize a request object

NSMutableURLRequest* request = [NSMutableURLRequest requestWithURL:url];

//execute conversation

[conversationManager executeRequest:req completionHandler:^(NSData *data, NSURLResponse *response,
NSError *error) {

    NSLog(@”Finished”);

    if(error != nil)

     {

        NSLog(@”Error: %@”, [error localizedDescription]);

                // perform meaningful error handling

     }

     else

     {

                // data received

     }

}];

The conversation manager instance usually cannot be used immediately to execute requests; it must first be configured to handle common authentication flows such as basic authentication.

Responding to Authentication Challenges

Challenge filters – assign authentication challenge filters to a manager instance to respond to authentication challenges. Use the addChallengeFilter: API to assign one or more challenge filters to a given manager instance.

Challenge Filter classes must adhere to the ChallengeFilterProtocol, which declares a delegate method that is called whenever an authentication challenge occurs during request execution.

samplecode:

-(void)handleChallenge:(NSURLAuthenticationChallenge*)challenge

conversationManager:(HttpConversationManager*)conversationManager
completionBlock:

(void (^)(BOOL useCredential, NSURLCredential* credential))completionBlock;

The delegate method should supply valid credentials in its completion block and set useCredential to YES (if set to NO or the credential is nil, it is interpreted as if no credential is provided.)

HTTPConvAuthFlows – the HttpConvAuthFlows library provides a set of authentication providers that can be used as an alternative to implementing challenge filters.

A CommonAuthenticationConfigurator instance must first be created, followed by setting the required providers and implementing specific delegates. In this example the manager instance is set up to retrieve user credentials from the implementing class.

samplecode:

// get an instance from the network standards based configurator

   CommonAuthenticationConfigurator* commonConfig = [CommonAuthenticationConfigurator new];

//add Username Password provider with our implementation

  [commonConfig addUsernamePasswordProvider:self];

//configure manager with standard set of plugins but with our own implementation of some providers

    [commonConfig configureManager:manager];

You must also implement the corresponding UsernamePasswordProviderProtocol delegate – provideUsernamePasswordForAuthChallenge:completionBlock.

samplecode:

#import “UsernamePasswordProviderProtocol.h”

@interface ViewController () <UsernamePasswordProviderProtocol,
SAML2ConfigProviderProtocol, ClientCertObserverProtocol, ClientCertProviderProtocol>

@end

#
pragma mark – Providers

/**

* Username Password provider. Provider hard-coded username/password for this sample only

  * Also shows how to override default UsernamePasswordProvider.

*/

-(void)
provideUsernamePasswordForAuthChallenge:(NSURLAuthenticationChallenge*)authChallenge
completionBlock:(void (^)(NSURLCredential*, NSError*))completionBlock {

    NSURLCredential* credential = [NSURLCredential credentialWithUser:@”username”
    password:@”password” persistence:NSURLCredentialPersistenceForSession];

    completionBlock(credential, nil);

}

The HttpConvAuthFlows class provides default implementations for:

  • Authentication Challenge Providers – UsernamePasswordProvider default implementation of UsernamePasswordProviderProtocol displays a secure alert view to enter username and password.
  • Configuration Providers:
    • OAuth2RequestFilter RequestFilter which handles OAuth authentication flow
    • SAML2ResponseFilter ResponseFilter which handles SAML2 authentication flow

Unit Tests and API Documentation

The HttpConversationManager and HttpConvAuthFlows libraries include an extensive set of unit tests, usage, and best practices.

Go to the <sdkinstall dir>\NativeSDK\ODataFramework\iOS\docs directory of your SAP Mobile Platform SDK installation, open the HttpConvAuthFlows-APIDoc.zip or HttpConversation-APIDoc.zip file, then open the index.html file to view API documentation for these libraries.

Additional Resources

See http://scn.sap.com/community/developer-center/mobility-platform/blog/2014/11/14/request-response-challenge-filters-in-httpconversationmanager on the SAP Community Network Web site for additional information about HttpConversationManager request, response, and challenge filters.

To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply