OpenPass SDK for Android reference

This comprehensive reference guide documents the following packages used to integrate OpenPass single sign-on (SSO) with Android devices.

Package Description
com.myopenpass.auth Package Contains the main interface for the OpenPass SDK. This includes the OpenPass manager, which is the key entry point for accessing authenticated users.
com.myopenpass.data.auth Package Contains different supported user flows for authenticating the current user. It includes a web-based experience to validate one-time verification codes and an OIDC device-authorization flow designed for connected TVs.
com.myopenpass.flow.auth Package Contains the primary data models exposed by the SDK.
com.myopenpass.network.auth Package Manages how the SDK makes network requests, including an option that enables the consuming application to inject its own implementation.

For general information on the OpenPass service and implementation, see Getting started with OpenPass.

com.myopenpass.auth Package

This package contains the main interface for the OpenPass SDK. This includes the OpenPass manager, which is the key entry point for accessing authenticated users.

Browser unavailable exception

class BrowserUnavailableException : OpenPassException

OpenPass cannot launch a web browser because one does not appear available on the device.

Constructors

Name Summary
BrowserUnavailableException constructor()

Functions

Name Summary
addSuppressed fun addSuppressed(p0: Throwable)
fillInStackTrace open fun fillInStackTrace(): Throwable
getLocalizedMessage open fun getLocalizedMessage(): String
getStackTrace open fun getStackTrace(): Array<StackTraceElement>
getSuppressed fun getSuppressed(): Array<Throwable>
initCause open fun initCause(p0: Throwable): Throwable
printStackTrace open fun printStackTrace()
open fun printStackTrace (p0:PrintStream)
open fun printStackTrace(p0: PrintWriter)
setStackTrace open fun setStackTrace(p0: Array<StackTraceElement>)

Properties

Name Summary
cause open val cause: Throwable?
message open val message: String?

OpenPass object

object OpenPass

An object that provides access to constants provided by the SDK.

Functions

Name Summary
getVersion fun getVersion(): String
Gets the version of the included SDK library in string format.

OpenPass exception

open class OpenPassException(message: String? = null, cause: Throwable? = null) : Exception

Base class for all custom exceptions reported by the SDK.

Inheritors

BrowserUnavailableException is used for inheritance.

Constructors

Name Summary
OpenPassException constructor(message: String? = null, cause: Throwable? = null)

Functions

Name Summary
addSuppressed fun addSuppressed(p0: Throwable)
fillInStackTrace open fun fillInStackTrace(): Throwable
getLocalizedMessage open fun getLocalizedMessage(): String
getStackTrace open fun getStackTrace(): Array<StackTraceElement>
getSuppressed fun getSuppressed(): Array<Throwable>
initCause open fun initCause(p0: Throwable): Throwable
printStackTrace open fun printStackTrace()
open fun printStackTrace(p0: PrintStream)
open fun printStackTrace(p0: PrintWriter)
setStackTrace open fun setStackTrace(p0: Array<StackTraceElement>)

Properties

Name Summary
cause open val cause: Throwable?
message open val message: String?

OpenPass Manager

class OpenPassManager

This class represents the primary way to interact with the SDK. It is responsible for signing a user in and providing access to their associated OpenPass tokens.

When the application is created, the consuming application calls OpenPassManager.init, which initializes the manager and enables it to load previously stored tokens.

The manager also makes user updates through OpenPassUserChangedListener or OpenPassManager.state.

See also Initialize the OpenPass Manager.

Types

Name Summary
Companion object Companion

Functions

Name Summary
getClientDetails suspend fun getClientDetails(clientId: String): ClientDetails
Returns client details for a given client identifier.
getClientLogo fun getClientLogo(clientId: String): String?
Returns a URL for the logo associated with the given client identifier.
signOut fun signOut()
Signs the user out and clears data stored by the SDK.

Properties

