Overview
Register the eAdm service-provider metadata on the identity provider, then issue the claim mapped in eAdm and exactly one NameID.
Download that metadata from Single Sign-On on the customer, as described on the parent page. Each customer has its own service-provider metadata. A shared identity provider needs one registration for each eAdm customer.
Example: Fableton Municipality, org NO999000001. The login button is Fableton AD FS. The test user's UPN in both directories is teacher@fableton.example.
Before you begin
You need:
-
The eAdm service-provider metadata for this customer, from Single Sign-On.
-
An administrator of the identity provider.
-
The claim URI mapped on the provider in eAdm. The parent page describes UPN, email, and national ID.
1. Export the identity provider metadata
Export the public SAML metadata. It should contain the entity ID, the sign-in URL, the logout URL, and the public signing certificates. Give eAdm that file, or a public HTTPS URL, in the wizard on the parent page. Do not send a private key or a PFX.
AD FS
The metadata URL is:
https://<your-adfs-host>/FederationMetadata/2007-06/FederationMetadata.xml
Open it and save the XML. An internal AD FS host, or one reached on a private address, stays a file upload.
2. Register eAdm
Import the eAdm service-provider metadata. That registers:
-
The entity ID for this customer.
-
The assertion consumer URL (HTTP POST).
-
The single logout URL (HTTP POST and HTTP-Redirect).
-
The public certificate eAdm uses to sign requests.
Do not configure that certificate for encryption. eAdm does not decrypt assertions. Sign assertions with SHA-256.
If the eAdm host changes, download the metadata again from Single Sign-On and update the trust. The consumer URL and the logout URL must match the file.
AD FS
-
Open AD FS Management.
-
Go to Relying Party Trusts.
-
Select Add Relying Party Trust.
-
Choose Claims aware.
-
Import the eAdm service-provider metadata file.
-
Enter a display name such as eAdm — Fableton.
-
Select an access-control policy that allows only the users or groups who should sign in to eAdm.
-
Finish the wizard.
On the relying party properties, confirm:
|
Tab |
What to check |
|---|---|
|
Identifiers |
The entity ID from the imported metadata |
|
Endpoints |
A SAML assertion consumer endpoint, HTTP POST |
|
Endpoints |
The eAdm SAML logout endpoint |
|
Signature |
The current eAdm request-signing certificate |
|
Encryption |
Empty |
|
Advanced |
SHA-256 |
Two eAdm customers on the same AD FS farm are two relying party trusts. AD FS allows one trust per entity ID.
3. Issue the mapped claim and one NameID
Release the claim mapped in eAdm.
Single logout also needs exactly one NameID on the assertion, plus a session index. The NameID does not have to be the claim eAdm uses to find the user. More than one NameID can make the assertion fail or can break logout.
Sign in again after you add or change the NameID rule. Existing sessions do not gain a NameID afterwards. The admin Test on Single Sign-On reports failure until logout can complete, even when the user was found.
AD FS
Open the relying party and select Edit Claim Issuance Policy.
Two rules are required, in this order:
-
An LDAP rule that reads the login identifier from Active Directory.
-
A transformation rule that issues one SAML NameID.
AD FS sends only the claims these rules issue.
UPN. Add Send LDAP Attributes as Claims:
-
Rule name: Issue UPN from Active Directory
-
Attribute store: Active Directory
-
LDAP attribute: User-Principal-Name
-
Outgoing claim type: UPN
In eAdm, map the UPN claim URI to UPN.
Email. Add Send LDAP Attributes as Claims:
-
Rule name: Issue email and UPN from Active Directory
-
Attribute store: Active Directory
-
LDAP attribute: E-Mail-Addresses → outgoing claim type E-Mail Address
-
LDAP attribute: User-Principal-Name → outgoing claim type UPN
In eAdm, map the email claim URI to email. UPN is still issued so it can be the NameID.
National ID. Only when the value is stored in Active Directory and the customer may release it.
-
Rule name: Issue national ID and UPN from Active Directory
-
Attribute store: Active Directory
-
LDAP attribute: the attribute that holds the national ID → your custom claim URI
-
LDAP attribute: User-Principal-Name → outgoing claim type UPN
In eAdm, map that custom URI to national ID.
NameID. After the LDAP rule, add Transform an Incoming Claim:
-
Rule name: Transform UPN to NameID
-
Incoming claim type: UPN
-
Outgoing claim type: Name ID
-
Outgoing Name ID format: Unspecified
-
Pass through all claim values
If UPN is not stable, use the same rule with incoming claim type E-Mail Address.
Keep the national ID out of NameID. Use it only as the mapped identifier, and only when you need it.
4. Prove sign-in and sign-out
Run Test on Single Sign-On, then sign in from the eAdm login page, as described on the parent page. Start there. A sign-in started on the identity provider's own sign-on page is rejected.
AD FS
The AD FS form accepts the user's UPN or DOMAIN\username. The mail attribute is a sign-in name only when that value is the user logon name.
For logout started in AD FS, the IdP-initiated sign-on page has to be available:
-
Sign in to eAdm through AD FS.
-
In the same browser, open
https://<your-adfs-host>/adfs/ls/idpinitiatedsignon.aspx. -
Choose Sign out from all the sites that you have accessed.
An AD FS administrator can enable that page with:
Set-AdfsProperties -EnableIdPInitiatedSignonPage $true
/adfs/ls/?wa=wsignout1.0 is a WS-Federation sign-out. It clears the AD FS session and does not send a SAML logout request to eAdm.
Troubleshooting
eAdm symptoms, such as a rejected metadata URL, a missing user, or an encrypted assertion, are on the parent page.
|
Symptom |
Likely cause |
Action |
|---|---|---|
|
AD FS reports MSIS3200 |
The assertion consumer URL is not on the relying party |
Import the current eAdm metadata and confirm the SAML POST consumer endpoint. |
|
AD FS signs the user in, eAdm cannot find them |
The issuance rule does not send the mapped claim, or the value differs from the eAdm user |
Compare the outgoing claim with the mapping on Single Sign-On. |
|
The admin test fails after a good AD FS sign-in |
No NameID rule, or the relying party has no eAdm logout endpoint |
Add the NameID rule and the logout endpoint. Sign in again, then retest. |
|
Signing out of AD FS does not call eAdm |
|
Use Sign out from all the sites that you have accessed. |
|
A second eAdm customer cannot be added on the same AD FS farm |
The new trust reuses the first customer's entity ID |
Download that customer's own service-provider metadata and create a separate relying party trust. |
Certificate changes
When eAdm shows a request-signing certificate rollover on Single Sign-On, download the current metadata and update the identity provider before eAdm signs with the new certificate. How eAdm refreshes the identity provider's certificates is on the parent page.
AD FS
AD FS metadata can list more than one public token-signing certificate during a rollover. With a file:
-
Download fresh AD FS metadata before the old token-signing certificate expires.
-
Upload it to the same provider in eAdm.
-
Sign in and sign out once.
On the relying party, replace the eAdm signature certificate when eAdm rolls its own key. Leave Encryption empty.
Go-live checklist
-
This customer's service-provider metadata is imported as its own trust
-
Assertion consumer is HTTP POST, and the logout endpoint is present
-
Encryption certificate list is empty, and the signature algorithm is SHA-256
-
The mapped claim is issued
-
Exactly one NameID is issued, on a new sign-in
-
Access at the identity provider is limited to the people who should open eAdm
-
Admin test on Single Sign-On succeeds
-
Sign-out from the identity provider is a SAML logout of relying parties, and the eAdm session ends
Fableton Municipality (org NO999000001) is fictional.