Getting started

This topic guide describes how you should get started with the Onegini iOS SDK. It outlines how the API is set up, how the SDK generally works and what the requirements are.

We first advice you to read the App developer quickstart before reading this topic guide.

General setup of the Onegini iOS SDK

OneginiClient

The main facade of the SDK is the OneginiClient. This class exposes the other Onegini client objects (UserClient and DeviceClient) that you can access. The OneginiClient is a singleton of which you can only construct a single instance using the ONGClientBuilder class. The other clients that can be accessed through the OneginiClient are:

• UserClient - only contains user related functionality
• DeviceClient - only contains device related functionality

Thread safety

All methods that you call on the Onegini iOS SDK must be performed on the main thread of your mobile application. The SDK will not enforce this, hence you might expect strange behaviour if you do not execute the methods on the main thread. Internally the SDK will use multiple threads to make sure it does not block the main thread. You as a developer only have to make sure that you execute the SDK methods from the main thread.

Keychain sharing

Keychain sharing is not supported by the SDK and cannot be enabled for the application.

Delegating control from the app to the SDK and vice versa

To utilize the functionality that the SDK provides you must integrate it into your application. The functionality that the SDK provides sometimes require interaction with the end-user. The SDK itself does not contain any UI but will request you to implement specific actions (that require a UI) for your end-users.

The general setup is that you must trigger a functionality in the SDK by calling one of it's methods. Let's take user authentication as an example. The other methods take a similar approach so when you understand the concept it should be easy to follow.

In order to start the user authentication you must call the UserClient#authenticateUser method. Below is an example of this method call (taken from the iOS example app):

- (void)authenticateUser:(ONGUserProfile *)user
{
    [[ONGUserClient sharedInstance] authenticateUser:user delegate:self];
}

- (void)userClient:(ONGUserClient *)userClient didReceivePinChallenge:(ONGPinChallenge *)challenge
{
    // Ask the user for his/her PIN
}

- (void)userClient:(ONGUserClient *)userClient didAuthenticateUser:(ONGUserProfile *)userProfile authenticator:(ONGAuthenticator *)authenticator info:(nullable ONGCustomInfo *)customAuthInfo
{
    // Authentication was successful
}

- (void)userClient:(ONGUserClient *)userClient didFailToAuthenticateUser:(ONGUserProfile *)userProfile authenticator:(ONGAuthenticator *)authenticator error:(NSError *)error
{
    // Authentication failed
}

The second parameter that you must provide is a delegate. This delegate is responsible for giving you the feedback whether the result of the triggered action was successful or not. However, as part of the authentication a few other things happen. Depending on the authentication method that is preferred for a user the user will be requested to enter his/her PIN or perform biometric authentication.

The Delegate contains methods that will be called by the SDK to hand over control to the application. In case of PIN authentication the userClient:didReceivePinChallenge: method is called by the SDK. That method invocation contains a challenge object. A challenge object contains a number of things. Some metadata about the incoming request, optionally an error and a sender object. The error object will only be present if a previous invocation of the userClient:didReceivePinChallenge: failed because the user entered an incorrect PIN. This also implies that on consecutive PIN attempts for a user the userClient:didReceivePinChallenge: method is called again. The sender object is the way to hand over the control from the app back to the SDK. In case of PIN authentication this sender object must be used to provide the PIN to the SDK so it can confirm it. The sender object can also be used to cancel a specific flow using the cancelChallenge: method. After you have cancelled the flow the userClient:didFailToAuthenticateUser:error: method of the delegate will be called to indicate that the authentication flow failed.

Error handling

Interaction with the Onegini SDK can result in errors. Please check out our error handling topic guide for more details on error handling.

Supported platform versions

The minimum iOS version support by the Onegini iOS SDK is 13.0

Info: Starting February 1, 2015, new iOS apps uploaded to the App Store must include 64-bit support and be built with the iOS 8 SDK, included in Xcode 6 or later. To enable 64-bit in your project, we recommend using the default Xcode build setting of “Standard architectures” to build a single binary with both 32-bit and 64-bit code.

https://developer.apple.com/news/?id=10202014a

Third party dependencies

The iOS SDK uses a number of commercial and open source 3rd party libraries. These are included in the framework and need NOT to be configured in the build settings of your App project workspace. These dependencies are linked to the SDK staticly and are prefixed which means these will NOT create naming collisions. Onegini SDK is distributed in two framework files: OneginiSDKiOS.xcframework and OneginiCrypto.xcframework.

External library dependencies

OneginiSDKiOS.xcframework v11.0.0 depenencies:

OneginiCrypto.xcframework v1.0.0 depenencies: