OMCAuthorization Class Reference

Inherits from NSObject
Declared in OMCAuthorization.h

Overview

Module responsible for handling OAuth 2.0, Basic Authentication, and other authentication modes. The API allows for authentication, validity check, refresh (if applicable) and logout. Optionally, the underlying toolkit supplies a login dialog to get the user ID and password.

In the documentation below, the term “authentication” refers to what is appropriate for the authentication type in use. For OAuth, authentication acquires an OAuth token, whereas for Basic Authentication the authentication simply validates that the user/password combination is correct.

Note an OMCAuthorization instance is capable of holding only one valid set of authentication credentials at a time, so subsequent calls to acquire a token will overwrite any previous token that has not been released. The methods in this class are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. For methods that use asynchronous callbacks, the lifetime of the concurrency includes completion of the user callback.

Note to Swift developers: for full visibility to all the API’s in this class, add the following headers to your Objective-C bridging header: OMCUser.h from the Core library (this module), plus OMAuthView.h and OMDefinitions.h from the IDM Security Library. The latter two may be found in the “PublicHeaders” folder under the thirdParty distributions folder of the release.

  accessToken

The string representing the authentication token. This could be an OAuth token. For basic Authentication, only the name of the logged in user is returned so as to not reveal the password.

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

Declared In

OMCAuthorization.h

  userName

The user name of the authenticated user. Returns nil if user is not authenticated or if client credentials OAUth Type (anonymous) was used.

@property (readonly, strong, nonatomic, nullable) NSString *userName

Declared In

OMCAuthorization.h

  authorized

Whether authorization has been performed. For example, this could be acquisition of an OAuth token, or validation of a user/password combination.

@property (readonly, nonatomic) BOOL authorized

Declared In

OMCAuthorization.h

  authenticationType

Property indicating current authentication type from the enumeration OMCAuthenticationType. Note if the server instance supports multiple authentication types, the user may switch the authentication type in use at runtime.

@property (readwrite, nonatomic) OMCAuthenticationType authenticationType

Declared In

OMCAuthorization.h

  authenticationMode

Property indicating the current authentication mode. See the enumeration for possible values.

@property (readonly, nonatomic) OMCAuthenticationMode authenticationMode

Declared In

OMCAuthorization.h

  offlineAuthenticationEnabled

Property indicating whether the user may authenticate offline. If this mode is enabled, the user may authenticate against their cached credentials when the server-side is not reachable through the network.

@property (readwrite, nonatomic) BOOL offlineAuthenticationEnabled

Discussion

Note the user must have previously authenticated online and then have not logged out to keep the credentials available for offline authentication.

The default setting for this property is YES.

Declared In

OMCAuthorization.h

– isAuthenticationConfiguredForType:

Returns whether a given authentication type is configured for this object. Based on the OMCMobileBackend settings, one or more authentication types may be configured.

- (BOOL)isAuthenticationConfiguredForType:(OMCAuthenticationType)type

Parameters

type

The authentication type to be checked for.

Declared In

OMCAuthorization.h

– authenticate:password:completionBlock:

Performs the handshake to do the authentication with the supplied user name and password. Any required credentials beyond user and password are obtained from the mobile backend. This method does not require a UI for use, and the result is returned asynchronously.

- (void)authenticate:(NSString *)userName password:(NSString *)password completionBlock:(nullable OMCAuthorizationAuthCompletionBlock)completionBlock

Parameters

userName

The user name of the person acquiring the token.
password

The password of the person acquiring the token.
completionBlock

The handler invoked after the handshake has completed. The format of the completion handler is ^(NSError*).

Discussion

This API may be used for social login (e.g. Facebook) but the user name and password will be ignored. Equivalently, athenticateSocial may be invoked for this case.

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

Declared In

OMCAuthorization.h

– authenticateAnonymous:

