Use redirect auth with the Identity Engine sample apps

Identity Engine

This guide covers how to set up an Okta sample app to demonstrate some Identity Engine features. Among the many setup options available with the Okta sample apps, the apps can redirect to the Okta Sign-In Widget for authentication. They can also redirect to a social Identity Provider like Facebook.

---

Learning outcomes

• Create, set up, and install an Okta OAuth 2.0 app.
• Enroll and authenticate a user.
• Enable self-service enrollment and enable a second factor for authentication.
• Use email and Okta Verify as recovery options.
• Add a profile attribute to the user profile policy.
• Route users to an external IdP.

What you need

Sample app

---

Use case scenarios

The following scenarios are included in this guide:

• Simple enrollment and authentication
• Enable self-service enrollment
• Add MFA with a mandatory second factor
• Authenticator recovery
• Progressive Profiling
• Identity Provider routing to Facebook

Initial setup

To get started, you need to create an Okta OAuth app to represent the

React Native for Android

app and then install the

React Native for Android

sample app.

Note: These steps assume that you are using Android Studio to run the sample app.

1. Sign in to your Admin Console (opens new window).

2. Go to Applications > Applications, and then click Create App Integration.

3. In the dialog that appears, select OIDC - OpenID Connect as the Sign-on method,

   Native Application

   as the Application type, and then click Next.

4. Fill in the New

   Native App

   Integration fields that you need, and then click Save:

   • Be sure to add the following values (or leave the defaults if they match):

     Sign-in redirect URIs:

     com.okta.example:/callback

     
     Sign-out redirect URIs:

     com.okta.example:/logoutCallback

     Note: Copy these values and store them temporarily. You need them in the next section.

   • In the Assignments section, select Allow everyone in your organization to access. This assigns all Users in the Everyone Group to the app. You must assign the app to either the Everyone Group or a custom Group that you create so that profile enrollment functions correctly.

5. On the new Application page, click the "Copy to clipboard" icon to copy the

   Client ID

   . Store this information temporarily for use when you

   add it to the samples.config.js file

   in the next section.

6. Build your issuer URL, which is the URL of the authorization server that performs the authentication. This example uses the default custom authorization server. The issuer is a combination of your Okta domain (found by clicking your username in the upper-right corner of the Admin Console) and /oauth2/default. For example: https://example-1234.oktapreview.com/oauth2/default

Install the sample app

1. Install the sample app wherever you want using: git clone https://github.com/okta/samples-js-react-native.git

2. From the command line, enter the browser-sign-in directory and run npm install to install the dependencies.

3. Within the samples-react-native directory, edit the samples.config.js file in the browser-sign-in directory with the information that you copied in previous steps:

   export default {
       oidc: {
   	    clientId: `${yourAppClientId}`,
   	    redirectUri: `com.okta.example:/callback`,
   	    endSessionRedirectUri: `com.okta.example:/logoutCallback`,
   	    discoveryUri: `https://${yourOktaDomain}/oauth2/default`,
   	    scopes: ['openid', 'profile', 'offline_access'],
   	    requireHardwareBackedKeyStore: false,
           },
       };
   

   Note: The discovery_uri is the issuer URL that you built in a previous step.

4. To redirect back to your application, you must specify a unique URI to your app. To do this, define a gradle manifest placeholder in the build.gradle file located in the browser-sign-in > android > app directory.

   android.defaultConfig.manifestPlaceholders = [
       "appAuthRedirectScheme": "com.okta.example"
       ]
   

Note: Make sure that this value is consistent with the redirect URI that you added to the samples.config.js file. For example, if your redirect URI is com.okta.example:/callback, then the appAuthRedirectScheme should be com.okta.example.

You have now created your App in Okta and installed the Okta

React Native for Android

app.

Simple enrollment and authentication

This section walks you through enrolling a user and authenticating that user.

Open and test the Sign-In Widget

1. From the command line inside the browser-sign-in subdirectory, start the

   React Native for Android

   app by running npm start.
