ONGUserClient Class Reference

Inherits from NSObject
Declared in ONGUserClient.h

Overview

This is the main entry point into the SDK. The public API of the SDK consists of this client and an authorization delegate. The client must be instantiated early in the App lifecycle and thereafter only referred to by it’s shared instance.

+ sharedInstance

Access to the initialized and configured instance of the ONGUserClient. Before calling this method You have to initialize SDK by calling [ONGClientBuilder build].

+ (ONGUserClient *)sharedInstance

Return Value

instance of the configured ONGUserClient.

Discussion

Warning: If the SDK is not initialized via [ONGClientBuilder build] this method throws an exception.

See Also

  • ONGClientBuilder, [ONGClient userClient]

Declared In

ONGUserClient.h

– authenticateUser:delegate:

One of two entry points into the authentication process. This method is using preferred authenticator to authenticate.

- (void)authenticateUser:(ONGUserProfile *)userProfile delegate:(id<ONGAuthenticationDelegate>)delegate

Parameters

userProfile

profile to authenticate
delegate

authentication delegate, ONGUserClient keeps weak reference on delegate to avoid retain cycles

Declared In

ONGUserClient.h

– authenticateUserWithAuthenticator:profile:delegate:

One of two entry points into the authentication process.

- (void)authenticateUserWithAuthenticator:(ONGAuthenticator *)authenticator profile:(ONGUserProfile *)profile delegate:(id<ONGAuthenticationDelegate>)delegate

Parameters

authenticator

authenticatior used to authenticate
profile

profile to authenticate
delegate

authentication delegate, ONGUserClient keeps weak reference on delegate to avoid retain cycles

Declared In

ONGUserClient.h

– implicitlyAuthenticateUser:scopes:completion:

Main entry point into the implicit authentication process.

- (void)implicitlyAuthenticateUser:(ONGUserProfile *)userProfile scopes:(nullable NSArray<NSString*> *)scopes completion:(void ( ^ ) ( BOOL success , NSError *error ))completion

Parameters

userProfile

profile to authenticate
scopes

array of scopes
completion

block that will be called on implicit authentication completion.

Declared In

ONGUserClient.h

– registerUserWithIdentityProvider:scopes:delegate:

Main entry point into the registration process.

- (void)registerUserWithIdentityProvider:(nullable ONGIdentityProvider *)identityProvider scopes:(nullable NSArray<NSString*> *)scopes delegate:(id<ONGRegistrationDelegate>)delegate

Parameters

identityProvider

a specific identity provider used for registration, if nil is provided the token server will pick a default identity provider
scopes

array of scopes
delegate

registration delegate, ONGUserClient keeps weak reference on delegate to avoid retain cycles

Declared In

ONGUserClient.h

– changePin:

Initiates the PIN change sequence. If no refresh token is registered then the sequence is cancelled. This will invoke a call to the ONGAuthorizationDelegate - (void)askForPinChange:(NSUInteger)pinSize;

- (void)changePin:(id<ONGChangePinDelegate>)delegate

Parameters

delegate

Object handling change pin callbacks

Declared In

ONGUserClient.h

– authenticatedUserProfile

Return currently authenticated user.

- (nullable ONGUserProfile *)authenticatedUserProfile

Return Value

authenticated user

Declared In

ONGUserClient.h

– implicitlyAuthenticatedUserProfile

Return currently implicitly authenticated user.

- (nullable ONGUserProfile *)implicitlyAuthenticatedUserProfile

Return Value

authenticated user

Declared In

ONGUserClient.h

– validatePinWithPolicy:completion:

Checks if the pin satisfies all pin policy constraints.

- (void)validatePinWithPolicy:(NSString *)pin completion:(void ( ^ ) ( BOOL valid , NSError *_Nullable error ))completion

Parameters

pin

pincode to validate against pin policy constraints
completion

completion block invoked when validation is completed

Discussion

The returned error will be either within the ONGGenericErrorDomain or the ONGPinValidationErrorDomain.

Declared In

ONGUserClient.h

– logoutUser:

Performs a user logout, by invalidating the access token. The refresh token and client credentials remain untouched.

- (void)logoutUser:(nullable void ( ^ ) ( ONGUserProfile *userProfile , NSError *_Nullable error ))completion

