Connect Microsoft ADFS to PE

Connect to Microsoft Active Directory Federation Services (ADFS) on a Windows server, enabling users to log in to PE using their ADFS credentials.

Note: This setup was tested using Windows Server 2019.
To connect ADFS to PE, add PE certificates to ADFS and configure SSO for ADFS in the PE console. Then, add PE as a relying trust party in ADFS, configure rules and groups, and add RBAC permissions for ADFS users.
  1. Add PE certificates to the ADFS server
  2. Connect to ADFS in the PE console
  3. Add the Relying Party Trust for PE to ADFS
  4. Disable certificate revocation checking
  5. Configure the Claim Issuance Policy in ADFS
  6. Configure an RBAC group and role in PE
  7. Test your SSO connection

Add PE certificates to the ADFS server

To ensure ADFS trusts the certificates PE uses to sign requests, add the Puppet CA certificates to the Trusted Root CA store on the ADFS server. There can be one or two certificates to import, depending on which version of PE you upgraded from.

  1. On your primary server, retrieve the certificates: 
    cat /etc/puppetlabs/puppet/ssl/certs/ca.pem
  2. Depending on how many certificates appear, do one of the following:
    • One certificate – copy the certificate text and paste it into a .cer file on your ADFS server. Then, import the certificate into the Trusted Root Certification Authorities store.
    • Two certificates – export the certificates with this command: 
      openssl pkcs12 -export -nokeys -in /etc/puppetlabs/puppet/ssl/certs/ca.pem -out ~/ca.pfx -passout pass

      Copy the resulting ca.pfx file to your ADFS server, then import it into the Trusted Root Certification Authorities store. The file has no password. The two certificates appear after importing the file.

Connect to ADFS in the PE console

Use the PE console to connect ADFS.

  1. In the console, on the Access control page, click the SSO tab.
  2. Click Configure.
  3. Input the configuration information as described in the ADFS configuration reference. Make sure to complete the Organization and Contacts sections.
  4. Commit changes.

ADFS configuration reference

Configure ADFS in the PE console with these settings and values.

ADFS configuration values

In the PE console, configure these values in the Identity provider information and Service provider configuration options sections of the SSO configuration page.
Setting Maps to ADFS configuration value
Display name display_name Example: "ADFS"
Identity provider entity ID idp_entity_id

An HTTP or HTTPS URL indicating the ADFS Identifier.

To find your URL, in the ADFS Microsoft Management Console, click Edit Federation Service Properties.

Example: "http://<federation service name>/adfs/services/trust"
Identity provider SSO URL idp_sso_url The ADFS Single Sign On URL.

To find your SSO URL, in the ADFS Microsoft Management Console, navigate to ADFS > Service > Endpoints. Under Token Issuance, in the Type column, click the endpoint that specifies SAML 2.0/WS-Federation.

Example: "https://<federation service name >/adfs/ls/"
Identity provider SLO URL idp_slo_url The ADFS Single Sign On URL with ?wa=wsignout1.0 added to the end.

Example: "https://<federation service name>/adfs/ls/?wa=wsignout1.0"
Identity provider SLO response URL idp_slo_response_url The same as the ADFS SLO URL.

Example: "https://<federation service name>/adfs/ls/?wa=wsignout1.0"
IdP certificate idp_certificate The ADFS Token Signing certificate.
To get the certificate, run this PowerShell script on your ADFS server:
$cert = Get-AdfsCertificate -CertificateType Token-Signing | ? IsPrimary -eq $true
$oPem = New-Object System.Text.StringBuilder
$oPem.AppendLine("-----BEGIN CERTIFICATE-----")
$oPem.AppendLine([System.Convert]::ToBase64String($cert.Certificate.RawData,1))
$oPem.AppendLine("-----END CERTIFICATE-----")
$oPem.ToString() | out-file ./adfs_token_signing.pem
Example: 
-----BEGIN CERTIFICATE-----
MIIGADCCA+igAwIBAgIBAjANBgkqhki
...
STkGww==
-----END CERTIFICATE-----
Name ID encrypted? name_id_encrypted true
Sign authentication requests? authn_request_signed true
Sign logout response? logout_response_signed true
Sign logout requests? logout_request_signed true
Require signed messages? want_messages_signed false
Require signed assertions? want_assertions_signed true
Sign metadata? sign_metadata true
Require encrypted assertions? want_assertions_encrypted true
Require name ID encrypted? want_name_id_encrypted true
Requested authentication context requested_auth_context urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
Requested authentication context comparison requested_auth_context_comparison exact
Allow duplicated attribute name? allow_duplicated_attribute_name false
Validate xml? want_xml_validation true
Signature algorithm signature_algorithm rsa-sha256

