Integrating Microsoft Azure AD OAuth into the OpenClaw Full‑Stack Template

1. Introduction

OpenClaw is a powerful, ready‑to‑run full‑stack template that ships with a flexible authentication module. By wiring Azure AD OAuth into this module, developers can leverage Microsoft’s enterprise‑grade identity platform while keeping the simplicity of UBOS’s low‑code deployment model.

This tutorial walks you through the entire process—from registering an Azure AD application to configuring OpenClaw’s auth service, updating environment variables, and finally testing the login flow. No prior Azure experience is required; just a basic familiarity with Node.js and Docker.

2. Prerequisites

• A Microsoft 365 or Azure subscription with admin rights.
• Access to the UBOS platform overview (you’ll need a UBOS account to deploy OpenClaw).
• Docker Engine (≥ 20.10) and Docker Compose installed locally.
• Node.js (≥ 18) for optional local debugging.
• Basic knowledge of environment variables and JSON configuration files.

3. Register Azure AD Application

Follow these steps in the Azure portal to create an app registration that OpenClaw can use for OAuth authentication.

1. Navigate to Azure AD → App registrations → New registration.
   • Give the app a descriptive name, e.g., OpenClaw‑AzureAD.
   • Supported account types: choose “Accounts in this organizational directory only” (single‑tenant) or “Any Azure AD directory” (multi‑tenant) based on your needs.
   • Redirect URI: set to https://YOUR_DOMAIN/auth/callback. Replace YOUR_DOMAIN with the domain where OpenClaw will be hosted (e.g., https://demo.mycompany.com/auth/callback).
2. Record the Application (client) ID and Directory (tenant) ID. You’ll need both for the OpenClaw configuration.
3. Create a client secret.
   • Go to Certificates & secrets → New client secret.
   • Give it a name (e.g., OpenClawSecret) and set an expiration period.
   • Copy the generated secret value immediately – it won’t be shown again.
4. Configure API permissions.
   • Click API permissions → Add a permission → Microsoft Graph → Delegated permissions.
   • Select openid, profile, and email. These scopes are required for basic user profile retrieval.
   • Click Grant admin consent to finalize the permissions.

For a deeper dive into Azure AD OAuth flows, see Microsoft’s official guide:

Azure AD OAuth 2.0 Authorization Code Flow
.

4. Configure OpenClaw Auth Module

OpenClaw ships with an auth microservice built on passport.js. We’ll add a new Azure AD strategy.

4.1. Install Required Packages

cd openclaw/auth
npm install passport-azure-ad dotenv

4.2. Create azureStrategy.js

require('dotenv').config();
const OIDCStrategy = require('passport-azure-ad').OIDCStrategy;

const azureStrategy = new OIDCStrategy(
  {
    identityMetadata: `https://login.microsoftonline.com/${process.env.AZURE_TENANT_ID}/v2.0/.well-known/openid-configuration`,
    clientID: process.env.AZURE_CLIENT_ID,
    responseType: 'code',
    responseMode: 'query',
    redirectUrl: process.env.AZURE_REDIRECT_URI,
    clientSecret: process.env.AZURE_CLIENT_SECRET,
    scope: ['openid', 'profile', 'email'],
    passReqToCallback: false,
  },
  (iss, sub, profile, accessToken, refreshToken, done) => {
    // Here you could map Azure AD profile to your internal user model
    return done(null, profile);
  }
);

module.exports = azureStrategy;

4.3. Wire the Strategy into Passport

const passport = require('passport');
const azureStrategy = require('./azureStrategy');

// Register the Azure AD strategy
passport.use('azuread', azureStrategy);

// Serialize / deserialize user (simple example)
passport.serializeUser((user, done) => done(null, user));
passport.deserializeUser((obj, done) => done(null, obj));

// Export configured passport
module.exports = passport;

4.4. Update Routes

Add two routes: one to initiate login and another to handle the callback.

const express = require('express');
const router = express.Router();
const passport = require('../passport'); // path to the file above

// Initiate Azure AD login
router.get('/login', passport.authenticate('azuread', { scope: ['openid', 'profile', 'email'] }));

// Azure AD callback
router.get(
  '/callback',
  passport.authenticate('azuread', {
    failureRedirect: '/login?error=auth_failed',
    successRedirect: '/',
  })
);

module.exports = router;

With the strategy in place, OpenClaw’s auth service can now delegate authentication to Azure AD.

5. Update Environment Variables

Add the Azure AD credentials you captured earlier to the .env file of the auth service.

# Azure AD OAuth Settings
AZURE_TENANT_ID=YOUR_TENANT_ID
AZURE_CLIENT_ID=YOUR_CLIENT_ID
AZURE_CLIENT_SECRET=YOUR_CLIENT_SECRET
AZURE_REDIRECT_URI=https://YOUR_DOMAIN/auth/callback

# Existing OpenClaw variables …
SESSION_SECRET=super_secret_key
PORT=3000

If you are using UBOS’s Workflow automation studio to manage deployments, you can inject these variables via the UI under “Environment → Secrets”.

6. Deploy and Test Login Flow

6.1. Build Docker Images

cd openclaw
docker compose build auth

6.2. Start the Stack

docker compose up -d

6.3. Verify the Service

• Open a browser and navigate to https://YOUR_DOMAIN.
• Click the “Login with Azure AD” button (you may need to add this UI element in the front‑end; see OpenClaw’s UI docs).
• You should be redirected to the Microsoft sign‑in page. After successful authentication, Azure AD will redirect back to /auth/callback.
• If everything is configured correctly, you’ll land on the OpenClaw dashboard as an authenticated user.

6.4. Debugging Tips

Once the flow works locally, you can promote the same configuration to a production UBOS environment using the UBOS pricing plans that match your scale.

7. Conclusion

By following this step‑by‑step guide, you have transformed OpenClaw into an Azure AD‑enabled SaaS application. The integration leverages UBOS’s low‑code deployment pipeline, keeping operational overhead low while delivering enterprise‑grade security.

Remember to monitor token lifetimes, configure conditional access policies in Azure, and keep your client secret rotated regularly. With these best practices in place, your users will enjoy a seamless SSO experience across all OpenClaw services.

Happy coding, and may your deployments be as smooth as Azure’s OAuth flow!