Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

iOS SDK

iOS SDK upgrade instructions

search

iOS SDK upgrade instructions

Upgrading the Onegini iOS SDK to version 12.2.0

This version adds improvements for the prewarming mechanism introduced in iOS 15.

The prewarming mechanism „learns” the usage pattern of the app and can „predict” when your app will be run. The iOS system can run the app itself (partially) in the background (when the phone is locked).

The prewarming mechanism can make the SDK start in the background trying to read some values from the Secure Enclave - while the device is locked - which can potentially lead to some unpredictable results returned by the SDK.

Using the new public builder method you ensure that the SDK is not being called before the device is locked. The improvements are available both for Objective-C and Swift public API. The change is yet backward compatible with the previous 12.x version, as it introduces a new (optional) public API method.

The new (optional) builder method is called buildAndWaitForProtectedData:

ClientBuilder().buildAndWaitForProtectedData { client in
    client.start { error in
        completion(...)
    }
}

Instructions for upgrading the Onegini oIS SDK to version 12.0.0

The public API rewritten in Swift.

Instructions for upgrading the Onegini oIS SDK to version 11.0.0

This version of the SDK requires:

  • the Token Server 12.16.0 or newer in case when the app is not using the optional Payload Encryption feature
  • the Token Server 12.16.0 or newer and the Security Proxy 5.4.0 or newer when the app is using the optional Payload Encryption feature

New tampering protection

For many years the SDK protected mobile apps from tampering by checking their binaries for any modifications in source code or assets. With the tampering protection enabled the app developers gained confidence that apps installed by customers do not contain malicious code injected by an attacker. Unfortunately, such verification was too strict to allow the app developers to use some functionalities like Bitcode since it was able to modify the binary file protected by the SDK.

Starting with iOS SDK 11.0.0 we're introducing a new tampering protection functionality. The new feature does not check what the app contains but who created the app. Whenever the user installs the app on a device, the iOS SDK checks if the developer identifier who signed the app matches the one configured on the Token Server.

The new functionality does not require any changes in the code of the mobile app, but you need to add your trusted certificates to the configuration of the Token Server. To read more about the certificate and configuration please follow the Application integrity chapter.

New error ONGGenericErrorInvalidDateTime

The OneWelcome MSP uses epoch timestamps for registering and validating mobile devices. In very rare cases when the mobile device has set an incorrect date or time, the SDK will not be able to register and verify the client. In such cases the SDK will return a new ONGGenericErrorInvalidDateTime error that can be used to indicate possible issues with the date or time that was set on the device.

Instructions for upgrading the Onegini oIS SDK to version 10.0.0

MSP compatibility

This version of the SDK requires:

  • the Token Server 12.6.0 or newer in case when the app is not using the optional Payload Encryption feature
  • the Token Server 12.8.0 or newer and the Security Proxy 5.4.0 or newer when the app is using the - optional Payload Encryption feature

New security controls

The security controls implementation has been modified, making the tampering protection optional. The application thumbprint (formerly known as application signature) can be calculated with two integrity levels:

  • FULL - the SDK will perform a full binary check to be sure that the app was not modified.
  • NONE - will skip the binary check, while still making basic application sanity checks.

The level of the integrity check can be set in the Token Server configuration

Cerificate pinning

Certificate pinning does no longer require including .cer files to the application bundle. It is recommended to use SDK Configurator version 5.0.0 or later.

Payload encryption

Now Payload Encryption feature requires to provide server public key in the configuration. The key is in the zip file of application version exported from the Token Server. That property can be configured using the SDK Configurator (version 5.0.0 or later) or manually using the setServerPublicKey: method on ONGClientBuilder.

Removed deprecated APIs

ONGUserClient

  • canHandlePushMobileAuthRequest: - please use pendingMobileAuthRequestFromUserInfo: method instead.
  • handlePushMobileAuthRequest:delegate: - please use handlePendingPushMobileAuthRequest:delegate: method instead.
  • authenticateUser:delegate: - please use authenticateUser:authenticator:delegate: method instead.
  • authenticateUserWithAuthenticator:profile:delegate: - please use authenticateUser:authenticator:delegate: method instead.

