feat(embedded): add /e/authorize email OTP flow #1075
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,42 +1,51 @@ | ||
| package com.auth0.android.embedded | ||
|
|
||
| import com.auth0.android.Auth0 | ||
| import com.auth0.android.embedded.authorize.AdvancingRequest | ||
| import com.auth0.android.embedded.authorize.AuthorizeCode | ||
| import com.auth0.android.embedded.authorize.EmbeddedAuthState | ||
| import com.auth0.android.embedded.authorize.EmbeddedCapability | ||
| import com.auth0.android.embedded.authorize.FailedRequest | ||
| import com.auth0.android.embedded.authorize.IdentifierType | ||
| import com.auth0.android.embedded.authorize.OtpType | ||
| import com.auth0.android.embedded.authorize.StepRequest | ||
| import com.auth0.android.embedded.authorize.authorizeCodeAdapter | ||
| import com.auth0.android.embedded.authorize.discoveryAdapter | ||
| import com.auth0.android.embedded.authorize.embeddedAuthErrorAdapter | ||
| import com.auth0.android.embedded.discovery.DiscoveryResult | ||
| import com.auth0.android.request.Request | ||
| import com.auth0.android.request.internal.GsonAdapter | ||
| import com.auth0.android.request.internal.GsonProvider | ||
| import com.auth0.android.request.internal.RequestFactory | ||
| import com.auth0.android.result.Credentials | ||
| import com.google.gson.Gson | ||
| import okhttp3.HttpUrl.Companion.toHttpUrl | ||
|
|
||
| /** | ||
| * | ||
| * | ||
| * API client for Auth0's embedded authentication API. | ||
| * | ||
| * ``` | ||
| * val auth0 = Auth0.getInstance("YOUR_CLIENT_ID", "YOUR_DOMAIN") | ||
| * val client = EmbeddedAuthClient(auth0) | ||
| * ``` | ||
| * | ||
| * **Note** | ||
| * Embedded Authorization is currently in [Beta](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#beta). Please reach out to Auth0 support to get it enabled for your tenant. | ||
| */ | ||
| public class EmbeddedAuthClient(private val auth0: Auth0) { | ||
|
|
||
| private val factory: RequestFactory<EmbeddedAuthException> = | ||
| RequestFactory(auth0.networkingClient, embeddedAuthErrorAdapter()) | ||
|
|
||
| private val gson: Gson = GsonProvider.gson | ||
|
|
||
| private val clientId: String | ||
| get() = auth0.clientId | ||
|
|
||
| @Volatile | ||
| private var transactionState: EmbeddedAuthState? = null | ||
|
Contributor
There was a problem hiding this comment.
Member
Author
There was a problem hiding this comment. Callbacks are usually returned on the main thread for us. But good to keep a safety check.
Member
Author
There was a problem hiding this comment. Added @volatile annotation to make this visible across threads |
||
|
|
||
| /** | ||
| * | ||
|
|
@@ -69,76 +78,192 @@ public class EmbeddedAuthClient(private val auth0: Auth0) { | |
| return factory.get(url.toString(), discoveryAdapter(gson)) | ||
| } | ||
|
|
||
| /** | ||
| * Begins an embedded authorization flow, abandoning any flow already in progress. | ||
| * | ||
| * This call never resolves successfully: the server always answers with a continuation, so the | ||
| * request completes through [EmbeddedAuthException]. Inspect | ||
| * [EmbeddedAuthException.isInsufficientAuthorization] and [EmbeddedAuthException.nextActions] to | ||
| * learn which step to call next. A terminal error is reported on the same failure channel. | ||
| * | ||
| * @param connection name of the connection to authenticate against. | ||
| * @param scope space-separated scopes to request. Must include `openid` for the terminal token | ||
| * exchange to return an ID token; defaults to `"openid profile email offline_access"`. | ||
| * @param audience optional API audience to request an access token for. | ||
| * @param capabilities the set of steps this client can handle in the flow. | ||
| */ | ||
| @JvmOverloads | ||
| public fun authorize( | ||
| connection: String, | ||
| scope: String = DEFAULT_SCOPE, | ||
| audience: String? = null, | ||
| capabilities: Set<EmbeddedCapability> = DEFAULT_CAPABILITIES | ||
| ): Request<Void?, EmbeddedAuthException> { | ||
| transactionState = null | ||
|
Contributor
There was a problem hiding this comment. Session gets read/cleared at construction, not execution. authorize() nulls the session the moment you build the request, and the step methods snapshot it at build time too. So client.authorize(...) kills an in-progress flow even if you never start it. Safer to do this when the request actually runs.
Member
Author
There was a problem hiding this comment. Each authorize call is a start of a new login flow. So irrespective of it returns us a valid auth_session or not, we will clear the existing session to mark the termination of any ongoing flow |
||
| val request = factory.post(authorizeUrl) | ||
| .addParameters(buildMap { | ||
| put(CLIENT_ID_KEY, clientId) | ||
| put(CONNECTION_KEY, connection) | ||
| put(SCOPE_KEY, scope) | ||
| audience?.let { put(AUDIENCE_KEY, it) } | ||
| }) | ||
| .addParameter(CAPABILITIES_KEY, capabilities.map { it.value }) | ||
| return stepping(request) | ||
| } | ||
|
|
||
| /** | ||
| * Continues the flow by submitting an identifier of the given [type]. | ||
| * | ||
| * This call never resolves successfully; it completes through [EmbeddedAuthException] whose | ||
| * [EmbeddedAuthException.nextActions] carry the next step to call. | ||
| */ | ||
| public fun identify( | ||
| identifier: String, | ||
| type: IdentifierType, | ||
| ): Request<Void?, EmbeddedAuthException> = when (type) { | ||
| IdentifierType.EMAIL -> | ||
| continueStep(EmbeddedCapability.IDENTIFY_EMAIL) { addParameter(EMAIL_KEY, identifier) } | ||
| } | ||
|
|
||
| /** | ||
| * Continues the flow by requesting an email challenge for the authenticator at [index]. | ||
| * | ||
| * This call never resolves successfully; it completes through [EmbeddedAuthException] whose | ||
| * [EmbeddedAuthException.nextActions] carry the next step to call. | ||
| */ | ||
| @JvmOverloads | ||
| public fun challengeEmail(index: Int = 0): Request<Void?, EmbeddedAuthException> = | ||
| continueStep(EmbeddedCapability.CHALLENGE_EMAIL) { | ||
| addParameter(INDEX_KEY, index) | ||
| } | ||
|
|
||
| /** | ||
| * Verifies a one-time [code] of the given [type]. This is the terminal step of the flow. | ||
| * | ||
| * On success, it yields the [Credentials]. If the server requires further steps the request | ||
| * completes through [EmbeddedAuthException] instead, with the next step on | ||
| * [EmbeddedAuthException.nextActions]. | ||
| */ | ||
| @JvmOverloads | ||
| public fun verifyOtp( | ||
| code: String, | ||
| type: OtpType = OtpType.OOB | ||
| ): Request<Credentials, EmbeddedAuthException> { | ||
| val session = transactionState?.authSession ?: return noActiveSession() | ||
| val request = factory.post(authorizeUrl, authorizeCodeAdapter(gson)) | ||
| .addParameters( | ||
| mapOf( | ||
| AUTH_SESSION_KEY to session, | ||
| ACTION_KEY to EmbeddedCapability.VERIFY_OTP.value, | ||
| CLIENT_ID_KEY to clientId | ||
| ) | ||
| ) | ||
| .addParameter(OTP_KEY, code) | ||
| .addParameter(TYPE_KEY, type.value) | ||
| return advancing(request) | ||
| } | ||
|
|
||
| private fun continueStep( | ||
| action: EmbeddedCapability, | ||
| addPayload: Request<Void?, EmbeddedAuthException>.() -> Unit = {} | ||
| ): Request<Void?, EmbeddedAuthException> { | ||
| val session = transactionState?.authSession ?: return noActiveSession() | ||
| val request = factory.post(authorizeUrl) | ||
| .addParameters( | ||
| mapOf( | ||
| AUTH_SESSION_KEY to session, | ||
| ACTION_KEY to action.value, | ||
| CLIENT_ID_KEY to clientId | ||
| ) | ||
| ) | ||
| request.addPayload() | ||
| return stepping(request) | ||
| } | ||
|
|
||
| private fun <T> noActiveSession(): Request<T, EmbeddedAuthException> = FailedRequest<T>( | ||
| EmbeddedAuthException( | ||
| NO_ACTIVE_SESSION_ERROR, | ||
| "No embedded authentication flow is in progress. Call authorize() first." | ||
| ) | ||
| ) | ||
|
|
||
| private fun stepping( | ||
| request: Request<Void?, EmbeddedAuthException> | ||
| ): Request<Void?, EmbeddedAuthException> = StepRequest(request, ::updateSessionFromFailure) | ||
|
|
||
| private fun advancing( | ||
| request: Request<AuthorizeCode, EmbeddedAuthException> | ||
| ): Request<Credentials, EmbeddedAuthException> = AdvancingRequest( | ||
| authorize = request, | ||
| exchange = ::exchange, | ||
| onStepFailure = ::updateSessionFromFailure, | ||
| onFlowComplete = { transactionState = null } | ||
| ) | ||
|
|
||
| private fun exchange(authorizationCode: String): Request<Credentials, EmbeddedAuthException> { | ||
| val url = auth0.getDomainUrl().toHttpUrl().newBuilder() | ||
| .addPathSegment(OAUTH_PATH) | ||
| .addPathSegment(TOKEN_PATH) | ||
| .build() | ||
| return factory.post(url.toString(), GsonAdapter(Credentials::class.java, gson)) | ||
|
Contributor
There was a problem hiding this comment. @pmathew92 in exchange dont we need to add id token verification?
Member
Author
There was a problem hiding this comment. Good point. We can take it as a follow up separate PR and not club with this |
||
| .addParameters( | ||
| mapOf( | ||
| CLIENT_ID_KEY to clientId, | ||
| GRANT_TYPE_KEY to GRANT_TYPE_AUTHORIZATION_CODE, | ||
| CODE_KEY to authorizationCode | ||
| ) | ||
| ) | ||
| } | ||
|
|
||
| private val authorizeUrl: String by lazy { | ||
| auth0.getDomainUrl().toHttpUrl().newBuilder() | ||
| .addPathSegment(EMBEDDED_PATH) | ||
| .addPathSegment(AUTHORIZE_PATH) | ||
| .build() | ||
| .toString() | ||
| } | ||
|
|
||
| private fun updateSessionFromFailure(error: EmbeddedAuthException) { | ||
|
Contributor
There was a problem hiding this comment. A network error wipes the session here. Network failures come through as unknown_error, not insufficient_authorization, so they hit the else and clear transactionState. But the spec (and our own authorize.md example) says network errors are safe to retry the same step — after this, the retry fails with no_active_session and forces a full restart. Can we only clear on terminal access_denied and keep the session on transient errors?
Member
Author
There was a problem hiding this comment. Yes. We can have check for transient errors for the same to ensure user is able to retry |
||
| when { | ||
| error.isInsufficientAuthorization && error.authSession != null -> | ||
| transactionState = EmbeddedAuthState(error.authSession) | ||
|
|
||
| error.isAccessDenied || error.isTooManyAttempts || error.isTooManyLogins -> | ||
|
Contributor
There was a problem hiding this comment. we should probably narrow it down to non retryable errors? @pmathew92
Member
Author
There was a problem hiding this comment. Yes, this will be revised with the error class refactoring changes |
||
| transactionState = null | ||
| } | ||
| } | ||
|
|
||
| private companion object { | ||
| private const val EMBEDDED_PATH = "e" | ||
| private const val DISCOVERY_PATH = "discovery" | ||
| private const val AUTHORIZE_PATH = "authorize" | ||
| private const val OAUTH_PATH = "oauth" | ||
| private const val TOKEN_PATH = "token" | ||
|
|
||
| private const val CLIENT_ID_KEY = "client_id" | ||
| private const val CONNECTION_KEY = "connection" | ||
| private const val SCOPE_KEY = "scope" | ||
| private const val AUDIENCE_KEY = "audience" | ||
| private const val CAPABILITIES_KEY = "capabilities" | ||
| private const val AUTH_SESSION_KEY = "auth_session" | ||
| private const val ACTION_KEY = "action" | ||
| private const val EMAIL_KEY = "email" | ||
| private const val PHONE_KEY = "phone" | ||
| private const val OTP_KEY = "otp" | ||
| private const val INDEX_KEY = "index" | ||
| private const val TYPE_KEY = "type" | ||
| private const val GRANT_TYPE_KEY = "grant_type" | ||
| private const val CODE_KEY = "code" | ||
| private const val GRANT_TYPE_AUTHORIZATION_CODE = "authorization_code" | ||
| private const val NO_ACTIVE_SESSION_ERROR = "no_active_session" | ||
|
|
||
| private const val DEFAULT_SCOPE = "openid profile email offline_access" | ||
|
Contributor
There was a problem hiding this comment. Default scope requests offline_access (i.e. a refresh token by default), but the spec has scope as optional. Just confirming that's intended. |
||
|
|
||
| private val DEFAULT_CAPABILITIES: Set<EmbeddedCapability> = setOf( | ||
| EmbeddedCapability.IDENTIFY_EMAIL, | ||
| EmbeddedCapability.CHALLENGE_EMAIL, | ||
| EmbeddedCapability.VERIFY_OTP | ||
| ) | ||
| } | ||
|
|
||
| init { | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.