How to consume SWAMID metadata with ADFS Toolkit

Installation/upgrading Procedure

The latest documentation for installation and upgrading can always be found here:
https://github.com/fedtools/adfstoolkit

Update Procedure

  1. Get-ADFSTkHealth -HealthCheckMode Full
  2. https://release-check.swamid.se
  3. Copy-Item -Path C:\ADFSToolkit -Destination "C:\ADFSToolkit - 2.2.1 before upgrade 2.3.0" -Recurse
  4. Update-Module ADFSToolkit
  5. Get-InstalledModule ADFSToolkit -AllVersions
  6. Uninstall-Module ADFSToolkit -RequiredVersion 2.2.1
  7. Disable-ADFSTkInstitutionConfiguration
    We do this so no imports are run untill we’re certain that everything looks good
    Get-ADFSTkFederationDefaults -URL https://mds.swamid.se/qa/entity-configurations/ADFSToolkit/v2.3.0/SWAMID_FederationDefaults.zip -InstallDefaults
  8. Update-ADFSTk
    This new cmdlet will take care of all configuration updates, including Federation Defaults, ADFSTk Config and ADFSTk Institution config(s)
    If you have ADFSTkStore or ADFSTkRefedsMFA/ADFSTkRefedsSFA installed, you will be asked to upgrade them if needed.
    If you don’t have F-ticks installed you will be asked to install it.
  9. $ReleaseCheckSPs = Get-ADFSTkToolEntityId -Search release-check.swamid.se | Select -ExpandProperty Identifier
    $i = 0
    foreach ($ReleaseCheckSP in $ReleaseCheckSPs) {
        $i++
        Write-Host "Importing '$ReleaseCheckSP'... ($i/$($ReleaseCheckSPs.Count))" -ForegroundColor Yellow
        Import-ADFSTkMetadata -ConfigFile C:\ADFSToolkit\config\institution\config.Swamid.xml -EntityId $ReleaseCheckSP -ForceUpdate
    }
  10. Register-ADFSTkFTicksScheduledTask
  11. Enable-ADFSTkInstitutionConfiguration

Installation Procedure

Downloading the ADFS Toolkit uses Microsoft’s PowerShellGallery.com service as the official primary distribution channel of ADFS Toolkit as a PowerShell Module.  This allows us to rely on Microsoft’s approach to managing distribution and updated PowerShell Modules for the life cycle of ADFS Toolkit.

To install ADFS Toolkit you will need to:

  • Visit https://PowerShellgallery.com and follow the instructions to install the latest PowerShellGet Module from PowerShellGallery
  • Alter your Execution Policy for PowerShell scripts on your AD FS Server

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 ADFS Toolkit through PowerShellGallery as a known trusted source.  Until the certification process is in place, ADFS Toolkit requires the ability to run AD FS modules from unsigned origins.

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

PowerShell
Set-ExecutionPolicy -ExecutionPolicy Remotesigned

Installing 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, depending on your OS version, 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 #]

Creating the main configuration file

The main configuration file contains information about the federation the IdP exists in (SWAMID), what F-ticks server is used and other central data.

To create a new main configuration file, issue the following command:

New-ADFSTkConfiguration

When asked to choose federation from a list, choose SWAMID. 

Federation Defaults

The "Federation Defaults" is files provided by SWAMID that helps you configure ADFS Toolkit for our federation.
They also contain the specific SWAMID-versions of the Entity Categories which includes Swedish-specific attributes like norEduPersonNIN, etc.

When using the cmdlet Get-ADFSTKFederationDefaults you should point to the following URL:
https://mds.swamid.se/entity-configurations/ADFSToolkit/v2.3.0/SWAMID_FederationDefaults.zip

Change the version in the link to reflect the ADFS Toolkit version.

Like this:

Get-ADFSTkFederationDefaults -URL https://mds.swamid.se/entity-configurations/ADFSToolkit/v2.3.0/SWAMID_FederationDefaults.zip -InstallDefaults

Creating the Institution Config file

This file contains information about where ADFSToolkit can get attribute values. It doesn't say if they should be sent or not, this is handled by Entity Categories and Local Manual Settings, only where to get the data.

Attribute information is fetched through different Stores. Active Directory is the most common store, but SQL is also common. ADFSToolkit also support Custom Stores (created by you) and ADFSTkStore, a store that can do data manipulation in runtime, like Hashing, Base32 encoding and more.

