Skip to content

iOS SDK Integration#

This quickstart guide serves as an integration example for our trusted partners so that you will be able to test and/or evaluate LoginID’s authentication service for your own needs. After going through this document you should be able to have your application connect to our platform in just 4 simple steps.

This document assumes that you are using Swift/Objective-C in your development environment. Additional independent configuration options and integration mechanisms will be described in additional API Documentation that is still under development.

Info

This document is for LoginID IOS SDK version 0_84_1+.

Create your client API keys#

The first step to onboard yourself with LoginID is to create your client credentials. This allows your servers to call LoginID services in an authenticated fashion.

Field Name Value
clientId 6fcd5bdd-bd51-4e26-9cd6-14f6e41b5862
baseUrl 060ce487-b934-43d0-a925-b66e80c7532f.sandbox.loginid.io

Install LoginID SDK for your build environment#

This instruction is for configuring your Xcode environment using Cocoapods. The LoginID SDK requires min iOS 10 for compatibility.

Add LoginSDK framework to your Podfile and then run pod install.

platform :ios, '10.0'

target 'MyTestObjcApp' do
   use_frameworks!
  #LoginSDK pod install
  pod 'LoginSDK','0.84.11', :source => 'https://github.com/loginid1/LoginSDKSpecs.git'
  # your other pods

end

Add NSFaceIDUsageDescription (Privacy - Face ID Usage Description) key/value to app's info.plist.

This is a privacy description for accessing FaceID feature on iOS. On device with FaceID like iPhoneX + user will be prompted with permission dialog based on this description about faceID usage for the app.

<?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>NSFaceIDUsageDescription</key>
<string>Privacy description regarding to usage of FaceID feature</string>
...
...
</plist>

Note

For Objective-C development, make sure to enable "Embed Swift Standard Libraries" in your build settings to avoid run-time error for objective-c

Build Settings > Build Options > Always Embed Swift Standard Libraries "YES"

Getting started with LoginID API SDK:#

The following diagram illustrates how the different API functions of the LoginID SDK interact with your application and the iOS platform. The API functions that you are responsible for are described in steps below and is marked by the blue arrows in the diagram.

image

Configure LoginID API#

First you need to configure the SDK with your client API key and baseURL obtained from LoginID's developer console. This API must call before any other apis. You should call this API within your AppDelegate's didFinishLaunchingWithOptions method.

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // clientId example 032690b3-9bc4-4602-87c1-60c1fae782f2
        let clientId="<your api key>"
        // baseURL example https://060ce487-b934-43d0-a925-b66e80c7532f.sandbox.loginid.io
        let baseURL="<your base url"

        LoginAPI.client.configure(clientId: clientId, baseURL: baseURL)
        ...
        ...
    }
...    
...
@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // clientId example 032690b3-9bc4-4602-87c1-60c1fae782f2
    NSString * clientId=@"<your api key>";
    // baseURL example 032690b3-9bc4-4602-87c1-60c1fae782f2.https://sandbox.loginid.io
    NSString * baseURL=@"<your baseURL>";

    [LoginAPI.client configureWithClientId:clientId baseURL:baseURL];
    ...
    ...
}
...
...

Getting user account information#

Here is a set of functions for retrieving user information and login status.

  • check if user has existing registered account
    // return true or false
    let result = LoginAPI.client.hasAccount()
    // return YES or NO
    BOOL result = [LoginAPI.client hasAccount];
  • get current username
    // return username in string value
    let username = LoginAPI.client.getCurrentUsername()
    // return username in string value
    NSString * username = [LoginAPI.client getCurrentUsername];
  • check if user has active login session
    // return true or false
    let result = LoginAPI.client.isLoggedIn()
    // return YES or NO
    BOOL result = [LoginAPI.client isLoggedIn]
  • get current access token which is the latest JWT token returned by the server after a successful registered or verified api called
    // return jwt in string value
    let token = LoginAPI.client.getCurrentAccessToken()
    // return jwt in string value
    NSString * token = [LoginAPI.client getCurrentAccessToken]

Here are an example on how to use the above functionalities:

    if(LoginAPI.client.hasAccount()){
      // get current username example
      let username = LoginAPI.client.getCurrentUsername()
      // check if user has active login session
      if(LoginAPI.client.isLoggedIn()){
          // get current token example
          let token = LoginAPI.client.getCurrentAccessToken()
          ...
      } else {
          // can setup login user here
          //present login option here
          ...
      }
      ...
    } else {
      // user has no account so can setup register user logic here
      ...
    }
    if([LoginAPI.client hasAccount]){
      // get current username example
      NSString * username = [LoginAPI.client getCurrentUsername];
      // check if user has active login session
      if([LoginAPI.client isLoggedIn]){
          // get current token example
          NSString * accessToken = [LoginAPI.client getCurrentAccessToken];
          ...
      } else {
         // present login option here  
         ...
      }
    } else {
      // user has no account so can setup register user logic here
      ...
    }

Register user account#

The registration flow of the api is shown in the following diagram

image

Register an account with username specified#

This api allows user to create new credential with username via a FIDO2 registration. Having username registered will allow user to login by username from multiple platforms.

LoginAPI.client.register(username: username, onComplete: { (response) in
    if(response.success){
        // handle success case here
        ...
        ...
    } else {
        // handle error case here
        print(response.errorMessage)
        ...
        ...
    }
})
[LoginAPI.client registerWithUsername:username onComplete:^(RegisterResponse * _Nonnull response) {
    if(response.success){
        // handle success case here
        ...
        ...
    } else {
        // handle error case here
        NSLog(response.errorMessage)
        ...
        ...
    }
}];

Login or re-authenticate an registered account#

Once the user has successfully registered, LoginID will assigned a JWT token to the response field. The token has a timestamp associate with it. You can ask the user to re-authenticate at anytime afterward based on your business logic or if the token expired.

LoginAPI.client.login(onComplete: { (response) in
    if(response.success){
        // handle success case here
        ...
        ...
    } else {
        // handle error case here
        print(response.errorMessage)
        ...
        ...
    }
})
[LoginAPI.client loginOnComplete:^(LoginResponse * _Nonnull response) {
    if(response.success){
        // handle success case here
        ...
        ...
    } else {
        // handle error case here
        NSLog(response.errorMessage)
        ...
        ...
    }
}];

Logout#

Call logout operation to invalidate the current access token.

LoginAPI.client.logout()
[LoginAPI.client logout];