Perform the handshake to do the authentication for the anonymous user. No user or password is required. For OAuth, The client ID and secret are obtained from the mobile backend. This method does not require a UI for use, and the result is returned asynchronously.

- (void)authenticateAnonymous:(nullable OMCAuthorizationAuthCompletionBlock)completionBlock

Parameters

completionBlock

the handler invoked after the handshake has completed. The format of the completion handler is ^(NSError*).

Discussion

Anonymous authentication is available from social login mode, although currently only Basic Authentication is supported.

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

Declared In

OMCAuthorization.h

– authenticate:password:

Gets the authentication token or logs in the user synchronously with the supplied user name and password. Any additional required credentials are obtained from the mobile backend. This method does not require a UI for use and should not be invoked from a UI thread. This method is primarily intended for testing and its use is not recommended in production code.

- (nullable NSError *)authenticate:(NSString *)userName password:(NSString *)password

Parameters

userName

The user name of the person acquiring the token.
password

The password of the person acquiring the token.

Return Value

An error if one occurred, else nil.

Discussion

This API may be used for social login (e.g. Facebook) but the user name and password will be ignored. Equivalently, athenticateSocial may be invoked for this case.

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

Declared In

OMCAuthorization.h

– authenticateAnonymous

Does the authentication synchronously for the anonymous login. No user or password is required. Any additional required credentials are obtained from the mobile backend. This method does not require a UI for use and should not be invoked from a UI thread. This method is primarily intended for testing and its use is not recommended in production code.

- (nullable NSError *)authenticateAnonymous

Return Value

An error if one occurred, else nil.

Discussion

Anonymous authentication is available from social login mode, although currently only Basic Authentication is supported.

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

Declared In

OMCAuthorization.h

– authenticateSocial:

Acquire the authentication credentials for a mobile social site asynchronously. Currently the only social app supported is Facebook. The user config file must be set up for Facebook-style authentication. This method does not require a UI for use, and the result is returned asynchronously.

- (void)authenticateSocial:(OMCAuthorizationAuthCompletionBlock)completionBlock

Parameters

completionBlock

the handler invoked after the handshake has completed. The format of the completion handler is ^(NSError*).

Discussion

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

Declared In

OMCAuthorization.h

– authenticateSocial

Acquire the authentication credentials for a mobile social site synchronously. Currently the only social app supported is Facebook. The user config file must be set up for Facebook-style authentication. This method is primarily intended for testing and its use is not recommended in production code.

- (NSError *)authenticateSocial

Discussion

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

Declared In

OMCAuthorization.h

– authenticateSSO:clearCookies:completionBlock:

Acquire the authentication credentials using federated single sign-on. The The user config file must be set up for SSO-style authentication. This method returns the result asynchronously.

- (void)authenticateSSO:(UIViewController *)presentingViewController clearCookies:(BOOL)clearCookies completionBlock:(OMCAuthorizationAuthCompletionBlock)completionBlock

Parameters

presentingViewController

A view controller upon which the SSO web browser view will be presented.
clearCookies

If set, clears all cookies related to authentication for this app
completionBlock

The handler invoked after the token acquisition attempt has completed. The format of the completion handler is ^(NSError*). If the user has cancelled, a standard iOS cancellation error is returned.

Discussion

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

Declared In

OMCAuthorization.h

– authenticateSSO:clearCookies:

Acquire the authentication credentials using federated single sign-on synchronously. The user config file must be set up for SSO-style authentication. This method is primarily intended for testing and its use is not recommended in production code due to thread-blocking behavior needed for synchronous execution.

- (NSError *)authenticateSSO:(UIViewController *)presentingViewController clearCookies:(BOOL)clearCookies

Parameters

presentingViewController

A view controller upon which the SSO web browser view will be presented.
clearCookies

If set, clears all cookies related to authentication for this app

Return Value

an error if one occurred, else nil

Discussion

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

Declared In

OMCAuthorization.h

– authenticateSSOTokenExchange:completionBlock:

Acquire the authentication credentials using the “SSO token exchange” paradigm, in which the caller acquires an external token and passes this external token to this method. The external token is exchanged for an internal token used as the credentials for future REST calls invoked by the mobile platform.

- (void)authenticateSSOTokenExchange:(NSString *)token completionBlock:(OMCAuthorizationAuthCompletionBlock)completionBlock

Parameters

token
  • The external token previously acquired by other means. This is assumed to be the base64 encoded representation of gzipped data.
completionBlock

the handler block called to report the results.

Discussion

  • If you choose to store the acquired MCS access token (by setting the storeAccessToken parameter to “YES”), you can then use the loadSSOTokenExchange() method so that the user does not have to log in again when restarting the app.

  • The stored access token will be associated with the mobile backend that was used when the token was obtained. Even if a different mobile backend is specified in the SDK config file or in any HTTP headers, if a token is reused, calls will be directed to the mobile backend that was specified originally. Therefore, if you update the app to use a different mobile backend (or mobile backend version), you need to clear the stored token with clearSSOTokenExchange() and then re-authenticate.

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

By default this method will not store token. See overloading method having storeAccessToken param to change it.

Declared In

OMCAuthorization.h

– authenticateSSOTokenExchange:

Acquire the authentication credentials using the “SSO token exchange” synchronously. The caller acquires an external token and passes this external token to this method. The external token is exchanged for an internal token used as the credentials for future REST calls invoked by the mobile platform.

- (NSError *)authenticateSSOTokenExchange:(NSString *)token

Parameters

token
  • The external token previously acquired by other means. This is assumed to be the base64 encoded representation of gzipped data.

Return Value

an error if one occurred, else nil

Discussion

  • If you choose to store the acquired MCS access token (by setting the storeAccessToken parameter to “YES”), you can then use the loadSSOTokenExchange() method so that the user does not have to log in again when restarting the app.

  • The stored access token will be associated with the mobile backend that was used when the token was obtained. Even if a different mobile backend is specified in the SDK config file or in any HTTP headers, if a token is reused, calls will be directed to the mobile backend that was specified originally. Therefore, if you update the app to use a different mobile backend (or mobile backend version), you need to clear the stored token with clearSSOTokenExchange() and then re-authenticate.

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

By default this method will not store token. See overloading method having storeAccessToken param to change it.

Declared In

OMCAuthorization.h

– authenticateSSOTokenExchange:storeAccessToken:completionBlock:

Acquire the authentication credentials using the “SSO token exchange” paradigm, in which the caller acquires an external token and passes this external token to this method. The external token is exchanged for an internal token used as the credentials for future REST calls invoked by the mobile platform.

- (void)authenticateSSOTokenExchange:(NSString *)token storeAccessToken:(BOOL)storeToken completionBlock:(OMCAuthorizationAuthCompletionBlock)completionBlock

Parameters

token
  • The external token previously acquired by other means. This is assumed to be the base64 encoded representation of gzipped data.
storeToken
  • If set to true, it will store the access token in secure keychain with expiry time on successful login.
completionBlock

the handler block called to report the results.

Discussion

  • If you choose to store the acquired MCS access token (by setting the storeAccessToken parameter to “YES”), you can then use the loadSSOTokenExchange() method so that the user does not have to log in again when restarting the app.

  • The stored access token will be associated with the mobile backend that was used when the token was obtained. Even if a different mobile backend is specified in the SDK config file or in any HTTP headers, if a token is reused, calls will be directed to the mobile backend that was specified originally. Therefore, if you update the app to use a different mobile backend (or mobile backend version), you need to clear the stored token with clearSSOTokenExchange() and then re-authenticate.

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

Declared In

OMCAuthorization.h

– authenticateSSOTokenExchange:storeAccessToken:

