Run the Plugin Installer

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

The procedure to follow for installation depends 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 is 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 are primary servers and the procedure thus is 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 have already been entered on the first primary server.

To prevent installation errors, make sure that the Azure MFA method is not selected as an additional authentication method. Please see the troubleshooting section for details.

To get the installer file for the plugin, write to support@miracl.com.

The installation procedure is then a two-step process:

  1. Run the installer on the primary ADFS server.

You are asked to accept our License Agreement:

license

On a primary server, the next screen displays 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 client id 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 service which the plugin authenticates against. You can set the network timeout parameter and enable debugging which displays hostname and version number during ADFS authentication and stack trace info if errors occur. If you’re using pluggable verification to enrol users, it is important to check Allow Unknown State so the plugin allows receiving of requests with unknown state. Otherwise, we suggest to leave it uncheck so the plugin requires and validate requests state.

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 are 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 overwrites the original. Otherwise the original is left intact:

select_theme

  1. 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 are not asked to enter any configuration options. You are only 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 are then asked to confirm the installation without re-entering config details.