Manage and customize Active Directory Federation Services by using Azure AD Connect

This article describes how to manage and customize Active Directory Federation Services (AD FS) by using Azure Active Directory (Azure AD) Connect. It also includes other common AD FS tasks that you might need to do for a complete configuration of an AD FS farm.

Topic What it covers
Manage AD FS
Repair the trust How to repair the federation trust with Office 365.
Federate with Azure AD using alternate login ID Configure federation using alternate login ID
Add an AD FS server How to expand an AD FS farm with an additional AD FS server.
Add an AD FS Web Application Proxy server How to expand an AD FS farm with an additional Web Application Proxy (WAP) server.
Add a federated domain How to add a federated domain.
Update the SSL certificate How to update the SSL certificate for an AD FS farm.
Customize AD FS
Add a custom company logo or illustration How to customize an AD FS sign-in page with a company logo and illustration.
Add a sign-in description How to add a sign-in page description.
Modify AD FS claim rules How to modify AD FS claims for various federation scenarios.

Manage AD FS

You can perform various AD FS-related tasks in Azure AD Connect with minimal user intervention by using the Azure AD Connect wizard. After you've finished installing Azure AD Connect by running the wizard, you can run the wizard again to perform additional tasks.

Repair the trust

You can use Azure AD Connect to check the current health of the AD FS and Azure AD trust and take appropriate actions to repair the trust. Follow these steps to repair your Azure AD and AD FS trust.

  1. Select Repair AAD and ADFS Trust from the list of additional tasks. Repair AAD and ADFS Trust

  2. On the Connect to Azure AD page, provide your global administrator credentials for Azure AD, and click Next. Connect to Azure AD

  3. On the Remote access credentials page, enter the credentials for the domain administrator.

    Remote access credentials

    After you click Next, Azure AD Connect checks for certificate health and shows any issues.

    State of certificates

    The Ready to configure page shows the list of actions that will be performed to repair the trust.

    Ready to configure

  4. Click Install to repair the trust.

Note

Azure AD Connect can only repair or act on certificates that are self-signed. Azure AD Connect can't repair third-party certificates.

Federate with Azure AD using AlternateID

It is recommended that the on-premises User Principal Name(UPN) and the cloud User Principal Name are kept the same. If the on-premises UPN uses a non-routable domain (ex. Contoso.local) or cannot be changed due to local application dependencies, we recommend setting up alternate login ID. Alternate login ID allows you to configure a sign-in experience where users can sign in with an attribute other than their UPN, such as mail. The choice for User Principal Name in Azure AD Connect defaults to the userPrincipalName attribute in Active Directory. If you choose any other attribute for User Principal Name and are federating using AD FS, then Azure AD Connect will configure AD FS for alternate login ID. An example of choosing a different attribute for User Principal Name is shown below:

Alternate ID attribute selection

Configuring alternate login ID for AD FS consists of two main steps:

  1. Configure the right set of issuance claims: The issuance claim rules in the Azure AD relying party trust are modified to use the selected UserPrincipalName attribute as the alternate ID of the user.
  2. Enable alternate login ID in the AD FS configuration: The AD FS configuration is updated so that AD FS can look up users in the appropriate forests using the alternate ID. This configuration is supported for AD FS on Windows Server 2012 R2 (with KB2919355) or later. If the AD FS servers are 2012 R2, Azure AD Connect checks for the presence of the required KB. If the KB is not detected, a warning will be displayed after configuration completes, as shown below:

    Warning for missing KB on 2012R2

    To rectify the configuration in case of missing KB, install the required KB2919355 and then repair the trust using Repair AAD and AD FS Trust.

Note

For more information on alternateID and steps to manually configure, read Configuring Alternate Login ID

Add an AD FS server

Note

To add an AD FS server, Azure AD Connect requires the PFX certificate. Therefore, you can perform this operation only if you configured the AD FS farm by using Azure AD Connect.

  1. Select Deploy an additional Federation Server, and click Next.

    Additional federation server

  2. On the Connect to Azure AD page, enter your global administrator credentials for Azure AD, and click Next.

    Connect to Azure AD

  3. Provide the domain administrator credentials.

    Domain administrator credentials

  4. Azure AD Connect asks for the password of the PFX file that you provided while configuring your new AD FS farm with Azure AD Connect. Click Enter Password to provide the password for the PFX file.

    Certificate password

    Specify SSL certificate

  5. On the AD FS Servers page, enter the server name or IP address to be added to the AD FS farm.

    AD FS servers

  6. Click Next, and go through the final Configure page. After Azure AD Connect has finished adding the servers to the AD FS farm, you will be given the option to verify the connectivity.

    Ready to configure

    Installation complete

Add an AD FS WAP server

Note

To add a WAP server, Azure AD Connect requires the PFX certificate. Therefore, you can only perform this operation if you configured the AD FS farm by using Azure AD Connect.

  1. Select Deploy Web Application Proxy from the list of available tasks.

    Deploy Web Application Proxy

  2. Provide the Azure global administrator credentials.

    Connect to Azure AD

  3. On the Specify SSL certificate page, provide the password for the PFX file that you provided when you configured the AD FS farm with Azure AD Connect. Certificate password

    Specify SSL certificate

  4. Add the server to be added as a WAP server. Because the WAP server might not be joined to the domain, the wizard asks for administrative credentials to the server being added.

    Administrative server credentials

  5. On the Proxy trust credentials page, provide administrative credentials to configure the proxy trust and access the primary server in the AD FS farm.

    Proxy trust credentials

  6. On the Ready to configure page, the wizard shows the list of actions that will be performed.

    Ready to configure

  7. Click Install to finish the configuration. After the configuration is complete, the wizard gives you the option to verify the connectivity to the servers. Click Verify to check connectivity.

    Installation complete

Add a federated domain

It's easy to add a domain to be federated with Azure AD by using Azure AD Connect. Azure AD Connect adds the domain for federation and modifies the claim rules to correctly reflect the issuer when you have multiple domains federated with Azure AD.

  1. To add a federated domain, select the task Add an additional Azure AD domain.

    Additional Azure AD domain

  2. On the next page of the wizard, provide the global administrator credentials for Azure AD.

    Connect to Azure AD

  3. On the Remote access credentials page, provide the domain administrator credentials.

    Remote access credentials

  4. On the next page, the wizard provides a list of Azure AD domains that you can federate your on-premises directory with. Choose the domain from the list.

    Azure AD domain

    After you choose the domain, the wizard provides you with appropriate information about further actions that the wizard will take and the impact of the configuration. In some cases, if you select a domain that isn't yet verified in Azure AD, the wizard provides you with information to help you verify the domain. See Add your custom domain name to Azure Active Directory for more details.

  5. Click Next. The Ready to configure page shows the list of actions that Azure AD Connect will perform. Click Install to finish the configuration.

    Ready to configure

Note

Users from the added federated domain must be synchronized before they will be able to login to Azure AD.

AD FS customization

The following sections provide details about some of the common tasks that you might have to perform when you customize your AD FS sign-in page.

Add a custom company logo or illustration

To change the logo of the company that's displayed on the Sign-in page, use the following Windows PowerShell cmdlet and syntax.

Note

The recommended dimensions for the logo are 260 x 35 @ 96 dpi with a file size no greater than 10 KB.

Set-AdfsWebTheme -TargetName default -Logo @{path="c:\Contoso\logo.PNG"}
Note

The TargetName parameter is required. The default theme that's released with AD FS is named Default.

Add a sign-in description

To add a sign-in page description to the Sign-in page, use the following Windows PowerShell cmdlet and syntax.

Set-AdfsGlobalWebContent -SignInPageDescriptionText "<p>Sign-in to Contoso requires device registration. Click <A href='http://fs1.contoso.com/deviceregistration/'>here</A> for more information.</p>"

Modify AD FS claim rules

AD FS supports a rich claim language that you can use to create custom claim rules. For more information, see The Role of the Claim Rule Language.

The following sections describe how you can write custom rules for some scenarios that relate to Azure AD and AD FS federation.

Immutable ID conditional on a value being present in the attribute

Azure AD Connect lets you specify an attribute to be used as a source anchor when objects are synced to Azure AD. If the value in the custom attribute is not empty, you might want to issue an immutable ID claim.

