Microsoft OAuth2 Exchange

Authenticate users via Microsoft (Azure AD) OAuth2 to retrieve access tokens and user profile data.

The Microsoft OAuth2 Exchange block is used to exchange an authorization code for Microsoft identity tokens (Azure AD / Microsoft Graph). This allows you to implement "Sign in with Microsoft" or access Microsoft 365 services like Outlook, Teams, and SharePoint.

Core Concept

When a user signs in through Microsoft, your application receives a code. This block exchanges that code for an access_token and an id_token, allowing you to identify the user and call Microsoft Graph APIs on their behalf.

Configuration

Field	Required	Description
Client ID	✅	Your application's Client ID from the Azure Portal (App Registrations).
Client Secret	✅	Your application's Client Secret. Must be stored as a Secret.
Redirect URI	✅	The URI where Microsoft redirects the user after authorization.
Authorization Code	✅	The code received from Microsoft (e.g., `{request.query.code}`).
Token Variable	✅	The variable name where the resulting data will be stored.

Security Requirement

Always store your Client Secret in the project's Secrets configuration. Never hardcode it as a plain string in the block.

Output

Once executed, the block stores a JSON object in your specified variable:

{
  "tokens": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...",
    "expires_in": 3599,
    "scope": "openid profile email",
    "token_type": "Bearer",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..."
  },
  "user": {
    "displayName": "John Doe",
    "givenName": "John",
    "surname": "Doe",
    "mail": "[email protected]",
    "userPrincipalName": "[email protected]",
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

You can access specific fields using dot notation:

{ms_auth.user.displayName}
{ms_auth.tokens.access_token}

Error Handling

MISSING_CLIENT_ID — The Client ID field is empty.
MISSING_CLIENT_SECRET — The Client Secret selection is empty.
MISSING_REDIRECT_URI — The Redirect URI is missing.
MISSING_CODE — No authorization code was provided.
SECRET_RETRIEVE_ERROR — Failed to retrieve the secret from storage.
INVALID_CODE — The authorization code is invalid or has already been used.
INVALID_CLIENT — Client authentication failed (check your Client Secret).
INVALID_REDIRECT_URI — The Redirect URI does not match the one registered in Azure.
INVALID_REQUEST — The request is missing a required parameter.
USER_FETCH_ERROR — Failed to retrieve the user profile after token exchange.
RUNTIME_ERROR — An unexpected error occurred.

Example

User Login: Redirect your user to Microsoft's Auth URL.
Callback: Microsoft redirects to your endpoint: https://myapp.com/callback?code=M.R2_....
Exchange: Use this block to process the code:
- Authorization Code: {request.query.code}
- Token Variable: ms_auth
Result: You can now welcome the user by their name: Hello {ms_auth.user.displayName}!.

Microsoft OAuth2 Exchange

Configuration

Output

Error Handling

Example

Other OAuth Providers

Google OAuth2

Discord OAuth2

GitHub OAuth2

On this page