Set up a SAML 2.0 provider with AD FS

Active Directory Federation Services (AD FS) is one of the SAML 2.0 identity providers you can use to authenticate visitors to your Power Pages site. You can use any provider that conforms to the SAML 2.0 specification.

This article describes the following steps:

• Set up AD FS in Power Pages
• Create an AD FS relying party trust
• Finish setting up the provider

Important

The steps for setting up AD FS might vary depending on the version of your AD FS server.

Set up AD FS in Power Pages

Set AD FS as an identity provider for your site.

1. In your Power Pages site, select Security > Identity providers.

   If no identity providers appear, make sure External login is set to On in your site's general authentication settings.

2. Select + New provider.

3. Under Select login provider, select Other.

4. Under Protocol, select SAML 2.0.

5. Enter a name for the provider.

   The provider name is the text on the button that users see when they select their identity provider on the sign-in page.

6. Select Next.

7. Under Reply URL, select Copy.

   Don't close your Power Pages browser tab. You'll return to it soon.

Create an AD FS relying party trust

You can also use a PowerShell script to perform these steps.

1. In Server Manager, select Tools, and then select AD FS Management.

2. Expand Service.

3. In the right side panel, select Add Claim Description.

4. Enter the following values:

   • Display name: Persistent Identifier

   • Claim identifier: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

   • Select both Publish this claim description in federation metadata… options.

5. Select OK.

6. Select Trust Relationships > Relying Party Trusts.

7. Select Add Relying Party Trust.

8. Select Start.

9. Select Enter data about the relying party manually, and then select Next.

10. Enter a name; for example, https://portal.contoso.com/.

11. Select Next.

12. Select AD FS 2.0 profile, and then select Next.

13. On the Configure Certificate page, select Next.

14. Select Enable support for the SAML 2.0 WebSSO protocol.

15. Under Relying party SAML 2.0 SSO service URL, enter the reply URL you copied. AD FS requires that the website run HTTPS, not HTTP.

16. Select Next.

17. On the Configure Identifiers page, enter your site's URL, and then select Add.

    You can add more identities for each additional relying party website if needed. Users can authenticate using any available identities.

18. Select Next.

19. On the Configure Multi-factor Authentication Now? page, select I do not want to configure multi-factor authentication settings for this relying party trust at this time.

20. On the Choose Issuance Authorization Rules page, select Permit all users to access this relying party, and then select Next.

21. Review the trust settings, and then select Next.

22. Select Close.

23. In Edit Claim Rules, select one the following tabs, depending on the trust you're editing and in which rule set you want to create the rule:

    • Acceptance Transform Rules
    • Issuance Transform Rules
    • Issuance Authorization Rules
    • Delegation Authorization Rules

24. Select Add Rule.

25. In the Claim rule template list, select Transform an Incoming Claim, and then select Next.

26. Enter or select the following values:

    • Claim rule name: Transform Windows account name to Name ID

    • Incoming claim type: Windows account name

    • Outgoing claim type: Name ID

    • Outgoing name ID format: Persistent Identifier

27. Select Pass through all claim values.

28. Select Finish, and then select OK.

Finish setting up the provider

After you set up the AD FS relying party trust:

1. Create an app registration in Azure.

2. Enter site settings in Power Pages.

Identity provider–initiated sign-in

AD FS supports the identity provider–initiated single sign-on (SSO) profile of the SAML 2.0 specification. For the service provider website to respond properly to the identity provider's SAML request, you must encode the RelayState parameter.

The basic string value to encode in the SAML RelayState parameter must be in the format ReturnUrl=/content/sub-content/, where /content/sub-content/ is the path to the page you want to go to on the service provider website. You can specify the path to any valid page on the website. The string value is encoded and placed in a container string of the format RPID=<URL encoded RPID>&RelayState=<URL encoded RelayState>. This entire string is once again encoded and added to another container of the format <https://adfs.contoso.com/adfs/ls/idpinitiatedsignon.aspx?RelayState=&lt;URL> encoded RPID/RelayState&gt;.

For example, given the service provider path /content/sub-content/ and the relying party ID https://portal.contoso.com/, follow these steps to construct the URL:

• Encode the value ReturnUrl=/content/sub-content/ to get ReturnUrl%3D%2Fcontent%2Fsub-content%2F

• Encode the value https://portal.contoso.com/ to get https%3A%2F%2Fportal.contoso.com%2F

• Encode the value RPID=https%3A%2F%2Fportal.contoso.com%2F&RelayState=ReturnUrl%3D%2Fcontent%2Fsub-content%2F to get RPID%3Dhttps%253A%252F%252Fportal.contoso.com%252F%26RelayState%3DReturnUrl%253D%252Fcontent%252Fsub-content%252F

