[Guide] How to Integrate Microsoft Entra ID (Azure AD) Login via API Connector

Tips
1

Hey everyone! :waving_hand:

I recently needed to implement Microsoft Entra ID (formerly Azure Active Directory) SSO for a project, and I noticed that the built-in plugins don’t always offer the flexibility you need (especially if you want to pull specific profile data or use specific tenant routing).

This was formulated due to a recurring error - Text too long for this field (Return key by Azure is quite long and plugin doesn’t handle it effectively, Bubble 0auth also failed to handle it)

I ended up building the integration directly through the API Connector using the OAuth2 User-Agent Flow. It works perfectly, so I wanted to share the exact setup in case anyone else is stuck on this!

Here is the step-by-step guide.

Step 1: App Registration in Microsoft Entra (Azure Portal)

First, we need to tell Microsoft about our Bubble app.

  1. Go to the Azure Portal and navigate to Microsoft Entra ID.

  2. Click on App registrations > New registration.

  3. Name: Enter your app’s name.

  4. Supported account types: Choose who can log in (Usually Accounts in this organizational directory only for internal tools, or Multitenant for public SaaS).

  5. Redirect URI: Select Web, and enter your Bubble app’s generic redirect URL. (You can usually find this at the bottom of the API Connector once you set up the auth, it looks like https://your-app.bubbleapps.io/api/1.1/oauth_redirect).

  6. Click Register.

Save these values—you’ll need them for Bubble:

  • Application (client) ID

  • Directory (tenant) ID

Step 2: Create a Client Secret & Add Permissions

  1. In your newly created App Registration, go to Certificates & secrets.

  2. Click New client secret. Give it a description (e.g., “Bubble API”) and set an expiration.

  3. Important: Copy the Value immediately. (Do not copy the Secret ID!). You won’t be able to see the Value again once you navigate away.

  4. Next, go to API permissions.

  5. Ensure you have the following Microsoft Graph permissions granted:

    • User.Read

    • email

    • openid

    • profile

    • offline_access (If you want to maintain long-term token refreshes)

Step 3: Configuring the Bubble API Connector

Now jump into your Bubble Editor > Plugins > API Connector. Create a new API and name it something like Entra_ID.

Configure the Authentication settings exactly like this:

  • Authentication: OAuth2 User-Agent Flow

  • App ID/API Key: YOUR_CLIENT_ID (From Step 1)

  • App Secret: YOUR_CLIENT_SECRET_VALUE (From Step 2)

  • Scope: openid profile email User.Read offline_access (Space separated)

  • Login dialog redirect: https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/authorize (Replace YOUR_TENANT_ID with your actual Tenant ID or use common if multitenant).

  • Access token endpoint: https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token

  • User profile endpoint: https://graph.microsoft.com/v1.0/me?$select=id,userPrincipalName,mail

  • User ID path: id

  • User email path: userPrincipalName (Microsoft usually stores the primary login email here rather than the mail field).

Checkboxes:

  • Use a generic redirect URL (Make sure this matches what you put in Azure!)

  • Add to Header (or authenticate via header depending on your exact Entra config, but standard is fine).

Once configured, click Initialize Call or Authenticate. Bubble will pop open a Microsoft login window. Log in with an account in your tenant, and if successful, Bubble will save the token payload!

Step 4: Add a “Get Profile Data” Call (Optional but Recommended)

Because we used the API Connector, we can easily pull more data from the Microsoft Graph API using the token we just got.

Add an API call under your Entra_ID configuration:

  • Name: GetMe

  • Use as: Data

  • Method: GET

  • URL: https://graph.microsoft.com/v1.0/me?$select=id,userPrincipalName,mail

Since the API is set to OAuth2, Bubble will automatically inject the authenticated user’s Bearer token into the headers for this call.

Step 5: Building the Login Workflow (Plan A)

Finally, let’s wire it up to the UI.

  1. Add a button on your login page: “Login with Microsoft Entra”.

  2. Start a workflow for the button click.

  3. Add Action: Account > Signup/login with a social network.

  4. Select Entra_ID (or whatever you named your API) as the OAuth provider.

  5. Add a subsequent action (e.g., Navigate to Dashboard).

How it works in practice:

When the user clicks the button, they are redirected to Microsoft’s secure login page. Upon successful login (including any MFA/Conditional Access policies your org has in place), they are bounced back to Bubble. Bubble automatically matches the userPrincipalName to a User record in your database, logging them in or creating a new user row seamlessly!

Step 5: Building the Custom Login Flow (oauth_redirect & Backend Workflows) - Plan B

Instead of relying on Bubble’s black-box “Signup/login with a social network” action, we are going to handle the OAuth callback manually. This allows us to strictly validate the OAuth state parameter, fetch the token via API, and seamlessly log the user into their Bubble account.

5.1 Pre-requisite: The Initial Login Button

When a user clicks “Login with Microsoft”, they shouldn’t just be redirected via an external link. Instead, your app should generate a unique, temporary “State Secret” (e.g., in a data type called ua_session_code) to prevent CSRF attacks. Redirect the user to the Microsoft Auth URL appending your generated state and requesting the code.

5.2 The Validation Endpoint (EXT_State_Check)

To securely validate the returning state parameter without exposing logic to the frontend, create a Backend API Workflow called EXT_State_Check:

  • Parameters: State (text)

  • Logic: Perform a search for the stored ua_session_code where:

    • state_secret matches the State parameter

    • used is “no” (false)

    • expires_at is >= Current Date/Time

  • Return Data: If the search result is empty, return an “Invalid” flag as true.

5.3 The Page Load Workflow (oauth_redirect)

Set your Azure Redirect URI to land on a specific Bubble page (e.g., oauth_redirect).

Create a workflow on this page triggered by “Page is loaded” (with the condition that the URL parameter code is not empty):

  1. Validate State (GetDataFromAPI): Use Bubble’s App API to call EXT_State_Check, passing the state parameter from the URL. If the response returns “Invalid”, redirect the user immediately to a 404 or error page.

  2. Prevent Double Execution: Set a Custom State on the page (e.g., token_call_started = yes) so the workflow doesn’t fire twice.

  3. Exchange Code for Token: Use your API Connector setup to call the Entra ID Token Endpoint (ETR_Fetch_Token), passing the URL code.

  4. Clean the URL: (Optional) Trigger a custom event to strip the code and state parameters from the browser’s address bar so they aren’t accidentally copied or shared.

  5. Get User Profile: Call the Microsoft Graph OIDC Endpoint (API_ETR_Get_OIDC) using the returned Access Token to retrieve the user’s email and name.

  6. Exit if Unrecognized: Perform a search for a Bubble User matching the Microsoft email. If no user is found (and you don’t allow public signups), trigger an alert and terminate the workflow.

  7. Set Temporary Password: If the user is found, use the Account > Assign a temp. password to a user action on the matched Bubble User.

  8. Log In: Use Account > Log the user in, passing the fetched email and the result of the Temporary Password step.

  9. Update Entra Name: Make changes to the CurrentUser to save their Entra name (name_entra_text = [API Profile Name]) if it’s currently empty.

  10. Invalidate State: Make changes to the ua_session_code record that matched the state parameter, setting used = yes so it cannot be reused (preventing replay attacks).

  11. Navigate to Dashboard: Redirect the newly authenticated user to the main app dashboard.

5.4 Handling Tokens Securely (Get_Entra_Token Backend Workflow)

If you need to store the access_token and refresh_token for background syncing (e.g., calendar reads or file uploads on behalf of the user when they are offline), do not do this on the frontend.

Instead, create a companion Backend Workflow called Get_Entra_Token:

  • Parameters: Passed_Code, Auth_URL, Passed_User

  • Logic:

    1. Call the ETR_Fetch_Token API Connector securely from the server.

    2. Make changes to Passed_User, saving the resulting access_token and refresh_token directly to their database row.

By using this manual OAuth flow, your app stays entirely in control of session management, user creation rules, and security tokens, completely avoiding the limitations of the standard Bubble social login action!

A few extra tips:

  • Missing Emails: If Bubble creates the user but the email field is empty, double-check your User email path in the API connector. It should be userPrincipalName.

  • Tokens Expiry: If your API calls to Graph start failing after a while, make sure you included the offline_access scope so Bubble can use the Refresh Token to get a new Access Token in the background.

Hopefully, this saves someone a few hours of reading Microsoft Graph documentation! Let me know if you have any questions or run into any specific errors. Happy building! :rocket:

Most of the heavy lifting was achieved using Buildprint by @georgecollier and this entire tips post was curated by the Buildprint with some minor tweaks by human

3 Likes