Okta: Setting up Inbound Federation with Azure AD

This guide will explain two methods: 

1. Azure AD inbound federation as a Social Provider
2. Azure AD as an enterprise IdP by using OpenID-Connect (OIDC)

Finally, this guide explains how to set up custom claims and a group claim with the enterprise IdP OIDC integration.

Prerequisites

This guide assumes that a working and correct licenced tenant on Azure AD and Okta is available. How to set up a new tenant for Azure AD or Okta is not part of this guide. 

Inbound Federation with Azure AD as social provider

Azure AD can be set up as a social provider (like Facebook or Google) in Okta. With this setup users from different Azure tenants can sign up and log in to Okta. 

This can be used both for social login use cases (e.g. login with Outlook.com account) and with use cases where several Azure ADs from different customers need to be connected. 

Note: This setup does not support custom claims or the group claim from Azure. This comes due the fact that you can't set up custom claims, by allowing all Azure tenants from various customers at the same time. 

Register an app on Azure AD

1. Go to https://portal.azure.com and navigate to:
   Azure Active Directory → App registrations
2. In the top menu click on New registration
3. Register a new app:

1. Type in a name for your connection 
2. Choose in the section "Supported account types" Accounts in any organizational directory (Any Azure AD directory - Multi-Tenant) and personal Microsoft accounts (e.g. Skype, Xbox)
   Note: Since we set up Azure AD as Social provider for Okta, this setting is necessary 
3. Choose Web and provide a redirect URL in this format: https://<YourOktaURL>/oauth2/v1/authorize/callback
4. Click on Register

4. Write down the Application (client) ID
5. Create a Client Secret:

1. Go to Certificates & Secrets
2. In the section "Client secrets" click on + New client secret
3. Add a description and choose an expiration time
4. Click on Add
5. Write down the value for your newly created client secret

Set up inbound federation in Okta

6. Go to the admin UI of Okta
7. Go to Security → Identity Providers
8. Click on + Add Identity Provider
9. Choose Add Microsoft

10. Set up the IdP

1. Provide a Name
2. Add the client id previous section
3. Add the client secret from previous section
4. Scopes can stay the same
5. Click on Add Identity Provider

Inbound Federation with Azure AD as enterprise IdP with OIDC

Azure AD can, like in the previous section, be used as an enterprise IdP. This can be done with the generic OIDC connector for Inbound Federation in Okta. The following section also explains how to set up custom claims and the group claim to communicate additional information from Azure AD to Okta’s Universal Directory. 

Register an app on Azure AD

1. Go to https://portal.azure.com and navigate to:
   Azure Active Directory → App registrations
2. In the top menu click on New registration
3. Register a new app:

1. Type in a name for your connection 
2. Choose in the section "Supported account types" Accounts in this organizational directory only (<yourAzureName> only - Single tenant)
   Note: Since we set up Azure AD as an enterprise IdP for Okta, this setting is necessary 
3. Choose Web and provide a redirect URL in this format: https://<YourOktaURL>/oauth2/v1/authorize/callback
4. Click on Register

4. Write down the Application (client) ID
5. Write down the Directory (tenant) ID
6. Create a Client Secret:

1. Go to Certificates & Secrets
2. In the section "Client secrets" click on + New client secret
3. Add a description and choose an expiration time
4. Click on Add
5. Write down the value for your newly created client secret

Set up some custom claims to send to Okta:

• Go to Token configuration in the left menu
• Click on + Add optional claim
• Choose Token: ID
• Select:

• family_name 
• given_name
• upn

• Click on Add 
• Choose Turn on the Microsoft Graph profile permission (required for claims to appear in token). 
• Click on Add

Note: If you don't set Okta to have the first and last name to be mandatory, you can remove the given_name and familiy_name. 

Set up inbound federation in Okta

1. Go to Security → Identity Providers
2. Click on + Add Identity Provider
3. Choose Add OpenID Connect IdP

4. Set up the IdP

