Skip to content

Installing and Configuring ADFS

Jump to bottom Edit New page
Andrew Owen edited this page Jun 21, 2019 · 29 revisions

Overview

ADFS is a Microsoft Identity Provider, that implements SAML 2.0. ADFS is proprietary in that it only interfaces with Active Directory, and no other credential repository.

When allowing users to authenticate on the internet, that means ADFS must be exposed on the internet. In this scenario, it is a best-practice to keep ADFS behind the firewall and deploy an "ADFS proxy" in the DMZ. The ADFS proxy securely communicates with the ADFS server for purposes of authenticating users.

ADFS Installation

There are many great articles and blogs on the web that explain how to install ADFS 3.0 so this article will not go into great detail about how to conduct the initial installation. For example, here is a good three-part series that explains how to installed ADFS 3.0:

https://blogs.technet.microsoft.com/rmilne/2014/04/28/how-to-install-adfs-2012-r2-for-office-365/

The first two steps are normally applicable to our projects. Step three focuses on integrating with Microsoft Office 365, which we may do at some point, but haven't yet.

ADFS Configuration

Once ADFS is installed, it is then time to configure ADFS to serve as a trusted identity provider. These instructions assume you are in the ADFS snap-in. To get there, go to the Server Manager (while on the ADFS server), click Tools and then choose ADFS Management.

Add Attributes