ONGResourceRequest

  • ONGParametersEncodingPropertyList - it is no longer supported.

ONGRegistrationDelegate

  • userClient:didRegisterUser:info: - please use userClient:didRegisterUser:userProfile:identityProvider:info: method instead.
  • userClient:didFailToRegisterWithError: - please use userClient:didFailToRegisterWithIdentityProvider:error: method instead.
  • ONGBrowserRegistrationChallenge
  • userProfile - it is no longer necessary.

ONGAuthenticationDelegate

  • userClient:didStartAuthenticationForUser: - please use -[ONGAuthenticationDelegate userClient:didStartAuthenticationForUser:authenticator:] method instead.
  • userClient:didReceiveFingerprintChallenge: - please use -[ONGAuthenticationDelegate userClient:didReceiveBiometricChallenge:] method instead.
  • userClient:didAuthenticateUser:info: - please use -[ONGAuthenticationDelegate userClient:didAuthenticateUser:authenticator:info:] method instead.
  • userClient:didFailToAuthenticateUser:error: -please use -[ONGAuthenticationDelegate userClient:didFailToAuthenticateUser:authenticator:error:] method instead.

ONGMobileAuthRequestDelegate

  • userClient:didReceiveFingerprintChallenge:forRequest: - please use userClient:didReceiveBiometricChallenge:forRequest: method instead.
  • userClient:didHandleMobileAuthRequest:info: - please use userClient:didHandleMobileAuthRequest:authenticator:info: method instead.
  • userClient:didFailToHandleMobileAuthRequest:error: - please use userClient:didFailToHandleMobileAuthRequest:authenticator:error: method instead."
  • ONGFingerprintChallenge
  • ONGFingerprintChallenge was removed, please use ONGBiometricChallenge
  • Changed API's nullablility

ONGUserClient

  • implicitlyAuthenticateUser:scopes:completion: now error parameter in completion block can be nil.
  • logoutUser: now user profile parameter in completion block can be nil.

Instructions for upgrading the Onegini oIS SDK to version 9.6.0

stf_product: OneWelcome Identity Platform

OpenID Connect Relying Party

The SDK is now an OpenID Connect Relying Party. During registration it can enforce the user to login with the Identity Provider. In order to force the user login the app has to provide the openid scope within the set of scopes used for a user registration:

[[ONGUserClient sharedInstance] registerUserWithIdentityProvider:nil scopes:@[@"read", @"openid"] delegate:self];

All mobile apps configured on the Token Server have the openid scope by default. It means that it will be also used when the app will not define the scopes and let the Token Server use default scopes:

[[ONGUserClient sharedInstance] registerUserWithIdentityProvider:nil scopes:nil delegate:self];

Instructions for upgrading the Onegini oIS SDK to version 9.5.1

When upgrading from an older SDK version to version 9.5.1, several changes have to be applied in your application. Although it is still possible to use the old APIs we recommend to update to the new APIs since the old ones will be removed in the next big update of the SDK.

ONGUserClient

  • authenticateUser:delegate: ==> authenticateUserProfile:authenticator:delegate:
  • authenticateUserWithAuthenticator:profile:delegate: ==> authenticateUserProfile:authenticator:delegate:

Instructions for upgrading the Onegini oIS SDK to version 9.3.0

When upgrading from an older SDK version to version 9.3.0, several changes have to be applied in your application. Although it is still possible to use the old APIs we recommend to update to the new APIs since the old ones will be removed in the next big update of the SDK.

Deprecated APIs

ONGAuthenticationDelegate

  • userClient:didStartAuthenticationForUser: ==> userClient:didStartAuthenticationForUser:authenticator:
  • userClient:didAuthenticateUser:info: ==> userClient:didAuthenticateUser:authenticator:info:
  • userClient:didFailToAuthenticateUser:error: ==> userClient:didFailToAuthenticateUser:authenticator:error:

ONGMobileAuthRequestDelegate

  • userClient:didHandleMobileAuthRequest:info: ==> userClient:didHandleMobileAuthRequest:authenticator:info:
  • userClient:didFailToHandleMobileAuthRequest:error: ==> userClient:didFailToHandleMobileAuthRequest:authenticator:error:

ONGBrowserRegistrationChallenge

userProfile will be removed in the next major release.

Instructions for upgrading the Onegini oIS SDK to version 9.1.3

When upgrading from an older SDK version to version 9.1.3, several changes have to be applied in your application. Although it is still possible to use the old APIs we recommend to update to the new APIs since the old ones will be removed in the next big update of the SDK.

Deprecated APIs

ONGFingerprintChallenge ==> ONGBiometricChallenge

ONGAuthenticationDelegate

  • userClient:didReceiveFingerprintChallenge: ==> userClient:didReceiveBiometricChallenge:

ONGMobileAuthRequestDelegate

  • userClient:didReceiveFingerprintChallenge:forRequest: ==> userClient:didReceiveBiometricChallenge:forRequest:

ONGAuthenticator

  • ONGAuthenticatorTouchID ==> ONGAuthenticatorBiometric

ONGErrors

  • ONGAuthenticationErrorTouchIDAuthenticatorFailure ==> ONGAuthenticationErrorBiometricAuthenticatorFailure
  • ONGRegistrationDelegate
  • userClient:didRegisterUser:info: ==> userClient:didRegisterUser:identityProvider:info:
  • userClient:didFailToRegisterWithError: ==> userClient:didFailToRegisterWithIdentityProvider:error:

Instructions for upgrading the Onegini oIS SDK to version 9.0

Onegini iOS SDK is now distributed as a dynamic framework. When upgrading from an older SDK version please:

  • refer to getting started guide in order to make sure that the SDK is linked correctly.
  • update your iOS Application Signature Calculator to version 1.4.0 or higher, previous versions will not be able to calculate signature of a dynamic framework.

Instructions for upgrading the Onegini oIS SDK to version 8.0

When upgrading from an older SDK version to version 8.0, several changes have to be applied in your application. Although it is still possible to use the old API's we recommend to update to the new API's since the old ones will be removed in the next big update of the SDK.

Removed APIs

ONGUserClient

  • registerUser:delegate: ==> registerUserWithIdentityProvider:scopes:delegate: user registration is now accepting optional identity provider argument.
  • userClient:didRegisterUser: ==> userClient:didRegisterUser:info: additional info parameter was added. The parameter is optional and used only when using Custom Registration.

Renamed APIs

ONGRegistrationDelegate

  • userClient:didReceiveRegistrationRequestChallenge: ==> userClient:didReceiveBrowserRegistrationChallenge:
  • ONGRegistrationRequestChallenge ==> ONGBrowserRegistrationChallenge
  • ONGRegistrationRequestChallengeSender ==> ONGBrowserRegistrationChallengeSender

Deprecated APIs

  • ONGResourceRequest
  • ONGParametersEncodingPropertyList will be removed in the next major release.

Instructions for upgrading the Onegini oIS SDK to version 7.0

When upgrading from an older SDK version to version 7.x, several changes have to be applied in your application.

Removed APIs

ONGUserClient

  • reauthenticateUser:delegate: ==> authenticateUser:delegate: The authenticate user method is always enforcing user authentication, just like reauthenticate user was doing before.
  • deregisterAuthenticator:completion: ==> deregisterAuthenticator:delegate: - completion was block replaced with the delegate object

Renamed APIs

ONGAuthenticationDelegate

  • userClient:didAuthenticateUser: ==> userClient:didAuthenticateUser:info: - additional info parameter was added. The parameter is optional and used only when using Custom Authenticators.
  • ONGAuthenticatorRegistrationDelegate
  • userClient:didRegisterAuthenticator:forUser: ==> userClient:didRegisterAuthenticator:forUser:info: - additional info parameter was added. The parameter is optional and used only when using Custom Authenticators.

ONGMobileAuthRequestDelegate

  • userClient:didHandleMobileAuthRequest: ==> userClient:didHandleMobileAuthRequest:info: - additional info parameter was added. The parameter is optional and used only when using Custom Authenticators.

