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. You can also 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 OpenID Connect (OIDC) mobile apps.
• Clear the session when appropriate.

What you need

• An Okta Integrator Free Plan org. Don't have one? Create one for free (opens new window).
• Android Studio with an emulator for Android testing.
• Xcode with a simulator for iOS testing.

Sample code

See the Classic Engine samples in the legacy branch of the iOS Samples repository (opens new window) for multiple samples.

You configure the Okta Classic Engine iOS Browser Sign-In Sample App (opens new window) in the Set up the first mobile app section.

---

Overview

In OAuth, the authentication flow for web apps uses URIs to initiate the authorization request and to return the response. The flow is similar for mobile apps. The mobile app uses an external user-agent (the device's browser) to perform authentication.

The authorization request from a mobile app is initiated from the device's browser. Therefore, you can apply sign-in principles that are similar to web apps to share a sign-in session between mobile apps on a device.

Session and persistent SSO

SSO allows users to authenticate once and access multiple resources without being prompted for more 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 apps 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 apps for as long as the persistent SSO cookie is valid.

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

To enable persistent SSO for iOS apps, you need to update the usePersistentCookie (opens new window) parameter in the appropriate global session policy. These steps use the Okta Policy Postman collection (opens new window) to enable the parameter.

Before you begin, be sure to:

• Create an API token for your Org.
• Download the Policy Postman collection.

1. In Postman, expand the Policies (Okta API) folder, and then the Global Session Policy folder.

2. Click the Get Global Session Policies request to open it, and then click Send to run it.

   Example request:

   GET https://{yourOktaDomain}/api/v1/policies?type=OKTA_SIGN_ON
   

3. In the response, locate the policy that you want to modify and copy its id value.

   Tip: You can also highlight the policy ID, right-click it, and set it as the value for the policyId variable in your environment.

4. Click the Get Rules request to open it.

5. In the request URL, replace the policyId variable with the policy ID that you copied. If you assigned the policy ID as a variable in your environment, skip this step.

   Tip: To see which value is assigned to a variable, hover over the variable in the request URL and a box pops up that displays the currently assigned variable value.

6. Click Send to run the request.

   Example:

   GET https://{yourOktaDomain}/api/v1/policies/00p2sy9ploJnRwPwp5g7/rules
   

7. In the response, locate the rule that you want to modify, copy its id value, and copy the actions property section of the JSON payload.

   Note: You can't modify the Default Rule properties usePersistentCookie or maxSessionLifetimeMinutes. Copy the id value of a custom rule instead. If you only see a Default Rule in the response, then you should first create a custom rule.

   Tip: You can also highlight the rule ID, right-click, and set it as the value for the ruleId variable in your environment.

8. Click the Update Global Session Policy rule request to open it.

9. In the request URL, replace the policyId and ruleId variables with the policy ID and rule ID that you copied previously. If you assigned these as variables in your environment, skip this step.

   Example:

   PUT https://{yourOktaDomain}/api/v1/policies/00p2sy9ploJnRwPwp5g7/rules/0pr2syd4moJ2gFXnD5g7
   
   

   Or

   https://{yourOktaDomain}/api/v1/policies/{policyId}/rules/{ruleId}
   

10. Select the Body tab of the request and add "type": "SIGN_ON", just below the name parameter.

11. Replace the actions property with the actions property that you copied previously.

12. In the actions property section, change the usePersistentCookie parameter value to true.

    {
        "name": "Your Policy Rule",
        "type": "SIGN_ON",
        "actions": {
            "signon": {
                "access": "ALLOW",
                "requireFactor": true,
                "factorPromptMode": "ALWAYS",
                "rememberDeviceByDefault": false,
                "session": {
                    "usePersistentCookie": true,
                    "maxSessionIdleMinutes": 100,
                    "maxSessionLifetimeMinutes": 100
                }
            }
        }
    }
    

13. Click Send to run the update request.

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 then 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 the Authorization Code and Refresh Token checkboxes 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, set up the mobile apps using the configuration from these native apps that you 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.

Use the sample iOS app that you cloned from GitHub to test how multiple apps can share a browser session with iOS. See the samples that are linked at the top of the guide.

Install the dependencies

To install the Okta Browser Sign-in sample app dependencies into your project, this guide uses CocoaPods (opens new window).

Enter the following at the command line inside the sample app:

pod install

Note: Be sure to work within the Okta BrowserSignIn Workspace in Xcode after you do pod install.

Modify the configuration file

Make the following modifications in the OktaBrowserSignIn/Okta.plist file of your sample app:

• redirectUri: Enter com.first.sample:/callback as the value, which is what you defined as one of the Sign-in redirect URIs in the Native app that you created in the previous step.

• clientId: Enter the Client ID that you copied during the previous step.

• issuer: This is the URL for the authorization server that performs authentication. It's a combination of your Okta domain and /oauth2/default.

  For example: https//${yourOktaDomain}/oauth2/default

Note: Locate your Okta domain by clicking your username in the upper-right corner of the Admin Console. The domain appears in the dropdown menu (for example, subdomain.okta.com).

logoutRedirectUri: Enter com.first.sample:/logout as the value, which is what you defined as one of the Sign-out redirect URIs in the Native app that you created in the previous step.

Add the redirect scheme

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

To add a redirect scheme for iOS, open Info.plist in your application bundle and set a URL Scheme to the scheme of the redirect URI.

For example, if your redirect URI is com.first.sample:/callback, the URL Scheme is com.first.sample.

Note: When you finish, you can build and run the app.

Create a second mobile app

You need a second mobile app to test with.

For quick testing, just use the Safari browser as the second app.

After signing in to the first app on the device, launch Safari and access your Org URL. You shouldn't be prompted for your credentials.

Optional settings

There are a few other 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 the user regardless of session

The default behavior when a session exists is to silently authenticate the user without a sign-in prompt if using the same Okta domain. If your second app requires a prompt for sign-in regardless of session, you can configure this by passing in the prompt=login parameter.

Use the prompt=login parameter when you want to force the user to enter their credentials.

Add the parameter to the second app's Okta.plist file in Xcode.

<key>prompt</key>
<string>login</string>

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 app receives an OAuth error response. See parameter details (opens new window) for more information on using the prompt parameter.

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

We recommend not using the prompt=none parameter as iOS can't silently check a user's session.

Clear the session

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

In the SignInViewController.swift file, add the following:

oktaOidc.signOutOfOkta(authStateManager, from: viewController) { error in
    if let error = error {
        // Handle error
        return
    }
}

Next steps

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

Android:

• Okta Mobile SDK for Kotlin (opens new window).
• Kotlin Sign in Example (opens new window).

iOS:

• Okta Mobile SDK for Swift (opens new window).
• iOS Sign in Sample App (opens new window).