> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velatir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Entra

> Assign organisation roles from Entra security groups, generate workspaces from your directory, and organise activity by team.

## Why Connect Entra?

Connecting Microsoft Entra lets Velatir follow how your organisation is actually set up:

* **Organisation membership** — people who sign in with Microsoft join the right Velatir organisation automatically, with the role that matches their security groups.
* **Workspaces** — Velatir can generate workspaces from directory properties and keep people in the right place as they move teams.

The same directory structure also organises activity by team, which powers the department and group breakdowns in [Insights](/insights/overview).

<Note>
  Connecting Entra is optional. You can invite members by email and create workspaces by hand instead. See [Organisations & workspaces](/platform/organizations-and-workspaces).
</Note>

## Assign Organisation Roles From Security Groups

Map Entra security groups to Velatir organisation roles. Anyone who signs in with Microsoft and belongs to a mapped group is added to the organisation with that role. If they belong to more than one mapped group, they receive the higher privilege (**Administrator** over **Reader**).

<Steps>
  <Step title="Open Members settings" icon="users">
    In your organisation, go to **Settings → Members**. You need the Administrator role to configure this.
  </Step>

  <Step title="Enter your tenant and groups" icon="key-round">
    Turn on Entra member sync and paste your Microsoft Entra **tenant ID**. Map at least one security group to **Administrator**. You can optionally map a group to **Reader**. Use each group's **Object ID** from Entra, not its display name.
  </Step>

  <Step title="People sign in with Microsoft" icon="log-in">
    Members must use **Sign in with Microsoft** for the mapping to apply. The next time they sign in that way, Velatir checks their groups and adds or updates their organisation role.
  </Step>
</Steps>

<Note>
  Email invitations are turned off while member sync is on. Access comes from the directory instead of one-off invites.
</Note>

### Members managed by Entra

People added this way appear in the member list with an **Entra** badge. While sync is on you cannot remove them or change their role in Velatir — the security groups own that. They lose access automatically when they leave the mapped groups, or when they next sign in after you change the mapping.

The person who created the organisation is the founder and is never removed by sync.

### Turning member sync off

Turning sync off does not delete anyone. Existing members stay, now as ordinary members you can invite, remove, and re-role as usual. Email invitations become available again.

<Warning>
  Membership is based on the Microsoft account that signs in, not on an email address someone types into Velatir. Signing up with an email that happens to match a directory user does not grant organisation access.
</Warning>

## Generate Workspaces From Your Directory

When you set up your organisation, choose **Generate workspaces with Microsoft Entra** and pick which directory properties define your structure.

<Steps>
  <Step title="Choose the top-level property" icon="building">
    Pick the Entra user property that defines your top-level workspaces, for example **Department**. Velatir creates one workspace per value.
  </Step>

  <Step title="Optionally nest a second level" icon="layout-grid">
    Add a second property, such as **Office** or **City**, to nest workspaces beneath the first. You can nest up to two levels.
  </Step>

  <Step title="People are placed automatically" icon="users-round">
    Everyone is assigned to the right workspace based on their directory details, and moved automatically when those details change.
  </Step>
</Steps>

## Properties You Can Use

| Property           | Typical use                                                                           |
| ------------------ | ------------------------------------------------------------------------------------- |
| **Department**     | Top-level workspaces such as Engineering, Sales, or Legal                             |
| **Office**         | Nested workspaces by location                                                         |
| **City**           | Workspaces by city, for organisations spread across several sites                     |
| **Country/region** | Top-level workspaces for organisations that operate in more than one country          |
| **Company name**   | Workspaces by legal entity or subsidiary, when one tenant hosts more than one company |
| **Group**          | Nested workspaces by team or function                                                 |

## Activity by Team in Insights

Once Entra is connected, activity is organised by your directory structure: department, office, and group. You can filter and break usage down by these across the platform, so you see where AI is being adopted without singling out individuals.

<CardGroup cols={2}>
  <Card title="Organised by your structure" icon="building-2">
    Activity is grouped by department, office, and group, so the picture always matches how your organisation is set up.
  </Card>

  <Card title="Team insights" icon="chart-line">
    Insights break usage down by department, office, and group, and show where adoption concentrates.
  </Card>
</CardGroup>

## Mapping Device Activity to Teams

So activity captured on a device lands in the right workspace, Velatir matches it to your directory structure using the organisational context the desktop client attaches to each trace.

***

<CardGroup cols={2}>
  <Card title="Organisations & workspaces" icon="building" href="/platform/organizations-and-workspaces">
    How your account is structured.
  </Card>

  <Card title="Roles & permissions" icon="shield" href="/platform/roles-and-permissions">
    What Administrator and Reader can do in the organisation.
  </Card>
</CardGroup>