Instructions for

On this page

Build a custom sign-in UI in your mobile app

Note: This document is written for Okta Classic Engine. If you are using Okta Identity Engine, contact your Okta account team for guidance or ask on our forum. See Identify your Okta solution to determine your Okta version.

You can connect your mobile app to Okta and sign users in by opening a browser, however, if you prefer that your users not leave your app, you need to build a custom sign-in UI with native controls and screens instead. Use this guide to build a customized sign-in experience inside your mobile application.

Note: We strongly advise against using WebViews for authentication on mobile apps as this practice exposes users to unacceptable security risks. See OAuth 2.0 for Native Apps. Consider using Okta's native SDKs instead.

Note: If the browser sign-in method works for your application, we recommend using that since building a custom sign-in UI takes more effort and development time.


Learning outcomes

Build a custom mobile sign-in UI.

What you need

Sample code


Create an Okta application

Before you can sign a user in, you need to create an Okta application that represents your mobile application.

Use the Okta application that you created when you walked through the Sign users into your mobile app using the redirect model guide.

Add and configure packages

To build the custom sign-in UI, you need to install and configure a native Okta SDK to your application.

You should already have added and configured packages when you walked through the Sign users into your mobile app using the redirect model guide.

In addition, you need to install the native Okta Authentication SDK. This SDK works together with the OpenID Connect SDK that you already installed to make authentication requests to Okta.

Build the primary authentication form

Okta's Authentication SDK is built around a state machine. Review the available states before you use this library.

You can implement an authentication flow using one screen or using multiple screens. When you use multiple screens, you can spilt responsibilties across screens and then inject related data as a dependency.

For example, multiple screens could handle:

  • login/password input
  • multifactor enrollment
  • factor selection
  • multifactor verification

Handle authentication responses

Every authentication transaction starts with primary authentication, which validates a user's password. Password Policy, MFA Policy, and Sign-On Policy are evaluated during primary authentication to determine if the user's password is expired, a factor should be enrolled, or additional verification is required. The transaction state of the response depends on the user's status, group memberships, and assigned policies.

Note: Custom sign-in only works with Org MFA. This means that before you exchange the session token for an access token, you must ensure that App-Level MFA (opens new window) is disabled for the application.

Note: In Identity Engine, the MFA Enrollment Policy name has changed to authenticator enrollment policy.

Next steps

You should now understand how to build a custom UI in your mobile application.

When a user signs in, their profile information (stored in Okta) is made available to your application. Use this information to personalize your app's UI for the user. See Get info about the user for details.