Seamless Identity Integration: Azure API Management with Azure AD B2C (AADB2C)

[Andrew_Redman]

Seamless Identity Integration: Azure API Management with Azure (AADB2C)

Introduction


Azure API Management (APIM) is a robust platform for managing and securing your APIs. In this blog post, we will guide you through integrating Azure API Management with Azure Active Directory B2C (AADB2C) for identity management. This integration enhances the security of your APIs by requiring user authentication before access is granted. We will break down the process into three key steps: setting up the Developer Portal to use AADB2C, configuring APIM to use OAuth 2.0 for authorization, and implementing token validation to ensure secure access.



This blog post consolidates information from three separate Microsoft Learn documents, providing a comprehensive, end-to-end guide for setting up AADB2C authentication in your APIM instance. Whether you're accessing your API via cURL, Postman, the Developer Portal, or other clients, this guide will ensure that your APIM instance is configured to handle authentication from AADB2C.



Part One: Setting up Developer Portal with AADB2C


In this section, we will prepare the Developer Portal to use AADB2C for user authentication.

Learning Document

1. Create Sign-Up and Sign-In Policy in AADB2C
   1. Set up a "Sign up and sign in" policy in AADB2C.
      1. For this you can use the same policy for both, just create a "Sign up and sign in" policy in AADB2C
      2. 
   2. Ensure you select all the attributes like Given Name, Surname, and return claims like Email Addresses and User's ObjectID. Here are the minimum requirements:
      1. Collect Attributes: Given Name, Surname
      2. Return claims: Given Name, Surname, Email Addresses, User's ObjectID
      3. 
2. Configure Identity in Developer Portal
   1. Add AADB2C as an identity provider in the Developer Portal.
      1. Open a new tab and navigate the Azure Portal for APIM and under the Developer Portal, select Identities:
         1. 
      2. Add a provider by clicking the “Add” button. That will prompt you with a choice of Types, you will want to select “Azure Active Directory B2C”
         1. 
   2. Use the MSAL (Microsoft Authentication Library) client library for authentication, do not worry about the rest of the attributes just yet, we will come back to them.
      1. 
   3. Copy the redirect URL for the Developer Portal.
      1. We will need this to create the backend app registration in the next step.
3. Create Backend App Registration in AADB2C
   1. Register an app to represent your API.
      1. Now, go back to your AADB2C tab, select App Registrations from the list on the left and click “New Registration”.
         1. 
            
            
            
      2. Enter a name for the app registration, for my example I am calling it `apim-api-backend`
      3. Select the Supported account types that best fit your scenario
      4. Setup the redirect URI (Uniform Resource Identifier) with a Single-page application (SPA) and paste the URI you copied from above.
         1. 
      5. Click register
   2. Create a client secret for this app registration.
      1. Now that the app registration is created, you will need to create a client secret
         1. Open the app registration you just created
         2. On the overview tab, you will see the Application (client) ID, copy that for later.
            1. 
         3. Then go to Certificates & secrets and create a new client secret. After you hit the Add button, it will show you the 'Value' of your secret. You will need to save this as it will not be shown again for security reasons.
            1. 
4. Add Identity Provider in APIM
   1. Now head back to APIM tab you left open earlier (or just open a new tab now and navigate to the APIM instance we have been working with), go to Identities, Add Identity Provider page and fill out the client id, and client secret with the values you copied from above
      1. You will also need to fill out the Signin tenant. This is your AADB2C tenant, and it has the following format: <aadb2c-tenant-name>.onmicrosoft.com. After you fill out that text box, it should fill out the Authority for you, but if not, it is <aadb2c-tenant-name>.b2clogin.com.
      2. Next fill out the sign-up and sign-in policy (we created this earlier in Step 1, so go copy the name you used above), if you have the profile editing and password reset policies you can add those here as well.
      3. Click Add
         1. 
   2. Now that you have created everything, you will need to republish the developer portal for these configurations to take effect.
      1. 
   3. It will take a few seconds for the portal to publish, but once it is complete you should be able to navigate to the Developer Portal and see a button to login using AADB2C.
      1. 
5. Test configuration
   1. Confirm that you can successfully log into the developer portal using an AADB2C login.

Part Two: Configuring APIM for OAuth 2.0 Authorization


Now that we have AADB2C integrated as an Identity into the Developer Portal, let us configure APIM for OAuth 2.0 authorization. This will let us ensure we can send the request with an Authorization header from the developer portal.

Learning Document

1. Modify Backend App Registration
   1. Add scopes that represent the APIs you are exposing.
      1. Go back to the AADB2C tenant and navigate to App Registrations
         1. 
      2. Find the app you created above (this will be our backend app registration; it represents our Api) and open it up
         1. 
      3. Go to expose an Api, and then click 'Add a scope'
         1. Create a new scope by giving it a name, and display name and a description
         2. Now click 'Add Scope'
         3. If this is the first scope you are adding it will ask you to create an Application ID URI, you can use the default or put your own in there it will just need to follow URI format
         4. Here is what the ‘Add a scope’ blade looks like
            1. 
      4. If you have more than one scope you want to add, repeat these steps. The scopes will represent the things the user will be able to do from the API
   2. Create a new app registration for the client (APIM Developer Portal).
      1. Create the new app registration and give it a meaningful name, I would suggestion something with 'client' in it
      2. Leave the Redirect uris empty for now and select 'Register'
         1. 
   3. Now that the new app registration is created for the client, you will need to create a client secret like you did for the backend app registration.
      1. Make sure you copy the client id and the secret value so you can use it again when we setup the OAuth server in the next few steps.
2. Allow Access to Backend App Registration
   1. In the client app registration, add permissions to request scopes from the backend app registration.
      1. Open the client app registration, under Api permissions, go to add a Permission
      2. This will give you a list of APIs to select from, use the ‘APIs my organization uses’ filter and find the backend-app you created earlier
         1. 
      3. Select Delegated Permissions for all the scopes you want to add and select Add permissions
         1. 
      4. You will then need to grant the admin consent for these new permissions
         1. 
3. Add OAuth 2.0 Auth Server in APIM
   1. Configure OAuth 2.0 settings in APIM, providing details from app registrations.
      1. Navigate back to the APIM tab and go to the 'Oauth 2.0 + OpenID Connect' section and click the '+ Add' button under the Oauth 2.0 tab
         1. 
      2. This should open the 'Add OAuth2 service' dialog
         1. Name: This will be how APIM identifies the auth server so use names appropriately
         2. Add a description
         3. The Client registration page URL is the page where users can create and manage their accounts, since AADB2C does not have a direct URL for that (you need to navigate via the azure portal) you can just put `http://localhost`
         4. Next select the Auth grant type, the default is Auth Code, but you will want to make sure to follow what you have set up in the app registrations. In my case I selected both Authorization code and Authorization code + PKCE because I set up my client app registration as a SPA. PKCE stands for Proof Key for Code Exchange
            1. 
         5. Now enter the authorization endpoint URL, you can get this from the Endpoints page on the Overview tab of an app registration, make sure to select the v2 endpoint
            1. 
         6. Select POST as the auth request method
         7. Now enter the token endpoint URL, you can also get this from the Endpoints page on the Overview tab of an app registration.
            1. 
         8. Just use the defaults on the 'Authorization request method’ and ‘Access token sending method’.
         9. In the Default scope, enter the permission that you exposed on the client app registration from the backend app registration just a few steps above this. You must use the fully qualified scope URL as the scope name here
            1. If you have multiple scopes, you can list them all here…space separated
            2. It will have this format <Application ID URI>/<permission name>
         10. Next, fill out the clientId and clientSecret from the client app registration that you saved a moment ago
         11. This will generate the Redirect URI
             1. **Important Step** You will need to go back to the client app registration and add this Redirect URI that will need to be added back to the client app registration
             2. 
         12. Hit Create and you are done
   2. Now you should have a new OAuth 2.0 server, you will need to republish the developer portal at this point to make sure the latest configuration is deployed
      1. Go back to the APIM tab and go to Portal overview, click the Revisions tab, and click the Publish button. This will take a few seconds, but you can refresh the table and see status.
      2. 
4. Add OAuth 2.0 server to your API
   1. Go to APIM and navigate to APIs -> Setting tab and then scroll down to the Security section. Select User authorization to Oauth 2.0 and then in the dropdown list select the Oauth server that we created above.
      1. If you need to use different scopes for a given Api you can override it here at this level using the Override scope checkbox
      2. 
         
         
         
5. Test in Developer Portal
   1. Log in using AADB2C credentials in the Developer Portal.
   2. Access APIs and see OAuth 2.0 authorization in action.
      1. In the Try It section you will see something like this:
         1. 
         2. Hit the dropdown and select the grant type you setup (in our case it is authorization code)
         3. 
         4. That should trigger an auth call which will pull the token from your initial login (or prompt you for a new login) and transform it appropriately and populate the 'Authorization' header in the test request.

Part Three: Adding Token Validation for Security


The last step ensures secure API access by adding token validation by adding a validation policy.

Learning Document

1. Add Validate-JWT Policy
   1. In APIM, add a validate-jwt policy to the inbound policy.
      1. Go to the Api you want to add the validation to, or you could set it at the global level:
         1. 
            
            
            
      2. Use the `validate-jwt` policy. You can find the documentation for it here. This is screenshot of what it might look like, I am using `Named Values` for some variables.
         1. 
   2. Update the <openid-config URL> property with the correct AADB2C endpoint.
      1. After you add that policy, you will want to update the <openid-config URL> property. The format looks like this:
         1. 
            https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<user-flow-name>/v2.0/.well-known/openid-configuration
      2. If you want to copy and paste it, you can get this endpoint from the Endpoints section on the overview tab of the app registration. It is under the `Azure AD B2C OpenID Connect metadata document`. You will just need to fill out the policy name for you signin policy you created above.
         1. 
      3. Configure Audience and Issuers
         1. Specify the audience and issuers for token validation.
      4. Testing and Security:
         1. If the JWT (JSON Web Token) is valid, APIM allows the request to continue to the backend.
         2. If the JWT is invalid, APIM blocks the request, enhancing security.

Conclusion


By following these steps, you can seamlessly integrate Azure API Management with Azure ADB2C, ensuring that your APIs are secure and accessible only to authorized users. This setup offers a robust authentication and authorization mechanism for your APIs, making them more reliable and trustworthy.

Continue reading...