Guide: Setup Azure API Management Developer Portal Authentication with Okta

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

• Prerequisites
• Step 1: New App Registration in Azure
• Step 2: Add a Client Secret
• Step 3: Authentication
• Step 4: Web App Integration in Okta
• Step 5: API Configuration
• Step 6: Add New Identity Provider in Azure
• Step 7: Add New User Flow
• Step 8: Add New Identity
• Step 9: Add User in Okta
• Step 10: Publish Your APIM Resource in Azure
• Step 11: Sign In to Your APIM Developer Portal

Step-by-Step Guide

Prerequisites

• ~Azure APIM Instance
• ~~Create an APIM instance directly from the Azure Portal following this Microsoft guide, or use a tool like Terraform
• ~AAD B2C Tenant
• ~~Follow Microsoft’s tutorial to create an AAD B2C Tenant
• ~Okta Tenant
• ~~Get started with an Okta Customer Identity Free Trial

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.

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

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

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.

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

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.

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

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

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

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.

Step 5: API Configuration

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

Under ‘Authorization Servers’ click on default.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.