Guide: Setup Azure API Management Developer Portal Authentication with Okta

Learn how to integrate Okta with the Azure API Management Developer Portal to provide authentication for developers accessing your APIs.

An image of the Azure API Management and Okta logos together on a blue abstract tech background.

Okta is a popular choice in the realm of third-party identity providers, so if your organization is currently using Okta (or considering it), you’ll be happy to learn that it can be used to provide authentication for users of the Azure API Management (APIM) Developer Portal. In this post we’ll go through the details of how to integrate Okta with APIM by leveraging Azure Active Directory B2C (AAD B2C).

APIM supports several identity provider types, namely, Username and Password, Azure Active Directory (AAD), and AAD B2C. Previously other identity providers were directly supported, like Microsoft, Google, Facebook, and Twitter, but as of writing this post they have been deprecated in favor of indirect integrations through AAD B2C. We can use AAD B2C to integrate with Okta because both support the OAuth 2.0 and OpenID Connect protocols.

For a helpful overview of those two protocols, check out Okta’s OAuth 2.0 and OpenID Connect Overview.

In this post, we’ll extend the basic Microsoft guide for using AAD B2C to manage access to the Azure APIM Developer Portal in order to show details specific to Okta integration. This post will not cover the deprecated legacy developer portal.

Note: In this post, we use the Azure Portal and Okta GUIs to make our configuration changes. Some, but not all, of the steps in this guide can be done through automation using a tool like Terraform. We believe in an “everything-as-code” approach when applicable, so consider using a tool like Terraform if you are configuring this for long-term use and not just a quick proof of concept.


Table of Contents


Step-by-Step Guide

Prerequisites

Step 1: New App Registration in Azure

Register Azure APIM Developer Portal as an App within Azure AD B2C

From your Azure AD B2C tenant within the Azure Portal, under Manage, select App registrations and then select New registration.

An image of setting up a new registration in the Azure Portal AD B2C tenant.

Fill out the app registration form:

  1. Enter a name for the app registration (this can be changed later)
  2. Under ‘Supported account types’ choose the third option: Accounts in any identity provider or organizational directory (for authenticating users with user flows)
  3. Under ‘Redirect URI (recommended)’ ensure the dropdown is set to Web and add your APIM Developer Portal sign-in URI: https://<apim_service_name>.developer.azure-api.net/signin
  4. Under ‘Permissions’ ensure the ‘Grant admin consent to openid and offline_access permissions’ checkbox is checked
  5. Click Register
An image of filling out a new app's registration details in the Azure Portal AD B2C tenant.

View the new App Registration and make note of its Application (client) ID as we will use it later in this guide.

An image of a newly registered app in the Azure Portal AD B2C tenant, with its app (client) ID highlighted.

Step 2: Add a Client Secret

From your App Registration page select Certificates & Secrets from the left hand menu then under ‘Client secrets’ click New client secret.

This client secret will be used with the Application ID you noted above when registering AAD B2C as an Identity Provider for APIM later in this guide.

Enter a description for the key and set an expiration time period then click Add.

An image of adding a new client secret to a registered app in the Azure Portal AD B2C tenant.

Your new client secret will appear under the ‘Client secrets’ section. Make a note of its Value for use later in this guide.

An image highlighting the new client secret value in the Azure Portal AD B2C tenant.

Step 3: Authentication

From your App Registration page select Authentication from the left hand menu. Under ‘Implicit grant and hybrid flows’, check the checkbox for Access tokens (used for implicit flows) and click Save.

An image of the Authentication panel, with access tokens checkbox turned on, in the Azure Portal AD B2C tenant.

Step 4: Web App Integration in Okta

Navigate to your Okta site and expand the ‘Applications’ section of the menu on the left hand side. Select Applications and then click Create App Integration

An image of creating a new app integration in the Okta interface.

For the ‘Sign-in method’ choose OIDC - OpenID Connect. An ‘Application type’ section will appear — choose Web Application. Finally, click Next.

An image of the new app integration details in Okta's interface.

Fill out the New Web App Integration form (these settings can be changed later):

  1. Enter an App integration name
  2. For ‘Grant type’ check all boxes
  3. For ‘Sign-in redirect URIs’ enter:
    https://<AAD B2C tenant>.b2clogin.com/<AAD B2C Tenant>.onmicrosoft.com/oauth2/authresp
    (Optional) Remove the default URI for ‘Sign-out redirect URIs’
  4. For ‘Controlled access’ choose Allow everyone in your organization to access
  5. Click Save
An image of the new web app integration details fields in the Okta interface.

You should now see your Web App Integration in Okta. Make note of its Client ID and Client Secret as we will need them later in this guide.

An image of the completed web app integration in Okta, with the client ID and client secret highlighted.

Step 5: API Configuration

From the left hand menu expand the ‘Security’ section and select API.

Under ‘Authorization Servers’ click on default.

An image of the API configuration section of the Okta interface.

Copy the Metadata URI for use later but when you make note of it replace the last segment ‘oauth-authorization-server’ with ‘openid-configuration’.

Your copy should look like:
https://<your-okta-instance>.okta.com/oauth2/default/.well-known/openid-configuration

An image of the API configuratio details with Metadata URI highlighted.

Step 6: Add New Identity Provider in Azure

Navigate to your Azure AD B2C Tenant in the Azure portal. From the menu on the left hand side under ‘Manage’ select Identity providers, then click New OpenID Connect provider.

An image of the Identity providers panel in the Azure AD B2C tenant.

A form will appear on the right side of the page which will allow you to configure a custom IDP. Fill out the form as follows and click Save when you are done.

  1. Name: Enter a name for the custom IDP
  2. Metadata url: Enter the Okta Metadata URI you saved during step #5
    https://<your-okta-instance>.okta.com/oauth2/default/.well-known/openid-configuration
  3. Client ID: Enter the Okta Client ID you saved during step #4
  4. Client secret: Enter the Okta Client Secret you saved during step #4
  5. Scope: Enter openid profile email
  6. Response type: Select id_token
  7. Response mode: Select form_post
  8. Domain hint: Leave this field empty
  9. User ID: Enter sub
  10. Display name: Enter name
  11. Given name: Enter given_name
  12. Surname: Enter family_name
  13. Email: Enter email
The Identity provider configuration form in the Azure AD B2C tenant.

Step 7: Add New User Flow

Still within your Azure AD B2C Tenant in the Azure portal, from the left hand menu under ‘Policies’ select User flows, then click New user flow.

An image of the user flows panel in the Azure AD B2C tenant.

A page will appear showing various user flow types, choose Sign up and sign in.
A version selection will appear, choose Recommended.
Finally, click Create.

From the ‘Create’ page fill out the form as follows:

  1. Name: Enter UF_SignUpOrSignIn
  2. Identity providers: Select the name of the custom IDP you added in step #6
  3. Multifactor authentication: Leave this disabled for now
  4. Conditional access: Leave this disabled for now
  5. User attributes and token claims: Click Show more… then from the ‘Return claim’ column select Email addresses, Given Name, Surname, and User’s Object ID, then click Ok.
  6. Finally, click Create.
The user flow configuration form in the Azure AD B2C tenant.

Step 8: Add New Identity

Navigate to your APIM resource in the Azure Portal. From the left hand menu under ‘Developer portal’ select Identities, then click Add.

An image of the add new identity panel inside of the Azure AD B2C Tenant.

Fill out the ‘Add identity provider’ form as follows:

  1. Type: Choose Azure Active Directory B2C from the dropdown menu
  2. Client ID: Enter the APIM Application (client) ID you saved in step #1
  3. Client secret: Enter the APIM Client Secret Value you saved in step #2
  4. Signin tenant: Enter the Domain name of your AAD B2C tenant (<AAD B2C tenant>.onmicrosoft.com) Can be found in the ‘Overview’ section of your AAD B2C tenant
  5. Authority: This field should auto-populate upon entering a proper Signin tenant and it should look like <AAD B2C tenant>.b2clogin.com
  6. Sign-up policy: Enter the name of the Sign-up/Sign-in policy you created in step #7 (B2C_1_UF_SignUpOrSignIn)
  7. Sign-in policy: Enter the name of the Sign-up/Sign-in policy you created in step #7 (B2C_1_UF_SignUpOrSignIn)
  8. Finally, click Add.
The Add identity provider details form inside of the Azure AD B2C tenant.

Since we will use Okta for managing access you can delete Username and password from the list of APIM Developer Portal identities.

Step 9: Add User to Okta

Navigate to Okta and sign in. From the left hand menu under ‘Directory’ select People, then click Add Person.

Fill out the ‘Add Person’ form with details for a test user. The name can be fake but enter a valid email address separate from your Okta admin email address.

For Password, select Set by user from the drop down menu.
Check Send user activation email now.
Finally, click Save.

The Add Person details form inside of Okta.

Open the email account you just entered and follow the instructions to set up a password for your test user.

Step 10: Publish Your APIM Resource in Azure

Navigate to your APIM resource in the Azure Portal and from the left hand menu under ‘Developer Portal’ select Portal overview.

If you’ve not previously provisioned your developer portal, click on the Developer Portal link. If you have already provisioned your developer portal, skip to the next paragraph. After a few moments the administrative view of your APIM Developer Portal will appear. From here you can make any changes you would like or leave it as is for now. Save any changes you make and once you are done go back to your Azure Portal tab where you just had your APIM resource open and refresh the page. The ‘Publish’ button should no longer be greyed out.

From the ‘Overview’ tab under ‘Publish the portal’, click Publish.

An image of the Portal overview panel inside of the Azure AD B2C tenant.

Step 11: Sign In to Your APIM Developer Portal

In an Incognito browser window, navigate to your APIM Developer Portal.
https://<apim-name>.developer.azure-api.net

At the top right of the page click Sign in.

An image of the APIM Developer Portal home page.

You will be directed to the developer portal sign-in page. Click Azure Active Directory B2C.

An image of the APIM Developer Portal sign in page.

An Okta sign-in prompt should appear. Enter the username and password of your Okta test user, then click Sign In.

An image of the APIM Developer Portal sign in prompt.

You should be redirected to the developer portal home page and should now be signed in. You should notice your view is now that of an authenticated user.

An image of the APIM Developer Portal home page after sign in.

Congratulations! You’ve now set up your Azure API Management Developer Portal to use Okta for authentication. If you want to learn more about how to integrate Okta or other tools with Azure services, reach out and ask us how we can help.

Share This Article

Have a question or comment?

Contact uS
The Liatrio logo mark.
The Liatrio logo mark.

About Liatrio

Liatrio is a collaborative, end-to-end Enterprise Delivery Acceleration consulting firm that helps enterprises transform the way they work. We work as boots-on-the-ground change agents, helping our clients improve their development practices, react more quickly to market shifts, and get better at delivering value from conception to deployment.