When ADFS creates SAML assertion for a user, it can include “attributes” about the user. It is important that attributes are named consistently (i.e. GFIPM_ so relying parties know how to interpret the information. This section explains how to establish the attribute name.

  1. Right-click “Claim Descriptions” under “Service” and select “Add Claim Description”
  2. Give it a display name such “GFIPM Given Name” and the claim type should be something like gfipm:2.0:user:GivenName, or whatever the applicable GFIPM attribute name is.
  3. Follow the previous two steps again to add additional attributes. You will map these in a later step.

Add Relying Parties

A "relying party" is synonymous for a "service provider". It is a SAML entity that ADFS trusts. For every service or relying party that ADFS will trust, you must add a “relying party entry”.

  1. Right-click on “Relying Party Trusts” under “Trust Relationships” and select “Add Relying Party Trust.
  2. Click Start
  3. Choose a method for importing the relying party’s SAML metadata. For the purpose of this project, we chose the second option (import from a file)
  4. Click Next
  5. Provide a Display Name. This should be descriptive of the relying party
  6. Click Next
  7. Choose whether to configure multi-factor authentication. For this project we chose not to do so.
  8. Click Next
  9. Permit All Users
  10. Click Next
  11. Feel free to view details of the trust, or just click Next.
  12. At this point you will see a new relying party trust entry

Add Claims Rules

Claim rules tell ADFS what attributes to send to which relying party trust and how to populate those attributes.

From LDAP

  1. Under "Trust Relationships", open the “relying party trusts” and right-click on the name of your service provider.
  2. Select “Edit claim rules”
  3. Add Rule
  4. Select “Send LDAP Attributes as Claims”, Next
  5. Give the claim rule a name, something like “Send AD Details”
  6. Under LDAP attribute, select (for example) “Given-Name” an under outgoing claim type select “GFIPM Given Name”. Add another that maps LDAP Surname to “GFIPM Sur Name”
  7. Repeat step 6 for other attributes collected in Active Directory

From SQL Database

Sometimes information needed about the user is not stored in Active Directory. In this case, it is a proven and recommended practice to create a SQL database to store the additional information. This document assumes the SQL database exists and will not go into detail of setting up the database. From an ADFS perspective, you need to do the following:

  1. Setup a SQL attribute store:

    1. Under “Trust Relationships” right-click on “Attribute Stores” and select “Add Attribute Store”
    2. Provide a display name
    3. Select “SQL” from the dropdown
    4. Enter a connection string. For example: Server=SERVERNAME\SQLEXPRESS;Database=DATABASE_NAME;Integrated Security=True

  2. Add SQL-based claim rules to a relying party:

    1. Under "Trust Relationships", open the “relying party trusts” and right-click on the name of your service provider.
    2. Select “Edit claim rules”
    3. Add Rule
    4. Select “Send Claims Using Custom Rule”, Next
    5. Provide a name and the rule text. For instance the following rule would add an attribute to the outgoing assertion called gfipm:2.0:user:EmployerORI and would populate that attribute from the “Agency_ORI” table in SQL database:
      c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"] => issue(store = "My SQL Attribute Store", types = ("gfipm:2.0:user:EmployerORI"), query = "SELECT Agency_ORI FROM AD WHERE sAMAccountName = {0}", param = c.Value);

Static or Hybrid Attributes

Sometimes you will need to release an attribute that requires some static information appended. To do this:

  1. Under "Trust Relationships", open the “relying party trusts” and right-click on the name of your service provider.
  2. Select “Edit claim rules”
  3. Add Rule
  4. Select “Send Claims Using Custom Rule”, Next
  5. Provide a name and the rule text. For instance the following rule would add an attribute to the outgoing assertion called “gfipm:2.0:user:FederationId” that always starts with FEDERATION:IDP:AGENCY:USER followed by the user’s User Principal Name (UPN) c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"] => issue(Type = "gfipm:2.0:user:FederationId", Value = "FEDERATION:IDP:AGENCY:USER:" + c.Value);

ADFS Proxy Configuration

The URL in the ADFS Installation section of this document explains how to setup the ADFS proxy, which is fairly straightforward. The only step not covered by that link is the need to “Publish” the proxy. To do this, you must follow these steps:

  1. Open “Server Manager
  2. Select “Remote Access Management” under “Tools”
  3. Select “Publish” under “General
  4. Click Next
  5. Choose “Pass-Through”
  6. Provide a Name to identify the proxy rule
  7. Provide the “external” URL. This is the URL that users will actually enter in a web browser
  8. Provide the SSL certificate. This is the one that has been issued by a trusted certificate authority (CA)
  9. Provide the “internal” URL. This is the URL where the ADFS service can be accessed. The best idea is for the “internal” and “external” URLs to be exactly the same, otherwise you will likely experience configuration issues.

Installation and Configuration Tips

Administrator Privileges

Since ADFS needs to communicate with Active Directory, when installing ADFS you will need the credentials for an account with Active Directory administrator privileges.

Certificates

ADFS uses x.509 certificates to secure all ADFS-related communications. These include:

Service Communications Certificate

ADFS uses this certificate to encrypt all client connectivity with the ADFS server. For instance, when a user is redirected to the ADFS login page, this is the certificate that will secure that SSL certificate (viewable in the browser). This same certificate is used to secure traffic between the ADFS proxy and ADFS. If this certificate expires, the proxy will not be able to communicate with ADFS. See Troubleshooting HTTP 503 Error ADFS requires a service communication certificate to secure all communications with ADFS. This should be a certificate issued by a trusted certificate authority; however, you can use a self-signed certificate if needed. When this certificate is issued (whether self-signed or by a trusted certificate authority), this certificate must have an “Extended Key Usage” of Server Authentication (1.3.6.1.5.5.7.3.1).

Token Signing Certificate

ADFS uses this certificate to sign the token (SAML Assertion) sent to the relying parties to prove that trusted identity provider issues the token.

Token-Decrypting Certificate

ADFS can use this certificate to encrypt the payload of a SAML token. This certificate is is rarely used in practice since the SAML assertions are always sent over a secure SSL connection.

Service Account

ADFS requires a service account; this can be a standard service account or a group-managed service account.

Hosts File

When the ADFS proxy communicates with the ADFS server, it now assumes that the proxy server resolves to whatever the public DNS name is for the ADFS proxy, so the ADFS proxy needs to have an entry in its “hosts” file to map the DNS name to the IP address of the ADFS server on the internal network. Since the hosts file is checked first, the proxy will resolve the DNS name to the ADFS internal IP address rather than to the proxy's external IP address.

Exporting and Importing Rules

It’s common that once you create claims rules in ADFS that you may want to export these and import elsewhere. For instance, you may want to have multiple relying parties in a single ADFS instance with the same claims rules or this is handy in the case that you need to create an entirely new instance of ADFS but want to preserve the rules.

To do this, you must open a PowerShell window as Administrator.
To export rules, run a command like the following. The “Name” is the name of the Relying Party Trust from which you would like to export the rules.

(Get-AdfsRelyingPartyTrust -Name "OJBC Demostate SP").IssuanceTransformRules | Out-File "C:\claimsrules.txt"

To import rules, run a command like the following. The “TargetName” is the name of the Relying Party Trust where you would like to import the rules.
Set-AdfsRelyingPartyTrust -TargetName "OJBC Demostate SP" -IssuanceTransformRulesFile "C:\claimsrules.txt" 

Troubleshooting

HTTP 503 Error

If users start seeing a HTTP 503 error, in the browser, when attempting to login, the issues is mostly related to an expired Service Communications Certificate. To resolve this, you must first update the ADFS server to use the new SSL certificate.

Open a Windows Powershell as Administrator and run Get-AdfsSslCertificate | fl to confirm that ADFS is still using an old certificate.

To change the certificate for ADFS simply run Set-AdfsSslCertificate -Thumbprint= where Thumbprint contains the identifier for the new certificate.

You will then need to place a copy of the new certificate on the ADFS proxy server, in the "local" certificate store. After doing so, follow these steps:

  1. Open Web Application Proxy Configuration wizard. (If the cert on the ADFS proxy server has expired, you will see a "notification" in the server manager console that contains a link to the Web Application Proxy Wizard. If you want to open this wizard at any other time, from the "Server Manager" click "Tools" then "Remote Access Management". Click "publish" to create a new proxy).
  2. Enter a federation service name, this must be the name that resolves to the internal ADFS server (this would align with the CN on the SSL cert)
  3. Provide log in credentials of an account with admin privileges on the ADFS server (not the proxy server)
  4. Select the new cert
  5. You should now see a message indicating that the web service proxy has been configured successfully
Add a custom footer
Add a custom sidebar

Clone this wiki locally