Parameters

completion

completion block that is going to be invoked upon logout completion.

Discussion

The returned error will be either within the ONGGenericErrorDomain or the ONGLogoutErrorDomain.

Declared In

ONGUserClient.h

– enrollForMobileAuth:

Enrolls the currently connected device for mobile authentication.

- (void)enrollForMobileAuth:(void ( ^ ) ( BOOL enrolled , NSError *_Nullable error ))completion

Parameters

completion

delegate handling mobile enrollment callbacks

Discussion

The returned error will be either within the ONGGenericErrorDomain or the ONGMobileAuthEnrollmentErrorDomain

Declared In

ONGUserClient.h

– isUserEnrolledForMobileAuth:

Indicates whenever user is enrolled for mobile authentication.

- (BOOL)isUserEnrolledForMobileAuth:(ONGUserProfile *)userProfile

Parameters

userProfile

user profile

Return Value

BOOL indicating if the user is enrolled for mobile auth

Declared In

ONGUserClient.h

– enrollForPushMobileAuthWithDeviceToken:completion:

Enrolls the currently connected user for mobile authentication with Push.

- (void)enrollForPushMobileAuthWithDeviceToken:(NSData *)deviceToken completion:(void ( ^ ) ( BOOL enrolled , NSError *_Nullable error ))completion

Parameters

deviceToken

device token returned by APNS
completion

delegate handling mobile authentication enrollment callbacks

Discussion

The returned error will be either within the ONGGenericErrorDomain or the ONGMobileAuthEnrollmentErrorDomain

Declared In

ONGUserClient.h

– isUserEnrolledForPushMobileAuth:

Indicates whenever user is enrolled for push mobile authentication.

- (BOOL)isUserEnrolledForPushMobileAuth:(ONGUserProfile *)userProfile

Parameters

userProfile

user profile

Return Value

BOOL indicating if the user is enrolled for mobile auth with push

Declared In

ONGUserClient.h

– canHandleOTPMobileAuthRequest:

Indicates if mobile authentication request can be handled by validating request string. The string should be in JSON format and it should contain valid transaction_id and otp code.

- (BOOL)canHandleOTPMobileAuthRequest:(NSString *)otp

Parameters

otp

base64 string containing the OTP

Return Value

true, if request string can be processed by the Onegini SDK

Declared In

ONGUserClient.h

– handleOTPMobileAuthRequest:delegate:

Handles mobile authentication done with the one time password (OTP). The client will then fetch the actual encrypted payload and invoke the delegate with the embedded message.

- (void)handleOTPMobileAuthRequest:(NSString *)otp delegate:(id<ONGMobileAuthRequestDelegate>)delegate

Parameters

otp

base64 string containing the OTP
delegate

delegate responsible for handling push messages

Discussion

The returned error will be either within the ONGGenericErrorDomain or ONGMobileAuthRequestErrorDomain domain.

Declared In

ONGUserClient.h

– pendingPushMobileAuthRequests:

Fetches the pending push mobile authentications.

- (void)pendingPushMobileAuthRequests:(void ( ^ ) ( NSArray<ONGPendingMobileAuthRequest*> *_Nullable , NSError *_Nullable ))completion

Parameters

completion

block passing an array (sorted by the date) of the pending requests or an error from ONGGenericErrorDomain

Declared In

ONGUserClient.h

– canHandlePushMobileAuthRequest:

Ensures that a push notification that is received by the application can be handled by the SDK. It is useful to check whether the SDK can handle it or not for various use reasons. In contrast to -handleMobileAuthenticationRequest:delegate: the -canHandleMobileAuthenticationRequest: does not start any handling of the noticiation (no side-effects). It might be useful when you’re building a queue of mobile authentication request handling to prevent interferences between simultaneously received / running requests.

- (BOOL)canHandlePushMobileAuthRequest:(NSDictionary *)userInfo

Parameters

userInfo

the userInfo of the received push notification

Return Value

true, if the notification can be processed by the Onegini SDK

Declared In

ONGUserClient.h

– pendingMobileAuthRequestFromUserInfo:

Parses user info object (from notification that is received by the application) into ONGPendingMobileAuthRequest. The returned ONGPendingMobileAuthRequest object should be used to handle received notification handlePendingPushMobileAuthRequest:delegate:.

- (nullable ONGPendingMobileAuthRequest *)pendingMobileAuthRequestFromUserInfo:(NSDictionary *)userInfo

Parameters

userInfo

the userInfo of the received push notification

Return Value

ONGPendingMobileAuthRequest object, if the notification can be processed by the Onegini SDK

Discussion

This should be invoked from the UIApplicationDelegate - (void)userNotificationCenter:(UNUserNotificationCenter )center didReceiveNotificationResponse:(UNNotificationResponse )response withCompletionHandler:(void (^)(void))completionHandler

The returned error will be either within the ONGGenericErrorDomain, ONGAuthenticationErrorDomain or ONGMobileAuthRequestErrorDomain.

Declared In

ONGUserClient.h

– handlePushMobileAuthRequest:delegate:

When a push notification is received by the application, the notification must be forwarded to the client. The client will then fetch the actual encrypted payload and invoke the delegate with the embedded message.

- (void)handlePushMobileAuthRequest:(NSDictionary *)userInfo delegate:(id<ONGMobileAuthRequestDelegate>)delegate

Parameters

userInfo

userInfo of received push notification
delegate

delegate responsible for handling push messages

Discussion

This should be invoked from the UIApplicationDelegate - (void)application:(UIApplication )application didReceiveRemoteNotification:(NSDictionary )userInfo

Declared In

ONGUserClient.h

– handlePendingPushMobileAuthRequest:delegate:

Handles pending push mobile authentication request. The client will then fetch the actual encrypted payload and invoke the delegate with the embedded message.

- (void)handlePendingPushMobileAuthRequest:(ONGPendingMobileAuthRequest *)pendingMobileAuthRequest delegate:(id<ONGMobileAuthRequestDelegate>)delegate

Parameters

pendingMobileAuthRequest

representation of a pending mobile authentication request.
delegate

delegate responsible for handling push messages

Declared In

ONGUserClient.h

– userProfiles

List of enrolled users stored locally

- (NSSet<ONGUserProfile*> *)userProfiles

Return Value

Enrolled users

Declared In

ONGUserClient.h

– deregisterUser:completion:

Delete user locally and revoke it from token server

- (void)deregisterUser:(ONGUserProfile *)userProfile completion:(nullable void ( ^ ) ( BOOL deregistered , NSError *_Nullable error ))completion

Parameters

userProfile

user to disconnect.
completion

completion block that will be invoke upon deregistration completion.

Discussion

The returned error will be either within the ONGGenericErrorDomain or the ONGDeregistrationErrorDomain.

Declared In

ONGUserClient.h

– fetchResource:completion:

Perform an authenticated network request. It requires passing an instance of the ONGResourceRequest as parameter. In case of a malformed request no task will be returned and the completion block is called immediatelly (sychronously). The User needs to be authenticated, otherwise SDK will return the ONGFetchResourceErrorUserNotAuthenticated error.

- (nullable ONGNetworkTask *)fetchResource:(ONGResourceRequest *)request completion:(nullable void ( ^ ) ( ONGResourceResponse *_Nullable response , NSError *_Nullable error ))completion

Parameters

request

instance of ONGResourceRequest instantiated manually or by using ONGRequestBuilder
completion

block that will be called either upon request completion or immediatelly in case if validation error.

Return Value

instance of ONGNetworkTask or nil. By utilizing ONGNetworkTask developer may observe and control execution of the request.

Discussion

The returned errors will be within the ONGGenericErrorDomain, ONGFetchResourceErrorDomain or NSURLErrorDomain.

Declared In

ONGUserClient.h

– fetchImplicitResource:completion:

Perform an implicitly authenticated network request. It requires passing an instance of the ONGResourceRequest as parameter. In case of a malformed request no task will be returned and the completion block is called immediatelly (sychronously). The User needs to be authenticated implicitly, otherwise SDK will return the ONGFetchImplicitResourceErrorUserNotAuthenticatedImplicitly error.

- (nullable ONGNetworkTask *)fetchImplicitResource:(ONGResourceRequest *)request completion:(nullable void ( ^ ) ( ONGResourceResponse *_Nullable response , NSError *_Nullable error ))completion