Acquire the authentication credentials using the “SSO token exchange” synchronously. The caller acquires an external token and passes this external token to this method. The external token is exchanged for an internal token used as the credentials for future REST calls invoked by the mobile platform.

- (NSError *)authenticateSSOTokenExchange:(NSString *)token storeAccessToken:(BOOL)storeToken

Parameters

token
  • The external token previously acquired by other means. This is assumed to be the base64 encoded representation of gzipped data.
storeToken
  • If set to true, it will store the access token in secure keychain with expiry time on successful login.

Return Value

an error if one occurred, else nil

Discussion

  • If you choose to store the acquired MCS access token (by setting the storeAccessToken parameter to “YES”), you can then use the loadSSOTokenExchange() method so that the user does not have to log in again when restarting the app.

  • The stored access token will be associated with the mobile backend that was used when the token was obtained. Even if a different mobile backend is specified in the SDK config file or in any HTTP headers, if a token is reused, calls will be directed to the mobile backend that was specified originally. Therefore, if you update the app to use a different mobile backend (or mobile backend version), you need to clear the stored token with clearSSOTokenExchange() and then re-authenticate.

Note: This method and all the other “authenticate” methods are not thread-safe, so the caller must use appropriate synchronization methods when the potential for concurrent invocation exists. The lifetime of the concurrency includes completion of the asynchronous user callback.

Declared In

OMCAuthorization.h

– loadSSOTokenExchange

Loads the cached MCS SSO token from the secure keychain.

- (BOOL)loadSSOTokenExchange

Return Value

If the token has been loaded from the secure keychain (the token is not null), returns true; otherwise false.

Discussion

  • This method reuses the token for on-going requests.

After calling this method, if the token is available, SDK calls will work using the obtained token from the secure keychain.

Declared In

OMCAuthorization.h

– clearSSOTokenExchange

Removes the MCS SSO token from the secure keychain and from memory.

- (void)clearSSOTokenExchange

Declared In

OMCAuthorization.h

– setHTTPHeadersOnRequest:

Sets the proper HTTP Authorization headers for an authorization-enabled request on the specified request. The exact headers depend on the authentication type in use.

- (void)setHTTPHeadersOnRequest:(NSMutableURLRequest *)request

Parameters

request

The request object to set the header on.

Discussion

Note this method does not add any MCS-specific headers other than those required for authentication. Call setHTTPHeadersOnRequest: from OMCMobileBackend to add all the MCS headers (including the authentication-specific headers).

See Also

Declared In

OMCAuthorization.h

– setHTTPHeadersOnRequest:completionHandler:

Sets the proper HTTP Authorization headers for an authorization-enabled request on the specified request. The exact headers depend on the authentication type in use. Note, this is an asynchronous method.

- (void)setHTTPHeadersOnRequest:(NSMutableURLRequest *)request completionHandler:(OMCErrorCompletionBlock)completionHandler

Parameters

request

The request object to set the header on.
completionHandler

The completion block invoked once the receiver’s HTTP headers have been set on the URL request or an error occurs. The format of the completion handler is ^(NSError* error).

See Also

Declared In

OMCAuthorization.h

– validateToken:

Returns whether the current token is valid (non-expired) and optionally refreshes the token if expired if the authentication protocol supports refresh.

- (BOOL)validateToken:(BOOL)refresh

Parameters

refresh

Whether to refresh the token (ignored for OAuth).

Return Value

Whether the token is still valid.

Discussion

Note: In the current implementation, OAuth token refresh is not supported by the server, so the the “refresh” will actually be a new token acquisition, provided the credentials have been cached.

For Facebook authentication, token refresh is unconditional, meaning that a new token will be acquired regardless of expiry and the “refresh” parameter value is ignored. Note these are long-lived tokens (60 days), so this method should only be called occasionally, or in response to receiving an HTTP 401.