• Prepend the AD FS identity provider–initiated SSO path to get the final URL https://adfs.contoso.com/adfs/ls/idpinitiatedsignon.aspx?RelayState=RPID%3Dhttps%253A%252F%252Fportal.contoso.com%252F%26RelayState%3DReturnUrl%253D%252Fcontent%252Fsub-content%252F

You can use the following PowerShell script to construct the URL. Save the script to a file named Get-IdPInitiatedUrl.ps1.

<#
.SYNOPSIS 
Constructs an IdP-initiated SSO URL to access a website page on the service provider.
.PARAMETER path
The path to the website page.
.PARAMETER rpid
The relying party identifier.
.PARAMETER adfsPath
The AD FS IdP initiated SSO page.
.EXAMPLE
PS C:\\> .\\Get-IdPInitiatedUrl.ps1 -path "/content/sub-content/" -rpid "https://portal.contoso.com/" -adfsPath "https://adfs.contoso.com/adfs/ls/idpinitiatedsignon.aspx"
#>
param
(
[parameter(mandatory=$true,position=0)]
$path,
[parameter(mandatory=$true,position=1)]
$rpid,
[parameter(position=2)]
$adfsPath = https://adfs.contoso.com/adfs/ls/idpinitiatedsignon.aspx
)
$state = ReturnUrl=$path
$encodedPath = [uri]::EscapeDataString($state)
$encodedRpid = [uri]::EscapeDataString($rpid)
$encodedPathRpid = [uri]::EscapeDataString("RPID=$encodedRpid&RelayState=$encodedPath")
$idpInitiatedUrl = {0}?RelayState={1} -f $adfsPath, $encodedPathRpid
Write-Output $idpInitiatedUrl

Configure AD FS using PowerShell

Instead of adding a relying party trust in AD FS manually, you can run the following PowerShell script on the AD FS server. Save the script to a file named Add-AdxPortalRelyingPartyTrustForSaml.ps1. After the script executes, continue to configure the site settings in Power Pages.

<# 
.SYNOPSIS
Adds a SAML 2.0 relying party trust entry for a website.
.PARAMETER domain
The domain name of the website.
.EXAMPLE
PS C:\\> .\\Add-AdxPortalRelyingPartyTrustForSaml.ps1 -domain portal.contoso.com
#>
param
(
[parameter(Mandatory=$true,Position=0)]
$domain,
[parameter(Position=1)]
$callbackPath = /signin-saml2
)
$VerbosePreference = Continue
$ErrorActionPreference = Stop
Import-Module adfs
Function Add-CrmRelyingPartyTrust
{
param (
[parameter(Mandatory=$true,Position=0)]
$name
)
$identifier = https://{0}/ -f $name
$samlEndpoint = New-ADFSSamlEndpoint -Binding POST -Protocol SAMLAssertionConsumer -Uri (https://{0}{1} -f $name, $callbackPath)
$identityProviderValue = Get-ADFSProperties | % { $_.Identifier.AbsoluteUri }
$issuanceTransformRules = @'
@RuleTemplate = MapClaims
@RuleName = Transform [!INCLUDE[pn-ms-windows-short](../../../includes/pn-ms-windows-short.md)] Account Name to Name ID claim
c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> issue(Type = "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["https://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent");
@RuleTemplate = LdapClaims
@RuleName = Send LDAP Claims
c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "[!INCLUDE[pn-active-directory](../../../includes/pn-active-directory.md)]", types = ("https://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"), query = ";givenName,sn,mail;{{0}}", param = c.Value);
'@ -f $identityProviderValue
$issuanceAuthorizationRules = @'
@RuleTemplate = AllowAllAuthzRule
=> issue(Type = https://schemas.microsoft.com/authorization/claims/permit, Value = true);
'@
Add-ADFSRelyingPartyTrust -Name $name -Identifier $identifier -SamlEndpoint $samlEndpoint -IssuanceTransformRules $issuanceTransformRules -IssuanceAuthorizationRules $issuanceAuthorizationRules
}
# add the 'Identity Provider' claim description if it is missing
[!INCLUDE[cc-pages-ga-banner](../../../includes/cc-pages-ga-banner.md)]
if (-not (Get-ADFSClaimDescription | ? { $_.Name -eq Persistent Identifier })) {
Add-ADFSClaimDescription -name "Persistent Identifier" -ClaimType "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" -IsOffered:$true -IsAccepted:$true
}
# add the website relying party trust
[!INCLUDE[cc-pages-ga-banner](../../../includes/cc-pages-ga-banner.md)]
Add-CrmRelyingPartyTrust $domain

See also

Set up a SAML 2.0 provider
Set up a SAML 2.0 provider with Microsoft Entra ID
SAML 2.0 FAQ