Parameters

request

instance of ONGResourceRequest instantiated manually or by using ONGRequestBuilder
completion

block that will be called either upon request completion or immediatelly in case if validation error.

Return Value

instance of ONGNetworkTask or nil. By utilizing ONGNetworkTask developer may observe and control execution of the request.

Discussion

The returned errors will be within the ONGGenericErrorDomain, ONGFetchImplicitResourceErrorDomain or NSURLErrorDomain.

Declared In

ONGUserClient.h

– identityProviders

Returns a set of identity providers.

- (NSSet<ONGIdentityProvider*> *)identityProviders

Return Value

set of identity providers

Declared In

ONGUserClient.h

  accessToken

Returns a access token for the currently authenticated user, or nil if no user is currently authenticated.

@property (nonatomic, readonly, nullable) NSString *accessToken

Return Value

String with access token or nil

Discussion

Warning: Do not use this method if you want to fetch resources from your resource gateway: use the resource methods instead.

Declared In

ONGUserClient.h

– nonRegisteredAuthenticatorsForUser:

Returns a set of authenticators which are supported both, client and server side, and are not yet registered.

- (NSSet<ONGAuthenticator*> *)nonRegisteredAuthenticatorsForUser:(ONGUserProfile *)userProfile

Parameters

userProfile

user profile for which authenticators are fetched

Return Value

set of non registered authenticators

Declared In

ONGUserClient.h

– registeredAuthenticatorsForUser:

Returns a set of registered authenticators.

- (NSSet<ONGAuthenticator*> *)registeredAuthenticatorsForUser:(ONGUserProfile *)userProfile

Parameters

userProfile

user profile for which authenticators are fetched

Return Value

set of registered authenticators

Declared In

ONGUserClient.h

– allAuthenticatorsForUser:

Returns a set of both registered and nonregistered authenticators.

- (NSSet<ONGAuthenticator*> *)allAuthenticatorsForUser:(ONGUserProfile *)userProfile

Parameters

userProfile

user profile for which authenticators are fetched

Return Value

set of registered authenticators

Declared In

ONGUserClient.h

– registerAuthenticator:delegate:

Registers an authenticator. Use one of the non registered authenticators returned by nonRegisteredAuthenticatorsForUser: method. Registering an authenticator may require user authentication which is handled by the delegate.

- (void)registerAuthenticator:(ONGAuthenticator *)authenticator delegate:(id<ONGAuthenticatorRegistrationDelegate>)delegate

Parameters

authenticator

to be registered authenticator
delegate

delegate registering the authenticator

Discussion

The returned errors will be within the ONGGenericErrorDomain, ONGAuthenticatorRegistrationErrorDomain or ONGAuthenticationErrorDomain.

Declared In

ONGUserClient.h

– deregisterAuthenticator:delegate:

Deregisters an authenticator. Use one of the registered authenticators returned by registeredAuthenticatorsForUser: method.

- (void)deregisterAuthenticator:(ONGAuthenticator *)authenticator delegate:(id<ONGAuthenticatorDeregistrationDelegate>)delegate

Parameters

authenticator

to be deregistered authenticator
delegate

delegate deregistering the authenticator

Discussion

The returned errors will be within the ONGGenericErrorDomain, ONGAuthenticatorDeregistrationErrorDomain or ONGAuthenticationErrorDomain.

Declared In

ONGUserClient.h

– appToWebSingleSignOnWithTargetUrl:completion:

This method allows to take a session from mobile application and extend it to a browser on the same device.

- (void)appToWebSingleSignOnWithTargetUrl:(NSURL *)targetUrl completion:(void ( ^ ) ( NSURL *_Nullable , NSString *_Nullable , NSError *_Nullable ))completion

Parameters

targetUrl

url for which the App To Web Single Sign On token is requested
completion

completion block invoked when action is completed

Discussion

The returned errors will be within the ONGGenericErrorDomain or ONGAppToWebSingleSignOnErrorDomain.

Declared In

ONGUserClient.h

  preferredAuthenticator

Represents preferred authenticator. By default SDK uses PIN as preferred authenticator.

@property (nonatomic) ONGAuthenticator *preferredAuthenticator

Declared In

ONGUserClient.h