For certain authentication types, such as Basic Authentication, where refresh is not supported, the “token” is taken to mean the “current login session”, so a return of YES indicates the user is currently logged in. Also for Basic Authentication, a return of NO indicates the refresh must be accomplished manually by invoking the authorization API, as the “refresh” parameter is ignored.

Declared In

OMCAuthorization.h

– refreshTokenAsync:

Returns asynchronously whether the current token is valid (non-expired) and refreshes the token if expired.

- (void)refreshTokenAsync:(nullable OMCAuthorizationTokenValidityBlock)completionBlock

Parameters

completionBlock

the handler block called to report the results. If valid is YES, the token was valid or has successfully been refreshed; otherwise, the entire authentication sequence should be re-initiated. The format of the completion handler is ^(BOOL valid, NSError* error).

Discussion

For Basic Authentication, the “token” is taken to mean the “current login session”, so if the token is not valid, the authentication sequence must be invoked by the caller as no refresh protocol is available for Basic Authentication.

Note: In the current implementation, OAuth token refresh is not supported by the server, so the “refresh” will actually be a new token acquisition, provided the credentials have been cached.

For Facebook authentication, token refresh is unconditional, meaning that a new token will be acquired regardless of expiry. Note that these are long-lived tokens (60 days), so this method should only be called occasionally, or in response to receiving an HTTP 401.

For Facebook authentication, token refresh is unconditional, meaning that a new token will be acquired regardless of expiry. Note that these are long-lived tokens (60 days), so this method should only be called occasionally, or in response to receiving an HTTP 401.

Declared In

OMCAuthorization.h

– logout:

Logs the user out and revokes the authentication credentials (if applicable and supported). Clears any local cached credentials. Note, this is an asynchronous method.

- (void)logout:(nullable OMCAuthorizationLogoutCompletionBlock)completionBlock

Parameters

completionBlock

The handler invoked after the logout attempt has completed. The completion handler is of the form ^(NSError*).

Declared In

OMCAuthorization.h

– logout

Synchronously logs the user out and revokes the authentication credentials (if applicable and supported). Clears any local cached credentials.

- (nullable NSError *)logout

Return Value

An error if one occurred, else nil.

Declared In

OMCAuthorization.h

– logoutClearCredentials:completionBlock:

Logs the user out and optionally revokes the authentication credentials (if applicable and supported). Clears any local cached credentials. Note this is an asynchronous call.

- (void)logoutClearCredentials:(BOOL)clearCredentials completionBlock:(nullable OMCAuthorizationLogoutCompletionBlock)completionBlock

Parameters

clearCredentials

whether or not to clear the cached credentials
completionBlock

the handler invoked after the logout attempt has completed. The completion handler is of the form ^(NSError*).

Declared In

OMCAuthorization.h

– logoutClearCredentials:

Synchronously logs the user out and revokes the authentication credentials (if applicable and supported). Clears any local cached credentials.

- (nullable NSError *)logoutClearCredentials:(BOOL)clearCredentials

Parameters

clearCredentials

whether or not to clear the cached credentials

Return Value

An error if one occurred, else nil.

Declared In

OMCAuthorization.h

– getCurrentUser:

Gets the properties for the currently authorized user. This is an asynchronous method where the success status is returned in the completion block.

- (void)getCurrentUser:(OMCUserRegistrationCompletionBlockWithUser)completionBlock

Parameters

completionBlock

The completion handler called upon return from the server. The completion handler is of the form ^(NSError, OMCUser).

Declared In

OMCAuthorization.h

– updateCurrentUser:completionCallback:

Updates the currently authorized user’s user management properties. This is an asynchronous method where the success status is returned in the completion block.

- (void)updateCurrentUser:(OMCUser *)user completionCallback:(OMCUserRegistrationCompletionBlock)completionBlock

Parameters

user

The user object to set as the current user attributes.
completionBlock

The completion handler called upon return from the server. The completion handler is of the form ^(NSError*).

Declared In

OMCAuthorization.h