|
|
| (6 intermediate revisions by the same user not shown) |
| Line 4: |
Line 4: |
| | [[Category:ADFS|A]] | | [[Category:ADFS|A]] |
| | | | |
| − | For ADFS 4: [[Microsoft ADFS 4 and 3 Authentication]]
| + | This article has been merged with the article for ADFS 4: [[Microsoft ADFS 4 and 3 Authentication]]. Please see that article. |
| | | | |
| − | | + | For ADFS version 2 see [[Microsoft ADFS 2 Integration]]. |
| − | = Introduction =
| |
| − | | |
| − | This article describes the Swivel Authentication Provider for ADFS 3, which is included in the Microsoft Windows 2012 R2 Server Operating System. For ADFS version 2 see [[Microsoft ADFS 2 Integration]]
| |
| − | | |
| − | Version History:
| |
| − | | |
| − | * 1.4.3.0 Fixed problems with monitoring standby appliance. Option to hide OTC for PINpad. Faster PINpad when connecting to cloud instances.
| |
| − | * 1.4.2.0 Support for Push added. Support for a standby appliance added. Various bug fixes.
| |
| − | | |
| − | * 1.3.1.0 Bug fixes. Support for cross-origin resource policies. ADFS 4 compatible.
| |
| − | * 1.0.6.1 Added option not to show TURing or PINpad automatically
| |
| − | * 1.0.5.3 Fix for special characters in username
| |
| − | * 1.0.4.1 Various bug fixes and added logging
| |
| − | * 1.0.3.2 Advanced connections added. Fixed language strings configuration.
| |
| − | * 1.0.2.1 Bug fix: in certain circumstances, the first security string would not work and refresh was required to authenticate
| |
| − | * 1.0.1.2 Fix to work with secondary ADFS servers
| |
| − | * 1.0.0.0 Initial release
| |
| − | | |
| − | = Requirements =
| |
| − | | |
| − | This solution only works with Windows Server 64-bit, with the ADFS role installed. This should be installed and tested before installing the Swivel provider. Version 1.4.2 has been tested against Server 2019, 2016 and 2012 R2. Version 1.3.1 has been tested against Server 2016 and 2019. Version 1.0.x has been tested against Server 2012 R2.
| |
| − | | |
| − | The Swivel proxy component can be installed separately, either on the ADFS proxy or any other Windows PC with IIS and ASP.Net 4.5 installed, and exposed publicly, either directly or through a proxy.
| |
| − | | |
| − | ==Current Version Installer==
| |
| − | | |
| − | The installer for version 1.4.2 of the Swivel ADFS Authentication Provider can be found [https://kb.swivelsecure.com/w/images/8/87/SwivelAuthProviderInstall.1.4.2.zip here].
| |
| − | | |
| − | ==Previous Versions==
| |
| − | * The installer for version 1.3.1 of the Swivel ADFS Authentication Provider can be found [https://kb.swivelsecure.com/w/images/7/79/SwivelAuthProvider.1.3.1.zip here].
| |
| − | * Version 1.0.6.1 can be found [https://kb.swivelsecure.com/wiki/images/f/fa/SwivelAuthProviderInstall.zip here].
| |
| − | | |
| − | ==Networking Requirements==
| |
| − | | |
| − | The following network connections are required in order for this product to work with ADFS. All connections use HTTP(S):
| |
| − | * Connection between the ADFS server and the Sentry appliance, or load balancer if used, on port 8080 if connecting directly to the Core Sentry application, or port 8443 if using the appliace proxy.
| |
| − | * If you are using a proxy for the TURing / PINpad images, you will need the same connections from the proxy to the appliance.
| |
| − | | |
| − | Note that it is possible to configure the appliance proxy to redirect to port 443, in which case you can use this port rather than port 8443.
| |
| − | | |
| − | = Installation =
| |
| − | | |
| − | NOTE: If you are installing on the ADFS server(s) and one or more proxies (see below), you should install on the ADFS server(s) first.
| |
| − | | |
| − | NOTE: You must uninstall any old version before installing a new one. See the notes below on uninstalling - in particular, you need to remove the old provider from any authentication policies. Note that the settings are not deleted on uninstall, so when you install the new provider, the previous settings will still be there.
| |
| − | | |
| − | If you have more than one ADFS server, you should install on the primary first.
| |
| − | | |
| − | To install this product, simply unzip the file SwivelAuthProviderInstall.msi from the download and double-click it. Note that you must be logged in as an administrator to install this product.
| |
| − | | |
| − | | |
| − | [[Image:AdfsAuthenticationProviderInstall1.png]]
| |
| − | | |
| − | | |
| − | You will next be asked to choose whether to install the ADFS Authentication Provider, the Swivel proxy or both. There are a number of possible scenarios, summarized below.
| |
| − | | |
| − | * ADFS 3 and IIS installed on the same public server, no proxy:
| |
| − | ** Install both components on the this server.
| |
| − | | |
| − | | |
| − | [[Image:AdfsAuthenticationProviderInstall2.png]]
| |
| − | | |
| − | | |
| − | * Single ADFS 3 server, no IIS:
| |
| − | ** Install Authentication provider only. For Swivel single channel, you will need to provide some other method to display the TURing or Pinpad.
| |
| − | | |
| − | | |
| − | [[Image:AdfsAuthenticationProviderInstall2a.png]]
| |
| − | | |
| − | | |
| − | * ADFS server and ADFS proxy, IIS installed on the proxy:
| |
| − | ** Install Authentication provider only on the ADFS server.
| |
| − | ** Install proxy component only on the ADFS proxy.
| |
| − | | |
| − | | |
| − | [[Image:AdfsAuthenticationProviderInstall2b.png]]
| |
| − | | |
| − | | |
| − | * ADFS server and ADFS proxy, IIS not installed on the proxy:
| |
| − | ** Install Authentication provider only on the ADFS server.
| |
| − | ** No additional components are required on the proxy.
| |
| − | ** Optionally, you can install the Swivel proxy on a third server with IIS installed, and proxy that through the ADFS proxy.
| |
| − | | |
| − | Note that, if you have not installed IIS (and ASP.Net 4.5) on the ADFS proxy, you do not need to install any components on the proxy. If you are using the ADFS proxy as a Swivel proxy, make sure that you only proxy the /adfs application through to the ADFS server, not the entire website.
| |
| − | | |
| − | | |
| − | [[Image:AdfsAuthenticationProviderInstall3.png]]
| |
| − | | |
| − | | |
| − | On the final screen, you will be prompted whether you want to run the filter configuration program.
| |
| − | | |
| − | = Configuration =
| |
| − | | |
| − | The configuration program for the authentication provider consists of 3 tabs, although typically you will only need to modify the first one. The Configuration program for the proxy only has a single tab, shown below.
| |
| − | | |
| − | | |
| − | [[Image:SentryAdfsAuthProviderConfigSettings143.png]]
| |
| − | | |
| − | | |
| − | Enter the URL for the Sentry appliance that will be used to authenticate users. If you have 2 Sentry appliances with different URLs, you can specify a second URL by clicking the "Alternate.." button:
| |
| − | | |
| − | [[Image:AdfsAuthenticationProviderConfigAlternate.png]]
| |
| − | | |
| − | Enter the alternative URL on this form. The primary URL will be used by preference, but the authentication provider will remember if the primary was not available for the last attempt and will use the alternative first in this case.
| |
| − | | |
| − | If the Sentry appliance uses HTTPS and does not have a valid, trusted certificate, check the option to ''Allow self-signed certificates'' (but see [[#Known Issues]]).
| |
| − | | |
| − | Enter the Agent secret for the Swivel twice: you should have previously created an Agent on the Swivel server corresponding to this ADFS server, and you should use the same secret here as you entered on that.
| |
| − | | |
| − | '''Image Type:''' You can choose to display either a TURing image, a Pinpad or no Swivel image (if you are using dual channel). Alternatively, you can specify Message on-demand or Push authentication.
| |
| − | | |
| − | Select ''Allow non-PINsafe users'' if you want users that do not have Swivel accounts to be able to authenticate without having to enter additional credentials. Generally, it is easier to manage this using Authentication Policies on ADFS.
| |
| − | | |
| − | Select ''Ignore domain prefix'' or ''Ignore domain suffix'', depending on your Swivel usernames: typically, you will always ignore the domain prefix, unless you configure your Swivel repository to automatically add a prefix. You will need to ignore domain suffix if you are using sAMAccountName as the Swivel username (the default), but not if you are using userPrincipalName.
| |
| − | | |
| − | Select ''Hide OTC for PINpad'' if you do not want the OTC to be displayed when using PINpad. If the image type is not PINpad, this option has no effect and the OTC will be displayed. The exception is for Push, when the OTC is never displayed, since it is not relevant.
| |
| − | | |
| − | '''Image Source:'''
| |
| − | | |
| − | There are 4 possible options for Image Source:
| |
| − | | |
| − | * Swivel direct: the image will be delivered directly from the Swivel server to the end user. In this case, the Swivel server must be publicly visible, and the URL for the image will be constructed from the Swivel URL.
| |
| − | * Local Proxy: the image will be delivered by the ADFS server or ADFS proxy, using the proxy component of the authentication provider. In this case, the proxy component must be installed either on the ADFS server or on a proxy with the same public URL as the ADFS server, which means that IIS must be installed on the appropriate server. Configuring the web application for the proxy is described in the Proxy section below.
| |
| − | * Remote Proxy: the image will be delivered by a web server that has the Swivel ADFS proxy application installed. See [[#Using_The_Swivel_Proxy|below]] for more details on using this option.
| |
| − | * Define manually: use this option if you have an alternative source for the TURing or Pinpad images. For example, if you have another Swivel integration, such as OWA, that provides an image proxy. This proxy must be to the same Swivel instance that is used for authentication, but does not have to be a direct connection. In this case, you must specify the full public URL for the image in the appropriate field below.
| |
| − | | |
| − | To directly access a Swivel appliance through a NAT etc, then the URL should be https://URL:8443/proxy/SCImage
| |
| − | | |
| − | NOTE: in Windows Server 2016 and later, you will need to add a response header to allow the page to load images from the proxy. This can be done using the following PowerShell command:
| |
| − | | |
| − | Set-AdfsResponseHeaders -SetHeaderName "X-Frame-Options" -SetHeaderValue "allow-from https://<proxy-host>"
| |
| − | | |
| − | Here, replace <proxy-host> with the public hostname of the proxy server. This should not be necessary in Windows Server 2012.
| |
| − | | |
| − | [[Image:AdfsAuthenticationProviderConfigLanguages.png]]
| |
| − | | |
| − | | |
| − | The languages tab allows you to change the messages used for various parts of the login page. You can either enter a new locale ID if you know the locale ID for the language you want to use. See [https://msdn.microsoft.com/en-gb/goglobal/bb964664.aspx here] for a list of Microsoft-assigned locale IDs. Alternatively, if you know that most of your users will be using a particular language, you can change the default messages.
| |
| − | | |
| − | | |
| − | [[Image:AdfsAuthenticationProviderConfigLogging.png]]
| |
| − | | |
| − | | |
| − | The Logging tab allows you to control how much information is logged by the provider, to view existing logs and to remove old logs. By default, nothing is logged.
| |
| − | | |
| − | [[Image:AdfsAuthenticationProviderConfigAdvanced.png]]
| |
| − | | |
| − | The Advanced tab provides advanced settings for the Swivel server connection. You should normally only use this if you are having problems connecting.
| |
| − | | |
| − | SSL protocols: Typically, you should stick to using just TLS 1.2, since all earlier protocols are deprecated. However, we have seen problems in some instances where there are no common cipher suites available between the appliance and the ADFS server. In this case, you will have to enable TLS 1.1 on both the appliance and the ADFS authentication provider. You may also need to add cipher suites to the appliance to support TLS 1.1.
| |
| − | | |
| − | You can configure a web proxy to be used for the connection. By default, the Automatic option is selected, in which case the connection will use whichever proxy is configured for internet connections on the ADFS server. The other options are None, in which case no proxy is used, or Manual, in which case you can specify the URL of a proxy to use.
| |
| − | | |
| − | User Agent provides a custom user agent string to be sent with the request. You might want to alter this to try emulating a particular browser, if you have problems connecting.
| |
| − | | |
| − | Finally, you can specify other HTTP headers that will be sent with the request. Right click on the Headers list to add, delete or edit them.
| |
| − | | |
| − | = Using the Swivel Proxy =
| |
| − | | |
| − | == Proxy Configuration ==
| |
| − | | |
| − | [[Image:AdfsAuthenticationProviderConfigProxy.png]]
| |
| − | | |
| − | | |
| − | The proxy configuration program is largely a simplified version of the full configuration program, including just the Settings and Advanced tabs. However, there is one additional option to take note of:
| |
| − | | |
| − | '''ADFS Host''': this must be the public URL for the ADFS appliance, including the "https://" prefix. It is essential that this is specified for the remote proxy, as it enables Cross-Origin Resource Sharing - so that images hosted by the proxy can be displayed on the ADFS login page. As of version 1.4.3, if the "https://" prefix is omitted, it will automatically be added.
| |
| − | | |
| − | == Enabling the Proxy Web Application ==
| |
| − | | |
| − | This is required for both Local and Remote Proxy, and is accessed by clicking the '''Virtual Directory''' link.
| |
| − | | |
| − | [[Image:SwivelAuthProviderProxyConfig1.png]]
| |
| − | | |
| − | | |
| − | Select the existing web application you want to install the proxy under (typically this will be the root application), and click '''Create...''' to show the following
| |
| − | | |
| − | | |
| − | [[Image:SwivelAuthProviderProxyConfig2.png]]
| |
| − | | |
| − | | |
| − | Enter the name of the directory you want to use for the proxy - note you should ''not'' include a "/" prefix - and click '''Create...''' again. This will create a web application with the given name. This application contains links for the TURing and Pinpad images.
| |
| − | | |
| − | In order to use this proxy, you need to specify the same directory name - but this time ''including'' a "/" prefix - in the ADFS configuration.
| |
| − | | |
| − | An additional menu option is provided to remove the virtual directory. This should normally be done before uninstalling the authentication provider.
| |
| − | | |
| − | = Using the Authentication Provider =
| |
| − | | |
| − | Note that the installer simply makes the Swivel Authentication Provider available for use: it does not actually enforce its use. To do so, you need to modify an Authentication Policy:
| |
| − | | |
| − | From ''Administrative Tools'', select ''AD FS Management'',
| |
| − | | |
| − | | |
| − | [[Image: SwivelAuthProviderADFSMgmt.png]]
| |
| − | | |
| − | | |
| − | then choose ''Authentication Policies''.
| |
| − | | |
| − | Under ''Multi-factor Authentication'', click Edit.
| |
| − | | |
| − | | |
| − | [[Image: SwivelAuthProviderADFSMFA.png]]
| |
| − | | |
| − | | |
| − | You should see ''Swivel Authentication Provider'' as an additional authentication method at the bottom of the dialog. Check this to enable it. You will also need to choose which users or groups are required to use MFA, and where they need to use it from. This document does not describe how to configure ADFS Authentication Policies - you should read the appropriate Microsoft documentation for that.
| |
| − | | |
| − | Note that if you have multiple ADFS Servers and/or ADFS Proxies you must install the Authentication Provider component '''every''' server. To use single-channel authentication, you must install the Proxy component on every proxy server. You do not need to install anything on the proxies if you are only using dual-channel authentication methods.
| |
| − | | |
| − | Once you have enabled MFA for the Swivel Authentication Provider, the next time you go to a page that requires ADFS authentication, after you enter your usual AD credentials successfully, you will be prompted to enter a Swivel one-time code.
| |
| − | | |
| − | | |
| − | = Advanced Features =
| |
| − | | |
| − | == Requiring Swivel Authentication for Single Applications ==
| |
| − | | |
| − | NOTE: these instructions are relevant to any ADFS Multi-Factor Authentication provider, not just Swivel, so are subject to the facilities provided by Microsoft.
| |
| − | | |
| − | It may be that you want to enable Swivel Authentication in ADFS for some applications but not others. It is possible to manage this, with certain limitations, as described below:
| |
| − | | |
| − | Firstly, you must set up Global Multi-factor Authentication (MFA), and enable "Swivel Authentication Provider". However, DO NOT add any groups or check any devices or locations options. This will enable the Swivel authentication provider, but not require it for anything.
| |
| − | | |
| − | Secondly, got to Authentication Policies -> Per Relying Party Trust and select the relevant Trust (i.e. Application). Click Edit Custom Multi-factor Authentication for this application, and set the conditions under which you require MFA.
| |
| − | | |
| − | You will note that the MFA providers are not listed here. You can only enable or disable MFA: you can't specify which MFA provider to use. This is a limitation of ADFS, and not within Swivel's control. There are advanced methods to manage this, using claim rules, but this is beyond the scope of this article.
| |
| − | | |
| − | | |
| − | = Known Issues =
| |
| − | | |
| − | == Public Access to Swivel Server, Untrusted Certificates and TURing/Pinpad Images ==
| |
| − | | |
| − | As noted above, by default TURing images and Pinpad images are delivered directly from the Swivel server. This has two consequences:
| |
| − | | |
| − | * The Swivel Server must be published on the Internet
| |
| − | | |
| − | * If the Swivel server is running HTTPS, it must have a valid commercial SSL certificate
| |
| − | | |
| − | The best solution for this is to install the optional local proxy, but this requires IIS to be installed on the ADFS server, the ADFS proxy or a suitable alternative public server. Alternatively, you can proxy the image through a different public web server, but this has the same provisos as for delivering images directly from the Swivel appliance.
| |
| − | | |
| − | | |
| − | = Uninstalling the Authentication Provider =
| |
| − | | |
| − | Before uninstalling the Swivel Authentication Provider, make sure that it is removed from ALL Authentication Policies. If you do not do this, you will not be able to reinstall or upgrade to a newer version. It is advisable to check that the authentication provider has been unregistered before attempting installation of a newer version, using the following PowerShell command:
| |
| − | | |
| − | Get-AdfsAuthenticationProvider -Name SwivelAuthenticationProvider
| |
| − | | |
| − | If details of the provider are shown, it has not been unregistered properly, and you should follow the next steps.
| |
| − | | |
| − | If the authentication provider has not been unregistered, before you can reinstall or upgrade, after removing it from all policies, you will need to unregister manually, by running the following command from a PowerShell command prompt:
| |
| − | | |
| − | Unregister-AdfsAuthenticationProvider -Name SwivelAuthenticationProvider
| |
| − | | |
| − | Then restart the ADFS service. It is important to restart the service on all ADFS servers before attempting a new installation.
| |
| − | | |
| − | The uninstallation procedure does not remove any web application for the image proxy. Typically, you should uninstall this, using the menu shortcut provided, before uninstalling, but if you are uninstalling in order to install a newer version, this is not necessary.
| |
| − | | |
| − | Note that the uninstallation procedure requires that you unregister the authentication provider. In order to do this, a prompt will be displayed, and you will have to confirm that you want to unregister it (by pressing 'Y' and Enter).
| |
| − | | |
| − | If you want to completely remove the Swivel Authentication Provider, you will also need to remove the folder C:\ProgramData\Swivel Secure\Swivel Authentication Provider. This contains the filter configuration and logs.
| |
| − | | |
| − | = Upgrading =
| |
| − | | |
| − | Currently, the filter installer does not permit direct upgrading from an earlier version, so it is necessary to uninstall the previous filter, including changing the ADFS authentication policy, before installing a new version, using the procedure above. However, the configuration is retained (unless you deleted it as above), and will be automatically applied to the new version. You will still have to re-enable the ADFS authentication policy, though.
| |
| − | | |
| − | = Troubleshooting =
| |
| − | | |
| − | Check to see if a connection can be made from the ADFS server to the Swivel server, for an appliance: https://Swivel-URL:8080/pinsafe
| |
| − | | |
| − | | |
| − | = Error Messages =
| |