Instructions to upgrade iOS SDK version to 6.x

When upgrading from a version 5.x SDK to version 6.x, several changes have to be applied in your application.

Note

Starting from this version we removed the leading zeros from our versioning scheme. So the SDK uses the standard major.minor.patch versioning scheme.

Removed APIs

  • ONGUserClient
  • enrollForMobileAuthentication: and storeDevicePushTokenInSession: ==> removed in favour for enrollForMobileAuth: and enrollForPushMobileAuthWithDeviceToken:completion. You can now enroll for mobile authentication without enrolling for push mobile authentication. Enrollment for push requires enrollment for mobile authentication to be done first.
  • ONGMobileAuthEnrollmentErrorMissingDevicePushToken ==> the error is no longer returned
  • ONGPublicCommons - file removed
  • ONGSDKInitializationException ==> removed in favour for NSInternalInconsistencyException
  • isEnrolledForMobileAuth ==> isUserEnrolledForMobileAuth:
  • isEnrolledForPushMobileAuth ==> isUserEnrolledForPushMobileAuth:

Removed deprecated APIs

  • ONGUserClient
  • handleApplicationURL: ==> respondWithURL:challenge: method of id<ONGRegistrationRequestChallengeSender> object provided by the ONGRegistrationRequestChallenge Registration redirect URL can now be passed to the sdk using id<ONGRegistrationRequestChallengeSender>, which makes handleApplicationURL: obsolete.
  • ONGRegistrationDelegate
  • userClient:didReceiveRegistrationRequestWithUrl: ==> userClient:didReceiveRegistrationRequestChallenge: The URL is passed within the ONGRegistrationRequestChallenge object. It also provides a sender object used to respond with the redirect URL or to cancel the registration.
  • ONGClientBuilder
  • setUseEmbeddedWebView ==> No longer required. The Onegini SDK no longer distinguishes how the registration request URL is handled.
  • ONGPublicCommons
  • ONGCloseWebViewNotification ==> No longer required. Called only if setUseEmbeddedWebView was set to YES. The Onegini SDK no longer distinguishes how the registration request URL is handled. If the registration request URL was handled within a UIWebView, it could be closed as soon as you send a response to the ONGRegistrationRequestChallengeSender or when you receive the userClient:didReceivePinRegistrationChallenge: on your ONGRegistrationDelegate.

Renamed APIs

  • ONGUserClient
  • handleMobileAuthenticationRequest:delegate ==> handlePushMobileAuthRequest:delegate:
  • canHandleMobileAuthenticationRequest ==> canHandlePushMobileAuthRequest
  • ONGMobileAuthenticationRequest ==> ONGMobileAuthRequest
  • ONGMobileAuthenticationRequestDelegate ==> ONGMobileAuthRequestDelegate
  • didFailToHandleMobileAuthenticationRequest ==> didFailToHandleMobileAuthRequest
  • didHandleMobileAuthenticationRequest ==> didHandleMobileAuthRequest
  • ONGMobileAuthenticationEnrollmentErrorDomain ==> ONGMobileAuthEnrollmentErrorDomain
  • ONGMobileAuthenticationEnrollmentErrorUserNotAuthenticated ==> ONGMobileAuthEnrollmentErrorUserNotAuthenticated
  • ONGMobileAuthenticationEnrollmentErrorDeviceAlreadyEnrolled ==> ONGMobileAuthEnrollmentErrorDeviceAlreadyEnrolled
  • ONGMobileAuthenticationEnrollmentErrorEnrollmentNotAvailable ==> ONGMobileAuthEnrollmentErrorEnrollmentNotAvailable
  • ONGMobileAuthenticationEnrollmentErrorUserAlreadyEnrolled ==> ONGMobileAuthEnrollmentErrorUserAlreadyEnrolled
  • ONGMobileAuthenticationEnrollmentErrorMissingDevicePushToken ==> ONGMobileAuthEnrollmentErrorMissingDevicePushToken
  • ONGMobileAuthenticationEnrollmentErrorNotEnrolled ==> ONGMobileAuthEnrollmentErrorNotEnrolled
  • ONGMobileAuthenticationRequestErrorDomain ==> ONGMobileAuthRequestErrorDomain
  • ONGMobileAuthenticationRequestErrorNotFound ==> ONGMobileAuthRequestErrorNotFound
  • ONGMobileAuthenticationRequestErrorUserDisenrolled ==> ONGMobileAuthRequestErrorUserDisenrolled

Renamed errors

  • ONGSDKInitialisationErrorDeviceRegistrationFailed ==> ONGGenericErrorDeviceRegistrationFailure
  • ONGRegistrationErrorDeviceRegistrationFailure ==> ONGGenericErrorDeviceRegistrationFailure

Removed error domains

  • ONGSDKInitializationErrorDomain The Initialization error domain is removed since it didn't contain any errors anymore after renaming & moving the ONGSDKInitialisationErrorDeviceRegistrationFailed error to the ONGGenericErrorDomain.

Instructions to upgrade iOS SDK version to 5.02

When upgrading from an older SDK version to version 5.02, several changes have to be applied in your application.

Although it is still possible to use the old APIs we recommend to update to the new APIs since the old ones will be removed in the next big update of the SDK.

Deprecated APIs

ONGUserClient

  • handleApplicationURL: ==> respondWithURL:challenge: method of id<ONGRegistrationRequestChallengeSender> object provided by the ONGRegistrationRequestChallenge <br/> Registration redirect URL can now be passed to the sdk using id<ONGRegistrationRequestChallengeSender>, which makes handleApplicationURL: obsolete.

ONGRegistrationDelegate

  • userClient:didReceiveRegistrationRequestWithUrl: ==> userClient:didReceiveRegistrationRequestChallenge:<br/> The URL is passed within ONGRegistrationRequestChallenge object. It also provides sender object used to respond with redirect URL or to cancel registration.

ONGClientBuilder

  • setUseEmbeddedWebView ==> No longer required. Onegini SDK no longer distinguishes how registration request URL is handled.

ONGPublicCommons

  • ONGCloseWebViewNotification ==> No longer required. Called only if setUseEmbeddedWebView was set to YES.<br/> Onegini SDK no longer distinguishes how registration request URL is handled. If registration request URL was handled by within UIWebView, it could be closed as soon as you send response to ONGRegistrationRequestChallengeSender or when you receive userClient:didReceivePinRegistrationChallenge: on your ONGRegistrationDelegate.

Instructions to upgrade iOS SDK version to 4.10

When upgrading from an older SDK version to version 4.10, several changes have to be applied in your application:

Although it is still possible to use the old APIs we recommend to update to the new APIs since the old ones will be removed in the next big update of the SDK.

Also the multiple profiles feature is not available when your app still uses the old APIs.

Deprecated APIs

