Microsoft (Entra ID and Microsoft Graph)

Call Microsoft Graph (Outlook mail, calendar, OneDrive, Teams) as the signed-in user.

Workspace Suites
OAuth 2.0 + PKCE
Works on Free plan
Bundled in Kirak
Maintained by Kirak

How to use it

This profile ships with Kirak. Add "integrations" to modules in kirak.json, then name the profile as below. There is nothing to download, and a copy in your project's integrations/ folder is an error.

Environment variables

Variable	Holds
`KIRAK_INTEGRATION_MICROSOFT_CLIENT_SECRET`	The OAuth client secret from the vendor's console. Secret: keep it out of kirak.json and out of source control.
`KIRAK_AUTH_ENCRYPTION_KEYS`	Encrypts stored tokens. Shared by every integration; the module refuses to start without it.

The names follow the integration's name in kirak.json (microsoft here). Name it something else, such as microsoft_sales, and the variables change to match.

Redirect URL

Register this as the redirect (callback) URL in the vendor's console, with your app's address in place of <your-app> (the base_url in kirak.json):

https://<your-app>/integrations/microsoft/callback

How to get your keys

In the Microsoft Entra admin center, open App registrations and choose New registration.
Pick the supported account types. They must match integrations.providers.microsoft.settings.tenant: common for any account, organizations for work and school accounts, consumers for personal accounts, or your tenant id for one organisation.
Add a redirect URI of type Web: https://<your-app>/integrations/microsoft/callback.
Under Certificates & secrets, create a client secret and copy its Value (it is shown once).
Under API permissions, add the Microsoft Graph delegated permissions your app needs. The default scopes are: User.Read (Sign in and read the user’s profile), offline_access (added by Kirak so it gets a refresh token)
Copy the Application (client) ID from the overview page.
Put the client ID in kirak.json as integrations.providers.microsoft.client_id, and the client secret in the environment as KIRAK_INTEGRATION_MICROSOFT_CLIENT_SECRET. Never put the secret in kirak.json.

The vendor's own guide · Instructions out of date? ·Suggest an edit

kirak.json

Scopes User.Read Sign in and read the user's profile Mail.Read Read the user's mail Calendars.Read Read the user's calendars Files.Read Read the user's files

{
  "integrations": {
    "providers": {
      "microsoft": {
        "type": "oauth2",
        "profile": "microsoft",
        "client_id": "your-client-id",
        "scope": [
          "User.Read"
        ],
        "settings": {
          "tenant": "common"
        }
      }
    }
  }
}

Merged into the profile: scope replaces the profile's default scopes, and offline_access is always added so Kirak gets a refresh token.

Settings

settings.tenant: The Entra tenant: common (any account), organizations (work and school accounts), consumers (personal accounts), or a tenant id or domain. Default common.

Good to know

The tenant is part of the authorize and token URLs. Use the app's own tenant for work apps, or common for apps that accept any account.
Refresh tokens are returned only with offline_access, and every refresh returns a new one that replaces the old.
Microsoft recommends PKCE with S256 for all app types, including confidential clients.

Example calls

GET /me: Read the signed-in user

Help improve this profile

Report a problem ·Suggest an edit to profile.json ·Add a profile ·Vendor docs the profile was checked against

Product names and logos are trademarks of their respective owners. Their use does not imply endorsement. To ask for this icon to be removed, email trademark@kirak.io.