By David,
Every signature horror story is a copy problem. Someone typed their title into their signature in 2024; the org chart moved on; the signature didn't. Multiply by every employee and every attribute - phone numbers, departments, office addresses - and you get the familiar zoo: hundreds of hand-maintained copies of facts the directory already knows.
Tokens are the fix, and they're simple enough to explain in a sentence: a template contains placeholders instead of facts, and the facts are fetched from Microsoft Entra ID for each user at the moment the signature is applied. This article is the practical mechanics - what hydrates from where, what breaks it, and the edge cases worth designing for.
How hydration actually works
In Atlas Ink, a template is one HTML document with merge tokens where the per-person data goes - display name, job title, department, email, mobile, company, office location. At push time, for each user in scope, Atlas reads that user's profile from Entra ID via Microsoft Graph - read-only, in place, from a service running in your own Azure subscription - substitutes the values, and writes the finished signature into the user's mailbox as their Outlook compose signature.
Three properties fall out of that design:
Signatures can't go stale - they re-resolve. The token isn't evaluated once at rollout; it hydrates on every push, and the daily reconcile keeps managed signatures re-applied. A promotion recorded in Entra today is in the signature by tomorrow without anyone touching a template.
There's exactly one place to fix bad data. When a signature shows the wrong phone number, the bug is in the directory - fix it there and every downstream consumer (signature included) heals. No parallel signature database drifts out of sync with Entra, because no parallel database exists; the directory isn't copied anywhere to be rendered from. (That's also the data-residency answer: nothing about your people rests outside your tenant.)
Templates become genuinely reusable. One tenant-wide template serves four hundred people; group variants exist for genuinely different blocks (sales booking links, legal disclaimers), not for per-person data. The governance piece on scoping and precedence covers how assignment layers on top.
The attributes that matter, and their failure modes
The workhorse Entra attributes for signatures, with the way each one goes wrong:
| Attribute | Feeds | Classic failure |
|---|---|---|
| displayName | The name line | Legal name vs preferred name policy never decided |
| jobTitle | Title line | Stale after promotions; free-text chaos ("Sr. Dev" vs "Senior Developer") |
| department | Team line | Reorg renames not propagated |
| telephoneNumber / mobilePhone | Contact lines | Empty for half the org; formats inconsistent |
| physicalDeliveryOfficeLocation | Office line | Site moves recorded in a spreadsheet, not Entra |
| companyName | Entity line | Wrong or blank after acquisitions - a real problem in multi-entity tenants |
The pattern across every row: the token mechanism is only as good as directory hygiene, which is why every serious rollout starts with an attribute audit and ends with HR changes wired into the joiner-mover-leaver process. It's also why the effort pays beyond signatures - Teams cards, the global address list, and every directory-driven system improve together. Our best-practices field guide ranks this the #1 practice for a reason.
Designing for the blanks
Real directories have holes, and a template that renders "Mobile: " followed by nothing looks worse than no line at all. Handle blanks deliberately:
- Make empty-attribute behavior explicit - a missing mobile number should drop its whole line (label included), not print an orphaned label.
- Decide the placeholder policy up front. For attributes that should exist (title, department), an obviously-wrong render in the pilot group is a feature - it surfaces directory gaps while the audience is friendly - whereas silently omitting them hides the debt.
- Watch the exotic mailboxes. Shared mailboxes, service accounts, and resource mailboxes have thin profiles by nature; scope them out of managed assignment, or give them a minimal template that doesn't depend on person-attributes.
Why hydrate at push rather than in transit
Transport-rule and stamping architectures do attribute substitution too - Exchange can inject AD attributes into a disclaimer as mail flows through. The difference is where and when: in-transit substitution happens per message, in the pipeline, with the rendering and reply-chain limitations that whole architecture carries, and the sender never sees the result. Push-time hydration produces a finished, native signature sitting in the user's mailbox - visible while composing, rendering like any client signature, with no per-message machinery. Same directory, better moment.
Directory-driven is what makes managed signatures stay managed: fix the data once, template once, and let hydration do the copying forever. If your directory is roughly right - or you're ready to make it right - the rest is a push.