Frequently asked questions (FAQ) about AD FS

You can upgrade/migrate AD FS by completing the steps in one of the following linked articles:

• Windows Server 2012 R2 AD FS to Windows Server 2016 AD FS or later. (The process is the same if you're upgrading from Windows Server 2016 AD FS to Windows Server 2019 AD FS.)
  • Upgrading to AD FS in Windows Server 2016 by using a WID database
  • Upgrading to AD FS in Windows Server 2016 by using a SQL database
• Windows Server 2012 AD FS to Windows Server 2012 R2 AD FS:
  • Migrate to AD FS on Windows Server 2012 R2
• AD FS 2.0 to Windows Server 2012 AD FS:
  • Migrate to AD FS on Windows Server 2012
• AD FS 1.x to AD FS 2.0:
  • Upgrade from AD FS 1.x to AD FS 2.0

If you need to upgrade from AD FS 2.0 or 2.1 (Windows Server 2008 R2 or Windows Server 2012), use the in-box scripts located in C:\Windows\ADFS.

HTTP/2 support was added in Windows Server 2016, but HTTP/2 can't be used for client certificate authentication. Many AD FS scenarios use client certificate authentication. And many clients don't support retrying requests by using HTTP/1.1. So AD FS farm configuration reconfigures the local server's HTTP settings to HTTP/1.1. This reconfiguration requires a server restart.

This configuration is supported, but no new AD FS 2016 features would be supported in it. This configuration is meant to be temporary during the migration from AD FS 2012 R2 to AD FS 2016. It shouldn't be used for long periods of time.

Yes, but as a side effect:

• You'll need to manually manage updates of token signing certificates because Microsoft Entra ID won't be able to access the federation metadata. For more information on manually updating token signing certificates, see Renew federation certificates for Office 365 and Microsoft Entra ID.
• You won't be able to use legacy auth flows (for example, the ExO proxy auth flow).

AD FS is a stateless system, so load balancing is fairly simple for sign-ins. Here are some key recommendations for load-balancing systems:

• Load balancers shouldn't be configured with IP affinity. IP affinity might put undue load on a subset of your servers in certain Exchange Online scenarios.
• Load balancers must not terminate the HTTPS connections and start a new connection to the AD FS server.
• Load balancers should ensure that the connecting IP address should be translated as the source IP in the HTTP packet when it's being sent to AD FS. If a load balancer can't send the source IP in the HTTP packet, the load balancer must add the IP address to the X-Forwarded-For header. This step is required for the correct handling of certain IP-related features (like Banned IP and Extranet Smart Lockout). If this configuration isn't implemented correctly, security could be reduced.
• Load balancers should support SNI. If they don't, be sure AD FS is configured to create HTTPS bindings to handle clients that don't support SNI.
• Load balancers should use the AD FS HTTP health probe endpoint to detect whether the AD FS or Web Application Proxy servers are running. It should exclude them if 200 OK isn't returned.

AD FS supports multiple multiforest configurations. It relies on the underlying AD DS trust network to authenticate users across multiple trusted realms. We strongly recommend two-way forest trusts because they're easier to set up, which helps ensure the trust system works correctly.

Additionally:

• If you have a one-way forest trust, like a perimeter network (also known as DMZ) forest that contains partner identities, we recommend that you deploy AD FS in the corporate forest. Treat the perimeter network forest as another local claims provider trust connected via LDAP. In this case, Windows Integrated Authentication won't work for the perimeter network forest users. They'll need to use password authentication because it's the only supported mechanism for LDAP.

  If you can't use this option, you need to set up another AD FS server in the perimeter network forest. Add it as a claims provider trust in the AD FS server in the corporate forest. Users will need to do Home Realm Discovery, but both Windows Integrated Authentication and password authentication will work. Make appropriate changes in the issuance rules in AD FS in the perimeter network forest because AD FS in the corporate forest won't be able to get more information about users from the perimeter network forest.

• Domain-level trusts are supported and can work. But we strongly recommend that you move to a forest-level trust model. You'd also need to ensure UPN routing and NetBIOS name resolution work correctly.

Yes, IPv6 addresses are considered for familiar and unknown locations.

AD FS provides an extensible mechanism for third-party multifactor authentication providers to integrate. There's no set certification program for this. It's assumed that the vendor has performed the necessary validations before release.

The list of vendors that have notified Microsoft is available here: Multifactor authentication providers for AD FS. There might be providers available that we don't know about. We'll update the list as we discover new ones.

Yes, third-party proxies can be placed in front of AD FS, but any third-party proxy must support the MS-ADFSPIP protocol to be used in place of the Web Application Proxy.

We're currently aware of the following third-party providers. There might be providers available that we don't know about. We'll update this list as we discover new ones.

• F5 Access Policy Manager
• Citrix Application Delivery Controller (ADC)

You can download the AD FS 2016 version of the spreadsheet. You can also use this spreadsheet for AD FS in Windows Server 2012 R2.

Apple has released a set of requirements called App Transport Security (ATS) that might affect calls from iOS apps that authenticate to AD FS. You can ensure your AD FS and Web Application Proxy servers comply by making sure they support the requirements for connecting by using ATS. In particular, you should verify that:

• Your AD FS and Web Application Proxy servers support TLS 1.2.
• The TLS connection's negotiated cipher suite will support perfect forward secrecy.

For information about enabling and disabling SSL 2.0 and 3.0 and TLS 1.0, 1.1, and 1.2, see Manage SSL Protocols in AD FS.

To ensure your AD FS and Web Application Proxy servers negotiate only TLS cipher suites that support ATP, you can disable all cipher suites that aren't in the list of ATP-compliant cipher suites. To disable them, use the Windows TLS PowerShell cmdlets.

The value of the "sub" claim is the hash of the client ID and the anchor claim value.

The lifetime of the refresh token will be the lifetime of the token that AD FS got from the remote claims provider trust. The lifetime of the access token will be the token lifetime of the relying party for which the access token is being issued.

You can use a customized id_token to add relevant information in the id_token itself. For more information, see Customize claims to be emitted in id_token.

A special ValueType (http://www.w3.org/2001/XMLSchema#json) and escape character (\x22) were added for this scenario in AD FS 2016. Use the following samples for the issuance rule and for the final output from the access token.

Sample issuance rule:

=> issue(Type = "array_in_json", ValueType = "http://www.w3.org/2001/XMLSchema#json", Value = "{\x22Items\x22:[{\x22Name\x22:\x22Apple\x22,\x22Price\x22:12.3},{\x22Name\x22:\x22Grape\x22,\x22Price\x22:3.21}],\x22Date\x22:\x2221/11/2010\x22}");

Claim issued in access token:

"array_in_json":{"Items":[{"Name":"Apple","Price":12.3},{"Name":"Grape","Price":3.21}],"Date":"21/11/2010"}

With AD FS on Windows Server 2019, you can now pass the resource value embedded in the scope parameter. The scope parameter can be organized as a space-separated list where each entry is structured as resource/scope.

AD FS in Windows Server 2019 supports Proof Key for Code Exchange (PKCE) for the OAuth Authorization Code Grant flow.

Supported:

• aza. If you're using OAuth 2.0 Protocol Extensions for Broker Clients and the scope parameter contains the scope aza, the server issues a new primary refresh token and sets it in the refresh_token field of the response. It also sets the refresh_token_expires_in field to the lifetime of the new primary refresh token, if one is enforced.
• openid. Allows an application to request the use of the OpenID Connect authorization protocol.
• logon_cert. Allows an application to request logon certificates, which can be used to interactively sign in authenticated users. The AD FS server omits the access_token parameter from the response and instead provides a Base64-encoded CMS certificate chain or a CMC full PKI response. For more information, see Processing details.
• user_impersonation. Required if you want to request an on-behalf-of access token from AD FS. For more information on how to use this scope, see Build a multi-tiered application using On-Behalf-Of (OBO) using OAuth with AD FS 2016.

Not supported:

• vpn_cert. Allows an application to request VPN certificates, which can be used to establish VPN connections by using EAP-TLS authentication. This scope is no longer supported.
• email. Allows an application to request an email claim for the signed-in user. This scope is no longer supported.
• profile. Allows an application to request profile-related claims for the signed-in user. This scope is no longer supported.

The AD FS SSL certificate isn't the same as the AD FS Service Communications Certificate in the AD FS Management snap-in. To change the AD FS SSL certificate, you need to use PowerShell. Follow the guidance in Managing SSL certificates in AD FS and WAP 2016.

For information about disabling and enabling SSL protocols and cipher suites, see Manage SSL protocols in AD FS.

• If the proxy is used to proxy AD FS requests that use Windows Integrated Authentication, the proxy SSL certificate must use the same key as the federation server SSL certificate.
• If the AD FS ExtendedProtectionTokenCheck property is enabled (the default setting in AD FS), the proxy SSL certificate must use the same key as the federation server SSL certificate.
• Otherwise, the proxy SSL certificate can have a different key from the AD FS SSL certificate. It must meet the same requirements.

AD FS shows only one authentication method on the sign-in screen when an application explicitly requires a specific authentication URI that maps to a configured and enabled authentication method. The method is conveyed in the wauth parameter in WS-Federation requests. It's conveyed in the RequestedAuthnCtxRef parameter in SAML protocol requests. Only the requested authentication method is displayed. (For example, password sign-in.)

When you use AD FS with Microsoft Entra ID, it's common for applications to send the prompt=login parameter to Microsoft Entra ID. Microsoft Entra ID by default translates this parameter to requesting a fresh password-based sign-in to AD FS. This scenario is the most common reason you might see a password sign-in on AD FS in your network or not see an option to sign in with your certificate. You can easily resolve this problem by making a change to the federated domain settings in Microsoft Entra ID.

For more information, see Active Directory Federation Services prompt=login parameter support.

To change the AD FS service account, use the AD FS Toolbox Service Account PowerShell module. For instructions, see Change AD FS Service Account.

See Configure browsers to use Windows Integrated Authentication (WIA) with AD FS.

If you don't have access control policies based on the device on AD FS or Windows Hello for Business certificate enrollment via AD FS, you can turn off BrowserSsoEnabled. BrowserSsoEnabled allows AD FS to collect a Primary Refresh Token (PRT) from the client that contains device information. Without that token, device authentication of AD FS won't work on Windows 10 devices.

Admins often wonder how long users get single sign-on (SSO) without having to enter new credentials, and how admins can control that behavior. That behavior, and the configuration settings that control it, are described in AD FS single sign-on settings.

The default lifetimes of the various cookies and tokens are listed here (together with the parameters that govern the lifetimes):

Registered devices

• PRT and SSO cookies: 90 days maximum, governed by PSSOLifeTimeMins. (If the device is used at least every 14 days. This time window is controlled by DeviceUsageWindow.)

• Refresh token: Calculated based on the preceding parameters to provide consistent behavior.

• access_token: One hour by default, based on the relying party.

• id_token: Same as access_token.

Unregistered devices

• SSO cookies: Eight hours by default, governed by SSOLifetimeMins. When Keep me signed in (KMSI) is enabled, the default is 24 hours. This default is configurable via KMSILifetimeMins.

• Refresh token: Eight hours by default. 24 hours if KMSI is enabled.

• access_token: One hour by default, based on the relying party.

• id_token: Same as access_token.

AD FS doesn't support implicit flows for confidential client. Client authentication is enabled only for token endpoint, and AD FS won't issue an access token without client authentication. If confidential client needs an access token and also requires user authentication, it will need to use authorization code flow.

HSTS is a web security policy mechanism. It helps mitigate protocol downgrade attacks and cookie hijacking for services that have both HTTP and HTTPS endpoints. It allows web servers to declare that web browsers (or other complying user agents) should interact with them only by using HTTPS and never via the HTTP protocol.

All AD FS endpoints for web authentication traffic are opened exclusively over HTTPS. So AD FS mitigates the threats that HSTS policy mechanism creates. (By design, there's no downgrade to HTTP because there are no listeners in HTTP.) AD FS also prevents cookies from being sent to another server that has HTTP protocol endpoints by marking all cookies with the secure flag.

So you don't need HSTS on an AD FS server because HSTS can't be downgraded. AD FS servers meet compliance requirements because they can't use HTTP and because cookies are marked secure.

Finally, AD FS 2016 (with the most up-to-date patches) and AD FS 2019 support emitting the HSTS header. To configure this behavior, see Customize HTTP security response headers with AD FS.

We don't recommend that you do SSL termination before the Web Application Proxy server. If it is done in front of the Web Application Proxy server, the X-MS-Forwarded-Client-IP will contain the IP of the network device in front of the Web Application Proxy server. Here's a brief description of the various IP-related claims supported by AD FS:

• X-MS-Client-IP. Network IP of the device connected to the STS. For extranet requests, this claim always contains the IP of the Web Application Proxy server.
• X-MS-Forwarded-Client-IP. Multivalued claim that contains any values forwarded to AD FS by Exchange Online. It also contains the IP address of the device connected to the Web Application Proxy server.
• Userip. For extranet requests, this claim contains the value of X-MS-Forwarded-Client-IP. For intranet requests, this claim contains the same value as X-MS-Client-IP.

AD FS 2016 (with the most up-to-date patches) and later versions also support capturing the X-Forwarded-For header. Any load balancer or network device that doesn't forward at layer 3 (IP is preserved) should add the incoming client IP to the industry-standard X-Forwarded-For header.

The AD FS UserInfo endpoint always returns the subject claim as specified in the OpenID standards. AD FS doesn't support additional claims requested via the UserInfo endpoint. If you need more claims in an ID token, see Custom ID tokens in AD FS.

This group is created only when a Windows Server 2016 domain controller with the FSMO PDC role exists in the domain. To resolve the error, you can create the group manually. Take these steps to add the required permissions after you add the service account as a member of the group:

1. Open Active Directory Users and Computers.
2. Right-click your domain name in the left pane and then select Properties.
3. Select Security. (If the Security tab is missing, turn on Advanced Features on the View menu.)
4. Select Advanced, Add, and then Select a principal.
5. The Select User, Computer, Service Account, or Group dialog appears. In the Enter the object name to select box, enter Key Admin Group. Select OK.
6. In the Applies to box, select Descendant User objects.
7. Scroll to the bottom of the page and select Clear all.
8. In the Properties section, select Read msDS-KeyCredentialLink and Write msDS-KeyCredentialLink.

For apps that use the Android ADAL library, authentication to Microsoft Entra ID might fail for federated users. The app will get an AuthenticationException when it tries to show the sign-in page. In the Chrome browser, the AD FS sign-in page might be described as unsafe.

For all versions and all devices, Android doesn't support downloading additional certificates from the authorityInformationAccess field of the certificate. This limitation applies to the Chrome browser as well. Any server authentication certificate that's missing intermediate certificates will cause this error if the entire certificate chain isn't passed from AD FS.

You can solve this problem by configuring the AD FS and Web Application Proxy servers to send the necessary intermediate certificates along with the SSL certificate.

When you export the SSL certificate from one computer to be imported to the computer's personal store of the AD FS and Web Application Proxy servers, be sure to export the private key and select Personal Information Exchange - PKCS #12.

Also, be sure to select Include all certificates in the certificate path if possible and Export all extended properties.

Run certlm.msc on the Windows servers and import *.pfx into the computer's personal certificate store. Doing so will cause the server to pass the entire certificate chain to the ADAL library.

AD FS doesn't support HEAD requests. Applications shouldn't use HEAD requests against AD FS endpoints. Using these requests might cause HTTP error responses that are unexpected or delayed. You might also see unexpected error events in the AD FS event log.

A refresh token isn't issued if the token issued by IdP has a validity of less than one hour. To ensure a refresh token is issued, increase the validity of the token issued by the IdP to more than one hour.

The RP token encryption is set to AES256. You can't change it to any other value.

Mixed-mode AD FS farms are meant to be temporary. We recommended that during your planning you either roll over the SSL certificate before the upgrade process or complete the process and increase the farm behavior level before you update the SSL certificate. If that recommendation wasn't followed, use the following instructions to update the SSL certificate.

On Web Application Proxy servers, you can still use Set-WebApplicationProxySslCertificate. On the AD FS servers, you need to use netsh. Complete these steps:

1. Select a subset of AD FS 2016 servers for maintenance.

2. On the servers selected in the preceding step, import the new certificate via MMC.

3. Delete the existing certificates:

   a. netsh http delete sslcert hostnameport=fs.contoso.com:443

   b. netsh http delete sslcert hostnameport=localhost:443

   c. netsh http delete sslcert hostnameport=fs.contoso.com:49443

4. Add the new certificates:

   a. netsh http add sslcert hostnameport=fs.contoso.com:443 certhash=THUMBPRINT appid="{5d89a20c-beab-4389-9447-324788eb944a}" certstorename=My verifyclientcertrevocation=Enable sslctlstorename=AdfsTrustedDevices

   b. netsh http add sslcert hostnameport=localhost:443 certhash=THUMBPRINT appid="{5d89a20c-beab-4389-9447-324788eb944a}" certstorename=My verifyclientcertrevocation=Enable

   c. netsh http add sslcert hostnameport=fs.contoso.com:49443 certhash=THUMBPRINT appid="{5d89a20c-beab-4389-9447-324788eb944a}" certstorename=My verifyclientcertrevocation=Enable clientcertnegotiation=Enable

5. Restart the AD FS service on the selected server.

6. Remove a subset of Web Application Proxy servers for maintenance.

7. On the selected Web Application Proxy servers, import the new certificate via MMC.

8. Set the new certificate on the Web Application Proxy server by using this cmdlet:

   • Set-WebApplicationProxySslCertificate -Thumbprint " CERTTHUMBPRINT"

9. Restart the service on the selected Web Application Proxy servers.

10. Put the selected Web Application Proxy and AD FS servers back in the production environment.

Update the rest of the AD FS and Web Application Proxy servers in the same way.

AD FS and Web Application servers support any firewall that doesn't perform SSL termination on the endpoint. Also, AD FS / Web Application Proxy servers have built-in mechanisms to:

• Help prevent common web attacks like cross-site scripting.
• Perform AD FS proxy.
• Satisfy all requirements defined by the MS-ADFSPIP protocol.

In AD FS 2016, token binding is automatically enabled and causes multiple known problems with proxy and federation scenarios. These problems cause this event. To resolve this event, run the following PowerShell command to remove token binding support:

Set-AdfsProperties -IgnoreTokenBinding $true

After an upgrade to Windows Server 2019, the configuration version of the Web Application Proxy will continue to display as Windows Server 2016. The Web Application Proxy doesn't have new version-specific features for Windows Server 2019. If the farm behavior level has been raised on AD FS, the Web Application Proxy will continue to display as Windows Server 2016. This behavior is by design.

When ESL is enabled, AD FS tracks the account activity and known locations for users in the ADFSArtifactStore database. This database scales relative to the number of users and known locations tracked. When you're planning to enable ESL, you can estimate that the ADFSArtifactStore database will grow at a rate of up to 1 GB per 100,000 users.

If the AD FS farm is using the Windows Internal Database, the default location for the database files is C:\Windows\WID\Data. To prevent filling this drive, be sure to have at least 5 GB of free storage before you enable ESL. In addition to disk storage, plan for total process memory to grow after you enable ESL by up to another 1 GB of RAM for user populations of 500,000 or less.

Here's the text of the event:

Active Directory trust enumeration was unable to enumerate one of more domains due to the following error. Enumeration will continue but the Active Directory identifier list may not be correct. Validate that all expected Active Directory identifiers are present by running Get-ADFSDirectoryProperties.

This event occurs when forests aren't trusted when AD FS attempts to enumerate all the forests in a chain of trusted forests and connect across all the forests. For example, assume AD FS Forest A and Forest B are trusted and that and Forest B and Forest C are trusted. AD FS will enumerate all three forests and attempt to find a trust between Forest A and Forest C. If users from the failing forest should be authenticated by AD FS, set up a trust between the AD FS forest and the failing forest. If users from the failing forest shouldn't be authenticated by AD FS, ignore this event.

Here's the text of the event:

Microsoft.IdentityServer.AuthenticationFailedException: MSIS5015: Authentication of the presented token failed. Token Binding claim in token must match the binding provided by the channel.

In AD FS 2016, token binding is automatically enabled and causes multiple known problems with proxy and federation scenarios. These problems cause this event. To resolve the event, run the following PowerShell command to remove token binding support:

Set-AdfsProperties -IgnoreTokenBinding $true

Here's the text of the event:

System.ServiceModel.FaultException: The formatter threw an error while trying to deserialize the message: There was an error while trying to deserialize parameter schemas.microsoft.com/ws/2009/12/identityserver/protocols/policystore:maxBehaviorLevel". The InnerException message was "Invalid enum value 'Win2019' cannot be deserialized into type 'Microsoft.IdentityServer.FarmBehavior'. Ensure that the necessary enum values are present and are marked with EnumMemberAttribute attribute if the type has DataContractAttribute attribute.

This event is expected when both of these statements are true:

• You have a mixed-mode farm.
• AD FS 2019 provides the farm max behavior level information to the primary federation server and isn't recognized by federation server version 2016.

AD FS 2019 keeps trying to share in the farm the MaxBehaviorLevel value Win2019 until it becomes stale after two months and is automatically removed from the farm. To avoid getting this event, migrate the primary federation role to the federation server with the latest version. Follow the instructions in To upgrade your AD FS farm to Windows Server 2019 Farm Behavior Level.

To resolve the issue, follow these steps:

1. Launch the AD FS management console.
2. Go to Services > Scope Descriptions.
3. In "Scope Descriptions, select More options, then select Add Scope Description.
4. Under Name, enter ugs, then select Apply > OK.
5. Launch PowerShell as Administrator.
6. Run the command Get-AdfsApplicationPermission. Look for the ScopeNames :{openid, aza} that has the ClientRoleIdentifier value. Make a note of the ObjectIdentifier value.
7. Run the command Set-AdfsApplicationPermission -TargetIdentifier <ObjectIdentifier from step 5> -AddScope 'ugs'.
8. Restart the AD FS service.
9. On the client, restart the client. You should be prompted to configure Windows Hello for Business.
10. If the configuration window doesn't pop up, then you need to collect trace logs and troubleshoot further.

Yes, but only in Windows Server 2019 or later. You can organize the scope parameter as a space-separated list where each entry is structured as a resource or scope, such as <create a valid sample request>.

Yes, but only in Windows Server 2019 or later. AD FS supports Proof Key for Code Exchange (PKCE) for the OAuth Authorization Code Grant flow.