2. From Android Studio, run the app.
3. In the emulator, click LOGIN. You are redirected to the Okta Sign-In Widget. Note that there currently is no Sign Up option.

4. Enter the Username and Password for an admin user in your Okta org. You're redirected to the success page.

   Note: Which authenticators appear during sign-in depends on how your authentication policy is configured.

5. Click

   LOGOUT

   to sign out of the

   React Native for Android

   app.

Enable self-service enrollment

This section walks you through enabling self-service enrollment for the Sign-In Widget and then trying self-service enrollment with a user.

Note: This section assumes that you followed the previous Initial setup and Simple enrollment and authentication sections. The steps may be different if you didn't.

1. In the Admin Console, select Security > User Profile Policies, and then select Add user profile policy.
2. Give your Policy a Name and then click Save.
3. On the Profile Enrollment page, select the pencil icon for your new Policy from the Actions column.
4. On the Policy page, click Manage Apps and then click Add an App to This Policy.
5. Locate the

   React Native for Android

   app that you created earlier, click Apply, and then Close.
6. Click Back to User Profile Policy.
7. Click Edit in the Profile Enrollment section.
8. Set Self-service registration to Allowed, and then click Save.

Note: See Configure user profile policies (opens new window).

Try enrollment

This section walks you through the self-service enrollment steps for a new user.

1. From the command line inside the browser-sign-in subdirectory, start the

   React Native for Android

   app by running npm start.
2. From Android Studio, run the app and then click LOGIN in the emulator.

3. In the Okta Sign-In Widget, click Sign up that follows the Forgot password? link.

4. Enter the requested information, and then click Sign Up.

5. Set up the email and password authenticators. Don't set up any other authenticators.

   Note: Be sure to copy the code from the email and paste it into the Sign-In Widget. This allows you to manually verify the email address rather than using the Verify Email Address button.

6. After you complete the setup, click Finish. You're redirected to the app's welcome page.

7. Click

   LOGOUT

   to sign out of the

   React Native for Android

   app.

Enable self-service password-optional enrollment

To enable self-service password-optional enrollments in the Sign-In Widget,

Set up your Okta org for a password-optional use case

. After completing the setup, try a password-optional enrollment with the following steps:

1. From the command line inside the browser-sign-in subdirectory, start the

   React Native for Android

   app by running npm start.
2. From Android Studio, run the app and then click LOGIN in the emulator.

3. In the Okta Sign-In Widget, click Sign up.

4. Enter the email, first and family name, and then click Sign Up.

5. Verify your email address by clicking Verify Email Address in the email sent by Okta.

   Note: Alternatively, you can verify your email address by copying the one-time passcode from the email into the Sign-In Widget.

6. Click Set up later for all the optional authenticators. The app redirects you to the home page.

7. Click

   LOGOUT

   to sign out of the

   React Native for Android

   app.

Add MFA with a mandatory second factor

You can modify the app's authentication policy to require the user to have a second factor enabled for authentication. In this example, use the phone authenticator.

Note: Your Okta org may have different authenticators enabled by default.

Enable multifactor authentication

1. Ensure that your org has the phone authenticator enabled by going to Security > Authenticators and checking that Phone is listed.

   If it isn't listed, add it:

   • Click Add Authenticator, and then click Add in the Phone authentication box.
   • Set This authenticator can be used for to Authentication and recovery, and click Add.

2. From the side navigation, select Applications > Applications and then select the app integration that you created earlier.

3. Select the Sign On tab.

4. Scroll down to the User authentication section and click Edit.

5. From the Authentication policy dropdown menu, select Any two factors and click Save.

Try multifactor authentication

1. From the command line inside the browser-sign-in subdirectory, start the

   React Native for Android

   app by running npm start.
2. From Android Studio, run the app and then click LOGIN in the emulator.

3. Enter the credentials of the user that you enrolled with earlier. The Set up security methods page appears, prompting you to set up either the Okta Verify app or the phone authenticator.
4. Under Phone, click Set up.
5. Fill out the requested phone authentication information and verify your phone with a code.
6. Under Set up optional, click Set up later. You're redirected to the

   React Native for Android

   welcome page.
7. Click

   LOGOUT

   to sign out of the

   React Native for Android

   app.

Self-service Password Recovery

Password recovery with email magic link

Note: In your org, password reset is configured by default to be initiated with an email. The steps in this section assume that you haven't changed that default configuration.

Try the email magic link recovery flow:

1. Select Forgot password? in the Sign-In Widget.
2. Enter your email or username when prompted and click Next.
3. Click Send me an email. A magic link is sent to your email address.
4. Click Sign In. A new window opens and you're automatically signed in.

Password recovery with email OTP

Note: In your org, password reset is configured by default to be initiated with an email. The steps in this section assume that you haven't changed that default configuration.

Try out the email password recovery flow:

1. Select Forgot password? in the Sign-In Widget.
2. Enter your email or username when prompted and click Next.
3. Click Select for the email authenticator. An OTP code is sent to your email address. Manually copy the code from the email.
4. In the Sign-In Widget, click Enter a code from the email instead, paste the code, and click Verify.
5. Enter a new password.
6. After you enter the new password successfully, you're prompted for the additional phone authentication that you set up in Enable multifactor authentication. You’re then redirected to the

   React Native for Android

   welcome page.
7. Click

   LOGOUT

   to sign out of the

   React Native for Android

   app.

Okta Verify recovery flow

In addition to recovering your password with an email, you can add Okta Verify as a recovery option.

1. Go to Security > Authenticators.
2. Click Actions beside the password authenticator, and then click Edit.
3. In the Add Rule section, click the pencil icon for the Default Rule.
4. In the Recovery authenticators section, locate AND Users can initiate recovery with.
5. Select Okta Verify (Push notification only) and click Update Rule.
6. Enroll a new user, ensuring that this time you also enroll Okta Verify.
7. Sign in with your new user to confirm that you added the user correctly, and then click

   LOGOUT

   .
8. Back on the welcome page of the

   React Native for Android

   app, click

   LOGIN

   .
9. After you're redirected to the Sign-In Widget, click Forgot password?.
10. Enter the email address of the user that you created with Okta Verify as a factor, and then click Next.
11. On the next page, click Select beside Get a push notification. You should receive a push notification in Okta Verify. Respond appropriately.
12. Enter the answer to your Security Question, and then you're asked to reset your password.
13. When you finish, the

    React Native for Android

    welcome page appears.
14. Click

    LOGOUT

    to sign out of the

    React Native for Android

    app.

Progressive Profiling

Okta gives you the ability to check for what data is required from a user before they can access an app. For example, you can change the required user profile information for the same app, or handle SSO between two apps with different profile requirements. In this example, add a required profile attribute, and the user you've already enrolled is asked for this information when they next authenticate.

When you enrolled your test user, the user was only prompted for first and family name, as well as their email and a password. Now add an additional required property to the user profile policy.

1. In the Admin Console, select Security > User Profile Policies.

2. Find the user profile policy that you created for self-service enrollment and click the pencil icon in the Actions column.

3. In the Enrollment Settings section, click the Actions menu icon (⋮), and then select Edit.

4. For Progressive Profiling, select Enabled.

5. From the side navigation, select Directory > Profile Editor.

6. Under Filters, select Okta, and then click the User (default) profile.

7. Under Attributes, click Add Attribute, and then fill out the dialog box that appears with the following values. The other fields are optional and can be left blank. Click Save when you finish.

   • Data type: string
   • Display name: Region
   • Variable name: region

8. Find the Region attribute that you created and click the pencil icon beside it.

9. In the Region dialog box that appears, set User permission to Read-Write, and then click Save Attribute.

   Note: You can check which user attributes are required for your directory by clicking the information icon beside each attribute. By default, First name and Last name are marked as required, in addition to what you specify in your enrollment policy.

10. Return to user profile policies (Security > User Profile Policies). Find the user profile policy that you created for self-service enrollment and click the pencil icon in the Actions column.

11. In the Profile enrollment form section, click Add form input and search for Region (region)

12. Select the Required checkbox, and then click Save.

