Single sign-on · Setup guides
Microsoft AD FS
Connect an on-premises Microsoft Active Directory Federation Services (AD FS) server to OrbitID as a SAML identity provider. You need administrator access to the AD FS server.
Step 1: Create a claims-aware Relying Party Trust using federation metadata
In AD FS, a relying party (RP) trust needs to be set up. You can supply OrbitID's SP metadata URL and let AD FS pick up the configuration automatically.
- Federation metadata URL
- https://app.orbitid.com/.well-known/sp-metadata
- The OrbitID SP metadata URL. For Sandbox, copy it from your Sandbox Configuration page.
The public certificate is needed for signature verification. You can download the certificate from the following URL:
- Public certificate
- https://app.orbitid.com/.well-known/saml.cer
- The OrbitID public signing certificate.
In Server Manager, click Tools, and then select AD FS Management. Under Actions, click Add Relying Party Trust.
On the Welcome page, choose Claims aware and click Start.
On the Select Data Source page, click Import data about the relying party published online or on a local network.
In Federation metadata address (host name or URL), type the federation metadata URL above, and then click Next.
On the Specify Display Name page type a name in Display name, under Notes type a description for this relying party trust, and then click Next.
On the Choose Issuance Authorization Rules page, select either Permit all users to access this relying party or Deny all users access to this relying party, and then click Next.
On the Ready to Add Trust page, review the settings, and then click Next to save your relying party trust information.
On the Finish page, click Close. This action automatically displays the Edit Claim Rules dialog box.
Step 2: Attribute mapping
On the Configure Claim Rule screen, enter a Claim Rule Name of your choice, select Active Directory as the Attribute Store, then add the following mapping:
| LDAP Attribute | Outgoing Claim Type |
|---|---|
| E-Mail-Addresses | E-Mail Address |
| Given-Name | Given Name |
| Surname | Surname |
| User-Principal-Name | Name ID |
Step 3: Transform rule
Create a transform rule mapping the incoming E-Mail Address to the outgoing Name ID (of type Email). AD FS by default sends Name ID as Unspecified, which results in an InvalidNameIDPolicy error if this step is missed.
If you'd rather use the claim rule language, the following rule can be applied:
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
Finally open Windows PowerShell as an administrator, then run the following command so that both the response and the assertion are signed:
Set-ADFSRelyingPartyTrust -TargetName <display-name> -SamlResponseSignature "MessageAndAssertion"
Step 4: Copy the IdP metadata
AD FS publishes its metadata at https://<your-adfs-host>/FederationMetadata/2007-06/FederationMetadata.xml. Use that URL, or download the file, when you finish the connection in OrbitID.
Finish in OrbitID
Finish in OrbitID: paste the IdP metadata URL or XML into the connection form (or the Admin Portal link). In the dashboard, open the environment, go to Connections, click New connection, choose SAML and paste the metadata URL or the XML you downloaded. If your customer's admin is following an Admin Portal link, they paste it into the final step of the portal instead.
You can also create the connection with the API: POST /api/v1/sso as described in the quickstart.
