AD FS is a standards-based service, by Microsoft, that allows the secure sharing of identity information between trusted business partners. Oktopost supports single sign-on (SSO) logins through SAML 2.0. A SAML 2.0 identity provider (IDP) can take many forms, one of which is a self-hosted Active Directory Federation Services (AD FS) server.
To use AD FS to log in to Oktopost, you need the following components:
- An Active Directory instance where all users have an email address attribute.
- An Oktopost instance with single sign-on enabled.
- A server running Microsoft Server 2012 or 2008.
- An SSL certificate to sign your AD FS login page and the fingerprint for that certificate.
Adding a Relying Party Trust
The first step in setting the connection between AD FS and Oktopost is to add a new Relying Party Trust to AD FS.
Select the Relying Party Trusts folder from AD FS Management, and add a new Standard Relying Party Trust from the Actions sidebar. This starts the configuration wizard for a new trust.
On Select Data Source, select the last option: Enter Data About the Party Manually.
On the next screen, enter a Display name that you'll recognize in the future, and any notes you want to make.
On the next screen, select the AD FS profile radio button.
On the next screen, leave the default certificate settings and click Next.
On the next screen, check Enable Support for the SAML 2.0 WebSSO protocol. The service URL should be https://app.oktopost.com/auth/acs.
On the next screen, add https://app.oktopost.com as the Relying party trust identifier.
On the next screen, you may configure multi-factor authentication but this is beyond the scope of this article.
On the next screen, check the Permit all users to access this relying party radio button.
On the next two screens, the wizard will display an overview of your settings. On the final screen use the Close button to exit and open the Claim Rules editor.
Creating Claim Rules
Once the relying party trust has been set up, you need to create a default claim rule that maps your users' email addresses to the Name ID attribute.
To create a new rule, click on Add Rule.
Select Send LDAP Attributes as Claims as the Claim rule template.
On the next screen, select E-mail Address under the LDAP Attribute column, and Name ID under Outgoing Claim Type. Note that the LDAP Attribute value may differ depending on where the email addresses are stored in your AD FS instance.
Once you're done, click on OK to save the new rule. You should now have a working Relying Party Trust for Oktopost.
After setting up AD FS, you need to configure Oktopost to authenticate using SAML.
Go to App Settings → Single sign-on, and enable single sign-on. Then, enter the following information:
- SAML Endpoint, enter your full AD FS server URL: https://adfs.yourcompany.com/adfs/ls/.
- Issuer URL, enter your Replying Party Trust URL: http://adfs.yourcompany.com/adfs/services/trust
- X.509 Certificate, upload your AD FS certificate.
You should now have a working AD FS single sign-on implementation for Oktopost.