A single AD FS server can be added (or another WS-Federation compliant security token service, STS) as an identity provider. In addition, a single Azure ACS namespace can be configured as a set of individual identity providers. The settings for both AD FS and ACS are based on the properties of the WsFederationAuthenticationOptions class.

AD FS (STS)

Settings for a single STS such as AD FS.

Create an AD FS Relying Party Trust

See the section below Configure AD FS with PowerShell on how to perform these steps in a PowerShell script.

Using the AD FS Management tool, select Trust Relationships > Relying Party Trusts.

  • Click Add Relying Party Trust
  • Welcome: Click Start
  • Select Data Source: Select Enter data about the relying party manually, click Next
  • Specify Display Name: Enter a name, click Next
    • Example: https://portal.contoso.com/
  • Choose Profile: Select AD FS 2.0 profile, click Next
  • Configure Certificate: Click Next
  • Configure URL: Check Enable support for the WS-Federation Passive protocol
    • Relying party WS-Federation Passive protocol URL: Enter https://portal.contoso.com/signin-federation
    • Note: AD FS requires that the portal run on HTTPS
    • The resulting endpoint has the following settings:
      • Endpoint type: WS-Federation
      • Binding: POST
      • Index: n/a (0)
      • URLhttps://portal.contoso.com/signin-federation
  • Configure Identities: Specify https://portal.contoso.com/, click Add, click Next
    • If applicable, more identities can be added for each additional relying party portal. Users will be able to authenticate across any/all of the available identities.
  • Choose Issuance Authorization Rules: Select Permit all users to access this relying party, click Next
  • Ready to Add Trust: Click Next
  • Click Close

Add the Name ID claim to the relying party trust:

  • Transform Windows account name to Name ID claim (Transform an Incoming Claim):
    • Incoming claim type: Windows account name
    • Outgoing claim type: Name ID
    • Outgoing name ID format: Unspecified
    • Pass through all claim values

Create Site Settings

Apply portal site settings referencing the above AD FS Relying Party Trust.

A standard AD FS (STS) configuration only uses the following settings (with example values):

  • Authentication/WsFederation/ADFS/MetadataAddress - https://adfs.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml
  • Authentication/WsFederation/ADFS/AuthenticationType - http://adfs.contoso.com/adfs/services/trust
    • Use the value of the entityID attribute in the root element of the Federation Metadata (open the MetadataAddress URL in a browser that is the value of the above site setting)
  • Authentication/WsFederation/ADFS/Wtrealm - https://portal.contoso.com/
  • Authentication/WsFederation/ADFS/Wreply - https://portal.contoso.com/signin-federation

The WS-Federation metadata can be retrieved in PowerShell by running the following script on the AD FS server:

Import-Module adfs
Get-ADFSEndpoint -AddressPath /FederationMetadata/2007-06/FederationMetadata.xml
Site Setting Name Description
Authentication/Registration/ExternalLoginEnabled

Enables or disables external account sign-in and registration. Default:true

Authentication/WsFederation/ADFS/MetadataAddress Required. The WS-Federation metadata URL of the AD FS (STS) server. Commonly ending with the path:/FederationMetadata/2007-06/FederationMetadata.xml . Example:https://adfs.contoso.com/FederationMetadata/2007-06/FederationMetadata.xmlMSDN.
Authentication/WsFederation/ADFS/AuthenticationType Required. The OWIN authentication middleware type. Specify the value of the entityID attribute at the root of the federation metadata XML. Example:http://adfs.contoso.com/adfs/services/trust.  MSDN.
Authentication/WsFederation/ADFS/Wtrealm Required. The AD FS relying party identifier. Example:https://portal.contoso.com/. MSDN.
Authentication/WsFederation/ADFS/Wreply Required. The AD FS WS-Federation passive endpoint. Example:https://portal.contoso.com/signin-federation.  MSDN.
Authentication/WsFederation/ADFS/Caption Recommended. The text that the user can display on a sign in user interface. Default: ADFSMSDN.
Authentication/WsFederation/ADFS/CallbackPath An optional constrained path on which to process the authentication callback. MSDN.
Authentication/WsFederation/ADFS/SignOutWreply The 'wreply' value used during sign-out. MSDN.
Authentication/WsFederation/ADFS/BackchannelTimeout Timeout value for back channel communications. Example: 00:05:00 (5 mins). MSDN.
Authentication/WsFederation/ADFS/RefreshOnIssuerKeyNotFound Determines if a metadata refresh should be attempted after a SecurityTokenSignatureKeyNotFoundException. MSDN.
Authentication/WsFederation/ADFS/UseTokenLifetime Indicates that the authentication session lifetime (e.g. cookies) should match that of the authentication token. MSDN.
Authentication/WsFederation/ADFS/AuthenticationMode The OWIN authentication middleware mode. MSDN.
Authentication/WsFederation/ADFS/SignInAsAuthenticationType The AuthenticationType used when creating the System.Security.Claims.ClaimsIdentity. MSDN.
Authentication/WsFederation/ADFS/ValidAudiences Comma separated list of audience URLs. MSDN.
Authentication/WsFederation/ADFS/ValidIssuers Comma separated list of issuer URLs. MSDN.
Authentication/WsFederation/ADFS/ClockSkew The clock skew to apply when validating times. MSDN.
Authentication/WsFederation/ADFS/NameClaimType The claim type used by the ClaimsIdentity to store the name claim. MSDN.
Authentication/WsFederation/ADFS/RoleClaimType The claim type used by the ClaimsIdentity to store the role claim. MSDN.
Authentication/WsFederation/ADFS/RequireExpirationTime A value indicating whether tokens must have an 'expiration' value. MSDN.
Authentication/WsFederation/ADFS/RequireSignedTokens A value indicating whether a System.IdentityModel.Tokens.SecurityToken can be valid if not signed. MSDN.
Authentication/WsFederation/ADFS/SaveSigninToken A boolean to control if the original token is saved when a session is created. MSDN.
Authentication/WsFederation/ADFS/ValidateActor A value indicating whether the System.IdentityModel.Tokens.JwtSecurityToken.Actor should be validated. MSDN.
Authentication/WsFederation/ADFS/ValidateAudience A boolean to control if the audience will be validated during token validation. MSDN.
Authentication/WsFederation/ADFS/ValidateIssuer A boolean to control if the issuer will be validated during token validation. MSDN.
Authentication/WsFederation/ADFS/ValidateLifetime A boolean to control if the lifetime will be validated during token validation. MSDN.
Authentication/WsFederation/ADFS/ValidateIssuerSigningKey A boolean that controls if validation of the System.IdentityModel.Tokens.SecurityKey that signed the securityToken is called. MSDN.
Authentication/WsFederation/ADFS/Whr Specifies a "whr" parameter in the identity provider redirect URL. MSDN

Azure Active Directory

The previous section describing AD FS can also be applied to Azure AD since Azure AD behaves like a standard WS-Federation compliant STS. To get started sign into the Azure Management Portal and create or select an existing directory. When a directory is available follow the instructions to add an applicationto the directory.

  • Under the Applications menu of the directory, click the Add button
  • Choose Add an application my organization is developing
  • Specify a custom name for the application and choose the type web application and/or web API
  • For the Sign-On URL and the App ID URI, specify the URL of the portal for both fields https://portal.contoso.com/
    • This corresponds to the Wtrealm site setting value
  • At this point, a new application is created. Navigate to the Configure section in the menu
    • Under the single sign-on section, update the first Reply URL entry to include a path in the URL http://portal.contoso.com/signin-azure-ad
    • This corresponds to the Wreply site setting value
  • Click Save in the footer
  • In the footer menu click the View Endpoints button and note the Federation Metadata Document field
    • This corresponds to the MetadataAddress site setting value
    • Paste this URL in a browser window to view the federation metadata XML and note the entityID attribute of the root element
    • This corresponds to the AuthenticationType site setting value

A standard Azure AD configuration only uses the following settings (with example values):

  • Authentication/WsFederation/ADFS/MetadataAddress - https://login.microsoftonline.com/01234567-89ab-cdef-0123-456789abcdef/federationmetadata/2007-06/federationmetadata.xml
  • Authentication/WsFederation/ADFS/AuthenticationType - https://sts.windows.net/01234567-89ab-cdef-0123-456789abcdef/
    • Use the value of the entityID attribute in the root element of the Federation Metadata (open the MetadataAddress URL in a browser that is the value of the above site setting)
  • Authentication/WsFederation/ADFS/Wtrealm - https://portal.contoso.com/
  • Authentication/WsFederation/ADFS/Wreply - https://portal.contoso.com/signin-azure-ad