To create a new main configuration file, issue the following command:

New-ADFSTkInstitutionConfiguration

If you installed the Federation Defaults for SWAMID you will be asked to choose production defaults, SWAMID_defaultConfigFile.xml, or test/QA defaults, SWAMID-QA_defaultConfigFile.xml. Choose the appropriate Federation Default file for your environment.

You will be prompted with some questions regarding the setup. If you selected a Federation Defaults file a suggested value is written in parentheses. To use this value, just press Enter, otherwise type your desired value and press Enter:

metadataURL: The URL to the federated metadata (https://mds.swamid.se/md/swamid-sp-transitive.xml).
Please provide a value for metadataURL:

The configuration item is default disabled. Before enabling it you need to configure all attributes and where ADFS can find them. to do so, open the configuration file in Power Shell ISE or Notepad++ or other application that can handle XML files in a good manner.

The Institution Config file created with SWAMID Federation Defaults can be found here:

C:\ADFSToolkit\config\institution\config.Swamid.xml

ADFS Toolkit Store

To support subject-id and pairwise-id we recommend that you install the ADFS Toolkit Store. It's a DLL that will help ADFS with data manipulation in runtime. The Store needs to be installed on all ADFS servers in the farm!

To install the ADFS Toolkit Store, issue the following command:

Install-ADFSTkStore

When installing on the first server you will be asked to generate a Salt. Unless you're migrating between farms, let the tool generate it for you. This will be saved in the ADFS database and can be found in AD FS Management tool under Services - Stores - ADFSTkStore. When installing on the other servers the same salt will be used.

Installing ADFSToolkit on the other servers in the farm

ADFS Toolkit Store, RefedsMFA and RefedsSFA needs to be installed on all servers in the farm. But it's also a good practice to have ADFS Toolkit installed on the other machines in case the main ADFS Toolkit server craches. 

Install the ADFS Toolkit module by issuing the following command:

Install-Module -Name ADFSToolkit

Instead of configuring it, copy the folder:

C:\ADFSToolkit

From the main ADFS Toolkit server to the other servers. All configuration for ADFS Toolkit is stored there.

Next install ADFS Toolkit Store and/or RefedaMFA/RefedaSFA (see above information or information on MFA Doc ADFSToolkit · GitHub

Scheduling Sync-ADFSTkAggregates to Run

ADFS Toolkit 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

ADFS Toolkit 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

ADFS Toolkit externalizes attribute release settings per Relying Party (RP) away from AD FS by housing the attribute release policies in a single PowerShell script file (Get-ADFSTkLocalManualSPSettings.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 
 
C:\ADFSToolkit\config\institution\get-ADFSTkLocalManualSPSettings.ps1

Import/re-import SWAMID Release Check SP's

It's a good idea to start testing your configuration by running SWAMID Release check (https://release-check.swamid.se).

There are quite some SP's to import or re-import so here's a small script to make it easier:

$ReleaseCheckSPs = Get-ADFSTkToolEntityId -Search release-check.swamid.se | Select -ExpandProperty Identifier

$i = 0
foreach ($ReleaseCheckSP in $ReleaseCheckSPs) {
    $i++
    Write-Host "Importing '$ReleaseCheckSP'... ($i/$($ReleaseCheckSPs.Count))" -ForegroundColor Yellow
    Import-ADFSTkMetadata -ConfigFile C:\ADFSToolkit\config\institution\config.Swamid.xml -EntityId $ReleaseCheckSP -ForceUpdate
}

ADFS Toolkit Operational Behaviour

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

The modular design of ADFS Toolkit 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:

  • Edits of the PowerShell script ADFSTkManualSPSettings.ps1 need to result in correct PowerShell syntax and function.
    • This script is used at runtime across all scheduled jobs or installations. If you edit and save the script file in an incomplete state, it will affect the operation of the job and result in possible failure or incomplete operation, both of which may have an impact on the stability of your production service.
    • Before making changes to the script, you should always make a backup copy so that you can revert to the last known “steady state” if needed.
    • Using a test environment outside of and separate from production during development and testing is strongly encouraged. Once edits have been fully verified, you can copy the script to your production environment and execute it in confidence. 
  • IMPORTANT: When you have completed editing ADFSTkManualSPSettings.ps1, you MUST reissue the Import-Module ADFS Toolkit command to capture the changes you have just created. This will also validate your PowerShell settings if there is a problem (i.e. fails to reload the module)
  • No labels