Name Summary
currentTokens val currentTokens: OpenPassTokens?
Gets the current user's tokens, if available.
onUserChangedListener var onUserChangedListener: OpenPassUserChangedListener?
Gets or sets the listener that will be notified when the user state changes.
state val state: Flow<OpenPassManagerState>
The flow representing the state of the OpenPass manager.

OpenPass Manager state

interface OpenPassManagerState

An interface that defines the state of the flow as communicated by the OpenPass manager.

Inheritors

The following are used for inheritance:

Types

Name Summary
Error data class Error(val error: Throwable) : OpenPassManagerState
An unexpected error occurred.
Loading data object Loading : OpenPassManagerState
The manager is loading its state.
SignedIn data class SignedIn(val tokens: OpenPassTokens) : OpenPassManagerState
The user is signed in and has a valid set of OpenPass tokens.
SignedOut data object SignedOut : OpenPassManagerState
The user is not signed in.

OpenPass user changed listener

interface OpenPassUserChangedListener

A listener interface that notifies the consumer when the user changes within the OpenPass manager.

Functions

Name Summary
onError abstract fun onError(error: Throwable)
An error occurred when attempting to sign the given user in.
onUserChanged abstract fun onUserChanged(tokens: OpenPassTokens?)
The user and their tokens have changes.

com.myopenpass.data.auth Package

This package contains different supported user flows for authenticating the current user. It includes a web-based experience to validate one-time verification codes and an OIDC device-authorization flow designed for connected TVs.

Client details

data class ClientDetails(val id: String, val name: String, val applicationUri: String?, val privacyPolicyUri: String?, val androidPackages: List<PackageDetails >)

The public information associated with a client application.

Constructors

Name Summary
ClientDetails constructor(id: String, name: String, applicationUri: String?, privacyPolicyUri: String?, androidPackages: List<PackageDetails >)

Properties

Name Summary
androidPackages val androidPackages: List<PackageDetails >
applicationUri val applicationUri: String?
id val id: String
name val name: String
privacyPolicyUri val privacyPolicyUri: String?

Device code

data class DeviceCode (val userCode: String, val verificationUri: String, val verificationUriComplete: String?, val expiresTimeMs: Long)

The information required to prompt the user to authenticate on a separate device.

Constructors

Name Summary
DeviceCode constructor(userCode: String, verificationUri: String, verificationUriComplete: String?, expiresTimeMs: Long)

Properties

Name Summary
expiresTimeMs val expiresTimeMs: Long
The epoch-based time (in milliseconds) when the user code expires.
userCode val userCode: String
The code that the user is required to enter at the location defined by the verification URI.
verificationUri val verificationUri: String
The website the user is required to navigate to and enter the provided code.
verificationUriComplete val verificationUriComplete: String?
The complete URI that includes the verification address and code. This can be used to generate a QR code for the user to use, which simplifies navigation.

ID token

data class IDToken (val issuerIdentifier: String, val subjectIdentifier: String, val audience: String, val expirationTime: Long, val issuedTime: Long, val email: String? = null)

OIDC ID Token Data Object

See also ID Token in OpenID Connect Core 1.0.

Constructors

Name Summary
IDToken constructor(issuerIdentifier: String, subjectIdentifier: String, audience: String, expirationTime: Long, issuedTime: Long, email: String? = null)

Properties

Name Summary
audience val audience: String
The audience this ID token is intended for
email val email: String? = null
Email address provided by user
given_name val email: String? = null
The given or first name of the end user. Here are key points:
  • Max 50 characters.
  • In some cultures, individuals may have multiple given names — enter all given names as a single field with parts separated by spaces. For example: Gabriel Jose.
family_name val email: String? = null
The surname or last name of the end user. Here are key points:
  • Max 100 characters.
  • In some cultures, individuals may have multiple family names or no family name — enter all family names as a single field with parts separated by spaces, hyphens, or apostrophes. For example: Garcia Marquez, Smith-Johnson, D'Angelo.