1. Provide a Name
2. Add the client id from the previous section
3. Add the client secret from the previous section
4. Scopes can stay the same (or change if necessary)
5. Add the following Endpoints (replace the placeholder with the tenant id from the previous section):

1. Issuer: https://login.microsoftonline.com/<AzureTenantID>/v2.0
2. Authorization endpoint: https://login.microsoftonline.com/<AzureTenantID>/oauth2/v2.0/authorize
3. Token endpoint: https://login.microsoftonline.com/<AzureTenantID>/oauth2/v2.0/token
4. JWKS endpoint: https://login.microsoftonline.com/<AzureTenantID>/discovery/v2.0/keys
5. Userinfo endpoint: let it empty 

Click on Add Identity Provider

Optional: If you don't have an email stored in Azure or want to use instead of the UPN, do the following: 

1. Click on your newly created Identity Provider Configure → Edit Profile and Mappings
2. Click on + Add Attribute
3. Add the following attribute:

1. Data type: string
2. Display name: UPN
3. Variable name: upn
4. External name: upn
5. Description: The User Principal Name from Azure

1. Click on Save 

5. Click on Mappings
6. Change the two mappings like in the screenshot below:

Note: If you have the email address stored in Azure, you don't need to change the mapping for the email attribute. 

7. Go back to Security -> Identity Providers
8. Click on your created Azure AD connection on Configure → Configure Identity Provider
9. Click on Show Advanced Settings in the bottom right corner
10. Change the value in IdP Username to idpuser.upn 
11. Save your configuration by clicking on Update Identity Provider

Using custom claims and group claim with Azure AD and OIDC

Sometimes it is necessary to add additional information from Azure AD as claims, to store this information in UD (e.g. birthday or title). This can be done by inserting custom claims into the token, which should be sent to Okta. 

Additionally it is possible to send group memberships in the group claim to Okta, to e.g. synchronize role information. 

Add custom claims and add group claim in Azure AD

1. Go to https://portal.azure.com and navigate to:
   Azure Active Directory → App registrations
2. Choose your App
3. Go to Token configuration
4. Click on + Add optional claim
5. Choose Token type ID
6. Choose the claim you want to add in UD
7. Click on Add

8. If you want to add group memberships, click on + Add groups claim
9. Select which groups you want to add
10. Verify, that Group ID is selected in the section ID
11. Click on Add
    Note: Azure will add only the internal group id into the token and not the display name

Set up Okta to store custom claims in UD

1. Go to Security → Identity Provider
2. In your Azure AD IdP click on Configure → Edit Profile and Mappings
3. For every custom claim do the following

1. Click on + Add Attribute
2. Data type need to be the same name like in Azure
3. Display name can be custom 
4. Variable name can be custom
5. External name need to be the same name like in Azure
6. Click on Save

1.  Optional: If you want to also store this information in the default Okta user profile add a mapping:

1. Click on Mappings
2. Add the mapping by editing the value on the left side 

Set up Okta to store group ids in UD and assign to Okta groups

1. Go to Security → Identity Provider
2. In your Azure AD IdP click on Configure → Edit Profile and Mappings
3. Add an attribute for groups

1. Click on + Add Attribute
2. Data type: string array
3. Display name: Azure AD groups
4. Variable name: groups
5. External name: groups
6. Click on Save

1.  Store this information in the default Okta user profile:

1. Click on Mappings
2. Add the mapping by editing the value on the left side 

1. Appuser.groups → azure_groups 

Note: You need to create this attribute before in the default Okta user profile as well

Optional: If you want to automatically add a User to an Okta group, you can use Group Rules for this: 

1. Go to Directory → Groups → Rules
2. Click on + Add Rule

1. Name: A name for this rule
2. IF: Use Okta Expression Language (advanced)
3. Value: Arrays.contains(user.azure_groups, "AzureADGroupID") 

1. Change the placeholder with the internal Azure AD group ID you want to use 

1. Assign to: The group you want to assign
2. Click on Save
3. On your newly created Rule, click on Actions → Activate

‍