com.microfocus.android.mobile.sdk.library

Interface ServiceContext

public interface ServiceContext

The principal SDK service context interface containing methods for:

• SDK cached content life cycle
• Symmetric Key Management
• Symmetric Key Management
• Identity Provider Persistence
• Authentication Persistence
• SDK Settings

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ServiceContext.RollKeyCallback Defines the interface that must be implemented by the callback object passed to the rollKey(Context, ServiceContext.RollKeyCallback) method.

Field Summary

Fields

Modifier and Type	Field and Description
static long	ACCESS_TOKEN_EXPIRATION_NO_AUTHENTICATION As a return value from ServiceContext#getTimeToAccessTokenExpiration(Context, String, String) indicates that no authentication information is available for the indicated Identity Provider, so the time to the access token's expiration could not be calculated.
static long	ACCESS_TOKEN_EXPIRATION_NOT_FOUND As a return value from ServiceContext#getTimeToAccessTokenExpiration(Context, String, String) indicates that no access token was present in the authentication information for the indicated Identity Provider, so the time to the access token's expiration could not be calculated.
static long	ACCESS_TOKEN_REFRESH_BEFORE_EXPIRATION_BY_DEFAULT The default value to use as the access token "refresh before exiration by" (1 minute).
static long	KEYAGE_UNKNOWN Initial state of the age of the encryption key.

Method Summary

Modifier and Type	Method and Description
void	authenticate(Authenticator authenticator) Initiate an authentication.
AuthState	deleteAuthentication(Context context) Delete from persisted data the Authentication Information for the currently persisted Identity Provider.
IdentityProvider	deleteIdentityProvider(Context context) Delete from persisted data the IdentityProvider instance.
AuthenticatorReport	fromJsonAuthenticatorReport(java.lang.String json) A utility method to allow clients to create a AuthenticatorReport from a JSON representation.
UnAuthenticatorReport	fromJsonUnAuthenticatorReport(java.lang.String json) A utility method to allow clients to create a UnAuthenticatorReport from a JSON representation.
java.lang.String	getAccessToken(Context context) Get the Access Token for the currently persisted Identity Provider.
AuthState	getAuthentication() Get from persisted data the Authentication Information for the currently persisted Identity Provider.
AuthenticatorBuilder	getAuthenticatorBuilder(Context context, AuthenticatorClientCallback onCompleteClientCallback) Obtain an Authenticator Builder object that can be used to instantiate a new Authenticator object.
IdentityProvider	getIdentityProvider() Get the persisted IdentityProvider.
IdentityProviderBuilder	getIdentityProviderBuilder(IdentityProvider source) Obtain an Identity Provider Builder object that can be used to instantiate a new IdentityProvider object with a IdentityProvider instance as the template.
IdentityProviderBuilder	getIdentityProviderBuilder(java.lang.String json) Obtain an Identity Provider Builder object that can be used to instantiate a new IdentityProvider object with a JSon document as the template.
IdentityProviderBuilder	getIdentityProviderBuilder(java.lang.String providerUrl, java.lang.String clientId, java.lang.String clientSecret, java.lang.String redirectURI) Obtain an Identity Provider Builder object that can be used to instantiate a new IdentityProvider object.
long	getKeyAge() Get the age of the current encryption key in millseconds since epoch.
java.lang.String	getRefreshToken(Context context) Get the Refresh Token for the currently persisted Identity Provider.
long	getTimeToAccessTokenExpiration(Context context) Get the amount of time until the next Access Token update needs to be performed for the currently persisted Identity Provider.
UnAuthenticatorBuilder	getUnAuthenticatorBuilder(Context context, UnAuthenticatorClientCallback onCompleteClientCallback) Obtain an Un-Authenticator Builder object that can be used to instantiate a new UnAuthenticator object.
void	invokeWithFreshToken(Context context, InvokeTask task, long tokenExpirationWindow) Invoke a client implemented task using an access token that will be automatically refreshed if need be.
void	onPause() Android activity lifecycle onPause() method.
void	onResume() Android activity lifecycle onResume() method.
void	onStart(Context context) Android activity lifecycle onStart() method.
void	onStop() Android activity lifecycle onStop() method.
IdentityProvider	putIdentityProvider(Context context, IdentityProvider identityProvider) Persist the provided IdentityProvider instance.
void	rollKey(Context context, ServiceContext.RollKeyCallback callback) Update the current encryption key to a new randomly generated key.
java.lang.String	toJson(AuthenticatorReport report) A utility method to allow clients to convert a AuthenticatorReport to a JSON representation.
java.lang.String	toJson(UnAuthenticatorReport report) A utility method to allow clients to convert a UnAuthenticatorReport to a JSON representation.
void	unauthenticate(UnAuthenticator unAuthenticator) Initiate an un-authentication (logout).

Field Detail

ACCESS_TOKEN_REFRESH_BEFORE_EXPIRATION_BY_DEFAULT

static final long ACCESS_TOKEN_REFRESH_BEFORE_EXPIRATION_BY_DEFAULT

The default value to use as the access token "refresh before exiration by" (1 minute).

See Also:

Constant Field Values

KEYAGE_UNKNOWN

static final long KEYAGE_UNKNOWN

Initial state of the age of the encryption key.

See Also:

Constant Field Values

ACCESS_TOKEN_EXPIRATION_NO_AUTHENTICATION

static final long ACCESS_TOKEN_EXPIRATION_NO_AUTHENTICATION

As a return value from ServiceContext#getTimeToAccessTokenExpiration(Context, String, String) indicates that no authentication information is available for the indicated Identity Provider, so the time to the access token's expiration could not be calculated.

See Also:

Constant Field Values

ACCESS_TOKEN_EXPIRATION_NOT_FOUND

static final long ACCESS_TOKEN_EXPIRATION_NOT_FOUND

As a return value from ServiceContext#getTimeToAccessTokenExpiration(Context, String, String) indicates that no access token was present in the authentication information for the indicated Identity Provider, so the time to the access token's expiration could not be calculated.

See Also:

Constant Field Values

Method Detail

onStart

void onStart(Context context)

Android activity lifecycle onStart() method. Call this method from your application's main activity onStart() method.

Parameters:

context - The android application context. Probably the main activity.

onResume

void onResume()

Android activity lifecycle onResume() method. Call this method from your application's main activity onResume() method.

onPause

void onPause()

Android activity lifecycle onPause() method. Call this method from your application's main activity onPause() method.

onStop

void onStop()

Android activity lifecycle onStop() method. Call this method from your application's main activity onStop() method.

getKeyAge

long getKeyAge()

Get the age of the current encryption key in millseconds since epoch.

Returns:

the age of the current encryption key in millseconds since epoch.

rollKey

void rollKey(Context context,
             ServiceContext.RollKeyCallback callback)

Update the current encryption key to a new randomly generated key.

All persisted settings, Identity Providers, and Authentications will be converted to use the new key.

Parameters:

context - The android application context.

callback - The client callback method that will be called once all persisted data has been converted to use the new key. Must not be null.

toJson

java.lang.String toJson(AuthenticatorReport report)

A utility method to allow clients to convert a AuthenticatorReport to a JSON representation. This may be necessary to pass AuthenticatorReport instances between Android activities.

Parameters:

report - The report to be converted to JSON.

Returns:

A JSON string representation of the provided AuthenticatorReport instance.

See Also:

fromJsonAuthenticatorReport(String)

fromJsonAuthenticatorReport

AuthenticatorReport fromJsonAuthenticatorReport(java.lang.String json)

A utility method to allow clients to create a AuthenticatorReport from a JSON representation. This may be necessary to pass AuthenticatorReport instances between Android activities.

Parameters:

json - The JSON representation to be used in instantiating the AuthenticatorReport.

Returns:

A newly instantiated AuthenticatorReport instance.

toJson

java.lang.String toJson(UnAuthenticatorReport report)

A utility method to allow clients to convert a UnAuthenticatorReport to a JSON representation. This may be necessary to pass UnAuthenticatorReport instances between Android activities.

Parameters:

report - The report to be converted to JSON.

Returns:

A JSON string representation of the provided UnAuthenticatorReport instance.

See Also:

fromJsonUnAuthenticatorReport(String)

fromJsonUnAuthenticatorReport

UnAuthenticatorReport fromJsonUnAuthenticatorReport(java.lang.String json)

A utility method to allow clients to create a UnAuthenticatorReport from a JSON representation. This may be necessary to pass UnAuthenticatorReport instances between Android activities.

Parameters:

json - The JSON representation to be used in instantiating the UnAuthenticatorReport.

Returns:

A newly instantiated UnAuthenticatorReport instance.

getAuthenticatorBuilder

AuthenticatorBuilder getAuthenticatorBuilder(Context context,
                                             AuthenticatorClientCallback onCompleteClientCallback)