OGOneginiClient

  • authorize ==> registerUser:delegate: and authenticateUser:delegate:. The authorize method had a dual responsibility: registering users and authenticating users. It has been split up into two methods: registerUser:delegate: and authenticateUser:delegate:. Use the first method in case you want to let a new user register his account in the application. After registration you must use authenticateUser:delegate: to authenticate the user. Only registerUser:delegate: will interact with a browser.
  • reauthorize: ==> reauthenticateUser:delegate:
  • authorizeClient: ==> authenticateClient:delegate:
  • confirmCurrentPin: ==> confirmPin: in the OGPinConfirmation protocol. Delegating control from the SDK to the app regarding the PIN has been changed to make it more clear that it is part of the authentication process. Therefore the SDK will call the askForCurrentPinForUser:pinConfirmation: method on the OGAuthenticationDelegate implementation. In response to the askForCurrentPinForUser:pinConfirmation: method which contains a delegate on which confirmPin must be called. The OGAuthenticationDelegate is the delegate that needs to be passed when calling authenticateUser:delegate:. Please look at the auto$ topic guide for more information regarding this topic.
  • confirmNewPin: ==> confirmPin: in the OGPinConfirmation protocol. Delegating control from the SDK to the app regarding the PIN has been changed to make it more clear that it is part of the registration process. Therefore the SDK will call the askForNewPin:user:pinConfirmation: method on the OGAuthenticationDelegate implementation. In response to the changePinRequest: method which contains a delegate on which confirmPin must be called. The OGAuthenticationDelegate is the delegate that needs to be passed when calling registerUser:delegate:. Please look at the auto$ topic guide for more information regarding this topic.
  • confirmCurrentPinForChangeRequest: ==> confirmPin: in the OGPinConfirmation protocol Delegating control from the SDK to the app regarding the PIN change functionality has been changed to make it more clear that it is part of the change PIN process. Therefore the SDK will call the askCurrentPinForChangeRequestForUser:pinConfirmation: method on the OGChangePinDelegate implementation. In response to the askCurrentPinForChangeRequestForUser:pinConfirmation: which contains a delegate on which confirmPin must be called. The OGChangePinDelegate is the delegate that needs to be passed when calling changePinRequest:.
  • confirmNewPinForChangeRequest: ==> confirmPin: in the OGPinConfirmation protocol Delegating control from the SDK to the app regarding the PIN change functionality has been changed to make it more clear that it is part of the change PIN process. Therefore the SDK will call the askNewPinForChangeRequest:pinConfirmation: method of the OGChangePinDelegate implementation. In response to the askNewPinForChangeRequest:pinConfirmation: which contains a delegate on which confirmPin must be called. The OGChangePinDelegate is the delegate that needs to be passed when calling changePinRequest:.
  • confirmCurrentPinForFingerprintAuthorization: ==> confirmPin: in the OGPinConfirmation protocol Delegating control from the SDK to the app regarding the fingerprint enrollment functionality has been changed to make it more clear that it is part of the fingerprint enrollment process. Therefore the SDK will call the askCurrentPinForFingerprintEnrollmentForUser:pinConfirmation: method on the OGFingerprintDelegate implementation. In response to the askCurrentPinForFingerprintEnrollmentForUser:pinConfirmation: which contains a delegate on which confirmPin must be called. The OGFingerprintDelegate is the delegate that needs to be passed when calling enrollForFingerprintAuthenticationWithDelegate:.
  • handleAuthorizationCallback: ==> handleAuthenticationCallback:
  • Fetching resources<br/> New methods have been introduced to fetch resources. The scopes attribute is no longer required in any of the fetchResource methods. Please follow the topic guide about auto$ to update your implementation to the latest methods
  • logoutWithDelegate: ==> logoutUserWithDelegate:
  • enrollForMobileAuthentication:delegate: ==> enrollUserForMobileAuthenticationWithDelegate:For more information regarding the enrollUserForMobileAuthenticationWithDelegate: method implementation see the auto$ topic guide.
  • enrollForFingerprintAuthentication:delegate: ==> enrollForFingerprintAuthenticationWithDelegate:For more information regarding the enrollForFingerprintAuthenticationWithDelegate: method implementation see the auto$ topic guide.
  • unenrollForFingerprintAuthenticationWithDelegate: ==> disableFingerprintAuthentication
  • disconnectWithDelegate: ==> deregisterUser:delegate: For more information regarding the deregisterUser:delegate: method implementation see the auto$ topic guide.
  • isClientRegistered ==> userProfiles In order to check whether a user is registered use the userProfiles method to get the profiles that are registered on this device.

OGEnrollmentHandlerDelegate

  • enrollmentInvalidClientCredentials ==> enrollmentErrorDeviceDeregistered

OGFingerprintDelegate

  • askCurrentPinForFingerprintAuthentication ==> askCurrentPinForFingerprintEnrollmentForUser:pinConfirmation:
  • fingerprintAuthenticationEnrollmentErrorTooManyPinFailures ==> fingerprintAuthenticationEnrollmentErrorUserDeregistered

OGResourceHandlerDelegate

  • resourceSuccess: ==> resourceResponse:body:requestId: We no longer distinguish between resource success or failure but always call the resourceResponse:body:requestId: method.
  • **resourceError ==> resourceResponse:body:requestId: We no longer distinguish between resource success or failure but always call the resourceResponse method.

On this page