For example, you might select ms-ds-consistencyguid as the attribute for the source anchor and issue ImmutableID as ms-ds-consistencyguid in case the attribute has a value against it. If there's no value against the attribute, issue objectGuid as the immutable ID. You can construct the set of custom claim rules as described in the following section.

Rule 1: Query attributes

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> add(store = "Active Directory", types = ("http://contoso.com/ws/2016/02/identity/claims/objectguid", "http://contoso.com/ws/2016/02/identity/claims/msdsconsistencyguid"), query = "; objectGuid,ms-ds-consistencyguid;{0}", param = c.Value);

In this rule, you're querying the values of ms-ds-consistencyguid and objectGuid for the user from Active Directory. Change the store name to an appropriate store name in your AD FS deployment. Also change the claims type to a proper claims type for your federation, as defined for objectGuid and ms-ds-consistencyguid.

Also, by using add and not issue, you avoid adding an outgoing issue for the entity, and can use the values as intermediate values. You will issue the claim in a later rule after you establish which value to use as the immutable ID.

Rule 2: Check if ms-ds-consistencyguid exists for the user

NOT EXISTS([Type == "http://contoso.com/ws/2016/02/identity/claims/msdsconsistencyguid"])
=> add(Type = "urn:anandmsft:tmp/idflag", Value = "useguid");

This rule defines a temporary flag called idflag that is set to useguid if there's no ms-ds-consistencyguid populated for the user. The logic behind this is the fact that AD FS doesn't allow empty claims. So when you add claims http://contoso.com/ws/2016/02/identity/claims/objectguid and http://contoso.com/ws/2016/02/identity/claims/msdsconsistencyguid in Rule 1, you end up with an msdsconsistencyguid claim only if the value is populated for the user. If it isn't populated, AD FS sees that it will have an empty value and drops it immediately. All objects will have objectGuid, so that claim will always be there after Rule 1 is executed.

Rule 3: Issue ms-ds-consistencyguid as immutable ID if it's present

c:[Type == "http://contoso.com/ws/2016/02/identity/claims/msdsconsistencyguid"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Value = c.Value);

This is an implicit Exist check. If the value for the claim exists, then issue that as the immutable ID. The previous example uses the nameidentifier claim. You'll have to change this to the appropriate claim type for the immutable ID in your environment.

Rule 4: Issue objectGuid as immutable ID if ms-ds-consistencyGuid is not present

c1:[Type == "urn:anandmsft:tmp/idflag", Value =~ "useguid"]
&& c2:[Type == "http://contoso.com/ws/2016/02/identity/claims/objectguid"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Value = c2.Value);

In this rule, you're simply checking the temporary flag idflag. You decide whether to issue the claim based on its value.

Note

The sequence of these rules is important.

SSO with a subdomain UPN

You can add more than one domain to be federated by using Azure AD Connect, as described in Add a new federated domain. You must modify the user principal name (UPN) claim so that the issuer ID corresponds to the root domain and not the subdomain, because the federated root domain also covers the child.

By default, the claim rule for issuer ID is set as:

c:[Type
== “http://schemas.xmlsoap.org/claims/UPN“]

=> issue(Type = “http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid“, Value = regexreplace(c.Value, “.+@(?<domain>.+)“, “http://${domain}/adfs/services/trust/“));

Default issuer ID claim

The default rule simply takes the UPN suffix and uses it in the issuer ID claim. For example, John is a user in sub.contoso.com, and contoso.com is federated with Azure AD. John enters john@sub.contoso.com as the username while signing in to Azure AD. The default issuer ID claim rule in AD FS handles it in the following manner:

c:[Type
== “http://schemas.xmlsoap.org/claims/UPN“]

=> issue(Type = “http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid“, Value = regexreplace(john@sub.contoso.com, “.+@(?<domain>.+)“, “http://${domain}/adfs/services/trust/“));

Claim value: http://sub.contoso.com/adfs/services/trust/

To have only the root domain in the issuer claim value, change the claim rule to match the following:

c:[Type == “http://schemas.xmlsoap.org/claims/UPN“]

=> issue(Type = “http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid“, Value = regexreplace(c.Value, “^((.*)([.|@]))?(?<domain>[^.]*[.].*)$”, “http://${domain}/adfs/services/trust/“));

Next steps

Learn more about user sign-in options.