What Microsoft Graph permissions does Gateco need?

Gateco needs three application permissions (not delegated): User.Read.All to read all users, Group.Read.All to read all groups, and GroupMember.Read.All to read group memberships. All three must be granted admin consent. Delegated permissions will not work because Gateco runs as a background service without a signed-in user.

How do I rotate the client secret before it expires?

In Azure Portal, go to App registrations → your Gateco app → Certificates & secrets → New client secret. Copy the new value, then update the Client Secret field in Gateco under Identity Providers → edit your Azure provider → Save. The old secret can then be deleted. Set a calendar reminder 30 days before the expiry date you chose.

Can I use SCIM provisioning and the polling sync at the same time?

Yes. SCIM provisioning (available on Growth plan and above) pushes changes from Entra ID to Gateco in real time, keeping identity-aware retrieval policies current as your Azure AD groups change. The polling sync still runs on its schedule and acts as a fallback. Running both ensures you catch any missed SCIM events. If you use SCIM, you can reduce the polling sync interval to hourly or longer.

Connect Azure Entra ID to Gateco

Gateco connects to Azure Entra ID via a registered application (service principal) that reads users and groups from the Microsoft Graph Groups API. This guide takes you from a blank Entra ID tenant to a working Azure AD group sync in about 10 minutes — enabling identity-aware retrieval and RAG access control based on your Azure directory.

Azure Entra ID integration requires the Growth plan or above. No Azure premium license is required — read-only service-principal access to users and groups is available on all Entra ID tiers.

Step 1 — Register an application

Go to Azure Portal → Microsoft Entra ID → App registrations → New registration.
Name: gateco (or any name meaningful to your org).
Supported account types: "Accounts in this organizational directory only (Single tenant)".
Redirect URI: leave blank.
Click Register.
On the app overview page, note the Directory (tenant) ID and Application (client) ID. You will need both.

Step 2 — Grant API permissions

Gateco uses application permissions, not delegated permissions. Application permissions allow the service to read your directory without a signed-in user — required for automated background sync.

In the app registration, go to API permissions → Add a permission.
Choose Microsoft Graph → Application permissions.
Search for and add: User.Read.All, Group.Read.All, GroupMember.Read.All.
Click Add permissions.
Click "Grant admin consent for <your tenant>" and confirm.
All three permissions should show a green checkmark and status "Granted for <tenant>".

Admin consent is required. The "Grant admin consent" button is only visible to Global Administrators and Application Administrators. If you do not see it, ask your Azure admin to grant consent for you.

Step 3 — Create a client secret

In the app registration, go to Certificates & secrets → Client secrets → New client secret.
Description: gateco-sync (or any label).
Expiry: 24 months (recommended). Set a calendar reminder to rotate before expiry.
Click Add.
Copy the Value immediately — it is shown only once. If you navigate away, you must create a new secret.

Step 4 — Add credentials to Gateco

In the Gateco dashboard:

Navigate to Identity Providers → Add provider → Azure Entra ID.
Enter the three values from the table below.
Click Test connection. Gateco will display the number of users and groups it can read.
Click Save.

Field	Value
`Tenant ID`	`Directory (tenant) ID from Step 1`
`Client ID`	`Application (client) ID from Step 1`
`Client Secret`	`Secret value from Step 3 (not the Secret ID)`

Step 5 — Trigger initial sync

After saving the provider, click Sync now. Gateco will:

Fetch all users from GET /v1.0/users (paginated).
Fetch all groups from GET /v1.0/groups.
Fetch group memberships for each group.
Create or update Principal records.

Sync typically completes in under 30 seconds for tenants up to 10,000 users.

How Gateco uses your Entra ID data

Entra ID field	Gateco principal field	Use in policy conditions
`mail (or userPrincipalName if mail is null)`	`email`	`principal.email`
`displayName`	`display_name`	`Display only`
`department`	`attributes.department`	`principal.attributes.department`
`jobTitle`	`attributes.title`	`principal.attributes.title`
`Group membership`	`groups array`	`principal.groups`

Users without Microsoft 365 licenses often have mail = null in the Graph API. Gateco automatically falls back to userPrincipalName in that case. Guest accounts with #EXT# in their UPN are synced as-is.

Troubleshooting

Error	Cause	Fix
`Connection test fails with 403 Forbidden`	`Admin consent not granted`	`Go to API permissions and click "Grant admin consent". Only Global Admins and App Admins can do this.`
`Zero users synced after successful connection`	`Delegated User.Read.All instead of application type`	`Delete the delegated permission and add the application version. Check the Type column shows "Application".`
`Groups sync but members not populating`	`GroupMember.Read.All missing or not consented`	`Add GroupMember.Read.All (application type) and grant admin consent.`
`Sync stops working after months`	`Client secret expired`	`Create new secret in Entra ID, update it in Gateco Identity Providers → edit → save.`