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 OMCUser
.h
to your Objective-C bridging header.
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 OMCErrorCompletionBlock)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 OMCErrorCompletionBlock)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:(OMCErrorCompletionBlock)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:(OMCErrorCompletionBlock)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:(OMCErrorCompletionBlock)completionBlock
Parameters
token |
|
---|---|
completionBlock |
the handler block called to report the results. |
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.
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 |
|
---|
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.
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:(OMCErrorCompletionBlock)completionBlock
Parameters
token |
|
---|---|
storeToken |
|
completionBlock |
the handler block called to report the results. |
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: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 |
|
---|---|
storeToken |
|
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
– loadSSOTokenExchange
Load the cached SSO Token Exchange from secure keychain. After calling this method, if token is avaiable, SDK calls will work using the obtained token from the secure keychain.
- (BOOL)loadSSOTokenExchange
Return Value
Incase of token has been loaded from secure keychain (token is not null), returns true otherwise false.
Declared In
OMCAuthorization.h
– clearSSOTokenExchange
Removes the token of SSO Token Exchange from secure keychain and from memory.
- (void)clearSSOTokenExchange
Declared In
OMCAuthorization.h
– setHTTPHeadersOnURLRequest:
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)setHTTPHeadersOnURLRequest:(NSMutableURLRequest *)request
Parameters
request |
The request object to set the header on. |
---|
Discussion
Note this method does not add any OMCe-specific headers other than those required for authentication. Call setHTTPHeadersOnURLRequest: from OMCMobileBackend to add all the OMCe headers (including the authentication-specific headers).
See Also
[OMCMobileBackend setHTTPHeadersOnURLRequest:]
Declared In
OMCAuthorization.h
– setHTTPHeadersOnURLRequest: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)setHTTPHeadersOnURLRequest:(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
– 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 OMCErrorCompletionBlock)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 OMCErrorCompletionBlock)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