Active Directory Federation Services + Relyra

Tested against: Microsoft Learn AD FS Windows Server 2025 docs verified on May 26, 2026

This is the authoritative Day-1 runbook for the :adfs preset. Use it when the IdP requires signed AuthnRequests or when you need the ADFS lowercase percent-encoding interop path.

Overview

The ADFS preset turns on the strict settings this path needs:

• sign_authn_requests: true
• signed_request_encoding: :adfs_lower
• require_signed_assertions?: true
• require_signed_response?: true
• algorithm_policy.signing: :rsa_sha256

ADFS often rejects unsigned AuthnRequests once the relying-party trust is configured to require them, so keep the preset defaults unless you are deliberately debugging an integration problem.

SP-side config

Configure the SP signing key in application config and use the preset when building the connection:

config :relyra,
  sp_signing_key_pem: File.read!("priv/certs/sp-signing-key.pem")

connection =
  Relyra.Provider.apply_defaults(:adfs, [
    sp_entity_id: "https://sp.example.com/metadata",
    acs_url: "https://sp.example.com/saml/acs",
    idp_sso_url: "https://adfs.example.com/adfs/ls/",
    idp_certificates: ["-----BEGIN CERTIFICATE-----..."]
  ])

Operator-owned values:

• sp_entity_id: ADFS calls this the relying party trust identifier.
• acs_url: ADFS uses this for the SAML assertion consumer endpoint.
• idp_sso_url: usually https://<adfs-host>/adfs/ls/.
• idp_certificates: load the active token-signing certificate.

ADFS-side PowerShell

Use the relying-party trust cmdlet parameters verified from Microsoft Learn on May 26, 2026: -SignedSamlRequestsRequired, -RequestSigningCertificate, -SignatureAlgorithm, and -SamlResponseSignature.

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2 "C:\path\to\sp-signing.cer"

Set-AdfsRelyingPartyTrust `
  -TargetName "Relyra App" `
  -SignedSamlRequestsRequired $true `
  -RequestSigningCertificate @($cert) `
  -SignatureAlgorithm "https://www.w3.org/2001/04/xmldsig-more#rsa-sha256" `
  -SamlResponseSignature "MessageAndAssertion"

Important naming mismatch:

• SAML metadata advertises AuthnRequestsSigned="true".
• PowerShell uses -SignedSamlRequestsRequired $true.

These represent the same trust expectation from opposite sides.

Claim rules

Minimum claim set to start with:

• Name ID
• Email address
• Given name
• Surname
• Display name

Keep the anchor stable. If you change the NameID format or source later, your application may see a different local identifier for the same user.

Interop notes

• ADFS can be sensitive to percent-encoded hex casing in redirect queries. The :adfs preset sets signed_request_encoding: :adfs_lower for this reason.
• Relyra signs outbound redirect queries with RSA-SHA256. Do not downgrade to SHA-1.
• -SignatureAlgorithm governs what ADFS expects for the outbound AuthnRequest signature. It is independent from how Relyra verifies inbound response signatures.
• The redirect signature covers the raw query octets before &Signature= is appended. Any re-encoding step between the SP core and the browser breaks the signature.

Troubleshooting

Provenance

Microsoft Learn sources verified on May 26, 2026:

• Set-AdfsRelyingPartyTrust (Windows Server 2025) for parameter names and accepted -SignatureAlgorithm values.
• Create a Non-Claims Aware Relying Party Trust for the relying-party trust creation path.