expirationTime val expirationTime: Long
Expiration Time in UTC
issuedTime val issuedTime: Long
Issue Identifier
issuerIdentifier val issuerIdentifier: String
Issuer Identifier
subjectIdentifier val subjectIdentifier: String
Subject Identifier

OpenPass tokens

data class OpenPassTokens(val idTokenJWT: String, val accessToken: String, val tokenType: String, val expiresIn: Long)

Data object for OpenPass ID and access tokens.

Constructors

Name Summary
OpenPassTokens constructor(idTokenJWT: String, accessToken: String, tokenType: String, expiresIn: Long)

Types

Name Summary
Companion object Companion

Properties

Name Summary
accessToken val accessToken: String
Access Token
expiresIn val expiresIn: Long
Expiration Time of Token (in UTC)
idToken val idToken: IDToken?
idTokenJWT val idTokenJWT: String
ID Token as JWT
tokenType val tokenType: String
Type of Access Token

Package details

data class PackageDetails(val name: String, val signatures: List<String>)

Data object representing an Android package. This provides the name of the package, along with a list of known SHA-256 encoded signatures for signing the package.

Constructors

Name Summary
PackageDetails constructor(name: String, signatures: List<String >)

Properties

Name Summary
name val name: String
signatures val signatures: List<String >

com.myopenpass.flow.auth Package

This package contains the primary data models exposed by the SDK.

Device authorization flow changed listener

interface DeviceAuthorizationFlowChangedListener

A listener interface allowing the consumer to be notified when the flow changes within the device authorization flow client.

Functions

Name Summary
onComplete abstract fun onComplete(tokens: OpenPassTokens?)
The flow is complete and the associated OpenPass manager has obtained the set of OpenPass tokens.
onDeviceCodeAvailable abstract fun onDeviceCodeAvailable(deviceCode: DeviceCode)
A new device code is available.
onDeviceCodeExpired abstract fun onDeviceCodeExpired()
The previous device code has expired, and the consumer is required to re-start the flow through DeviceAuthorizationFlowClient.fetchDeviceCode.
onError abstract fun onError(error: Throwable)
An unexpected error has occurred.

Device authorization flow client

class DeviceAuthorizationFlowClient : SignInFlowClient

An implementation of the sign-in flow client designed to work with input-constrained devices. Rather than authenticating directly, the flow asks the user to go to a link on their computer or smartphone to authorize the device. This flow exposes the link and associated code while it waits for confirmation that authorization is complete.

See also device authorization flow in the Auth0 developer guide.

Constructors

Name Summary
DeviceAuthorizationFlowClient constructor(clientId: String, manager: OpenPassManager)
Constructor.

Functions

Name Summary
cancel open override fun cancel()
Cancels the current authorization flow.
close open override fun close()
Redirects to cancel the flow.
fetchDeviceCode fun fetchDeviceCode()
Starts the authorization flow by requesting a device code from the associated API server. The request is performed asynchronously, and the results are reported through the associated listener and/or state flow.

Properties

Name Summary
currentDeviceCode val currentDeviceCode: DeviceCode?
Gets the current device code, if available.
isComplete val isComplete: Boolean
Gets whether the current flow is complete.
isExpired val isExpired: Boolean
Gets whether the current device code has expired. If it has, a new instance needs to be re-fetched through fetchDeviceCode.
onDeviceAuthorizationFlowChangedListener var onDeviceAuthorizationFlowChangedListener: DeviceAuthorizationFlowChangedListener?
Gets or sets the listener that will be notified when the flow's state changes.
state val state: Flow<DeviceAuthorizationFlowState >
The flow representing the state of the device authorization flow client.
verifyExpiresAtLeeway var verifyExpiresAtLeeway: Long
Sets a specific time window in seconds during which the Expires At ("exp") claim remains valid.
verifyIssuedAtLeeway var verifyIssuedAtLeeway: Long
Sets a specific time window in seconds during which the Issued At ("iat") claim remains valid. This method overrides the value set by acceptLeeway(long). By default, the "Issued At" claim is verified when the value is present.

Device authorization flow state

interface DeviceAuthorizationFlowState

An interface that defines the state of the flow as communicated by the device authorization flow client.

Inheritors

The following are used for inheritance:

Types

Name Summary
Complete data class Complete(val tokens: OpenPassTokens?) : DeviceAuthorizationFlowState
The flow is complete. As an option, the resulting tokens are set on the OpenPass manager.
DeviceCodeAvailable data class DeviceCodeAvailable(val deviceCode: DeviceCode) : DeviceAuthorizationFlowState
A new device code is available.
DeviceCodeExpired data object DeviceCodeExpired : DeviceAuthorizationFlowState
The previous device code has expired, and the consumer is required to re-start the flow through DeviceAuthorizationFlowClient.fetchDeviceCode.
Error data class Error(val error: Throwable) : DeviceAuthorizationFlowState
An unexpected error has occurred.
Initialized data object Initialized : DeviceAuthorizationFlowState
The flow was initialized but not started.

Sign-in flow client

abstract class SignInFlowClient(clientId: String, dispatcher: CoroutineDispatcher) : Closeable

A base class for all flows that attempt to sign in. This allows the SDK to offer multiple custom flows based on consumer and platform needs.

Inheritors

The following are used for inheritance:

Constructors

Name Summary
SignInFlowClient constructor(clientId: String, dispatcher: CoroutineDispatcher)

Functions

Name Summary
cancel open fun cancel()
Cancels previous sign-in attempts.
close open override fun close()
Redirects to cancel the flow.

Properties

Name Summary
verifyExpiresAtLeeway var verifyExpiresAtLeeway: Long
Sets a specific time window in seconds during which the Expires At ("exp") claim remains valid.
verifyIssuedAtLeeway var verifyIssuedAtLeeway: Long
Sets a specific time window in seconds during which the Issued At ("iat") claim remains valid. This method overrides the value set by acceptLeeway(long). By default, the "Issued At" claim is verified when the value is present.

Web sign-in flow client

open class WebSignInFlowClient : SignInFlowClient

An implementation of the sign-in flow client using Custom Tabs to present a web-based authentication flow. This enables the user to enter an email address and receive a code for signing in. After the user validates their email, the web browser running the web flow closes and uses a new Android Intent to redirect to the consuming application. The Intent contains necessary information required for The Trade Desk to generate a set of OpenPass tokens.

Constructors

Name Summary
WebSignInFlowClient constructor(clientId: String, manager: OpenPassManager)
Constructor.

Functions

Name Summary
cancel open override fun cancel()
Cancels in-flight authentication flows.
checkSignIn fun checkSignIn (intent: Intent): Job
Checks the given Intent to see if it's a response from the Custom-Tabs-based authentication flow. If it is, The Trade Desk will attempt to generate and return a set of OpenPass tokens.
close open override fun close()
Redirects to cancel the flow.
launchSignIn fun launchSignIn(context: Context)
Attempts to launch the Custom Tabs authentication flow using the provided Context.

Properties

Name Summary
isComplete val isComplete: Boolean
Gets whether the current flow is complete.
navigationBarColor var navigationBarColor: Int?
Sets the navigation bar color. Has no effect on API versions below Lollipop.
navigationBarDividerColor var navigationBarDividerColor: Int?
Sets the navigation-bar divider color. Has no effect on API versions below Pie.
onWebSignInFlowChangedListener var onWebSignInFlowChangedListener: WebSignInFlowListener?
Gets or sets the listener that will be notified when the flow state changes.
secondaryToolbarColor var secondaryToolbarColor: Int?
Sets the color of the secondary toolbar.
state val state: Flow<WebSignInFlowState >
The flow representing the state of the device authorization flow client.
toolbarColor var toolbarColor: Int?
Sets the toolbar color. On Android Lollipop and above, this color is also applied to the status bar.
verifyExpiresAtLeeway var verifyExpiresAtLeeway: Long
Sets a specific time window in seconds during which the Expires At ("exp") claim remains valid.
verifyIssuedAtLeeway var verifyIssuedAtLeeway: Long
Sets a specific time window in seconds during which the Issued At ("iat") claim remains valid. This method overrides the value set by acceptLeeway(long). By default, the "Issued At" claim is verified when the value is present.

