|
|
| (40 intermediate revisions by 2 users 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. |
| | | | |
| − | = Introduction =
| + | For ADFS version 2 see [[Microsoft ADFS 2 Integration]]. |
| − | | |
| − | 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.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 2012 R2 64-bit, with the ADFS role installed. This should be installed and tested before installing the Swivel provider.
| |
| − | | |
| − | 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.
| |
| − | | |
| − | The installer for the Swivel ADFS Authentication Provider can be found [https://kb.swivelsecure.com/wiki/images/f/fa/SwivelAuthProviderInstall.zip here].
| |
| − | | |
| − | = 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 also install on the primary first. You should also note the option for Primary ADFS server. When you are installing on secondary ADFS servers, ensure that this option is unchecked, or you will see errors on installation, and will have difficulties when uninstalling. This option is ignored if the authentication provider is not installed.
| |
| − | | |
| − | 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:SwivelADFSAuthProviderInstall1.png]]
| |
| − | | |
| − | | |
| − | Accept the licence agreement and proceed to install.
| |
| − | | |
| − | | |
| − | [[Image:SwivelADFSAuthProviderInstall2.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:SwivelADFSAuthProviderInstallSingle.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:SwivelADFSAuthProviderInstallAuthOnly.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:SwivelADFSAuthProviderInstallProxy.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:SwivelADFSAuthProviderInstall4.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:SwivelAdfsProviderConfigSettings.png]]
| |
| − | | |
| − | | |
| − | Enter the URL for the Swivel server that will be used to authenticate users.
| |
| − | | |
| − | If the Swivel server 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.
| |
| − | | |
| − | 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.
| |
| − | | |
| − | '''Image Type:''' You can choose to display either a TURing image, a Pinpad or no Swivel image (if you are using dual channel).
| |
| − | | |
| − | '''Image Source:'''
| |
| − | | |
| − | There are 3 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 the proxy, which means that IIS must be installed on the appropriate server. see [[#Installing_a_Local_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
| |
| − | | |
| − | | |
| − | [[Image:SwivelAdfsProviderConfigLanguages.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:SwivelAdfsProviderConfigLogging.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:SwivelAdfsProviderConfigAdvanced.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: version 2.x appliances only use SSLv3 and TLS 1.0. However, if you are not using a Swivel appliance, and your Swivel server is using Java 7 or higher, you can try using higher versions of TLS. By default, all protocols are permitted. The connection will try all permitted protocols until it finds one that both ends support, so disabling SSL 3 and TLS 1.0 for a version 2 Swivel appliance will cause the connection to fail.
| |
| − | | |
| − | 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.
| |
| − | | |
| − | == Proxy Configuration ==
| |
| − | | |
| − | [[Image: SwivelADFSAuthProviderConfigProxy.png]]
| |
| − | | |
| − | | |
| − | The proxy configuration program is a simplified version of the settings tab for the full configuration program.
| |
| − | | |
| − | = Installing a Local Swivel Proxy =
| |
| − | | |
| − | | |
| − | This is an optional enhancement to the login experience. It requires that IIS is installed on the ADFS server or proxy server. It provides links for TURing and Pinpad images local to the ADFS server, thereby avoiding the problems experienced when hosting the images on a different server.
| |
| − | | |
| − | You can either access this from the main configuration program, so long as "Local Proxy" is selected, or you can use the menu option '''Swivel Authentication Provider Proxy Configuration'''. The following dialog is shown:
| |
| − | | |
| − | | |
| − | [[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 and click '''Create...''' again. This will create a web application with the given name, and automatically configure the required settings to use it. This application contains links for the TURing and Pinpad images.
| |
| − | | |
| − | 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. If you accidentally forget to remove the authentication provider before uninstalling, it will not be unregistered properly. Therefore, 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.
| |
| − | | |
| − | The uninstallation procedure does not remove any local image proxy defined. 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. 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 =
| |
