#Microsoft Entra ID setup
SignetMail uses one app registration in Microsoft Entra ID for three jobs:
- Portal sign-in — administrators sign in with their work account (single sign-on, MFA, Conditional Access).
- Add-in sign-in — the Outlook add-in obtains a token silently (Nested App Auth).
- Directory access — the server reads users and groups through Microsoft Graph, authenticating with a certificate (no client secret to leak).
You need an account that can register applications and grant admin consent.
#1. Register the application
- Open Microsoft Entra admin center → Entra ID → App registrations → New registration.
- Name:
SignetMail. Supported account types: Accounts in this organizational directory only. - Leave the redirect URI empty for now and click Register.
- On the Overview page copy Application (client) ID and Directory (tenant) ID. These go into
.envasENTRA_CLIENT_IDandENTRA_TENANT_ID.
#2. Sign-in redirect addresses
Authentication → Add a platform → Single-page application. Add:
| Redirect URI | Used by |
|---|---|
https://<host>/portal/ |
The web portal (the trailing slash matters). |
brk-multihub://<host> |
The Outlook add-in (Nested App Auth). Required for the add-in to sign in silently. |
brk-9199bf20-a13f-4107-85dc-02114787ef48://<host> |
The Outlook add-in, Outlook desktop broker. Without it the task pane shows AADSTS700046. |
Click Configure. Do not tick any Implicit grant boxes.
The new Entra experience rejects the third address. Authentication (Preview) validates redirect URIs and refuses anything that does not start with
https://orhttp://localhost, sobrk-9199bf20-…cannot be added there. Either switch to the old experience with the link in the blue banner, or open Manifest and add the address tospa.redirectUrisby hand. The manifest is not validated the same way. Remove any other redirect URIs (for example leftovers from testing) that you do not need.
For the Windows agent with Entra sign-in (classic Outlook on PCs joined to Entra ID, or a hosted server), also add Add a platform → Mobile and desktop applications with the redirect URI ms-appx-web://microsoft.aad.brokerplugin/<client-id> (your application's client ID). The agent then signs in silently with the account the user is signed in to Windows with. Agents that use Kerberos (domain PCs and a server in the same domain) do not need it.
#3. Expose an API
- Expose an API → Application ID URI → Add and accept
api://<client-id>. - Add a scope: name
access_as_user, Who can consent: Admins and users, display name e.g. "Access SignetMail", state Enabled. - Open the Manifest and make sure
requestedAccessTokenVersionis2(underapi). Version 2 tokens containpreferred_username, which SignetMail uses to identify the person.
#4. Permissions
API permissions → Add a permission.
First, let the portal call the API:
- My APIs → SignetMail → Delegated →
access_as_user.
Then let the server read the directory:
- Microsoft Graph → Application permissions (not Delegated):
| Permission | Needed for |
|---|---|
User.Read.All |
Reading users and their attributes (name, title, department, phone, extension attributes). Required. |
Group.Read.All |
Listing groups so you can pick them in rules and campaigns. |
GroupMember.Read.All |
Reading group membership so group-based rules match the right people. |
Finally click Grant admin consent for <your tenant> and confirm that every row shows a green check mark.
Note. Without the two group permissions SignetMail still works for people and attribute-based rules. The portal shows a warning instead of the group list, and group-based rules and group-based roles have no effect.
#5. Certificate
- Certificates & secrets → Certificates → Upload certificate.
- Upload
certs/graph.cerproduced bysetup.shon the server (copy it to your computer, for example withscp). - Do not create a client secret. Certificate authentication is stronger and the private key never leaves the server.
The certificate is valid for 730 days. Put the expiry date in your calendar; renewal takes a few minutes.
#6. Roles from Entra groups (optional)
To grant portal roles to a security group instead of each person (Access and roles), the sign-in token must contain the user's groups:
- Token configuration → Add groups claim → Security groups.
- For the Access token choose Group ID.
- Prefer Groups assigned to the application so tokens stay small. When a user belongs to too many groups, Entra omits the list (the "groups overage" case) and the portal shows a warning; in that case only roles granted directly to the person apply.
#7. Restrict who can sign in (strongly recommended)
By default every user in your tenant could try to open the portal (they would then see "no access", but you should not rely on that).
- Entra ID → Enterprise applications → SignetMail → Properties → Assignment required? = Yes.
- Users and groups → Add user/group — assign only the people who administer signatures.
- Conditional Access: create a policy that requires MFA (and preferably compliant devices) for the SignetMail application.
#8. Apply the settings
- Make sure
ENTRA_TENANT_ID,ENTRA_CLIENT_IDandPORTAL_OWNERare set in.env. - Restart the API:
sudo docker compose up -d(orsudo docker compose restart signetmail-api). - Check
https://<host>/health—lastSyncUtcshould be recent. - Open
https://<host>/portal/and sign in as the owner.
#Hosted service (many customers on one server)
This section is for operators of a hosted SignetMail (one server, many customer organizations). Customers of a hosted service only click through the in-portal setup and need nothing from this page. For a normal single-organization install, skip it.
- In the app registration set Supported account types to Accounts in any organizational directory (multitenant).
- Set
SignetMail__MultiTenant=true,AzureAd__TenantId=organizationsandSignetMail__Portal__TenantId=organizations.SignetMail:Directory:Sourcemust beGraph. - Add this Web redirect URI (used after a customer's admin grants consent):
https://<your-host>/api/onboarding/consent-callback. - Complete publisher verification so customers' admins see a verified publisher instead of a warning on the consent screen.
How a customer joins: they open the portal and sign in with their Microsoft 365 account. The organization is recognised by its directory ID; if it is new, a registration screen creates it and makes the first person its Owner. The Owner then presses Grant admin consent and a Global Administrator approves read-only access to user profiles. Each customer's data, directory and license are fully separate.
#Common errors
| Message | Cause and fix |
|---|---|
| AADSTS50011 — reply URL does not match | The redirect URI https://<host>/portal/ is missing or has no trailing slash. Add it under Authentication → Single-page application. |
| Groups list shows Insufficient privileges | Group.Read.All / GroupMember.Read.All missing as Application permissions or admin consent not granted. Fix it, then restart signetmail-api. |
| "No access" after signing in | Your UPN is not PORTAL_OWNER and no role has been granted to you. Ask an Owner to add you under Access. |
Sign-in loop or AADSTS700016 |
ENTRA_CLIENT_ID or ENTRA_TENANT_ID in .env is wrong. |
| Add-in cannot sign in | brk-multihub://<host> or brk-9199bf20-a13f-4107-85dc-02114787ef48://<host> redirect URI missing (error AADSTS700046). |
More in Troubleshooting.