Browser Identity Provider

In case when user tries to register with an Indentity Provider (IdP) that is browser-based, the SDK needs to ask for an access grant to the Token Server via the browser. The app should use url returned in ONGBrowserRegistrationChallenge to ask for the access grant in a separate web browser.

• Handling Browser Registration Challenge
  • Handling Browser Registration URL with UIWebView
  • Handling Browser Registration URL with External Web Browser

Handling Browser Registration Challenge

When registering a user the application will receive a browser registration challenge containing a URL, which must be handled. The challenge will be passed as an argument to userClient:didReceiveBrowserRegistrationChallenge: method of your ONGRegistrationDelegate. This URL will redirect user to a web page where he can authenticate to his user account. When authentication is successful page will redirect you to your Redirect URL defined in token server application configuration.

The userClient:didReceiveBrowserRegistrationChallenge: method has two parameters:

• userClient (ONGUserClient) user client performing registration.
• challenge (ONGBrowserRegistrationChallenge) challenge containing URL used to perform a registration code request.

Challenge object represents browser registration challenge. It provides all information about the challenge and the sender awaiting for the response:

• userProfile (ONGUserProfile) user profile for which registration request challenge was sent.
• identityProvider (ONGIdentityProvider) identity provider used to register the user.
• url (NSURL) URL used to perform a registration code request.
• error (NSError) error describing cause of failure of previous challenge response. Possible error domains: ONGGenericErrorDomain.
• sender (id<ONGBrowserRegistrationChallengeSender>) sender awaiting for response to the registration request challenge.

You can respond to the challenge using sender object by calling one of the following methods:

• respondWithURL:challenge: - used to deliver the redirection URL to the SDK
• cancelChallenge - used for registration cancelation

It's up to you how you want to handle this URL, however it's recommended to use a web browser like Safari or preferably embedded web browser like UIWebView.

We recommend to use an embedded UIWebView to open this URL because this is the least disruptive for the end-user and also benefits from the additional security measures included in the SDK. The SDK from release 2.3 and upwards is updated to intercept the URL requests from the embedded UIWebView and perform certificate pinning.

Handling Browser Registration URL with UIWebView

You can perform request using UIWebView by using its loadRequest method.

NSURLRequest *request = [NSURLRequest requestWithURL:self.browserRegistrationChallenge.url];
[self.webView loadRequest:request];

Web view should guide the user through authentication process and then redirect back to the application using the Redirect URL. In order to intercept this redirection its recommended to implement webView:shouldStartLoadWithRequest:navigationType: method on your UIWebViewDelegate. Example implementation:

-(BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
    if ([request.URL.absoluteString hasPrefix:[OneginiConfigModel configuration][@"ONGRedirectURL"]]) {
        [self.browserRegistrationChallenge.sender respondWithURL:request.URL challenge:self.browserRegistrationChallenge];
        [self.navigationController dismissViewControllerAnimated:YES completion:nil];
        return NO;
    }
    return YES;
}

It's up to you when the web view will be closed. You could close it as soon as challenge sender receives redirection url, which is shown in the example or when yours ONGRegistrationDelege receives userClient:didReceivePinRegistrationChallenge:.

Handling Browser Registration URL with External Web Browser

In order to handle registration request using external web browser first you need to configure custom URL scheme.

After the user has authenticated he/she is redirected back to the app using a custom URL scheme. The app must add an active URL scheme to the info.plist file. Administration of the redirect URL (that includes the custom URL scheme) is done in the application configuration in the Token Server admin console.

Below you can see the contents of the URL Type configuration in Xcode:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLName</key>
<string>com.onegini.OneginiSDKiOSTestApp</string>
<key>CFBundleURLSchemes</key>
<array>
<string>oneginisdk</string>
</array>
</dict>
</array>
</dict>
</plist>

Next, you need to open the URL using external web browser. You can you use openURL method of UIApplication shared instance.

- (void)userClient:(ONGUserClient *)userClient didReceiveBrowserRegistrationChallenge:(ONGBrowserRegistrationChallenge *)challenge
{
    [[UIApplication sharedApplication] openURL:challenge.url];
}

Redirection using a custom URL scheme must be implemented within your UIApplicationDelegate object. It's done by implementing one of the following methods:

• application:openURL:options: - available from iOS 9
• application:handleOpenURL: - deprecated, but available before iOS 9
• application:openURL:sourceApplication: - deprecated, but available before iOS 9

Example implementation:

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary<NSString*, id> *)options
{
    if ([request.URL.absoluteString hasPrefix:[OneginiConfigModel configuration][@"ONGRedirectURL"]]) {
        [self.browserRegistrationChallenge.sender respondWithURL:request.URL challenge:self.browserRegistrationChallenge];
        return YES;
    }
    return NO;
}