Setting up the project

This section describes the first steps to integrate the Onegini iOS SDK with an existing iOS project.

Adding the SDK to your project

There are two ways to add the iOS SDK to your project. Manually or through CocoaPods as a Pod.

Cocoapods

CocoaPods is the preferred way to add the Onegini SDK to your project. It provides the most convenience and ease of use. You don't have to manually change your Xcode project file.

Install the CocoaPods Artifactory plugin

The Onegini SDK is uploaded to the Onegini Artifactory repository. In order to let CocoaPods use an Artifactory repository you need to install a specific plugin.

gem install cocoapods-art

Note: It is strongly recommended that you install CocoaPods as a Rubygem and not through Homebrew. Installing with Homebrew may cause issues with the CocoaPods hooks mechanism that the plugin relies on.

Setup authentication

The Onegini SDK repository is not a public repository. You must provide credentials in order to access the repo.

Create a file named .netrc in your Home folder (~/) and add the following contents to it:

machine repo.onegini.com
login <username>
password <password>

Replace the <username> and <password> with the credentials that you use to login to support.onegini.com.

Add the OneginiSDK to your Podfile

Adding the OneginiSDK to your Podfile is done in two steps. First you need to add the cocoapods-art plugin as a plugin in your Podfile.

plugin 'cocoapods-art', :sources => [
 'onegini'
]

Second you need to add the Onegini SDK as a Pod in one of your project targets.

target 'OneginiExampleApp' do
  pod 'OneginiSDKiOS', '~> 5.01.01-SNAPSHOT'
  pod 'ZFDragableModalTransition', '~> 0.6'
  pod 'MBProgressHUD', '~> 1.0.0'
end

Adding and updating the onegini CocoaPods repository

The Onegini CocoaPods repository must be added to your local machine using the following command.

pod repo-art add onegini https://repo.onegini.com/artifactory/api/pods/cocoapods-public

In order to update the Repository you must manually perform an update

pod repo-art update onegini

Note: It is a good habbit to perform pod repo-art update onegini every once in a while just as you are doing it with the CocoaPods master repository.

Manually

Copy the Onegini SDK static library and header files into the Frameworks group of the project workspace. Add the libOneginiSDKiOS-X.XX.XX.a static library (along with all the required libraries and frameworks) to the "Link Binary With Libraries" section of the Build Phases. You can obtain the Onegini SDK through Onegini support.

The result should look similar to the following example:

Add SDK

Build Settings

The Following settings needs to be changed:

  • Other Linker Flags - add the -ObjC flag
  • Enable bitcode - set to No
  • Library Search Paths - Add the folder containing the static library and header files, in this example the folder is named "OneginiSDK" so the "Library Search Paths" should be similar to the following example:

Build Settings

SDK configuration

Before the SDK can be used in an application it needs to be configured. E.g. you need to tell it the location (URL) of the Token Server instance, but also some of the security features need to be configured. There are two ways of the providing configuration:

The latter is the preferred way of working since it does not require the manual steps described in the paragraph below. The SDK configurator can be found on GitHub. If you don't have access you can request it through Onegini Support.

Manual configuration

The paragraphs below explain how to manually configure the SDK.

Configuration model

The SDK relies on a set of configuration parameters which must be provided to the SDK by means of an instance of ONGConfigModel. The backing data model of the ONGConfigModel is a property list. The App is responsible for creating an instance of the ONGConfigModel with a backing property list and the app also needs to provide it to the ONGClientBuilder. Initialization of ONGConfigModel is described here.

Certificate pinning

Certificates used by the SDK are secured from tampering. In order for the SDK to detect certificate tampering it is required to perform Certificate Pinning.

Instantiating the SDK

The whole functionality of the SDK is accessed by means of a single shared client which is named ONGClient. The client must be instantiated once early in the App lifecycle and thereafter only referred to by it's shared instance. This is usually done in the root view controller but can also be done in a specific non UI class. In order to instantiate SDK ONGConfigModel containing the configuration parameters and an array of PEM Base64 encoded X509 certificates has to be provided to the ONGClientBuilder. This class is the only way to instruct SDK about configuration, X509-encoded certificates and other settings.

After instantiating the shared instance of ONGClient it is required to call its start: method. At this method the client verifies integrity and performs validation and registration calls, the result is returned in callback. Accessing ONGDeviceClient and ONGUserClient (both as shared instances or ONGClient properties) before calling start: method will raise NSInternalInconsistencyException.

Example of the ONGClient initialization:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ...
    NSString *const certificate = @"AaXeRCk/luuGtm87fM04wO+mPZn+C+mv626PAcwDj1hKvTfIPWhRRH224hoFiB85ccsJP81cqcdnUl4XmGFO3";
    NSString *configPath = [[NSBundle mainBundle] pathForResource:@"config" ofType:@"plist"];
    ONGConfigModel *configModel = [[ONGConfigModel alloc] initWithContentsOfFile:configPath];

    [[[[ONGClientBuilder new] setConfigModel:configModel] setX509PEMCertificates:@[certificate]] build];
    [[ONGClient sharedInstance] start:nil];
    ...
}

Configuration via SDK configurator

Once configurator has generated and added the OneginiConfigModel class to your App, you can instantiate SDK by calling the -[ONGClientBuilder build] method. It automatically finds the OneginiConfigModel in order to configure SDK correctly.

Example of the ONGClient initialization:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ...
    [[ONGClientBuilder new] build];
    [[ONGClient sharedInstance] start:^(BOOL result, NSError *error) {
        if (error != nil) {
            if (ONGGenericErrorOutdatedApplication == error.code) {
                [self showAlertWithTitle:@"Application disabled" message:@"The application version is no longer valid, please visit the app store to update your application"];
            }

            if (ONGGenericErrorOutdatedOS == error.code) {
                [self showAlertWithTitle:@"OS outdated" message:@"The operating system that you use is no longer valid, please update your OS."];
            }
        }
    }];
    ...
}

Important additional information

Using the security controls during development

Please note that the iOS SDK has the ability to detect if the app works in debug mode or with a debugger attached. This feature is enabled by default. When debug mode detection is enabled and a debugger is detected (which is most likely the case if you run your app in an simulator), the SDK will not allow to execute any of the user related flows and return an error. To disable this feature during development please follow the security controls guide.

Prevent calculating the application signature during development

Regardless when you configure the SDK manually or use the SDK Configurator, you must calculate the Application Signature and provided it to the Token Server every time your application is modified. During development this will hamper development greatly. To suppress this, turn on development mode in the Token Server application configuration.