Azure AD SSO

This section walks you through setting up Single Sign-On (SSO) so users can log in to Herd using their Azure AD credentials.

Azure AD SSO Login and Architecture Overview

This section walks you through setting up Single Sign-On (SSO) so users can log in to Herd using their Azure AD credentials, giving them one-click access with the same identity they already use at work. By connecting Herd to Azure AD for authentication, you reduce password fatigue, improve security, and keep access control aligned with your central identity provider.​

You’ll find step-by-step instructions for creating the required app registration in Azure AD, configuring tokens and permissions, and wiring those settings into Herd. Once configured, your users will be able to sign in through Azure AD while you maintain centralized control over who can access Herd, making it easier to onboard, offboard, and audit accounts as your organization grows.

User → Herd App → AWS Cognito → Azure AD → User Authenticated

Herd uses AWS Cognito as the identity broker, which federates to Azure AD for authentication.

What You'll Need

• Admin access to your Azure AD tenant

• Admin access to AWS Cognito

• About 20 minutes

Step 1: Create an App Registration for SSO

Note: This is a SEPARATE app registration from the User Sync app. SSO requires different settings.

1. Go to Azure Portal

2. Navigate to Azure Active Directory > App registrations

3. Click + New registration

4. Fill in:

   • Name: Herd SSO (or any name you prefer)

   • Supported account types: Select "Accounts in this organizational directory only"

   • Redirect URI:

     • Platform: Web

     • URL: https://your-cognito-domain.auth.us-west-2.amazoncognito.com/oauth2/idpresponse

5. Click Register

Step 2: Note Your IDs

Copy these values from the Overview page:

Field	Where to Find It
Application (client) ID	Overview page
Directory (tenant) ID	Overview page

Step 3: Create a Client Secret

1. Go to Certificates & secrets

2. Click + New client secret

3. Add a description (e.g., "Herd SSO")

4. Choose an expiration (recommended: 24 months)

5. Click Add

6. IMPORTANT: Copy the secret VALUE immediately - you won't be able to see it again

⚠️ Common Mistake: Copy the Value column, NOT the Secret ID column. Using the Secret ID will cause authentication to fail.

Step 4: Configure Token Claims

Azure AD needs to send the user's email in the token:

1. Go to Token configuration

2. Click + Add optional claim

3. Select ID token type

4. Check these claims:

   • email

   • preferred_username

   • upn

5. Click Add

6. Repeat for Access token type

Step 5: Configure API Permissions

1. Go to API permissions

2. Click + Add a permission

3. Select Microsoft Graph

4. Select Delegated permissions

5. Add these permissions:

   • openid

   • profile

   • email

6. Click Add permissions

7. Click Grant admin consent for [Your Organization]

Step 6: Configure AWS Cognito

1. Go to AWS Cognito Console

2. Select your User Pool

3. Go to Sign-in experience > Federated identity provider sign-in

4. Click Add identity provider

5. Select SAML or OpenID Connect (OIDC recommended)

For OIDC Configuration:

Field	Value
Provider name	AzureAD-yourorg (e.g., AzureAD-devmscust)
Client ID	Application (client) ID from Step 2
Client secret	The secret VALUE from Step 3
Authorize scope	openid profile email
Issuer URL	https://login.microsoftonline.com/{tenant-id}/v2.0
Attribute mapping	Map email → email, sub → username

1. Click Create identity provider

Step 7: Configure Herd Organization

1. In Herd admin, go to organization settings

2. Set:

   • Auth Type: federated

   • Domain: Your Cognito domain (e.g., https://your-app.auth.us-west-2.amazoncognito.com)

   • Client ID: Your Cognito app client ID

   • Identity Provider: AzureAD-yourorg (must match the provider name in Cognito)

SSO Troubleshooting

Error: "Invalid client secret provided"

AADSTS7000215: Invalid client secret provided. Ensure the secret being sent
in the request is the client secret value, not the client secret ID

Cause: You copied the wrong value when creating the client secret.

Fix:

1. Go to Azure AD → App Registrations → your SSO app → Certificates & secrets

2. Create a new client secret

3. Copy the Value column (NOT the "Secret ID")

4. Update the secret in AWS Cognito → User Pool → Identity providers → AzureAD

Error: "Access Token does not have required scopes"

This error appears in backend logs when the Cognito access token doesn't have the scopes needed to call Cognito's GetUser API.

Cause: This is expected for federated (SSO) users. The system automatically falls back to extracting email from the ID token.

Fix: No action needed if authentication succeeds. If it fails:

1. Ensure the ID token is being passed from frontend to backend via x-id-token header

2. Verify Azure AD is configured to include email claims (Step 4)

Error: User not found / Cannot create user

Cause: The user doesn't exist in Herd and couldn't be auto-created.

Fix:

1. Run Azure AD User Sync first to import users

2. Or ensure Azure AD is sending the email claim so users can be auto-created

Error: "Token does not belong to requested organization"

Cause: Token issuer mismatch during token refresh.

Fix:

1. Clear browser storage and cookies

2. Log out completely

3. Log in again

SSO Login Not Redirecting to Azure

Cause: Identity provider not configured or identityProvider field not set.

Fix:

1. Verify the identity provider exists in Cognito

2. Set the identityProvider field on the organization to match the Cognito provider name exactly

Understanding the Username Format

Azure AD SSO users in Cognito have usernames like:

azuread-devmscust_f7dsazfc_3_lpr9jokhw0-20fr-y97vwyfkgb57bpkk

This is generated by Cognito and contains:

• Prefix: Identity provider name (e.g., azuread-devmscust)

• Separator: _

• Suffix: Unique identifier from Azure AD

The system automatically detects these as SSO users and handles authentication appropriately.