website logo
⌘K
Introduction and Concepts
Keyri and its Uses
Smart Deep Linking
User+Device Signatures
Risk Analytics
End-to-End Encryption
Browser - Keyri Widget Quickstart
Mobile SDKs
Device Fingerprinting - UX & Fraud
iOS
Android
React Native
Flutter
Server-Side Authentication
Integrations
Amazon Cognito
Auth0
Firebase
Supabase
Ping Identity
AlphaPoint APEX System
Banno Digital Banking
Changelog
Docs powered by archbee 
27min

iOS

The latest source code of the Keyri iOS SDK can be found here: https://github.com/Keyri-Co/keyri-ios-whitelabel-sdk/tags

System Requirements

  • iOS 14+
  • Swift 5+
  • Apple A7 chip or newer (The A7 shipped with the iPhone 5s)

Integration

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate the Keyri iOS SDK into your Xcode project using CocoaPods, specify it in your Podfile:

Ruby
|

The SDK can then be imported into any Swift file as follows:

Swift
|

Option 1 - Universal Links

To handle Universal Links (e.g., for QR login straight from the user's built-in camera app), you need to add the Associated Domains Entitlement to your App.entitlements file. To set up the entitlement in your app, open the target’s Signing & Capabilities tab in Xcode and add the Associated Domains capability, or if you already have entitlements you can modify your App.entitlements file to match this example:

XML
|

This will handle all links with the following scheme: https://{yourCompany}.onekey.to?sessionId={sessionId}

Note: Keyri will create your https://{yourCompany}.onekey.to page automatically once you configure it in the dashboard

In the AppDelegate where the processing of links is declared, you need to add handlers in the application(_:continue:restorationHandler:) method:

AppDelegate.swift
|

Note: Keyri will set up the required /.well-known/apple-app-site-association JSON at your https://{yourSubdomain}.onekey.to page as required by Apple to handle Universal Link handling. Details on this mechanism are described here: https://developer.apple.com/documentation/Xcode/supporting-associated-domains

Option 2 - In-App Scanner

This can be used in conjunction with Universal links or exclusively.

The Keyri SDK includes a default Scanner view, which can be invoked and displayed as shown below. Unfortunately, due to platform limitations, we had to keep this in UIKit for the time being but will be on the lookout for options to convert over to SwiftUI as time goes on. The completion block is the important piece here: we return the exact string as shown in the QR code. All you need to do is convert to URL, and then you're free to process the response the same way we did above (notice the process(url) function is exactly the same in both cases)

Swift
|

Interacting with the API

The following methods are available to interact with the Keyri SDK API, which can be used to craft your own custom flows and leverage the SDK in different ways:

  • func easyKeyriAuth(userId: String, appKey: String, payload: String): Result<Bool, Error>- call to have Keyri drive you through the entire process - we display the scanner, scan the QR code, handle user confirmation and fire off the result to the browser - all with one line of code in your app :)
  • func initializeQrSession(sessionId: String, appKey: String): Result<Session, Error> - call after obtaining the sessionId from QR-code or deep link. Returns Session object with Risk attributes (needed to show confirmation screen) or Exception
  • func confirmationScreen(session: Session): Boolean - to show Confirmation with default UI. Alternatively, you can implement a custom Confirmation Screen. The Default screen is built using SwiftUI, however the session object is designed to work seamlessly with UIKit as well should you prefer that route
  • func Session.confirm(publicUserId: String?, payload: String):Result<Bool, Error> - call this function if user confirms the dialog. Returns authentication result
  • func Session.deny(publicUserId: String?, payload: String): Result<Bool, Error> - call if the user denies the dialog. Returns authentication result
  • func generateAssociationKey(publicUserId: String): P256.Signing.PublicKey - creates a persistent ECDSA keypair for the given public user ID (example: email address) and return public key
  • func getUserSignature(publicUserId: String, data: Data): P256.Signing.ECDSASignature - returns an ECDSA signature of the timestamp and optional customSignedData with the publicUserId's privateKey (or, if not provided, anonymous privateKey), data can be anything
  • func getAssociationKey(publicUserId: String): P256.Signing.PublicKey - returns Base64 public key for the specified publicUserId

payload can be anything (session token or a stringified JSON containing multiple items. Can include things like publicUserId, timestamp, customSignedData and ECDSA signature)

Session Object

The session object is returned on successful initalizeQrSession calls, and is used to handle presenting the situation to the end user and getting their confirmation to complete authentication. Below are some of the key properties and methods that can be triggered. If you are utilizing the built-in views, you are only responsible for calling the confirm/deny methods above

  • IPAddressMobile/Widget - the IP Address of both mobile device and web browser
  • WidgetUserAgent - the browser user-agent (e.g., Chrome on macOS)
  • RiskAnalytics - if available on your subscription plan
    • RiskStatus - clear, warn or deny
    • RiskFlagString - if RiskStatus is warn or deny, this string alerts the user to what is triggering the risk situation
    • GeoData - Location data for both mobile and widget
      • Mobile
        • city
        • country_code
      • Browser
        • city
        • country_code
  • Session.confirm() and Session.deny() - see descriptions in Interacting with the API

Disclaimer

We care deeply about the quality of our product and rigorously test every piece of functionality we offer. That said, every integration is different. Every app on the App Store has a different permutation of build settings, compiler flags, processor requirements, compatibility issues etc and it's impossible for us to cover all of those bases, so we strongly recommend thorough testing of your integration before shipping to production. Please feel free to file a bug or issue if you notice anything that seems wrong or strange on GitHub 🙂

https://github.com/Keyri-Co/keyri-ios-whitelabel-sdk/issues

UP NEXT
Android
Docs powered by archbee 
TABLE OF CONTENTS
System Requirements
Integration
Option 1 - Universal Links
Option 2 - In-App Scanner
Interacting with the API
Session Object
Disclaimer