<aside>

Last updated: 05/06/2026

</aside>

<aside>

Before starting the role mapping guide, please complete the configuration and connection setup guide linked below

Start Here ⬇️

Configure SAML SSO and Complete Connection Setup

</aside>

Overview

Aviary supports a "Smart Sync" approach to identity management. While users can be managed manually within the Aviary UI, this guide details how to control roles, permissions, and group membership centrally from Microsoft Entra ID using SAML Attributes.

How Synchronization Works

1. Source of Truth: When a user logs in via SSO, Aviary inspects specific SAML attributes (Claims).
2. Partial Updates: The synchronization is non-destructive.

• If an attribute is present: Aviary updates the user's profile to match Entra ID.
• If an attribute is missing: Aviary ignores that field and preserves whatever settings exist in the application database.
• Benefit: This allows IT Admins to manage high-level roles (e.g., Global Admin) via SSO, while allowing specific team managers to fine-tune granular permissions inside the app without fear of them being wiped out on the next login.

Part 1: The Bootstrap Workflow

Because Aviary uses specific "SAML Identifiers" for Knowledge Base groups, you cannot simply guess the Group IDs. You must follow this one-time bootstrap workflow to retrieve the correct identifiers.

Step 1: Establish a Global Admin

The first user needs Global Admin access to set up the environment. In Entra ID, assign the following attribute to your primary IT Admin user:

• Attribute: aviary_global_access
• Value: true

Step 2: Configure Resources in Aviary