Planning Your Installation

System Requirements

ADFSToolkit must be installed on a Windows Server (your AD FS host) with:

While not a firm requirement, we strongly suggest a test AD FS environment to perform the installation prior to installing in production. You should be aware that after installation, you will see a few thousand trusts displayed within the administration toolset, AD FS-Microsoft Management Console (MMC).

Minimum Server OS

Windows Server 2012 R2 or newer is the minimal level of OS supported. You should also be current on latest OS and security patch/updates provided by Microsoft.

Minimum PowerShell Version

ADFSToolkit uses Microsoft’s PowerShell with Windows Management Framework (WMF) 5.1. To see if your host is WMF5.1 ready, check the Microsoft Compatibility Matrix.

To quickly see which version of PowerShell you have, open a PowerShell window or PowerShell ISE window and enter $PSVersionTable. If you do not see version 5.1, you will need to update your environment first.

WMF 5.1 can be downloaded from here: https://docs.microsoft.com/en-us/PowerShell/wmf/5.1/installconfigure  
ADFSToolkit will not proceed until your environment has been upgraded to at least this latest PowerShell version.

Installation Procedure

Downloading the ADFSToolkituses Microsoft’s PowerShellGallery.com service as the official primary distribution channel of ADFSToolkit as a PowerShell Module.  This allows us to rely on Microsoft’s approach to managing distribution and updated PowerShell Modules for the lifecycle of ADFSToolkit.

To install ADFSToolkit you will need to:

Required Security Conditions

All installation steps are assumed to be performed by a user with both Local Administrator level access and AD FS Administrator access.  SWAMID is in the process of acquiring a certificate for the securely deliver of the ADFSToolkit through PowerShellGallery as a known trusted source.  Until the certification process is in place, ADFSToolkit requires the ability to run AD FS modules from unsigned origins.

To prepare your system for the ADFSToolkit Execution policy settings issue the following PowerShell command to relax the policy.

PowerShell
Set-ExecutionPolicy -ExecutionPolicy Remotesigned


Install the Module

The module is installed by issuing the command:

PowerShell 
 
Install-Module –name ADFSToolkit

If this is your first time installing items from PowerShell Gallery, you may see this:
 

Answer yes to install the required NuGet provider

You may also see this:

Either update the PowerShell Gallery to be trusted or answer ‘Y’ to proceed.

Once connected, the Module will be installed in the default PowerShell home of:

C:\Program Files\WindowsPowerShell\Modules\ADFSToolkit\[version #]

Bootstrapping Trust Explained

AD FS does no trust verification on the data it loads other than having a valid HTTPS endpoint. This minimal validation alone is insufficient for AD FS to participate in a Federation’s circle of trust.  ADFSToolkit helps elevate or ‘bootstrap’ AD FS as a trusted endpoint in the federation by:

ADFSToolkit processes help ensure that the content is valid and safe for AD FS to load and that it originated from an authority that you trust: SWAMID.  

The validation approach ADFSToolkit uses is based on the user supplying the fingerprint of the certificate that they want to trust. 

The SHA256 fingerprint of the SWAMID certificate to be used is:

A6785A37C9C90C25AD5F1F6922EF767BC97867673AAF4F8BEAA1A76DA3A8E585

This fingerprint can be verified manually by:

openssl.exe x509 -noout -fingerprint -sha256 -inform pem -in ./md-signer2.crt
SHA256 Fingerprint=A6:78:5A:37:C9:C9:0C:25:AD:5F:1F:69:22:EF:76:7B:C9:78:67:67:3A:AF:4F:8B:EA:A1:A7:6D:A3:A8:E5:85

Configuring ADFSToolkit

To create the configuration file for SWAMID metadata, issue these commands: 

PowerShell 
 
New-ADFSTkConfiguration


The command will prompt you for the following answers (see table below) and results in a configuration file created on disk. Optionally, a scheduled job to hourly process the aggregate can be created. The scheduled job is disabled by default.

QuestionAnswer
Metadata Aggregatehttp://mds.swamid.se/md/swamid-2.0.xml
Certificate FingerprintA6785A37C9C90C25AD5F1F6922EF767BC97867673AAF4F8BEAA1A76DA3A8E585
Metadata Prefix
  • This is the prefix added to each Relying Party (RP, also known as Service Provider) entry in AD FS. Defaults to ‘ADFSTk’ unless you provide one here. 
  • We recommend using ADFSTk or Swamid as prefix.
  • Note that colons are used as a separator and are not allowed to be used as part of the prefix.
Institution Name

Your Organization’s official  name

Country NameSweden
Country CodeSE
Institution Domain
  • The domain of your institution.
  • It is used as the scope for certain attributes to ensure unique identifiers are unique globally
Short Name for Your InstitutionThe short name representation of your institution that you commonly use, e.g. Linköpings universitet is known as LiU.
External DNS Name of Your AD FS InfrastructureThe Fully Qualified Domain Name (FQDN) of your AD FS instance


When the configuration is complete, the resulting XML configuration file will be found in the “/config” folder in the PowerShell Module’s base directory.  It is this configuration file that will be processed in a subsequent PowerShell command to load (or synchronize) metadata aggregate into AD FS.

PowerShell Hint: Use this to see ADFSToolkit’s Module base directory 
 
(Get-Module –Name ADFSToolkit).ModuleBase


In addition, a new directory will be created on disk here: C:\ADFSToolkit\.  This directory contains the Task Scheduler job sync-ADFSTkAggregates.ps1.  This permits one or more aggregates to be loaded (or re-loaded) with a single command. 
Subsequent runs of “New-ADFSTkConfiguration” command in PowerShell will append a command to load that aggregate in the sync-ADFSTkAggregates.ps1 PowerShell script.

Importing the metadata through ADFSToolkit

Once the configuration has been created, the ADFSToolkit directory will contain the PowerShell script <sync-ADFSTkAggregates.ps1> used to load the aggregate.  To import the metadata, simply execute the sync-ADFSTkAggregates.ps1 command and observe the output on the screen or via the Event Viewer in the ADFSToolkit event log.

This command is designed to run repeatedly, synchronizing the aggregate and keeping it up-to-date. The first execution of the command may take more than one hour to synchronize all entities, and will run at about 100 entities per minute. Subsequent runs will perform more quickly in comparison, as the records have already been created and are only updated if a change is detected.

Note: You will notice some errors or warnings in the PowerShell Console window. This is expected and you can review details in the Event Viewer to determine severity or if any action needs to be taken.

In Case of a Problem

If for any reason you want to revert or remove all the trusts created from loading the aggregate, we have provided a command within the ADFSToolkit called unpublish-ADFSTkAggregates to do just that. If this command is invoked without any arguments, it will assume the default prefix of ‘ADFSTk’. The metadataPrefix is the value you set for each of the entities when they are loaded and is stored in the configuration file. You do not need to include the prefix separator of a colon “:” in the prefix definition. 

This command will select all entities with this prefix and delete them. Please take special care using this command, as it is a non-reversible, destructive action.

Scheduling sync-ADFSTkAggregates to Run

ADFSToolkit automatically creates a scheduled job with a default status of “Disabled”, allowing you to make edits to the configuration settings and to test them before enabling the automatically scheduled operation.

An hourly cycle is recommended and should be activated by the administrator to ensure your AD FS system is always synchronized with the SWAMID metadata.

We also recommend that a service account is used to run the scheduled task.

Reviewing Runtime Logs

ADFSToolkit uses the Microsoft Windows Event Log infrastructure for application logging, available in the Event Viewer. Each record seen on the command line through manual execution is added to the logs and follows Microsoft recommendations for log rotation.

Configuring manual Attribute Release

ADFSToolkit externalizes attribute release settings per Relying Party (RP) away from AD FS by housing the attribute release policies in a single PowerShell script file (/config/getADFSTkManualSPSettings.ps1).

This allows administrators to refresh the attribute release for a given RP on each execution of the PowerShell script.  It also provides AD FS administrators a convenient way to centrally manage attribute release rather than trying to find an element in the AD FS Administration Console, which may list thousands of RPs.

This script contains a number of commented out attribute release sets that can be copied and uncommented to be put into effect. Lines beginning with the pound ‘#’ character denote a comment and will not execute if they contain code or commands.

The PowerShell script file to edit for releasing attributes is:

PowerShell 
 
~<install_home>/config/get-ADFSTkManualSPSettings.ps1

ADFSToolkit Operational Behaviour

ADFSToolkit (PowerShell Module) is designed for one installation per machine.  Attempting to install multiple instances of ADFSToolkit on a single host with different versions is possible, but it is not recommended or supported. 

The modular design of ADFSToolkit promotes code simplification and re-use, i.e. the settings and configurations can be re-used regardless of how many aggregates are loaded. Operational decisions and considerations should take into account the following best practices:

ADFSToolkit’s Lifecycle Management

ADFSToolkit’s Module uses the PowerShell Gallery tool command ‘Update-Module’ to manage delivery of updates.  Sites using ADFSToolkit are strongly encouraged to have a test system to review changes between versions.  In cases where there is no test system, a snapshot/backup of their environment is strongly recommended. 

Before running the Update-Module command, it is strongly recommended to back up the configuration directory of the module and the C:\ADFSToolkit directory. 

When an Update-Module is run, it will attempt to detect if there is a newer version and download it into another directory (containing version number).  ADFSToolkit will not run properly with more than one instance on disk.

At this time, the process to handle an update is to: