Connect your identity provider

This guide is for the identity-provider administrator at your organization — the person who manages Microsoft Entra ID, Shibboleth/InCommon, Okta, or your SAML 2.0 stack. It walks through registering TheAccessible as a SAML 2.0 service provider (SP) and releasing the attributes we need.

The whole process is a metadata exchange plus attribute release. Budget about 30 minutes.

1. What TheAccessible gives you (our SP coordinates)

We will send you these when your organization is set up. Every URL contains your organization's short slug (shown here as <slug>):

Field	Value
SP Entity ID	https://api-pdf.theaccessible.org/api/sso/<slug>/metadata
ACS / Reply URL	https://api-pdf.theaccessible.org/api/sso/<slug>/acs
SP metadata	https://api-pdf.theaccessible.org/api/sso/<slug>/metadata
Binding	HTTP-POST (assertion), HTTP-Redirect (authn request)
NameID format	emailAddress
Signed authn requests	No
Encrypted assertions	Not supported
Single Logout (SLO)	Not supported

You can point your IdP straight at the SP metadata URL to import these automatically.

2. What we need from you

Please send your TheAccessible contact:

1. Your IdP metadata URL or XML file. This is the single most important item — it carries your entity ID, sign-in URL, and signing certificate.
2. Which IdP stack you run (Entra ID, Shibboleth, Okta, Google Workspace, or other). This tells us the attribute name format to expect.
3. The exact email domain(s) your assertions release in the email attribute (for example yourschool.edu, and any secondary domains like yourschool.tmc.edu). We only provision users on domains you confirm.
4. A technical contact we can reach when your signing certificate is due to rotate.

3. Attributes to release

We need one attribute for certain, and recommend two more:

Purpose	Required?	Notes
Email address	Required	Must be on one of your confirmed domains. If your NameID is the email address, this can double as the email.
Display name	Recommended	Populates the user's profile name.
Department / affiliation	Optional	Only if you want users grouped by unit in TheAccessible.

The attribute names differ by stack. Send us the names exactly as your IdP releases them:

Field	Shibboleth / InCommon (OID)	Microsoft Entra ID
Email	urn:oid:0.9.2342.19200300.100.1.3 (mail)	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Display name	urn:oid:2.16.840.1.113730.3.1.241	http://schemas.microsoft.com/identity/claims/displayname
Principal name	urn:oid:1.3.6.1.4.1.5923.1.1.1.6 (eduPersonPrincipalName)	.../claims/name
Department / affiliation	urn:oid:1.3.6.1.4.1.5923.1.1.1.1 (eduPersonAffiliation)	group claim

Watch the email domain. If you release a principal name like jdoe@sub.yourschool.edu in the email slot rather than a @yourschool.edu mail value, sign-in will be rejected unless that domain is on the confirmed list. Tell us every domain your mail attribute can contain.

4. Register TheAccessible in your IdP

Microsoft Entra ID

1. Entra admin center → Enterprise applications → New application → Create your own application → "Integrate any other application you don't find in the gallery."
2. Open the app → Single sign-on → SAML.
3. Basic SAML Configuration:
   • Identifier (Entity ID): https://api-pdf.theaccessible.org/api/sso/<slug>/metadata
   • Reply URL (ACS): https://api-pdf.theaccessible.org/api/sso/<slug>/acs
4. Attributes & Claims: ensure the email address claim is released; add display name if desired.
5. SAML Certificates: download the Federation Metadata XML (or copy the App Federation Metadata Url) and send it to us.
6. Assign the users/groups who should have access.

Shibboleth / InCommon

1. Import our SP metadata from https://api-pdf.theaccessible.org/api/sso/<slug>/metadata, or register the SP entity ID and ACS URL manually.
2. Add an attribute-filter policy releasing mail (required) and displayName (recommended) to our entity ID. Add eduPersonAffiliation only if you want department mapping.
3. If you are in InCommon, you may register us there — but sending your metadata directly is faster for a single SP.
4. Send us your IdP metadata URL.

Okta

1. Applications → Create App Integration → SAML 2.0.
2. Single sign-on URL (ACS): https://api-pdf.theaccessible.org/api/sso/<slug>/acs
3. Audience URI (SP Entity ID): https://api-pdf.theaccessible.org/api/sso/<slug>/metadata
4. Name ID format: EmailAddress. Add an email attribute statement.
5. From Sign On → View SAML setup instructions, send us the IdP metadata / sign-in URL / signing certificate.

5. Test and go live

Once you send us your metadata, we configure the connection on our side and arrange a short test window with you standing by. Have one test user ready. On a successful test we enable the connection and hand your organization a bookmarkable sign-in link.

6. Keep it healthy — certificate rotation

The most common cause of a broken SSO connection later is a rotated signing certificate. IdP signing certs typically expire on a 1–3 year cycle. When yours rotates, every sign-in fails at signature validation until we update the stored certificate.

Please notify your TheAccessible contact 60 days before any certificate roll or IdP migration, and we will update it with no downtime. There is no charge and no deploy required on our side.