Integrate Azure MFA with IBM API Connect Using OIDC

Enhancing the security of your API developer portal is no longer optional; it’s essential. Multi-Factor Authentication (MFA) is a critical layer of defense, protecting your APIs and sensitive data from compromised credentials.

In this guide, we’ll walk through integrating Azure Active Directory (Azure AD) as an OpenID Connect (OIDC) identity provider for your IBM API Connect v10 Developer Portal. The best part? We’ll leverage Azure AD Conditional Access to enforce MFA for every single login, ensuring that access to your portal is secured by robust, cloud-based authentication.

PREREQUISITES

Before you begin, make sure you have the following:

A valid TLS certificate for your public-facing Developer Portal hostname (e.g., https://developer.yourcompany.com).

An Azure AD Tenant with Global Administrator or Conditional Access Administrator permissions.

A running IBM API Connect v10.x environment (on IBM Cloud Pak for Integration or a standalone setup).

Step 1: Configure Azure AD as an OIDC Provider

1.1. Create a New App Registration

This app registration in Azure AD will represent your API Connect Developer Portal.

1. Log into the Azure Portal with an administrator account.
2. Navigate to Azure Active Directory > App registrations and click + New registration.
3. Provide a descriptive Name (e.g., APIC-DeveloperPortal).
4. Choose the Supported account types that fit your needs (e.g., “Accounts in this organizational directory only” for internal users).
5. For the Redirect URI:
   • Select Web.
   • Enter your Developer Portal’s full callback URL. The standard path for API Connect v10 is:
     https://developer.yourcompany.com/sandbox/idm/authorize/ibm_sec_client
6. Click Register. Note down the Application (client) ID and Directory (tenant) ID from the overview page.

1.2. Generate a Client Secret

Your API Connect instance needs a secret to authenticate with Azure AD.

1. In your new App Registration, go to Certificates & secrets.
2. Under Client secrets, click + New client secret.
3. Add a description, choose an expiry period, and click Add.
4. Crucial: Immediately copy the secret’s Value. You cannot retrieve it again later.

1.3. Configure API Permissions

1. Go to API permissions in your app registration.
2. Ensure the delegated permissions for Microsoft Graph include openid and profile. Add email if you want to use the user’s email address within API Connect.
3. Click Grant admin consent for [Your Tenant] to pre-approve these permissions for all users.

1.4. Locate Your OIDC Endpoints

1. From the App Registration overview, click Endpoints.
2. Note the OpenID Connect metadata document URL. This .well-known endpoint contains all the configuration API Connect needs, like the issuer and jwks_uri.

Step 2: Enforce MFA with a Conditional Access Policy

Now, let’s ensure every login to this app requires MFA.

1. In the Azure Portal, go to Azure Active Directory > Security > Conditional Access.
2. Click + New policy and give it a name (e.g., Enforce-MFA-for-APIC-Portal).
3. Under Users and groups, select the users or groups who must use MFA to access the portal.
4. Under Cloud apps or actions, choose Select apps and then pick the App Registration you created earlier (APIC-DeveloperPortal).
5. Under Grant, select Grant access, check the box for Require multi-factor authentication, and click Select.
6. Set the policy to On and click Create.

This policy now mandates MFA for any user trying to sign in to your API Connect Developer Portal.

Step 3: Configure IBM API Connect

3.1. Create an OIDC User Registry

1. Log in to your API Connect Manager as an administrator.
2. Navigate to Manage > Security > User Registries.
3. Click Add Registry and select OAuth/OIDC or OpenID Connect (OIDC).

3.2. Configure the Registry Settings

Populate the form with the information from your Azure AD App Registration. If your API Connect version supports OIDC discovery (most do), you only need to provide the issuer, client ID, secret, and redirect URI—the rest will be auto-discovered.

Field	Value
Name	AzureAD-OIDC
Type	OpenID Connect (OIDC)
Issuer URL	https://login.microsoftonline.com/{your-tenant-id}/v2.0/
Client ID	(Your Application Client ID)
Client Secret	(The Client Secret you generated)
JWKS URL	https://login.microsoftonline.com/{your-tenant-id}/discovery/v2.0/keys
Scopes	openid profile email
Redirect URL(s)	https://developer.yourcompany.com/sandbox/idm/authorize/ibm_sec_client
User ID Claim	sub (or email if you prefer)
Name Claim	name

Pro Tip: Use the Authorization Code flow. The “Implicit” flow is considered less secure and is deprecated.

3.3. Assign the Registry to the Portal

1. After saving the registry, find it in the list and click Apply to… or Associate with….
2. Assign it to your Developer Portal.
3. Ensure it is set as the primary authentication source. API Connect may briefly restart the portal to apply the new settings.

Step 4: Test the Integration

1. Open a new incognito or private browser window.
2. Navigate to your Developer Portal URL.
3. You should be redirected to a Microsoft login page. Enter your credentials.
4. You should now be prompted to complete your MFA challenge (e.g., approve a notification in the Authenticator app).
5. After successful authentication, you will be redirected back and logged into the API Connect Developer Portal.

Success! Your login is now fully protected by Azure MFA.

Troubleshooting Common Issues

• Redirect URI Mismatch: The most common error. Ensure the redirect URI in Azure AD exactly matches (including https:// and path) the one configured in API Connect.
• Invalid Client Secret: The secret is case-sensitive. If you didn’t copy it correctly or it has expired, generate a new one in Azure AD and update the API Connect registry.
• MFA Not Prompting: Double-check your Conditional Access policy. Ensure the correct app and users are targeted and that the policy is set to On. Check the Azure AD Sign-in logs for detailed failure reasons.
• “Invalid Authorization Grant”: Verify the scopes in API Connect include openid profile. Ensure the user in Azure AD has the required permissions.

Conclusion

By following these steps, you’ve successfully created a secure, modern authentication flow for your IBM API Connect platform. You’ve moved beyond basic passwords by integrating the robust identity and access management capabilities of Azure AD, including mandatory Multi-Factor Authentication.

This setup not only significantly boosts your security posture but also provides a seamless Single Sign-On (SSO) experience for your developers, all managed centrally in Azure.