Obtain an Authenticator Builder object that can be used to instantiate a new Authenticator object.

Parameters:

context - The android application context.

onCompleteClientCallback - The client's callback that will be invoked when authentication completes. Must not be null

Returns:

The builder instance.

authenticate

void authenticate(Authenticator authenticator)
           throws AuthenticatorException

Initiate an authentication.

The authentication will be initiated on the calling thread and then will complete on other threads.

Once authentication is complete, the provided callback will be invoked with a report of the completion status of the authentication.

Parameters:

authenticator - The Authenticator object fully configured to perform the authentication.

Throws:

AuthenticatorException - If the thrown exception is:
AuthenticatorException.CANNOT_REUSE_AUTHENTICATOR
AuthenticatorException.ACTIVE_AUTHENTICATION
then the onCompleteClientCallback callback will not be called. On all other AuthenticatorException types the callback will be called.

getUnAuthenticatorBuilder

UnAuthenticatorBuilder getUnAuthenticatorBuilder(Context context,
                                                 UnAuthenticatorClientCallback onCompleteClientCallback)

Obtain an Un-Authenticator Builder object that can be used to instantiate a new UnAuthenticator object.

Parameters:

context - The android application context.

onCompleteClientCallback - The client's callback that will be invoked when un-authentication completes. Must not be null

Returns:

The builder instance.

unauthenticate

void unauthenticate(UnAuthenticator unAuthenticator)
             throws AuthenticatorException

Initiate an un-authentication (logout).

The un-authentication will be initiated on the calling thread and then will complete on other threads.

Once un-authentication is complete, the provided callback will be invoked with a report of the completion status of the un-authentication.

Parameters:

unAuthenticator - The logout object that contains the configuration for the logout.

Throws:

AuthenticatorException - If the thrown exception is any of the following:
AuthenticatorException.CANNOT_REUSE_AUTHENTICATOR
then the onCompleteClientCallback callback will not be called. On all other AuthenticatorException types the callback will be called.

getIdentityProviderBuilder

IdentityProviderBuilder getIdentityProviderBuilder(java.lang.String providerUrl,
                                                   java.lang.String clientId,
                                                   java.lang.String clientSecret,
                                                   java.lang.String redirectURI)

Obtain an Identity Provider Builder object that can be used to instantiate a new IdentityProvider object.

This signature of a builder will typically be used when creating a new IdentityProvider from a recently acquired identity provider data set.

This signature does not provide all of the end points required to successfully instantiate the new IdentityProvider. Either the IdentityProviderBuilder.setDiscoveryEndPoint(String) must be set to allow the additional Identity Provider end points to be obtained from the remote OAuth2 server, or the two methods, IdentityProviderBuilder.setAuthorizationEndPoint(String) and IdentityProviderBuilder.setTokenEndPoint(String), must be called to manually set these two end points.

If the IdentityProviderBuilder.build() method is called without a setting the end points as described above, then the builder will automatically assume the Identity Provider is an instance of a Novell Access Manager (NAM) server and all end points will be set to the well known NAM end point values. This may. or may not, be desired behavior.

Parameters:

providerUrl - The provider (root) URL for the new Identity Provider. Must not be null.

clientId - The OAuth2 client identifier for the new Identity Provider. Must not be null.

clientSecret - The OAuth2 client secret for the new Identity Provider. Must not be null.

redirectURI - The redirect URI for the new Identity Provider. Must not be null.

Returns:

The builder that may be used to set additional properties of the resultant IdentityProvider.

getIdentityProviderBuilder

IdentityProviderBuilder getIdentityProviderBuilder(java.lang.String json)

Obtain an Identity Provider Builder object that can be used to instantiate a new IdentityProvider object with a JSon document as the template.

This signature of a builder will typically be used when a previously existing IdentityProvider was serialized to JSon, passed through an Intent, or some other event requiring a stringified version of the IdentityProvider, and then needs to be reconstituted into an IdentityProvider instance.

The JSon may provide all of the client data and end points required to successfully instantiate the new IdentityProvider.

Parameters:

json - The JSon representation of an IdentityProvider object that will be used as the template for the new Identity Provider. The format of the JSon document must match exactly the format produced by IdentityProvider.toJson(). Must not be null.

Returns:

The builder that may be used to set additional properties of the resultant IdentityProvider.

getIdentityProviderBuilder

IdentityProviderBuilder getIdentityProviderBuilder(IdentityProvider source)

Obtain an Identity Provider Builder object that can be used to instantiate a new IdentityProvider object with a IdentityProvider instance as the template.

This signature of a builder will typically be used when cloning a previously existing IdentityProvider. Client applications will probably have little need of doing this.

The source IdentityProvider instance will provide all of the client data and end points required to successfully instantiate the new IdentityProvider.

Parameters:

source - The IdentityProvider instance that will be used as the template for the new Identity Provider. Must not be null.

Returns:

The builder that may be used to set additional properties of the resultant IdentityProvider.

getIdentityProvider

IdentityProvider getIdentityProvider()

Get the persisted IdentityProvider.

Returns:

The IdentityProvider instance. May be null if a Identity Provider is not found.

putIdentityProvider

IdentityProvider putIdentityProvider(Context context,
                                     IdentityProvider identityProvider)

Persist the provided IdentityProvider instance. Any persisted existing IdentityProvider instance will be overwritten with the provided IdentityProvider instance.

Parameters:

context - The android application context.

identityProvider - The Identity Provider to persist.

Returns:

The previously existing IdentityProvider instance. May be null if no Identity Provider existed.

deleteIdentityProvider

IdentityProvider deleteIdentityProvider(Context context)

Delete from persisted data the IdentityProvider instance.

Parameters:

context - The android application context.

Returns:

The previously existing IdentityProvider instance. May be null if no Identity Provider existed.

deleteAuthentication

AuthState deleteAuthentication(Context context)

Delete from persisted data the Authentication Information for the currently persisted Identity Provider.

Parameters:

context - The android application context.

Returns:

The previously existing AuthState instance. May be null if no Identity Provider or authentication information existed.

getAuthentication

AuthState getAuthentication()

Get from persisted data the Authentication Information for the currently persisted Identity Provider.

Using this method to access authentication information bypasses all checks to ensure that the access token and refresh token are up to date. Use of this method by users of this sdk library is discouraged. Instead, use an Authenticator object to complete an authentication and obtain authentication information from the provided AuthenticatorReport.

Returns:

The current existing AuthState instance. May be null if no Identity Provider existed or if no AuthState instance existed.

getRefreshToken

java.lang.String getRefreshToken(Context context)

Get the Refresh Token for the currently persisted Identity Provider.

Parameters:

context - The android application context.

Returns:

The Refresh Token. May be null.

getAccessToken

java.lang.String getAccessToken(Context context)

Get the Access Token for the currently persisted Identity Provider.

Parameters:

context - The android application context.

Returns:

The Access Token. May be null.

getTimeToAccessTokenExpiration

long getTimeToAccessTokenExpiration(Context context)

Get the amount of time until the next Access Token update needs to be performed for the currently persisted Identity Provider.

Parameters:

context - The android application context.

Returns:

The amount of time in milliseconds. A positive value indicates the amount of time until the next update. A negative value indicates the amount of time that the update is overdue. Two special case negative numbers exist: ACCESS_TOKEN_EXPIRATION_NO_AUTHENTICATION means the authentication information is not found (no authentication information at all), ACCESS_TOKEN_EXPIRATION_NOT_FOUND means the the Access Token does not exist.

invokeWithFreshToken

void invokeWithFreshToken(Context context,
                          InvokeTask task,
                          long tokenExpirationWindow)
                   throws AuthenticatorException

Invoke a client implemented task using an access token that will be automatically refreshed if need be. The task may perform any operation, but the underlying support classes are built assuming that the probable operation will be to make asynchronous HTTP requests.

To use this method, there must be a persisted IdentityProvider and a persisted authentication AuthState with at least a valid refresh token. The access token in the authentication may be expired.

This method does the following:
1) Examines persisted Identity Provider. If none, throws.
2) Examines persisted authentication, If none, throws.
3) Examines access token, if not expired (or within window) prepares and executes task.
4) Examines access token, if expired but exists a refresh token, refreshes access token and then prepares and executes task.

The task may, or may not, contain a client callback that will be called at the completion of task execution.

Parameters:

context - The Android application context.

task - The client implemented task that will be prepared by the SDK framework with the access token and then executed. This task will not be executed if this method throws an Exception.

tokenExpirationWindow - The duration of the window before the expiration of the access token in which the access token should STILL BE REFRESHED even though it is not fully expired yet. In milliseconds.

Throws:

AuthenticatorException - Throws exception when state failures are detected. For example, no persisted IdentityProvider or no persisted AuthState.