New Features Included in version 2.0
Removed all sensitive information from pages (Security context and hidden fields). The TOTP key is never transmitted or inserted into a page.
RNG - a strong number generator (it was the default in versions 1.x)
RSA - The user keys are encrypted with RSA (certificate, verification information is included to be validated when checking the TOTP code)
Custom – Each user RSA key is encrypted with a distinct certificate, and validation is done when checking the TOTP code. this require a new database for storing certs (demo)
Possibility to manage your own keys, an API is provided: ISecretKeyManager
Following the various questions regarding the deployment of assemblies in the GAC, we provide an MSI installation file. The deployment of binaries is now fully automated.
The MSI file must be deployed on each ADFS server of your farm (never on proxy servers
All configuration actions can be performed using PowerShell CmdLets (see later)
All configuration actions can be performed with an MMC extension (not yet operational in this beta version)
Policies for integrating users with MFA
Custom templates for emails
Users management
- Adding, Deleting, Updating, Enabling users (PS, MMC)
- Import Users (PS, MMC) – not available in this beta
Configuration management
- Management of all config properties (ADDS, SQL, Mail, Keys, SMS, Common) via PS and MMC, no need to edit xml file.
- Soft update between server farm (no need to restart instances)
- Upgrade from previous versions of adfsmfa.
msi installation does not configure adfsmfa,
it is responsible for deploying the components on the system, in the GAC and in Program Files, correctly register services and MMC snapin, create a shortcut on the desktop.
this step don’t require that you unconfigure adfsmfa. For example when patching or deploying a new version. You can patch each server at time (disabling the node in NLB). in this case no more actions are required, the system must be “operational”.
uninstallation does not unconfigure or disable MFA, so you need to install a new version quickly. If you don’t want to use MFA you must run Disable-MFASystem or UnRegister-MFASystem PS Cmdlet before unintalling binaries.
Component registration can only be done with a PS Cmdlet Register-MFASystem.
The registration process create component Registration with ADFS Farm, and optionally activate the component as an active MFA provider in your ADFS Farm.
You can also decide to set the security configuration (default RNG or RSA or RSA per user).
This is the configuration you are using, whether it is a first installation or a new ADFS farm.
- Create a new default configuration that is using ADDS and RNG 512 bytes for users keys generation.
Register-MFASystem –Activate –RestartFarm –Verbose
- Create a new default configuration using ADDS and RSA 2048 bytes for users keys generation. duration of certificate is set to 10 years (default is 5)
Register-MFASystem –Activate –RestartFarm –KeyFormat RSA –RSACertificatDuration 10 –Verbose
- Create a new default configuration using ADDS and RSA 2048 bytes for users keys generation, one key for each user. duration of certificate is set to 2 years (default is 5)
Register-MFASystem –Activate –RestartFarm –KeyFormat CUSTOM –RSACertificatDuration 2 –Verbose
This configuration (CUSTOM) require additional configuration, a custom database for storing al users keys and certificates (see New-MFASecretKeysDatabase)
This is the configuration you are using, when you want to upgrade from adfsmfa 1.x
Register-MFASystem –Activate –RestartFarm –AllowUpgrade –BackupFilePath “.\myconfig 1.2.xml”
When upgrading, It is not recommended to change KeyFormat, in this case all user keys would become invalid
- Log on the ADFS server you want to add to your farm for MFA as administrator
- Launch a new PowerShell session as administrator
- type get-help Register-MFAComputer –detailed to get information.
- Enter your command
Register-MFAComputer
When you add an ADFS Server to your farm, you must execute Register-MFACompter to add this computer to the MFA servers list (used by notification system).
This operation is also needed if your ADFS farm servers are 2012 R2, for 2016 Register-MFASystem can do the job without need to register the computer with Register-MFAComputer.
UnRegister-MFAComputer
Removing an ADFS Server from the MFA farm doesn’t remove the server from ADFS farm
. Server is removed from MFA servers list. So, no notification can occur, and some commands will not operate.
Notifications are used to sync configuration changes without restarting ADFS instances. for example, if you change the password in SMTP configuration, this modification is “live” updated on all servers in the MFA list.
UnRegister-MFASystem completely removes adfsmfa for the ADFS configuration. adfsmfa is removed from ADFS’s MFA providers list and configuration is deleted.
You can backup your adfsmfa configuration in a file.
- Log on the Primary ADFS server of your farm as administrator
- Launch a new PowerShell session as administrator
- type get-help UnRegister-MFASystem –detailed to get information.
- Enter your command
UnRegister-MFASystem
or
UnRegister-MFASystem –BackupFilepath .\myconfig.xml –RestartFarm –Verbose
No need to uninstall this beta version, you can run the following as follow :
UnRegister-AdfsAuthenticationProvider -Name "MultifactorAuthenticationProvider" -Confirm:$false
$typeName = "Neos.IdentityServer.MultiFactor.AuthenticationProvider, Neos.IdentityServer.MultiFactor, Version=1.2.0.0, Culture=neutral, PublicKeyToken=175aa5ee756d2aa2"
Register-AdfsAuthenticationProvider -TypeName $typeName -Name "MultiFactorAuthenticationProvider" -Verbose -ConfigurationFilePath ".\myconfig 1.2.xml"
net stop adfssrv
net start adfssrv
As in versions 1.x, it is necessary to modify some basic properties of the MFA configuration. As a general rule, the default values propose optimal operation.
Define the mail from the administrative contact, choose ADDS Mode and SQL Mode, set the security policy remain options to which we can not respond by default.To view your configuration you must use PowerShell applets or the MMC (not operational now).
Get-MFA Config
or
$config = Get-MFAConfig
$config
Properties |
Values |
Comments |
RefreshScan |
3000 |
When running async operations like sending email or SMS, time between to check for the external call (default 3 seconds) |
DeliveryWindow |
300 |
An OTP code change every 30 seconds, no network transmission occurs, it’s computed. but for external systems we rely on the transmission of the data like email providers or SMS gateways, the time to distribute the access code to the user is not guaranteed. DeliveryWindow is the maximun time allowed for submitting the OTP Code. this value is in seconds 300 (5 minutes) |
TOTPShadows |
2 |
An TOTP code change every 30 seconds, so the user have to quickly submit the code to ADFS, for better user experience this property allow to “remember” and accept the current generated code and the x previous. in this case the user has 1,30 minute max to enter a generated TOTP. |
MailEnabled |
true |
Enable the use of emails for sending access code. default is true. |
SMSEnabled |
true |
Enable the use of “ExternalOTPProvider” aka SMS for sending access code. default is true. A sample working with Azure MFA is provided and must be configured according your Azure subscription. An API is provided if you want to implement custom Provider to work for example with your Phone provider or manage high security options. see implementing IExternalOTPProvider |
AppsEnabled |
true |
Enable the use of TOTP client applications like Microsoft Authenticator or Google Authentication. TOPT algorithm RFC 6238. this the default mode and it’s true by default. Remember ! this protocol is considered more secure by security experts, because in first, no data is sent on the wire. |
Algorithm |
SHA1 |
Hash used when computing the TOTP code, RFS 6238 allow other HASH functions, but Google never implement it, so SHA1 is the only one HASH function for TOTP codes. TOTP code is generated with the user secret Key, the utc time, SHA1 hashing and Base 32 encoding SHA1 is compatible with the internet providers applications (MS, Google), but it’s possible to create a new client app with custom security |
Issuer |
specific |
String representing your company (eg : contoso), you must change it. this property is used in email and SMS for example. default value is : MFA |
UseActiveDirectory |
true |
This property allows you to set the operating mode for storing user credentials. The default is to use Active Directory (requires an AD 2012 schema, and uses the msDS-cloudExtensionAttribute10 attributes to msDS-cloudExtensionAttribute18), or to store this information on SQLServer in a specific database (see New-MFADatabase ). See later “Choose between ADDS or SQL mode” |
CustomUpdatePassword |
true |
Use of our custom “Change password form”, after identification when managing user properties. if No, use of standard ADFS form if your ADFS administrators have enabled required endpoint : /adfs/portal/updatepassword/ |
DefaultCountryCode |
FR |
Default country code, used with phone numbers when trying to validate. US, ES and more |
AdminContact |
valid email |
A valid email used by users to send request to your administrators |
UserFeatures |
Used to configure how users can register or enable their MFA account, and if users can manage their options alone. Values must be mixed with a binary OR. It’s more simple to use Set-MFAPolicyTemplate and use predefined models |
|
AdvertisingDays |
1-31 |
When users are prompted to register their account for MFA. Specifies the range of days during which a callback is imposed |
to change configuration values you must use Set-MFAConfig Cmdlet
$config = Get-MFAConfig
$Config.UseActiveDirectory = $false
Set-MFAConfig $config
During the initial configuration of the component, there is a very important configuration parameter to take into account: UseActiveDirectory.
You can decide whether to store users' MFA metadata in ADDS attributes or to use SQLServer as a repository.
Below are a few items that can help you choose.
The default is to use ADDS as repository
ADDS |
ADDS Comments |
SQL |
SQL Comments |
|
Single ADFS Server |
Yes |
Pro Most simple configuration. No need of external platform. Data is replicated against All DCs Can work with any ADDS Schema version Cons Data replication can take some time Not a good practice to write on AD Default config require ADDS Schema 2012 version |
Maybe |
Pro Easy to share data with other applications No replication of data needed Must be used with “AdfsLocalClaimsProviderTrust” and “AdfsLdapServerConnection” ADFS 2016 Can use Windows Internal Database if only ONE ADFS server Cons Need of additional platform (SQL-Server). No replication of data, need backup strategy. Management is let to DBAs, not to security admins. |
Multiple ADFS Servers |
Yes |
Pro Simple configuration. No need of external platform. Data is replicated against All DCs Can work with any ADDS Schema version Cons Data replication can take some time Not a good practice to write on AD Default config require ADDS Schema 2012 version |
Yes |
Pro Easy to share data with other applications No replication of data needed Must be used with “AdfsLocalClaimsProviderTrust” and “AdfsLdapServerConnection” ADFS 2016 Cons Need of additional platform (SQL-Server). No replication of data, need backup strategy. Management is let to DBAs, not to security admins. Depending of your network configuration (DMZ or other) access to SQL instance must be granted and secured. |
I want to use RSA security options |
Yes |
it’s a feature |
Yes |
It’s a feature |
I want to use CUSTOM RSA security options |
Yes |
Pro it’s a feature Cons Require additional configuration (New-MFASecretKeysDatabase) Require a SQLServer Server for storage |
Yes |
Pro it’s a feature Cons Require additional configuration (New-MFASecretKeysDatabase) Require a SQLServer Server for storage |
can I use AdfsLocalClaimsProviderTrust to authenticate users stored in LDAP server and use MFA |
No |
ADFS requirements by design. We cannot store users metadata in external LDAP server. |
Yes |
LDAP users can be registered with MFA when using SQL Mode |
If you have choose to use ADDS, you must verify or modify your ADDS config.
To view your configuration you must use PowerShell applets or the MMC (not operational now).
Get-MFAConfigADDS
or
$config = Get-MFAConfigADDS
$config
Properties |
Values |
Comments |
Account |
empty (optional) |
All request to ADDS are made under ADFS Service Account. If you have authentication problems, you can specific the account you want to use to access ADDS forest. domain\account is the required format or managed account domain\account$ |
Password |
Empty (optional) |
Password used with custom account |
DomainAddress |
Empty (optional) |
domain address in LDAP format : mydomain.com |
KeyAttribute |
msDS-cloudExtensionAttribute10 |
Attribute used to store the user key (RNG, RSA) |
MailAttribute |
msDS-cloudExtensionAttribute11 |
Attribute used to store personal email address |
PhoneAttribute |
msDS-cloudExtensionAttribute12 |
Attribute used to store mobile phone number |
MethodAttribute |
msDS-cloudExtensionAttribute13 |
Attribute used to store user’s preferred method for MFA (Code, Mail, SMS, Choose) |
NotifCreateDateAttribute |
msDS-cloudExtensionAttribute14 |
DateTime when OTP is requested |
NotifValidityAttribute |
msDS-cloudExtensionAttribute15 |
DateTime for OTP validity |
NotifCheckDateAttribute |
msDS-cloudExtensionAttribute16 |
DateTime of OTP validation |
TOTPAttribute |
msDS-cloudExtensionAttribute17 |
OTP code value |
TOTPEnabledAttribute |
msDS-cloudExtensionAttribute18 |
Boolean, specify if the user account for MFA is enabled. Access would be allowed depending of the Policy Template you choose. |
to change configuration values you must use Set-MFAConfigADDS Cmdlet
$config = Get-MFAConfigADDS
$Config.MailAttribute = “emailaddress”
Set-MFAConfigADDS $config
If you have choose to use SQL mode, you must verify or modify your SQL config.
To view your configuration you must use PowerShell applets or the MMC (not operational now).
Get-MFAConfigSQL
or
$config = Get-MFAConfigSQL
$config
to initialize an MFA Database you have to run New-MFADatabase Cmdlet applet or the MMC snapin.
The account under witch you run New-MFADatabase Cmdlet must have the SQLServer dbcreator role.
Using an SQL account for connecting to the MFA Database
New-MFADatabase -ServerName SQLServer\Instance -DatabaseName MFADatabase -UserName sqlaccount -Password pass
Using a domain account for connection to the MFA Database
New-MFADatabase -ServerName SQLServer\Instance -DatabaseName MFADatabase -UserName Domain\ADFSaccountUsing ADFS managed account for connecting to the new MFA Database
New-MFADatabase -ServerName SQLServer\Instance -DatabaseName MFADatabase -UserName Domain\ADFSManagedAccount$The ConnectionString property is set after executing this command.
Grant of SQL rights are made for the specified account.
To change manually the ConnectionString
$config = Get-MFAConfigSQL
$config.ConnectionString = “Persist Security Info=False;Integrated Security=SSPI;Initial Catalog=MFADatabase;Data Source=sqlserver\instance” // Using ADFS Service Account Identity
Set-MFAConfigSQL $config
You must configure all the properties related for sending emails
To view your configuration you must use PowerShell applets or the MMC (not operational now).
Get-MFAConfigMails
or
$config = Get-MFAConfigMails
$config
Properties |
Values |
Comments |
UserName |
|
Valid UserName to connect to your SMTP platform |
Password |
Valid Password to connect to your SMTP platform |
|
From |
Valid sender email present in your SMTP platform |
|
Host |
smtp.office365.com (sample) |
Valid HostName to connect to your SMTP platform |
Port |
587 |
Valid port to connect to your SMTP platform |
UseSSL |
true |
|
Company |
the name of your organization (used in emails sent by MFA) |
|
MailOTP |
If you want to use your own e-mail templates for sending TOTP codes by mails |
|
MailInscription |
If you want to use your own e-mail templates for sending inscription requests by mails |
|
MailSecureKey |
If you want to use your own e-mail templates for sending users keys by mails |
|
For mail templates you must provide 3 properties - LCID for localization - FileName path to html file - Enabled Is the template active Your html files must contains placeholders - {0} Company - {1} User Name - {2} Mail address - {3} Phone number - {4} Preferred MFA method (code, mail sms) |
to change configuration values you must use Set-MFAConfigMails Cmdlet
$config = Get-MFAConfigMails
$Config.Password = “mypass”
Set-MFAConfigMails $config
Implementing an External OTP Provider
Why use this API?
- You need to get an access code for single use from an external source, an SMS provider, RSA appliance, Azure, Google or just a pin code stored in your information system.
In this case ADFS take the provided code to validate the two-factor authentication.
At this point, I remind you the original objectives of this project:
Provide you a basis for implementing your own solution.
To compensate for the different demands of customers not wishing to rely on a third party service, concerned with issues of confidentiality or security.
I remind you that there are a large number of solutions provided by third-party publishers and validated by Microsoft (Gemalto, EMC, Login People, Azure MFA (PhoneFactors), and many others)
https://TechNet.Microsoft.com/en-us/library/dn758113(v=WS.11).aspx
How to code your own solution?
- You must create a new project with Visual Studio (2012, 2013, 2015) of type assembly .net (Framework 4.6.2 and up)
- Reference Neos.IdentityServer.MultiFactor.Common.dll and implement the interface "IExternalOTPProvider"
There is only one method to encode with the provided parameters you must return a valid code or even zero to indicate an error.
- int GetUserCodeWithExternalSystem (string upn, string phonenumber, string email, ExternalOTPProvider externalsys, CultureInfo culture);
- Parameters
- upn : user id;
- phonenumber : Phone number for the user if provided.
- email : email address for the user if provided
- Culture : a CultureInfo object, can be used for Globalization scenarios.
- ExternalOTPProvider : a wrapper class (Neos.IdentityServer.MultiFactor.Common.dll) used to deserialize metadata stored in configuration file used by ADFS
- Company : string describing your company
- DefaultCountryCode : default country code for sms calls, if not provided in the user’s phone number
- Sha1Salt : your salt for hashing the message.
- FullQualifiedImplementation : Full description for your assembly and class (implementing IExternalOTPProvider), this type will be dynamically loaded and executed at runtime
- Parameters : Your custom parameters, are stored in CDATA in configuration file. it’s up to you to parse, decrypt, deserialize this value.
Configuring the Azure MFA demo
To use this demo, you must configure authentication multi-factor on your subscription Azure or Office 365 (AAD). Note, that this feature is subject to a payment either by user ($ 1.49 per month) or the number of queries (10 requests $ 1.49)
You must be administrator Global to set up MFA Azure. If you have a valid MSDN account, you can activate your subscription.
You can of course use the solution provided by Microsoft, in this case there is no need of our component.The demo provided uses the MFA Azure SDK. You must follow the explanations given in the following link: https://azure.microsoft.com/en-us/documentation/articles/multi-factor-authentication-sdk/Once Azure configured, as well as the recovery of the SDK (asp.net).
Take your client certificate from SDK (aka: "c:\\cert_key.p12") and install it in the machine certificate store with the password in the provided source pf_auth.cs (CERT_PASSWORD)
In this file, please retrieve the values of the following constants:
private const string LICENSE_KEY = "Your license key";
private const string GROUP_KEY = "Your group key";
private const string CERT_PASSWORD = "client certificate password";
You will notice that the example does not use the certificate that is stored on disk as in the SDK, it's not very secure...
so you need to retrieve the thumbprint of the certificate when this one will be deployed correctly in the Machine certificate store.You’re Done !
To view your configuration you must use PowerShell applets or the MMC (not operational now).
Get-MFAExternalOTPProvider
or
$config = Get-MFAExternalOTPProvider
$config
Properties |
Values |
Comments |
Company |
Your company name |
|
Sha1Salt |
0x123456789 |
Any salt value |
FullQualifiedImplementation |
Auto generated |
Neos.IdentityServer.Multifactor.SMS.SMSCall, Neos.IdentityServer.Multifactor.SMS.Azure, |
IsTwoWay |
true/false |
Indicates whether the answer code is to be returned by phone or whether the user must enter this code in the ADFS page |
Timeout |
300 |
In seconds, max call duration to external provider |
Parameters |
Your parameters stored as cdata section you must use Parameter.Data = “Your values” For the Azure example, the format is the following LICENSE_KEY = yourlicencekey, GROUP_KEY = yourgroupkey, CERT_THUMBPRINT = |
to change configuration values you must use Set-MFAExternalOTPProvider Cmdlet
$sms = Get-MFAExternalOTPProvider
$sms.Parameters.Data = "LICENSE_KEY = V2J41MNLAAAAA, GROUP_KEY = 320034002743b0063600e21500ed154f, CERT_THUMBPRINT = FFFFFFFFFF51AD10D5FAAAAE8A22BBBBBBD241AC"
Set-MFAExternalOTPProvider $sms
With the 2.0 version we supports 3 Kind of Keys that are used to generated TOTP code and QRCode (RNG, RSA, CUSTOM).
The default value is RNG like in versions 1.x for compatibility.
To view your configuration you must use PowerShell applets or the MMC (not operational now).
- Log on the Primary ADFS server of your farm as administrator
- Launch a new PowerShell session as administrator
- type get-help Get-MFAConfigKeys to get information.
- Enter your command
Get-MFAConfigKeys
or
$config = Get-MFAConfigKeys
$config
Properties |
Values |
Comments |
KeyGenerator |
ClientSecret512 |
RNG : number length in bytes - Guid - ClientSecret128 (128 bytes) - ClientSecret256 (256 bytes) -ClientSecret384 (384 bytes) - ClientSecret512 (512 bytes) - default |
KeySize |
KeySize1024 |
ALL : max key length to generate TOTP code Even, if the user key is 2048 bytes length. it will be truncated for better rendering of QRCode. 2048 or 4096 generates a huge QRCode that phone apps can’t capture
- KeySize512 (512 bytes) - KeySize1024 (1024 bytes) - KeySize2048 (2048 bytes) |
KeyFormat |
RNG |
RNG : is a strong Random Number Generator RSA : is one certificate RSA encryption with user identity and verification (SHA256) CUSTOM : One certificate per user, RSA encryption with user identity and verification (SHA256). must create a separate database for storing users keys |
CertificateThumbprint |
cert thumbprint |
RSA only |
CertificateValidity |
5 |
RSA and CUSTOM Duration of certificates (in years) |
ExternalKeyManager |
CUSTOM only |
|
(ExternalKeyManager).FullQualifiedImplementation |
CUSTOM only Your implementation of ISecretKeyManager Default Neos.IdentityServer.Multifactor.Keys.CustomKeyManager, |
|
(ExternalKeyManager).Parameters |
CUSTOM only Your parameter as cdata, you must use “Parameters.Data” to change value Default ConnectionString to the database created with New-MFASecretKeysDatabase |
to change configuration values you must use Set-MFAConfigMails Cmdlet
$keys = Get-MFAConfigKeys
$keys.KeyFormat = CUSTOM
$keys.Parameters.Data = “mycustomdata”
Set-MFAConfigKeys $keys
Changing the certificate IN RSA mode
to install a new certificate for RSA encryption you have to run Install-MFACertificate Cmdlet applet or the MMC snapin.
The account under witch you run Install-MFACertificate Cmdlet must have the Administrator role for the server.
The certificate is also stored in ADFS configuration.
Install-MFACertificate
Install-MFACertificate -RSACertificateDuration 10 –RestartFarm
Remember changing the certificate invalidates all the users keys, you must use it if you want to renew all the keys.
Creating Keys Database in CUSTOM mode
to initialize an MFA Database you have to run New-MFASecretKeysDatabase Cmdlet applet or the MMC snapin.
The account under witch you run New-MFASecretKeysDatabase Cmdlet must have the SQLServer dbcreator role.
Grant of SQL rights are made for the specified account.
New-MFASecretKeysDatabase -ServerName SQLServer\Instance -DatabaseName MFAKeysDatabase -UserName Domain\ADFSaccount
get-help New-MFASecretKeysDatabase
to get the complete list of MFA CmdLets : get-help *-MFA*
To get the list of each mfa CmdLet you must press <TAB>
Farm management
Register-MFASystem
Unregister-MFASystem
Register-MFAComputer
Unregister-MFAComputer
Enable-MFASystem
Disable-MFASystem
Get-MFAComputers
Restart-MFAComputer
Get-MFAFarmInformation
Restart-MFAFarm
Install-MFACertificate
New-MFADatabase
New-MFASecretKeysDatabase
Users management
Get-MFAUsers
Set-MFAUsers
Add-MFAUsers
Remove-MFAUsers
Enable-MFAUsers
Disable-MFAUsers
General configuration management
Get-MFAConfig
Set-MFAConfig
Set-MFAPolicyTemplate
SQL configuration management
Get-MFAConfigSQL
Set-MFAConfigSQL
New-MFADatabase
ADDS configuration management
Get-MFAConfigADDS
Set-MFAConfigADDS
SMTP configuration management
Get-MFAConfigMails
Set-MFAConfigMails
KEYS Manager configuration management (RNG, RSA)
Get-MFAConfigKeys
Set-MFAConfigKeys
SMS configuration management
Get-MFAExternalOTPProvider
Set-MFAExternalOTPProvider