This repository contains an SDK written in Kotlin for the Okta Identity Engine, as well as a sample Android application which can be used a reference for using okta-idx-kotlin on Android.
❕ This SDK requires usage of the Okta Identity Engine. This functionality is in General Availability but is being gradually rolled out to customers. If you want to gain access to the Okta Identity Engine, please reach out to your account manager. If you do not have an account manager, please reach out to [email protected] for more information.
Add the Okta IDX Kotlin dependency to your build.gradle file:
implementation 'com.okta.android:okta-idx-kotlin:3.0.1'See the CHANGELOG for the most recent changes.
If you run into problems using the SDK, you can
- Ask questions on the Okta Developer Forums
- Post issues here on GitHub (for code errors)
The idx-kotlin SDK embraces the dynamic policies of Okta Identity Engine with the interaction code flow. The SDK attempts to simplify the responses provided by the IDX endpoints, and provide a standard way of interaction with the IDX endpoints. This is a high level flowchart of how the idx-kotlin SDK methods would be used by a calling application.
graph TD
A(OidcClient.createInteractionCodeFlow) --> B(interactionCodeFlow.resume)
B --> C[Gather User Input]
C --> D(interactionCodeFlow.proceed)
D --> E{idxResponse.isLoginSuccessful}
E --> |yes| F(interactionCodeFlow.exchangeInteractionCodeForTokens)
E --> |no| C
F --> G[Use properties from TokenResponse in your application]
Gather User Input Notes:
- Use IdxResponse properties such as
remediationsandauthenticatorsto continue satisfying remediations until the user is logged in - Set
valueproperty in IdxRemediation.Form.Field - Set
selectedOptionproperty in IdxRemediation.Form.Field
Notice the cyclical call-and-response pattern. A user is presented with a series of choices in how they can iteratively step through the authentication process, with each step giving way to additional choices until they can either successfully authenticate or receive actionable error messages.
Each step in the authentication process is represented by an IdxResponse object, which contains the choices they can take, represented by the IdxRemediation class. Remediations provide metadata about its type, a form object tree that describes the fields and values that should be presented to the user, and other related data that helps you, the developer, build a UI capable of prompting the user to take action.
When a remediation is selected and its inputs have been supplied by the user, the InteractionCodeFlow.proceed method can be called on the remediation to proceed to the next step of the authentication process. This returns another IdxResponse object, which causes the process to continue.
The InteractionCodeFlow class is used to define and initiate an authentication workflow utilizing the Okta Identity Engine.
This class makes heavy use of Kotlin Coroutines to perform the actions asynchronously.
InteractionCodeFlow can be instantiated with OAuth2Client.default by using the default constructor InteractionCodeFlow(). Alternatively, a non-default OAuth2Client or OidcConfiguration can be provided.
The start method starts the authentication flow, and returns the result as OAuth2ClientResult<Unit>. The result is empty on success, and an error in form OAuth2ClientResult.Error in case of an error.
The resume method on an InteractionCodeFlow is used to reveal the current remediations.
This method is usually performed after an InteractionCodeFlow is created, but can also be called at any time to reveal what remediations are available to the user.
Executes the remediation option and proceeds through the workflow using the supplied form parameters.
This method is used to proceed through the authentication flow, using the data assigned to the nested fields' value and selectedOption to make selections.
This method is used when IdxResponse.isLoginSuccessful is true, and there is an IdxRemediation having a type of IdxRemediation.Type.ISSUE in the IdxRemediationCollection.
Pass the IdxRemediation with type IdxRemediation.Type.ISSUE to exchange the interaction code in the remediation for ID, access, and refresh tokens (based on the scopes provided in the OidcConfiguration).
This method evaluates the given redirect url to determine what next steps can be performed. This is usually used when receiving a redirection from an IDP authentication flow.
We are happy to accept contributions and PRs! Please see the contribution guide to understand how to structure a contribution.