On This Page

Get set up

Identity Engine
Limited GA

Overview

Okta provides two embedded identity solutions:

  • Embedded SDK only: A highly customizable solution that provides native language support for a variety of identity use cases.
  • Embedded Widget + SDK: A quick and easy to set up solution that moves most of the the heavy lifting to Okta. Although the amount of code that you need to write is small, many of the most advanced identity use cases (for example, social sign-in, multifactor authentication) are supported out of the box.

Displays Okta embedded solution components: (SDK) and (Sign-In Widget + SDK)

This guide shows you how to set up your Okta org to support the embedded SDK or the embedded Widget with SDK solutions. Ensure that you get set up with Okta and set up your Okta org for your use case before you download and set up the SDK, Widget, and sample app.

Get set up

Sample apps are provided for each solution to show you exactly how to integrate the SDK and the Widget into your own app. Before you can run the sample apps or integrate embedded authentication into your own app, you need to do the following:

  1. Create your Okta account
  2. Update the default Custom Authorization Server
  3. Create a new application

After you've created your app, you need to set up your Okta org for your use case scenario.

Instructions for

Create your Okta account

If you don't have an Okta Identity Engine org, you need sign up for an Okta account and an Identity Engine org.

  1. Sign up (opens new window) for an Okta account.

    After you sign up, Okta sends you a verify email with the email address that you provided.

  2. Using the activate link in Okta's email, activate your account and provide a new password. Okta redirects you to the Admin Console of your new Identity Engine org.

Update the default Custom Authorization Server

You need to configure your default Custom Authorization Server to enable the Interaction Code flow.

  1. From your Okta org's Admin Console, select Security > API.
  2. On the Authorization Servers tab, select the pencil icon for the default Custom Authorization Server.
  3. Select the Access Policies tab.
  4. Select the pencil icon from the Actions column for the Default Policy Rule.
  5. In the Edit Rule dialog box, select the Interaction Code check box.
  6. Click Update Rule.

Create a new application

Create an app integration representing the application you want to provide embedded authentication in Okta:

  1. In the Admin Console, go to Applications > Applications.

  2. Click Create App Integration.

  3. Select OIDC - OpenID Connect as the Sign-in method.

    • Enter an application name.
    • Ensure that the Interaction Code check box is selected.
    • Select the Refresh Token check box.
    • Set Sign-in redirect URIs to:
  4. Click Save.

  5. Select the Sign On tab.

  6. In the Sign On Policy section, verify that the Available Authenticators is appropriate for your app. For non-multifactor use cases, ensure that the 1 factor authenticator is Password.

Note: From the General tab of your app integration, save the generated Client ID value (and if applicable, the Client secret value) that is used later on in your embedded solution.

Set up your Okta org for your use case

After you've created your app integration in your Okta org, the next step is to configure your app and org to support the use case that you're implementing.

Set up your Okta org for a password factor only use case

This section shows you how to set up your Okta org and app to support password factor only use cases. These use cases are intended to use the password factor only without any additional factors (such as email or phone SMS). Perform the following configuration after you've created a new app in your Okta org:

  1. Update the password authenticator to password only
  2. Update your app sign-on policy with password only authentication

1: Update the password authenticator to password only

For password only authentication, you need to update the password authenticator policy rule to not require any additional verification.

  1. In the Admin Console, go to Security > Authenticators.
  2. Select Edit from the Actions menu on the Password authenticator row.
  3. On the Password policy page, scroll down to the rules section and click the pencil icon next to the Default Rule.
  4. In the Edit Rule dialog box, select Not required in the AND Additional verification is section.
  5. Click Update Rule.

2: Update your app sign-on policy with password only authentication

  1. In the Admin Console, go to Applications > Applications.
  2. From the Applications page, select the application that you've created.
  3. On the page for your application, select the Sign On tab.
  4. In the Sign On Policy section, select the action menu icon (⋮) beside the ENABLED flag for Catch-all Rule and select Edit.
  5. On the Edit Rule dialog box, scroll down to the AND User must authenticate with drop-down menu and select Password.
  6. Click Save.

Set up your Okta org for a multifactor use case

This section shows you how to set up your Okta org and app to support the multifactor use cases available in this embedded authentication guide. In addition to the password factor, the multifactor use cases presented in this guide use the email and phone factors. Perform the following configuration after you've created a new app to set up the email and phone factors in your Okta org:

  1. Set up the email authenticator for authentication and recovery
  2. Add the phone authenticator for authentication and recovery
  3. Update your app sign-on policy with multifactor authentication

Note: The multifactor use cases in this guide implement the password, email, and phone factors. However, there are other supported factors that you can use in your embedded authentication app. See Multifactor Authentication (opens new window).

1: Set up the email authenticator for authentication and recovery

  1. In the Admin Console, select Security > Authenticators.
  2. Select Edit from the Actions drop-down menu on the Email authenticator row.
  3. In the Used for section, select the Authentication and recovery option for the This authenticator can be used for field.
  4. Click Save.

2: Add the phone authenticator for authentication and recovery

  1. In the Admin Console, select Security > Authenticators.

  2. Click Add Authenticator.

  3. On the Add Authenticator page, click Add for the Phone authenticator.

  4. In the Verification options section, select SMS for the User can verify with field.

    Note: Some SDKs support only SMS with a phone authenticator.

  5. In the Used for section, select the Authentication and recovery option for the This authenticator can be used for field.

  6. Click Add.

If your org already has the phone authenticator added, ensure that the Authentication and recovery option is selected for the This authenticator can be used for field for the phone authenticator.

3: Update your app sign-on policy with multifactor authentication

  1. In the Admin Console, go to Applications > Applications.
  2. From the Applications page, select the app that you created to represent your application.
  3. On the page for your application, select the Sign On tab.
  4. In the Sign On Policy section, select the action menu icon (⋮) beside the ENABLED flag for Catch-all Rule and select Edit.
  5. On the Edit Rule dialog box, scroll down to the AND User must authenticate with drop-down menu and select Password + Another Factor.
  6. Ensure that no options are selected for the AND Possession factor constraints are field.
  7. Click Save.

Set up your Okta org for a social IdP use case

This section shows you how to set up your Okta org and app to support Facebook IdP use cases that are available in this embedded authentication guide. If you want to implement a use case with another social IdP, see Add an external Identity Provider for the list of Okta-supported social IdPs and instructions on how to configure them for social authentication with Okta.

Perform the following configurations after you've created a new app to set up the Facebook IdP and your Okta org:

  1. Create a Facebook app in Facebook
  2. Set up the Facebook test user
  3. (Optional) Switch your Facebook app to Live mode — this step is not required if you want to remain in Facebook Development mode
  4. Create the Facebook Identity Provider in Okta
  5. Add an Identity Provider routing rule in Okta

1: Create a Facebook app in Facebook

  1. Go to Facebook for Developers (opens new window) and click the Login link. If you don't have an account, then create one.
  2. Using these Facebook instructions (opens new window) as a guide, create a Facebook app. When you create the Facebook app, ensure that you select None as the app type.
  3. From the Facebook Apps (opens new window) page, select the app that you just created.
  4. On the App Dashboard page, scroll to the Add a product section.
  5. Click the Set up link in the Facebook Login tile.
  6. On the first set up page, select Web as the platform type.
  7. On the next page, set the value for Site URL to https://${yourOktaDomain}/oauth2/v1/authorize/callback (for example, https://dev-12345678.okta.com/oauth2/v1/authorize/callback).
  8. Click Save and then Continue.
  9. Click through all the Next buttons until you run through all of the sections.
  10. In the left navigation menu, click Facebook Login (under products) and then click Settings.
  11. On the Settings page and under Client OAuth Settings, add the following URLs for the Valid OAuth Redirect URIs field: https://${yourOktaDomain}/oauth2/v1/authorize/callback (for example, https://dev-12345678.okta.com/oauth2/v1/authorize/callback).
  12. Click Save Changes at the bottom of the page.
  13. On the App Dashboard page, expand Settings on the left side of the page, and then click Basic.
  14. Save the App ID and the App Secret values so you can add them to your Okta org's Identity Provider settings.

2: Set up the Facebook test user

A test account is required to test Facebook sign-in in Development mode. Facebook automatically creates one test user for you to use with the Facebook sign-in use cases. Perform the following steps to find, set the password, and save this user's information.

  1. From the Facebook App Dashboard page, click Roles and then click Test Users.
  2. Click Edit for the test user and select Change the name or password for this test user.
  3. In the Edit Test User dialog box, set a password for the New Password and Confirm New Password fields.
  4. Click Save.
  5. Save the test user's email and password for testing social IdP sign-in use cases with Okta and Facebook.

3 (Optional): Switch your Facebook app to Live mode

By default, your Facebook app is in Development mode and can only be used by the test user and the user that you used to sign in and create the Facebook app. As a result, you can only use these users when you test your Facebook sign-in use cases.

If you would like to sign in any public Facebook user, you need to set the Facebook app to Live mode. To switch your Facebook app to Live mode, perform the following steps:

  1. From the Facebook App Dashboard page, click Settings and then click Basic.
  2. Specify a value in the Privacy Policy URL field for your app. If you don't have a privacy URL, you can temporarily use: https://www.okta.com/privacy-policy/.
  3. Click Save Changes at the bottom of the page.
  4. At the top of the App Dashboard page, use the App Mode toggle to switch the app from In development to Live mode.
  5. In the Switch to Live Mode dialog box, click Switch Mode.

4: Create the Facebook Identity Provider in Okta

To connect your org to the Facebook, you need to add and configure the Facebook IdP in Okta. The following steps assume that you have already created and configured your Facebook app and that you have the Facebook App ID and App Secret values available.

  1. In the Admin Console, go to Security > Identity Providers.
  2. Click Add Identity Provider and then select Add Facebook.
  3. On the Add Identity Provider - Facebook page, enter a name (for example, Facebook IdP).
  4. Keep the default SSO Only option for the Idp Usage field.
  5. Specify the Facebook App ID value as the Client ID.
  6. Specify the Facebook App Secret value as the Client Secret.
  7. Keep the default values, public_profile and email, in the Scopes field.
  8. Click Add Identity Provider.

5: Add an Identity Provider routing rule in Okta

The final step is to add the created Facebook IdP to the routing rule.

  1. In the Admin Console, go to Security > Identity Providers.

  2. On the Identity Providers page, click the Routing Rules tab.

  3. Click Add Routing Rule.

  4. Specify the Rule Name (for example, FB and Okta Rule).

  5. From the THEN Use this identity provider drop-down list, select the Facebook Identity Provider that you've just created. Since Okta is the default IdP, the two values should be:

    • Okta
    • Facebook Identity Provider (IdP)
  6. Click Create Rule.

  7. At the prompt, click Activate.

  8. Your new rule appears above the Default Rule in the routing rule list. This top position signifies that the setting in your new rule overrides the Default Rule.