AD FS SSO Integration Guide

Active Directory Federation Services (AD FS) is a technology that extends your Active Directory configuration to services outside of your infrastructure. With AD FS, you can give users access to PagerDuty without them having to manage another set of credentials. This guide was written and tested on Windows Server 2012 R2 (also tested with Windows Server 2016), however earlier versions of Windows Server provide AD FS as well.    

On Your AD FS Server

1. Open the AD FS Management console, click Add Relying Party Trust... in the Actions pane and click Start on the wizard introduction page.
2. Select Enter data about the relying party manually and click Next.
3. Enter a Display name, such as PagerDuty, and click Next.
4. Select AD FS profile and click Next.
5. You will not need a token encryption certificate, so click Next to continue.
6. Log in to your PagerDuty account, click the User Icon menu, select Account Settings and then select the Single Sign-on tab.
7. Select the SAML radio button to configure Single Sign On in PagerDuty and then copy the SAML Endpoint URL to paste into the wizard.
8. Back on your AD FS server, check the box to Enable support for the SAML 2.0 WebSSO protocol, then paste the URL you copied in the Relying party SAML 2.0 SSO service URL box and click Next. (Please Note, if your PagerDuty Subdomain contains EU, it is necessary to enter the full PagerDuty Subdomain including the eu, for example: https://(your_subdomain).eu.pagerduty.com)
9. Enter your PagerDuty subdomain in the Relying party trust identifier field - including https:// and with no trailing slash and click Next.Note: It is very important to enter your PagerDuty subdomain exactly as described. The integration will not work if you do not include https:// here, nor if you include a slash at the end of the URL. (Please Note, if your PagerDuty Subdomain contains EU, it is necessary to enter the full PagerDuty Subdomain including the eu, for example: https://(your_subdomain).eu.pagerduty.com)
10. Select your desired multi-factor authentication option for users and click Next.Note: Enabling multi-factor authentication will require additional steps that are outside the scope of this guide and will not be covered.
11. Select Permit all users to access this relying party and click Next.Note: You may change this setting to deny by default and grant only specific users access to PagerDuty, however this process is outside the scope of this guide and will not be covered.
12. Review your settings and click Next.
13. Click Close to finish the wizard.
14. Click Add Rule... on the Issuance Transform Rules tab.
15. Select Send LDAP Attributes as Claims and click Next.
16. Enter a Claim rule name, such as Get Attributes, then set the Attribute store to Active Directory, type in E-Mail-Addresses for the first LDAP attribute and set its outgoing type to E-Mail Address, and type in Display-Name for the second LDAP attribute and set its outgoing type to Name. Click Finish when you are done.Note: Is it very important to select the options with the exact same dashes and spaces documented after you begin typing in the specified value. The integration may not work if you select a variant which does not match exactly.
17. Click Add Rule... on the Issuance Transform Rules tab again.
18. Select Transform an Incoming Claim and click Next.
19. Enter a Claim rule name, such as Name ID Transform, set Incoming claim type to E-Mail Address, set Outgoing claim type to Name ID, and set Outgoing name ID format to Email. Select Pass through all claim values and click Finish.Note: Is it very important to select the options with the exact same dashes and spaces documented after you begin typing in the specified value. The integration may not work if you select a variant which does not match exactly. For example, setting Outgoing claim type to NameID instead of Name ID will not allow you to set Outgoing name ID format to Email, and the integration will not work.
20. Click Add Rule... on the Issuance Transform Rules tab again.
21. Select Send Claims Using a Custom Rule and click Next.
22. Enter a Claim rule name, such as 'Name' Attribute Name Transform, then set Custom rule to the following:

    c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"]
     => issue(Type = "Name", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType);

    Click Finish when you are done.
23. Click OK on the Edit Claim Rules dialog.
24. Go to Service > Certificates, select your Token-signing certificate and click View Certificate... in the Actions pane.
25. Go to the Details tab and click Copy to File... and click Next on the Certificate Export Wizard introduction.
26. Select Base-64 encoded X.509 (.CER) and click Next.
27. Choose a location to save the certificate file, click Next and click Finish, OK, and OK again.
28. Go to Authentication Policies and click Edit under Primary Authentication Global Settings.
29. Under Intranet, check Forms Authentication and click OK.Note: This is required for Windows Server 2012 R2. Previous versions of Windows already have Forms Authentication enabled by default. Also note that enabling Forms Authentication will apply to all sites configured, not just PagerDuty.An alternative option is to set forms as a fall back authentication method for intranet using the following PowerShell command:

    Set-AdfsGlobalAuthenticationPolicy –PrimaryIntranetAuthenticationProvider @('WindowsAuthentication','FormsAuthentication')

    
30. Open the certificate file you exported in Notepad (or another plain text editor) and copy the contents.Note: You must include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- headers when copying the certificate file contents. You should use Notepad or another plain text editor to open the certificate file; WordPad, Word, etc. are not plain text editors and may prevent you from copying the certificate correctly.
31. In PagerDuty, paste the certificate in the X.509 Certificate field, then enter the Login URL for your AD FS service. The Login URL is usually the FQDN or IP or your server with /adfs/ls appended (i.e. https://login.company.com/adfs/ls).
32. When you complete the steps in this guide and are done testing, you can return to this page to disable user logins via username and password. With auto provisioning enabled, you can allow SSO users to create a PagerDuty account without manual intervention, however please keep in mind that adding additional users will affect your billing if you go over the number of users included in your pricing plan. Click Save Changes when you are done on this page.
33. Congratulations! You should now be able to login to PagerDuty using AD FS.

FAQ

Can the account owner log in without SSO if username and password authentication is disabled?

Even with this username and password authentication disabled for users, the Account Owner will always be able to login with their username and password as a backup option should you need to change the SSO configuration or disable it completely.

Why don't I see the Single Sign-on option when I go to Account Settings?

SSO is only available in accounts on our current Standard or Enterprise plans. Please contact our sales team if you are interested in upgrading your plan. How do I create a Custom Claim Rule to include user roles/job titles in my configuration? Follow the steps you used to create a Custom Claim Rule for 'Name' Attribute Name Transform, but set Claim Rule to the following:

c:[Type == "jobresponsibilities"]
 => issue(Type = "Role", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType);