ADFS Plugin

Table of Contents:

Overview

Microsoft's Active Directory Federation Services (ADFS) is an Identity Provider (IdP) providing Single Sign-On for supporting client applications (e.g. Office365). ADFS authenticates users against an Active Directory instance and, optionally, a third-party MFA provider can be configured to provide an extra layer of authentication for added security. The MIRACL Trust® ZFA ADFS authentication provider is a plugin which enables you to use the MIRACL Trust® ZFA OIDC-based authentication platform as such a third-party MFA authentication provider for ADFS. The plugin is deployed on each ADFS server using a simple installation package, and does not require the installation of any other on-premise MIRACL services. It is then configured through the standard ADFS administration interface. The plugin does not provide or require any additional network endpoints and therefore no changes need to be made to incoming firewall rules. The plugin requires outgoing access to request the following urls: https://api.mpin.io/oidc/certs, https://api.mpin.io/oidc/token and https://api.mpin.io/.well-known/openid-configuration. The following diagram gives a high-level overview of the components involved:

flow_diagram

In order to setup the plugin, the following steps must be taken:

In the following instructions it is assumed that an ADFS server / server farm and a proxy (e.g. MSWAP) are set up and running as your organisation requires (https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/windows-server-2012-r2-ad-fs-deployment-guide) It is also assumed that any client applications (e.g. Office365) are already working with your ADFS instance.

  1. Create a new app in the MIRACL Trust® portal which gives you a client id and client secret to enable authentication with the MIRACL Trust® service (https://trust.miracl.cloud)

  2. Run the MIRACL Trust® ADFS plugin installer, entering the client id and client secret for your app when prompted. On a server farm, this must be run first on the primary ADFS server, then on each of the secondary servers without entering the client id and client secret again (the procedure for this varies slightly depending on whether you are running a standard / WID setup or a SQL setup)

  3. Activate the plugin in ADFS using the ADFS administration interface

  4. Configure users in Active Directory (Please note that in the MFA platform all identities are converted to lowercase. Hence, if you assign an email containing uppercase characters to a Windows user in Active Directory the user will be required to authenticate with the lowercase equivalent. For example John.Smith@example.com will need to authenticate as john.smith@example.com)

When users then access a configured client application, they will be guided through a two-step authentication process:

  1. The Primary Authentication phase, whereby they will enter their Active Directory username and password.

    primary_auth

  2. The Multi-Factor Authentication phase, whereby the MIRACL Trust® service will deal with final authentication of the user. At this point the user will be presented with a QR code which they can scan with their mobile app before entering their PIN to authenticate.

    mfa_auth

  3. The user's browser is then redirected back to the client application, and they are logged in.

Create a new app in the MIRACL Trust® portal

Login to your account at https://trust.miracl.cloud (or register if you do not already have an account).

Then click on Apps > Add new App (choose ADFS App)

The following endpoints need to be entered as redirect urls for your app (replace youradfshost.net with your actual ADFS host url):

a) https://youradfshost.net/adfs/ls/ This endpoint is called by client applications to request sign-on with ADFS.

b) https://youradfshost.net/adfs/ls/wia This endpoint is called during Windows Integrated Authentication (WIA), allowing login without username and password during Primary authentication

c) https://youradfshost.net/adfs/ls/idpinitiatedsignon This endpoint is called by a user logging in directly to ADFS

The following screenshot shows an app being created in the portal:

miracl_app

For domain just enter your company domain. For reporting purposes, the system will then identify registered users from e.g. @mycompany.com as internal and all others as external.
Click 'Show Keys' to display the Client ID and Client Secret which you will need in the next step.

Run the MIRACL Trust® plugin installer

Before proceeding, please verify that your ADFS server is running and operational. In the process of installation, ADFS will be restarted several times

The procedure to follow for installation will depend on what ADFS setup you are working with. This could be one of:

  • Standard / Windows Internal Database (WID) installation. In this case, the plugin is first installed with configuration details (client ID, Client secret etc.) on the primary server. The installer must then be run on all secondary servers, in which case it will be automatically detected that configuration details do not need to be added again.

  • SQL installation. If an ADFS server farm has been set up with a SQL database, all the servers will be primary servers and the procedure will thus be slightly different. The full installer with configuration details should be run on one primary server only. The installer then still must be run on the remaining primary servers. However, as the installer detects another primary server, the 'Deploy Configuration' box which appears after the license agreement should be unticked to prevent having to re-enter the configuration details which will have already been entered on the first primary server.

The installer file for the plugin can be found at http://repo.miracl.com/?prefix=windows/adfs-plugin/ (note that the highest numbered build is the latest stable version, while the un-numbered Miracl.Zfa.Adfs.Installer.exe is the absolute latest version which may not be stable)

The installation procedure is then a two-step process:

  1. Run the installer on the primary ADFS server

    You will be asked to accept our License Agreement:

    license

    On a primary server, the next screen will display the Deploy Configuration tick-box. Make sure this is ticked if you are running the installer for the only primary server in a standard / WID setup, or for the first primary server in a SQL server farm:

    install_deploy

    In the subsequent screen, you can then enter your client id and client secret, as obtained from the portal and described above. You also need to choose a Session Secret:

    The Session Secret parameter is a secret used to encrypt the state data passed around during the authentication process. It must be a hard to guess strong string and it is subject to the following rules:

    • It must contain both uppercase and lowercase and digits
    • It must contain non alphanumerics !£$$%^&*()_+{}:@~<>?|¬-=[];'#,./` but not " or \
    • Session Secret supports international characters such as cyrillic, e.g. Здравей*_1234)
    • It must contain 10 characters or more
    • It must not contain the clientid or client secret of your MIRACL Trust® app

    options

    Advanced configuration options are then displayed.

    Note that these are for expert users only, and should be left as is unless there is a specific requirement to change them

    adv_config

    Server Base Address displays the IssuerURL (https://api.mpin.io) of the MIRACL Trust® ZFA service. Server Base Address combines with the Discovery Path to give the url (https://api.mpin.io/.well-known/openid-configuration) which returns the OIDC parameters which are used by the service. You can set the network timeout parameter and enable debugging which will display hostname and version number during ADFS authentication, and stack trace info if errors occur.

    Code Pad Uri should be set as https://mcl.cdn.mpin.io/mpad/mpad.js (note that it begins with mcl)

    Debugging mode should only be enabled for test purposes and should never be enabled in production. For debugging in production, the Windows server event log gives stack trace and other information.

    Also note that, due to limitations with ADFS, the only way to turn off debugging mode is to re-run the MIRACL installer

    At this point you will be asked to choose the name for the ADFS web theme. The MIRACL Trust® ADFS installer makes a slight adjustment to the original ADFS web theme, which is made active immediately. If you name the theme exactly the same as the original theme, it will overwrite the original. Otherwise the original will be left intact:

    select_theme

  2. Run the installer on the remaining ADFS servers

    It is now necessary to run the installer on all remaining servers.

    When, in a standard / WID setup, you run the installer on a secondary server, you will not be asked to enter any configuration options. You will only be asked to confirm the License Agreement and then begin the installation:

    begin_install

    However, in a SQL setup, all servers are primary servers, so it is necessary to make sure the Deploy Configuration box is unticked:

    install_deploy

    You will then be asked to confirm the installation without re-entering config details.

Activate the plugin in ADFS

Once installed you will need to configure the plugin in the ADFS management console on the primary server. To do this in Windows server 2012, select 'Authentication Policies' on the left, followed by 'Edit Global Multi-Factor Authentication':

adfs1

In Windows server 2016 the wording is slightly different:

adfs1_2016

You can then tick the 'MIRACL Trust® ZFA' box to activate the plugin, as in Windows server 2012:

adfs2

Here you can add the users, groups, devices and locations for which MIRACL Trust® ZFA login is required (further information can be found here)

Again, the setup in Windows Server 2016 is slightly different:

adfs2_2016

Configure users in Active Directory

Please note that in the MFA platform all identities are converted to lowercase. Hence, if you assign an email containing uppercase characters to a Windows user in Active Directory the user will be required to authenticate with the lowercase equivalent. For example John.Smith@example.com will need to authenticate as john.smith@example.com.

For each user, the 'user logon name' in their 'Account' tab is their AD username which they will use in the Primary Authentication phase of the login process:

adfs_user2

The email address entered in the 'General' tab is then the email that they must use for the MFA stage of the authentication process - i.e. with the MIRACL authentication server:

adfs_user1

Verification of installation

You can verify your installation by using the IdP-initiated sign-on url, i.e. https://youradfshost.net/adfs/ls/idpinitiatedsignon Note that your device, user and location must be within the parameters of your Global Authentication Policy.


Terminal installation procedure


It is also possible to install the plugin via the terminal. Please make sure you have read and understood the above notes on the plugin installer which explain the correct process for installation on either Standard / WID or SQL setups.

When the installer is run on a main primary server, the client ID and client secret for your app need to be passed, plus a session secret (see above note on session secret rules). Note that, in order to support special characters (^ < > | & /), the values entered must be escaped with "" double-quotes. Also note that Session Secret supports international characters such as cyrillic, e.g. /SESSION_SECRET="Здравей*_1234"

In any command, /S runs the installer silently. Note that, as mentioned above, ADFS will be restarted several times in the process of installation.

Standard / WID setup

The following example is for installation on the primary server:

start "" /WAIT Miracl.Zfa.Adfs.Installer.exe /S /CLIENT_ID="glc_votxda4" /CLIENT_SECRET="sdf_efdyD*-iswle18" /SESSION_SECRET="SecRet_1234$" /CODE_PAD_URI="https://mcl.cdn.mpin.io/mpad/mpad.js" /THEME_NAME="miracl"

The following example is for installation on a secondary server:

start "" /WAIT Miracl.Zfa.Adfs.Installer.exe /S

It is important that the installation commands are prefixed with start "" /WAIT as this will ensure the correct ERRORLEVEL is returned (0 indicating success and non-0 indicating failure).

SQL setup (multiple primary servers)

As per the standard setup, the following example is for installation on the primary server:

start "" /WAIT Miracl.Zfa.Adfs.Installer.exe /S /CLIENT_ID="glc_votxda4" /CLIENT_SECRET="sdf_efdyD*-iswle18" /SESSION_SECRET="SecRet_1234$" /CODE_PAD_URI="https://mcl.cdn.mpin.io/mpad/mpad.js" /THEME_NAME="miracl"

And for installation on subsequent primary servers, /DEPLOY_CONFIG should be set to 0:

start "" /WAIT Miracl.Zfa.Adfs.Installer.exe /S /DEPLOY_CONFIG=0

Note that /DEPLOY_CONFIG=0 ensures that you are not asked to enter config details (Client ID, Client Secret etc.) again. It is necessary to set this on subsequent primary servers.

It is important that the installation commands are prefixed with start "" /WAIT as this will ensure the correct ERRORLEVEL is returned (0 indicating success and non-0 indicating failure).

Verification of installation

You can verify your installation by using the IdP-initiated sign-on url, i.e. https://youradfshost.net/adfs/ls/idpinitiatedsignon Note that your device, user and location must be within the parameters of your Global Authentication Policy.

Notes on using install scripts

When using windows batch files, commands will block until completion.

However, a key point to note is that, when scripting without windows batch files, the commands won't block until completion. In order to block it is necessary to prefix the commands with start "" /WAIT For example: start "" /WAIT Miracl.Zfa.Adfs.Installer.exe /S

Using start "" /WAIT in these scenarios will ensure that the correct ERRORLEVEL is returned. Without this there will be misleading error messages - it will only be indicated that commands are running without giving a 0 or non-0 on completion. echo %ERRORLEVEL% can also be used to check whether installation completed correctly, with 0 indicating success and non-0 indicating failure.

Parameter Reference

The following is a full list of the available parameters for terminal installation:

Parameter Default value Notes
/CLIENT_ID=
/CLIENT_SECRET=
/SESSION_SECRET=
/SERVER_BASE_ADDRESS= https://api/mpin.io Combines with the Discovery Path to give the url (https://api.mpin.io/.well-known/openid-configuration) which returns the OIDC parameters which are used by the service. This should be left as is and changed by Advanced users only
/DISCOVERY_PATH= .well-known/openid-configuration should be left as is and changed by Advanced users only
/CODE_PAD_URI= This should be https://mcl.cdn.mpin.io/mpad/mpad.js
/NETWORK_TIMEOUT= 10
/IS_DEBUG= 0 Set as 1 or 0 - Debugging mode should only be enabled for test purposes and should never be enabled in production. For debugging in production, the Windows server event log gives stack trace and other information
/DEPLOY_CONFIG= 1 on a primary server or 0 on a secondary Set as 1 or 0 (Please see above notes on the plugin installer for details on how to use this parameter )
/THEME_NAME= Set the ADFS web theme name for the newly-configured MIRACL ADFS plugin (see notes above)
/S Run installer silently
/D Sets the default installation directory ($INSTDIR), overriding InstallDir and InstallDirRegKey. It must be the last parameter used in the command line and must not contain any quotes, even if the path contains spaces. Only absolute paths are supported. For example: /D=C:\Program Files\MIRACLADFS
/NCRC Disables the CRC check (an error-checking mechanism, similar to a checksum, that enables an application to determine whether the information in a file has been modified).

Top