Azure ACS

Even though Azure ACS is a standard/compliant STS server and it is possible to configure an ACS namespace using the above AD FS based settings, special handling is given to ACS due to the fact that it contains multiple "underlying identity providers" within a single namespace. Configuring an ACS namespace as a regular STS using the above AD FS based settings results in just a single sign-in button on the sign-in page (clicking this button goes to a secondary ACS home realm discovery page where the user is then able to choose a specific identity provider). It is preferable to have a separate button for each ACS identity provider directly on the sign-in page and to treat each identity provider as separately managed external accounts. A distinct set of settings specifically for ACS allows this sort of behaviour to be enabled.

Create an ACS Relying Party Application

Ensure that all the required identity providers are created or available. Then create a new relying party application in the ACS namespace with the following example values.

Setting Value
Name My Portal
Realm http://portal.contoso.com/
Return URL http://portal.contoso.com/signin-azure
Error URL (optional) http://portal.contoso.com/error
Token format SAML 2.0
Token encryption policy None
Token lifetime (secs) 600
Identity providers <check any identity provider that should be available for portal authentication>

Create Site Settings

Apply portal site settings referencing the above ACS Relying Party Application.

A standard ACS configuration only uses the following settings (with example values):

  • Authentication/WsFederation/Azure/MetadataAddress- https://mynamespace.accesscontrol.windows.net/FederationMetadata/2007-06/FederationMetadata.xml
  • Authentication/WsFederation/Azure/Wtrealm - http://portal.contoso.com/
  • Authentication/WsFederation/Azure/Wreply - http://portal.contoso.com/signin-azure

Then for each identity provider that is available in the ACS namespace, add the AuthenticationType setting:

  • Authentication/WsFederation/Azure/Facebook/AuthenticationType - Facebook-0123456789
  • Authentication/WsFederation/Azure/Microsoft/AuthenticationType - uri:WindowsLiveID
  • Authentication/WsFederation/Azure/Google/AuthenticationType - Google
  • Authentication/WsFederation/Azure/Yahoo/AuthenticationType - Yahoo!
  • Authentication/WsFederation/Azure/WsFederation/AuthenticationType - http://adfs.contoso.com/adfs/services/trust

Note that the out-of-the-box site settings only allow for a single Facebook application and a single WS-Federation application to be configured (while ACS itself allows for multiples of those applications to be created).

Site Setting Name Description
Authentication/Registration/ExternalLoginEnabled

Enables or disables external account sign-in and registration. Default:true

Authentication/WsFederation/Azure/MetadataAddress Required. The WS-Federation metadata URL of the ACS namespace. Example:https://mynamespace.accesscontrol.windows.net/FederationMetadata/2007-06/FederationMetadata.xml MSDN.
Authentication/WsFederation/Azure/Wtrealm Required. The value of the Realm field of the ACS Relying Party Application. Example: http://portal.contoso.com/. MSDN.
Authentication/WsFederation/Azure/Wreply Required. The value of the Return URL field of the ACS Relying Party Application. Example: http://portal.contoso.com/signin-azure.  MSDN.
Authentication/WsFederation/Azure/Facebook/AuthenticationType Specify the value of the Realm field from the Facebook identity provider settings in the namespace. Example: Facebook-0123456789 MSDN.
Authentication/WsFederation/Azure/Microsoft/AuthenticationType Specify the value of the Realm field from the Windows Live ID identity provider settings in the namespace. Example: uri:WindowsLiveID MSDN.
Authentication/WsFederation/Azure/Google/AuthenticationType Specify the value of the Realm field from the Google identity provider settings in the namespace. Example: Google MSDN.
Authentication/WsFederation/Azure/Yahoo/AuthenticationType Specify the value of the Realm field from the Yahoo! identity provider settings in the namespace. Example: Yahoo!. MSDN.
Authentication/WsFederation/Azure/WsFederation/AuthenticationType Specify the value of the Realm field from the WS-Federation identity provider settings in the namespace. Example: http://adfs.contoso.com/adfs/services/trust MSDN.