Web sign-in flow listener

interface WebSignInFlowListener

A listener interface allowing the consumer to be notified when the flow changes within the web sign-in flow client.

Functions

Name Summary
onComplete abstract fun onComplete()
The flow is complete and the associated OpenPass manager has obtained a set of OpenPass tokens.
onError abstract fun onError(error: Throwable)
An unexpected error has occurred.

Web sign-in flow state

interface WebSignInFlowState

An interface that defines the state of the flow as communicated by the web sign-in flow client.

Inheritors

The following are used for inheritance:

Types

Name Summary
Complete data object Complete : WebSignInFlowState
The flow is complete and the associated OpenPass manager has obtained a set of OpenPass tokens.
Error data class Error(val error: Throwable) : WebSignInFlowState
An unexpected error has occurred.
Launched data object Launched : WebSignInFlowState
The flow was started, and the web component requesting to authorize the user was launched.

com.myopenpass.network.auth Package

This package manages how the SDK makes network requests, including an option that enables the consuming application to inject its own implementation.

DefaultNetworkSession

open class DefaultNetworkSession : NetworkSession

A default implementation of a network session that leverages HttpURLConnection to make the necessary GET and POST requests.

Constructors

Name Summary
DefaultNetworkSession constructor()

Functions

Name Summary
loadData open override fun loadData(url: URL, request: NetworkRequest): NetworkResponse
Loads the given URL and network request using an HttpURLConnection.
openConnection open fun openConnection(url: URL): HttpURLConnection
Opens the given URL to return the HttpURLConnection.

Network request

data class NetworkRequest(val type: NetworkRequestType, val headers: Map <String, String> = mapOf(), val data: String? = null)

A class which represents a network request. This could include a number of headers to be used within the request. If the request is a POST, additional data needs to be written to the connection.

Parameters

Name Summary
type The type of request required.
headers The collection of headers (in key/value pairs) to be used in the request.
data Optional body data used in NetworkRequestType.POST.

Constructors

Name Summary
NetworkRequest constructor(type: NetworkRequestType, headers: Map <String, String > = mapOf(), data: String? = null)

Properties

Name Summary
data val data: String? = null
headers val headers: Map <String, String>
type val type: NetworkRequestType

Network request type

enum NetworkRequestType : Enum <NetworkRequestType>

The type of request that needs to be made. The Trade Desk only requires a GET or POST.

Methods

Name Summary
GET GET
An HTTP GET request.
POST POST
An HTTP POST request. It should include data within the body.

Functions

Name Summary
valueOf fun valueOf(value: String): NetworkRequestType
Returns the enum constant of this type with the specified name. The string must match an identifier used to declare an enum constant in this type. Extraneous whitespace characters are not permitted.
values fun values(): Array < NetworkRequestType >
Returns an array containing the constants of this enum type in the order they are declared.

Properties

Name Summary
name val name: String
ordinal val ordinal: Int

Network response

data class NetworkResponse(val code: Int, val data: String = "")

A class which represents a network response. This includes the HTTP status code and any response data.

Parameters

Name Summary
code The HTTP response code received after attempting to make a request.
data The body data contained within the response. If none is available, a empty string will be provided.

Constructors

Name Summary
NetworkResponse constructor(code: Int, data: String = "")

Properties

Name Summary
code val code: Int
data val data: String

Network session

interface NetworkSession

This interface manages network access. The library provides a default implementation, but developers can also implement the interface to use their own networking code, such as OkHttp.

Inheritors

DefaultNetworkSession is used for inheritance.

Types

Name Summary
Companion object Companion

Functions

Name Summary
loadData abstract fun loadData(url: URL, request: NetworkRequest): NetworkResponse
Requests the given URL with the details provided in the request.