Integrating Azure Active Directory With Okta

I've been working with Okta lately and I wanted to share a more detail guide on how to integrate Okta with Azure Active Directory by adding it as an identity provider within the Okta platform. Okta provides a fairly detailed guide that I'll be referencing throughout this post (linked at the bottom of this post).

However, there are a few specific steps their documentation misses that I'd like to share.

Step 1: Create Azure AD Enterprise Application

1. Start by navigating to Azure Active Directory within the Azure Portal

2. Click "Enterprise applications" on the left menu

3. Choose "+ New application" in the top menu

4. Click "+ Create your own application" on the top menu of the "Browse Azure AD Gallery" page

5. Name your new enterprise application "Okta"

6. Choose "Integrate any other application you don't find in the gallery"

Step 2: Configure Your Enterprise Application

This step is the core of the issue I found within the Okta documentation. Follow them very closely, or you'll see exceptions when you first attempt to log in after the configuration.

1. On your enterprise application's page, click "Single sign-on" on the left menu

2. Choose "SAML"

3. Within the SAML configuration, on step 2 (User Attributes & Claims), choose Edit

4. Update it with claims that match the screenshot below (Claims Settings)

5. Go back to the "Single sign-on" page within your Azure Active Directory enterprise application

6. On step 3 (SAML Signing Certificate) click Add a certificate

7. Choose "+ New Certificate"

8. Click Save

Claims Settings

Step 3: Create Okta Identity Provider

Okta provides excellent documentation on this part of the configuration. To get the Okta side of things configured, follow these two guides they've published:

1. Create An Active Directory identity provider within Okta

2. Map Azure Active Directory attributes to Okta attributes

Step 4: Let's Test It

1. Head back to your Azure Active directory SAML-based Sign-on page

2. Scroll to the bottom of the page and click "Test" in step 5

3. Choose Sign in as current user

4. If you land on the home page of your Okta tenant, you're all done! If not, see my troubleshooting guide below

Bonus: Troubleshooting

So, you very well may run into issues setting this up. If that's the case, you'll want to:

1. Head to the system logs within your Okta tenant under Reports > System Log

2. Look for Authenticate user via IDP logs

3. If you see "Unknown Profile Attribute" or "Unable to transform email to username" check to make sure you've configured the claims outlined in Step 2 of this guide. That means that Okta can't find the claims it needs within your SAML token.

References

1. Okta: Integrate Active Directory With Okta: https://help.okta.com/en/prod/Content/Topics/Provisioning/azure/azure-integrate-main.htm