Each of the ACS identity provider configurations can be further modified through the following settings. Substitute the[provider] tag in the site setting name with a specific identity provider name: Facebook, Google, Yahoo, Microsoft, orWsFederation.

Site Setting Name Description
Authentication/WsFederation/Azure/[provider]/Caption Recommended. The text that the user can display on a sign in user interface. Default: Facebook, Google, Yahoo!, Windows Live ID, WS-FederationMSDN.
Authentication/WsFederation/Azure/[provider]/CallbackPath An optional constrained path on which to process the authentication callback. MSDN.
Authentication/WsFederation/Azure/[provider]/SignOutWreply The 'wreply' value used during sign-out. MSDN.
Authentication/WsFederation/Azure/[provider]/BackchannelTimeout Timeout value for back channel communications. Example: 00:05:00 (5 mins). MSDN.
Authentication/WsFederation/Azure/[provider]/RefreshOnIssuerKeyNotFound Determines if a metadata refresh should be attempted after a SecurityTokenSignatureKeyNotFoundException. MSDN.
Authentication/WsFederation/Azure/[provider]/UseTokenLifetime Indicates that the authentication session lifetime (e.g. cookies) should match that of the authentication token. MSDN.
Authentication/WsFederation/Azure/[provider]/AuthenticationMode The OWIN authentication middleware mode. MSDN.
Authentication/WsFederation/Azure/[provider]/SignInAsAuthenticationType The AuthenticationType used when creating the System.Security.Claims.ClaimsIdentity. MSDN.
Authentication/WsFederation/Azure/[provider]/ValidAudiences Comma separated list of audience URLs. MSDN.
Authentication/WsFederation/Azure/[provider]/ValidIssuers Comma separated list of issuer URLs. MSDN.
Authentication/WsFederation/Azure/[provider]/ClockSkew The clock skew to apply when validating times. MSDN.
Authentication/WsFederation/Azure/[provider]/NameClaimType The claim type used by the ClaimsIdentity to store the name claim. MSDN.
Authentication/WsFederation/Azure/[provider]/RoleClaimType The claim type used by the ClaimsIdentity to store the role claim. MSDN.
Authentication/WsFederation/Azure/[provider]/RequireExpirationTime A value indicating whether tokens must have an 'expiration' value. MSDN.
Authentication/WsFederation/Azure/[provider]/RequireSignedTokens A value indicating whether a System.IdentityModel.Tokens.SecurityToken can be valid if not signed. MSDN.
Authentication/WsFederation/Azure/[provider]/SaveSigninToken A boolean to control if the original token is saved when a session is created. MSDN.
Authentication/WsFederation/Azure/[provider]/ValidateActor A value indicating whether the System.IdentityModel.Tokens.JwtSecurityToken.Actor should be validated. MSDN.
Authentication/WsFederation/Azure/[provider]/ValidateAudience A boolean to control if the audience will be validated during token validation. MSDN.
Authentication/WsFederation/Azure/[provider]/ValidateIssuer A boolean to control if the issuer will be validated during token validation. MSDN.
Authentication/WsFederation/Azure/[provider]/ValidateLifetime A boolean to control if the lifetime will be validated during token validation. MSDN.
Authentication/WsFederation/Azure/[provider]/ValidateIssuerSigningKey A boolean that controls if validation of the System.IdentityModel.Tokens.SecurityKey that signed the securityToken is called. MSDN.

Facebook App (Page Tab) Settings

If the Facebook identity provider is enabled in ACS, the portal can be hosted as a Facebook App in the context of a Facebook Page Tab. This requires specific configurations in the Facebook application at the Facebook Developers portal as well as configurations in the ACS namespace.

Configure Facebook App Authentication

Apply the configuration described here.

Create a Facebook App Specific ACS Relying Party Application

Create a new relying party application that is specifically used for Facebook App based authentication.

Setting Value
Name My Facebook App Portal
Realm http://facebook-portal.contoso.com/
Return URL http://facebook-portal.contoso.com/signin-azure
Error URL (optional) http://facebook-portal.contoso.com/error
Token format SAML 2.0
Token encryption policy None
Token lifetime (secs) 600
Identity providers

