Instructions for

On this page

Share a sign-in session with native mobile apps

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.

This guide uses sample apps to demonstrate how to share a Single Sign-On (SSO) session on a mobile device. After you complete this guide, you should have a better understanding of how a sign-in session is shared between two mobile apps on a device and will be able to use the steps in the guide to help you configure your own apps.

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.


Learning outcomes

  • Persist a session between multiple OIDC mobile apps
  • Clear the session when appropriate

What you need

Sample code


Overview

In OAuth, the authentication flow for web apps uses URIs to initiate the authorization request and to return the response to the web app. The flow is similar for mobile apps. The mobile app uses an external user-agent (the device's browser) to perform authentication. Since the authorization request from a mobile app is initiated from the device's browser, you can apply sign-in principles that are similar to web apps in order to share a sign-in session between mobile apps on a device.

Session and persistent Single Sign-On

Single Sign-On (SSO) allows users to authenticate once and access multiple resources without being prompted for additional credentials. Okta supports both session and persistent SSO:

  • Session SSO: Session SSO cookies are written for the authenticated user, which eliminates further prompts when the user switches applications during a particular session. However, if a particular session ends, the user is prompted for their credentials again.
  • Persistent SSO: Persistent SSO cookies are written for the authenticated user, which eliminates further prompts when the user switches applications for as long as the persistent SSO cookie is valid.

The difference between persistent SSO and session SSO is you can be maintain persistent SSO across different sessions. Persistent SSO is disabled by default in Okta. To share a sign-in session with native mobile apps, you need to enable persistent SSO.

Configure Two OpenID Connect Native Apps

Within the same org, you need to set up two Native OpenID Connect (OIDC) client apps.

  1. In the Admin console, go to Applications > Applications.
  2. Click Create App Integration.
  3. Select OIDC - OpenID Connect as the Sign-in method.
  4. Select Native Application as the Application type and click Next.
  5. Give the app integration a name, and then enter com.first.sample:/callback in the Sign-in redirect URIs box for the first app.

    Note: When you create the second app, enter com.second.sample:/callback.

  6. Ensure that Authorization Code and Refresh Token are selected in the Grant Type Allowed section.
  7. Assign the group that you want (if you set Group Assignments for your app) or leave the Everyone default. For instructions on how to assign the app integration to individual users and groups, see the Assign app integrations (opens new window) topic in the Okta product documentation.
  8. Click Save.
  9. In the General Settings section, click Edit.
  10. In the Login section, click Add URI next to Sign-out Redirect URIs.
  11. Enter com.first.sample:/logout for the first app.

    Note: When you create the second app, enter com.second.sample:/logout.

  12. Scroll to the Client Credentials section. Copy the Client IDs for both the first and second app for use in a later step.

Next, you set up the mobile applications using the configuration from these native apps that you just created.

Set up the first mobile app

In this section, you configure settings for the first mobile app.

Note: This section assumes that you have already downloaded the appropriate sample apps — see the sample links at the top of the article.

Add the redirect scheme

To redirect back to your application from a web browser, specify a unique URI to your app.

Create a second mobile app

You need a second mobile app to test with.

Optional settings

There are a few additional settings that you can play with while testing shared SSO that involve the use of the prompt parameter. See Parameter details (opens new window) for more information on using the prompt parameter.

Always prompt for sign in regardless of session

If you are using the same Okta domain for both of your apps, the default behavior when a session already exists is that the user is silently authenticated without a sign-in prompt. If your second application requires a prompt for sign-in regardless of session, you can configure this by passing in the prompt=login parameter.

Check for a valid session

You can also check if the browser has a valid session by using the prompt=none parameter. The prompt=none parameter guarantees that the user isn't prompted for credentials. Either the requested tokens are obtained or if the session is invalid or doesn't exist, the application receives an OAuth error response. See Parameter details (opens new window) for more information on using the prompt parameter.

If your application requires that the user signs in to the first app first, then you can use the prompt=none parameter in the second app to check whether the user is already signed in to the first app.

Clear the session

To clear a session, add the following code to both of your apps:

Next steps

You should now have a better understanding of how a sign-in session is shared between two mobile apps on a device and the knowledge to configure your own apps.

To learn more about our Mobile OpenID Connect (OIDC) SDKs and sample apps:

Android:

iOS: