Today there are many organizations around the world that leverage the rich capabilities of the Microsoft Identity Platform. Often these organizations also need to integrate with third-party identity platforms. In this post, I will demonstrate the flexibility of the Microsoft Identity Platform and how it can be used to integrate a third-party identity provider (Okta) with our Azure API Management (APIM) service.
More specifically, this post demonstrates how to configure APIM to use Okta identities for the APIM developer portal.
By default, the APIM developer portal authenticates users using a username and password, acting as its own identity provider (IdP). If you need to use external IdPs, APIM provides out-of-the-box support for the following:
- Azure Active Directory
- Azure Active Directory B2C
- Microsoft
You may be thinking, “I don’t see Okta listed here. Does that mean that APIM does not support Okta?”
The short answer is APIM supports Okta indirectly because Okta supports certain security protocols that APIM and AAD B2C also support.
To integrate the APIM Developer Portal with Okta, we will need to add an AAD B2C identity provider to our APIM configuration. The product team has done a pretty decent job of outlining the essential steps of configuring AAD B2C as an identity provider for APIM here. I will be extending this to include Okta.
It is important to note that having a good foundational understanding of security protocols such as OpenID Connect and OAuth2 is extremely helpful in navigating the complexities of security integration. There are a number of ways you can configure Okta and AAD B2C to leverage the various security flows and token types. For this article, I am going to demonstrate a basic configuration that you can extend.
1) Get Access to an Okta Tenant
You will need to have an Okta tenant and administrative access to configure it. If you don’t already have access to Okta, you can sign up for a free account at: https://developer.okta.com/
Okta will assign a unique host name for your tenant, such as “dev-831740.okta.com” and the administration portal will have “-admin” tacked onto it. For example, the admin portal for the previous host will be “https://dev-831740-admin.okta.com”.
Once you have access, sign into the admin interface following the instructions sent via email.
2) Create an Azure AD B2C Tenant
Next, we will create an Azure AD B2C tenant. Simply follow the steps documented here.
3) Register the APIM Developer Portal as an Application in AAD B2C
Once we have our AAD B2C tenant, we will need to register the APIM Developer Portal as an application in B2C. The new application registration dialog should look like the following:
The reply URLs are important as they instruct AAD B2C where to respond with the requested response type when authenticating users and exchanging security tokens. There are two specific reply URLs for APIM, with each one representing the legacy developer portal and the new developer portal:
https://<your APIM instance>.portal.azure-api.net/signin-aad
https:// <your APIM instance>.developer.azure-api.net/signin
I have added an additional reply URL (https://jwt.ms) for debugging purposes, which I will talk more about later.
Once registered, AAD B2C will create an Application ID for the application, otherwise known as the Client ID of the APIM Developer Portal application registered in B2C. Make a note of the value from your registration:
4) Generate App Key (Client Secret)
Next, you will need to generate a Client Secret for your registered application.
Select Keys on the left, then Generate key and then Save to view the key value. Copy this value to use later:
5) Register AAD B2C as an Application in Okta
At this point, we should have our APIM instance, our AAD B2C instance, and have registered our APIM developer portal as an application in AAD B2C. Now we need to register AAD B2C as an application in Okta.
Navigate to the Okta Developer Console and select the Applications tab. Click on Add Application:
Select Web as the platform option.
Next you should see a few fields for application settings:
Enter a value for the name that signifies this is for your AAD B2C.
For Grant type allowed, select all options for now.
Finally, add a Login redirect URI so that Okta knows where to send its responses to, which in this case, will be AAD B2C:
https://<your B2C tenant>.b2clogin.com/mcpcsab2c.onmicrosoft.com/oauth2/authresp
Just like before, you can also add https://jwt.ms to make it easier to debug.
Click Done to save the configuration.
At this point, your application should be listed under the Applications tab in the Okta admin interface. Select the B2C application and then go to the General tab. Scroll to the bottom to get to the Client Credentials section:
You will need the Client ID and Client secret values, so copy those for later.
You will also need the metadata URL from your Okta Authorization Server. To find this, click on API tab at the top, followed by Authorization Servers:
Click on the default Authorization Server to bring up the details.
Under the settings tab, you should see a Metadata URI:
To use this with AAD B2C, we need to change this to its OpenID Connect equivalent. Replace the “oauth-authorization-server” with “openid-configuration” like so:
https://<your okta tenant>.okta.com/oauth2/default/.well-known/openid-configuration
You can test the metadata URI by pasting it in a browser:
Save the Okta metadata URL for later.
Before continuing, you should have the following information from earlier in this step:
- Metadata URL
- Client ID
- Client secret
6) Add a New OpenID Connect provider in AAD B2C
Since we are going to be authenticating users to the APIM Developer Portal using AAD B2C, we need to tell AAD B2C that we want those identities to come from an external identity provider.
To do this, we need to go back to our AAD B2C Azure blade and select the Identity providers tab. Next, click on the New OpenID Connect provider button at the top:
For the Metadata URL, Client ID, and Client secret, enter the values obtained from step 5 earlier.
For Scope, enter openid profile email.
For Response type, change the value to id_token.
For User ID, enter sub.
For Display name, enter name.
For Given name, enter given_name.
For Surname, enter family_name.
For Email, enter email.
Click on Save.
You should see a new OpenID Connect identity provider listed now in the identity providers tab of your AAD B2C tenant. Your configuration will look like this:
7) Add a Sign-In and Sign-Up AAD B2C Policy
While still on the AAD B2C blade, select the User flows tab under Policies and then select New user flow:
Select the Sign up and sign in policy:
For the name of the user flow, enter UF_SignUpOrSignIn.
For the identity provider, select the identity provider added to B2C from step 6.
For the return claims, specify:
- Given Name
- Surname
- User’s Object ID
Click on Create to create the user flow.
Once the user flow is created, you can select it to see its details.
If you have registered https://jwt.ms/ as a reply URL from step 3, you can click on the Run user flow to test the flow right from the Azure portal.
For the application, select the name you used to register the APIM developer portal from step 3:
At this point, when you click on Run user flow, you should be prompted by Okta to authenticate and if successful, you’ll be redirected to jwt.ms where you will see the information about the token issued by B2C.
8) Add Azure Active Directory B2C as an Identity Provider in APIM
Back in your APIM instance, select the Identities tab and then select Add to add a provider:
Select Azure Active Directory B2C from the drop down.
For the Client id and Client secret, enter the values obtained from steps 3 and 4 respectively.
For Sign-in tenant, enter your AAD B2C domain name, which you can find on the AAD B2C overview tab:
For Authority, set the value to <your b2c tenant name>.b2clogin.com.
For the Sign-up policy, Sign-in policy, Profile editing policy, and Password reset policy, enter the names of the B2C policies from B2C (step 7).
Your configuration will look like this:
Click Add to complete the configuration of the B2C identity provider in API Management.
You can also choose to optionally remove the default Username and password provider type which is configured by default with a new API Management instance.
9) Add Test User to Okta
We will need a user that is not registered as the administrator of your APIM instance in order to test the sign-in/sign-up process. Since we’ve configured the APIM Developer Portal to accept user identities from Okta (through AAD B2C), we need to go back to the Okta administrative portal and create a user in our Okta tenant.
Select the Users tab and then click on Add Person. Fill out the form with an email address from an account that you have access to and be sure to check Send user activation email now:
Check your email and follow the links to activate the new account and set a user password.
10) Test Sign-In with APIM Developer Portal
At this point, we should be able to test out the sign-in/sign-up experience using the APIM Developer Portal.
Open a new InPrivate or Incognito browser window and navigate to the legacy APIM Developer Portal for your APIM instance and select the SIGN IN link at the top right:
You should be redirected to your Okta’s tenant sign-in page.
Enter your Okta test user account information from step 9.
Once authenticated, Okta will redirect the user back to the APIM Developer Portal to complete the sign-up experience. Provide any missing information and click on Sign up:
If all goes well, you should be directed back to your profile page on the portal:
Once you complete the sign-up process, APIM will have a record of that user in its user database which can then be used to map to subscriptions and APIs. You can verify this by going to the Users tab of your APIM instance:
And that is it!