<check Facebook and uncheck all other identity providers>

If multiple identity providers are checked, the user is presented with the intermediate home realm discovery page to select a specific identity provider. This is undesirable since the user should be required to sign-in with Facebook only. In this case, the Authentication/WsFederation/Azure/Facebook/App/Whr setting is used to skip the home realm discovery page to go directly to the Facebook sign-in.

Rule Groups <check the Default Rule Group for the ACS namespace>

Apply portal site settings referencing the above ACS Relying Party Application.

Site Setting Name Description
Authentication/OpenAuth/Facebook/ClientSecret

Required. Specify the value of the Application secret field from the Facebook identity provider settings in the namespace. Click the Show Secret button to retrieve the original value. The alternative name Authentication/OpenAuth/Facebook/AppSecret  can also be specified for the site setting name.

The Application ID (Client ID) value of the Facebook identity provider is not used in any site setting (in an ACS configuration) and can be ignored.

Authentication/WsFederation/Azure/Facebook/App/Wtrealm Required. The value of the Realm field of the Facebook App specific ACS Relying Party Application. Example: http://facebook-portal.contoso.com/.  MSDN.
Authentication/WsFederation/Azure/Facebook/App/Wreply Required. The value of the Return URL field of the Facebook App specific ACS Relying Party Application. Example: http://facebook-portal.contoso.com/signin-azure.  MSDN.
Authentication/WsFederation/Azure/Facebook/App/Whr Optional. Specify the value of the Realm field from the Facebook identity provider settings in the namespace. Example: Facebook-0123456789. Use this setting if it is necessary to skip the home realm discovery page to go directly to the Facebook sign-in.

Browse to the new Facebook Page Tab to view the portal hosted in Facebook. Visitors that are authenticated with Facebook automatically authenticate to the hosted portal with the same Facebook identity.

Configure AD FS with PowerShell

The process of adding a relying party trust in AD FS can also be performed by running the following PowerShell script on the AD FS server (save contents to a file named Add-AdxPortalRelyingPartyTrust.ps1). After running the script, continue with configuring the portal site settings.

<#
.SYNOPSIS 
Adds a relying party trust entry for an Adxstudio Portals website.
 
.PARAMETER domain
The domain name of the portal.
 
.EXAMPLE
PS C:\> .\Add-AdxPortalRelyingPartyTrust.ps1 -domain "portal.contoso.com"
#>
 
param
(
 [parameter(Mandatory=$true,Position=0)]
 $domain
)
 
$VerbosePreference = "Continue"
$ErrorActionPreference = "Stop"
 
Import-Module adfs
 
Function Add-CrmRelyingPartyTrust
{
 param (
 [parameter(Mandatory=$true,Position=0)]
 $name,
 [parameter(Position=1)]
 $callbackPath = "/signin-federation"
 )
 
 $identifier = "https://{0}/" -f $name
 $wsFedEndpoint = "https://{0}{1}" -f $name, $callbackPath
 
 $issuanceTransformRules = @'
@RuleTemplate = "MapClaims"
@RuleName = "Transform Windows Account Name to Name ID claim"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
 => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType);
 
@RuleTemplate = "LdapClaims"
@RuleName = "Send LDAP Claims"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
 => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"), query = ";givenName,sn,mail;{0}", param = c.Value);
'@
 
 $issuanceAuthorizationRules = @'
@RuleTemplate = "AllowAllAuthzRule"
 => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", Value = "true");
'@
 
 Add-ADFSRelyingPartyTrust -Name $name -Identifier $identifier -WSFedEndpoint $wsFedEndpoint -IssuanceTransformRules $issuanceTransformRules -IssuanceAuthorizationRules $issuanceAuthorizationRules
}
 
# add the portal relying party trust
 
Add-CrmRelyingPartyTrust $domain

Write-Host "[Relying Party Trust]"
Get-ADFSRelyingPartyTrust -Name $domain | Select-Object Name, WSFedEndpoint, Identifier, IssuanceTransformRules | fl

Write-Host "[Metadata URL]"
Get-ADFSEndpoint -AddressPath /FederationMetadata/2007-06/FederationMetadata.xml | % { $_.FullUrl.AbsoluteUri }