Attribute binding values for ADFS

In the PE console, add these values in the Attribute binding section of the SSO configuration page.
Attribute binding value ADFS value
User http://schemas.xmlsoap.org/claims/CommonName
Email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Display name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Groups http://schemas.xmlsoap.org/claims/Group

Add the Relying Party Trust for PE to ADFS

Add PE to ADFS as a Relying Party Trust using a metadata address, allowing ADFS to recognize and communicate with PE as the service provider. Use the PE console to retrieve the metadata URL, then add it to ADFS using the ADFS Management console.

  1. In the PE console, on the Access Control page, click the SSO tab, click Show configuration information, and copy the SAML Metadata URL.
  2. In the ADFS Management console, click Relying Party Trusts > Add Relying Trust Party > Claims aware.
  3. When the wizard opens, click Start.
  4. Select Import data about relying party published online or on a local network and enter the SAML Metadata URL, then click Next.
  5. Enter a Display name for your PE server, taking note of the name to refer to later, then click Next.
  6. Accept the defaults for the Access Control Policy and click Next.
  7. On the Ready to Add Trust page, click Next.
  8. On the Finish page, uncheck Configure claims issuance policy for this application and click Close.

Disable certificate revocation checking

ADFS can't look up the certificate revocation status because certificates from PE don't include CRL information. Use PowerShell to disable certificate revocation checking so ADFS doesn't perform certificate revocation checks on the relying party trust, resulting in trust failures.

  1. In PowerShell, display the names for all relying party trusts: 
    Get-AdfsRelyingPartyTrust | ft Name
  2. Find the trust with the display name you selected for your PE server.
  3. Determine the status of the revocation check for the PE trust: 
    Get-AdfsRelyingPartyTrust -Name <DISPLAY NAME> | ft EncryptionCertificateRevocationCheck, SigningCertificateRevocationCheck
  4. If the encryption and signing certificate revocation checks show anything other than None, disable checking: 
    Get-AdfsRelyingPartyTrust -Name <DISPLAY NAME> | Set-AdfsRelyingPartyTrust -SigningCertificateRevocationCheck None -EncryptionCertificateRevocationCheck None

Configure the Claim Issuance Policy in ADFS

Add rules to the Claims Issuance Policy so it can send the correct LDAP attribute and user group information to PE.

Tip: In ADFS, a claim is the same thing as an assertion, and the Claims Issuance Policy defines what pieces of information about a user go where in a claim.
  1. In the ADFS Management console, click Relying Party Trusts.
  2. Select the PE trust you created and click Edit Claim Issuance Policy.
  3. Add a rule to send LDAP attributes as claims:
    • Claim rule template: Send LDAP Attributes as Claims
    • Claim rule name: LDAP Attributes
    • Attribute store: Active Directory LDAP attribute mappings
    In the LDAP attribute mapping table, select these options from the drop down:
    • SAM-Account-Name: Common Name
    • Display-Name: Name
    • E-Mail-Addresses: E-mail Address
    • SAM-Account-Name: Name ID
  4. Add a rule to send group membership as a claim:
    • Claim rule template: Send Group Membership as a Claim
    • Claim rule name: Group membership- <GROUP NAME>
    • User's group: <DOMAIN NAME>\<GROUP NAME>
    • Outgoing claim type: Group
    • Outgoing claim value: <GROUP NAME>
  5. Add additional rules for passing group membership of other ADFS user groups at your organization.

Configure an RBAC group and role in PE

In the PE console, configure RBAC to grant permissions to new ADFS user groups.

  1. In the console, on the Access control page, click the User groups tab.
  2. In the Login field, enter the name of the ADFS user group and click Add Group.
    Tip: This is the same <GROUP NAME> you added when configuring group membership rules.
  3. Click the User roles tab, then click the role you want to add the group to. For example, Viewers.
  4. Click the Member groups tab and, in the drop-down list, select your ADFS user group.
  5. Click Add group and commit the change.
  6. Add additional ADFS user groups at your organization to RBAC roles.

Test your SSO connection

Ensure your connection between PE and ADFS works by logging out and logging back in.

  1. Log out of PE.
  2. On the login screen, click Sign in with ADFS.
  3. Log in to PE using your ADFS credentials.
    After logging back in, your permissions match what is assigned to your ADFS group.