13. Try to authenticate using one of the same users from the previous steps. You're prompted with a Region field and a Sign Up button. After you add a value, you can confirm that it's saved by accessing Directory > People in the Admin Console. Then, locate the correct user and select their Profile tab. If you try to register a new user, you see the Region field added to the sign-in page.

Identity Provider routing to Facebook

Instead of signing in to Okta, it's possible to route users to an external Identity Provider (IdP) using the Okta IdP Routing Rules.

Note: For B2B scenarios, you may want to add a SAML 2.0 Identity Provider rather than a social Identity Provider. See Add an external Identity Provider.

Create a Facebook App

1. Go to Facebook for Developers (opens new window) and register for a developer account if you haven't already done so.

2. Access the Facebook App Dashboard (opens new window).

3. Create a Facebook app using these instructions (opens new window).

   Note: When you create the app, select Consumer as the app type.

4. After you create the app, on the Add Products to Your App page, click Set Up on the Facebook Login tile.

5. On the first page of the Quickstart, select Web.

6. In the Site URL box, enter your Okta domain. The site URL can also be any URL that makes sense for your app. To locate your Okta domain, click your username in the upper-right corner of the Admin Console. Your Okta domain appears in the dropdown menu.

7. Click Save, click Continue, and then click Next until you exit the Quickstart wizard.

   Note: Normally, under the Facebook Login > Settings section, you would enter the Valid OAuth Redirect URIs, but Facebook automatically adds localhost redirects so this isn't required for this example.

8. On the App's Dashboard page, expand Settings on the left side of the page, and then click Basic.

9. Save the App ID and the App Secret values so that you can add them to the Okta configuration in the next section.

Note: There may be more settings on the Facebook App Dashboard (opens new window) that you can configure for the app. The steps in this guide address the quickest route to setting up Facebook as an Identity Provider with Okta. See the Facebook documentation for more information on other configuration settings.

Create an Identity Provider in Okta

To connect your org to the IdP, add and configure that IdP in Okta.

Note: Be sure to assign your app to either the Everyone group or a custom group that you create so that profile enrollment functions correctly.

1. From the Admin Console side navigation, select Security > Identity Providers.

2. Select Add Identity Provider and then select Add Facebook.

3. In the Add an Identity Provider dialog box, define the following:

   • Name: Enter a name for the IdP configuration.
   • Client ID: Paste the app ID that you obtained from the IdP in the previous section.
   • Client Secret: Paste the secret that you obtained from the IdP in the previous section.
   • Scopes: Leave the defaults.

   By default, Okta requires the email attribute for a user. The email scope is required to create and link the user to the Okta Universal Directory.

   Note: For more information about these settings and the Advanced Settings, see Social Identity Provider Settings.

4. Click Add Identity Provider. The Identity Provider page appears.

5. Locate the IdP that you just added and click the arrow next to the IdP name to expand.

6. Copy the Redirect URI (ending in /callback).

7. On the page for your Facebook app, under Facebook Login, select Settings. Then paste the redirect URI that you copied into the Valid OAuth Redirect URIs box.

8. Click Save Changes.

Create the Routing Rule

Note: These steps assume that you have no other Routing Rules defined. The following steps may be different if you have existing Routing Rules for the Identity Provider.

Create a Routing Rule that automatically routes all authentication requests to Facebook.

1. On the Identity Providers page in the Admin Console, select the Routing Rules tab.
2. Click Add Routing Rule.
3. Name the Rule, and then for the purposes of this example set two rule conditions:
   • For AND User is accessing, select Any of the following applications, and then choose your Application. This routes any attempts to access the

     React Native for Android

     app to the Facebook IdP, but still allows you to access your Admin Console normally.
   • For THEN Use this identity provider, select the Facebook IdP that you added earlier, and then click Create Rule.
4. Click Activate in the dialog box that appears.
5. Start the

   React Native for Android

   app in an incognito/private browser window and click ç. You are redirected to the Facebook site, where you can sign in.
6. After successful authentication, you're returned to the

   React Native for Android

   app's welcome page.