Hypersocket SSO Getting Started Guide

Lee Painter HYPERSOCKET LIMITED Unit 1, Vision Business Centre, Firth Way, Nottingham, NG6 8GF, United Kingdom

Table of Contents

PREFACE ...................................................................................................................................... 4 DOCUMENT OBJECTIVE ............................................................................................................................ 4

Audience ......................................................................................................................................... 4 Document Organization ................................................................................................................. 4

DOCUMENT CONVENTION ........................................................................................................................ 5 DOCUMENTATION FEEDBACK .................................................................................................................... 5 OBTAINING TECHNICAL ASSISTANCE ........................................................................................................... 5

INTRODUCTION ........................................................................................................................... 6 WHAT IS A SSO? .................................................................................................................................... 6 KEY BENEFITS OF HYPERSOCKET SSO .......................................................................................................... 6

INSTALLING HYPERSOCKET SSO .................................................................................................... 7 NETWORK DEPLOYMENT .......................................................................................................................... 7

LAN ................................................................................................................................................. 7 DMZ ................................................................................................................................................ 8

FIREWALL RULES ..................................................................................................................................... 8 SUPPORTED PLATFORMS .......................................................................................................................... 8 INSTALLING HYPERSOCKET ........................................................................................................................ 9 THE SETUP WIZARD ................................................................................................................................. 9

Step 1 – License Agreement ......................................................................................................... 10 Step 2 – Set Password .................................................................................................................. 10 Step 3 – Upload License Key ......................................................................................................... 11 Step 4 – Download/Install Components ....................................................................................... 11 Step 5 – Configure SSL Certificate ................................................................................................ 11 Step 6 – Complete Setup............................................................................................................... 13 Logging in for the First Time ......................................................................................................... 13

INSTALLING SSO EXTENSIONS ..................................................................................................... 14 AVAILABLE FEATURES ............................................................................................................................. 15

Passwords->Browser Password Manager .................................................................................... 15 Passwords->SAML Identity Provider ............................................................................................. 15 Passwords->Password Server ....................................................................................................... 15

SETTING UP RESOURCES ............................................................................................................. 16 REALMS ............................................................................................................................................... 16 BROWSER CREDENTIALS RESOURCES ........................................................................................................ 18

What is a Browser Credentials Resource? .................................................................................... 18 Configuring form detection .......................................................................................................... 18 An example browser credential configuration ............................................................................. 19

SAML RESOURCES ................................................................................................................................ 22 What is a SAML Resource? ........................................................................................................... 22 An example SAML configuration .................................................................................................. 22

PASSWORD RESOURCES ......................................................................................................................... 27 What is a Password Resource? ..................................................................................................... 27 A password resource example ...................................................................................................... 27

PLEASANT PASSWORD SERVER SUPPORT ................................................................................................... 30 What is Pleasant Password Server? ............................................................................................. 30 An example configuration ............................................................................................................ 30

INSTALLING THE BROWSER SSO EXTENSION ............................................................................... 32

LAUNCHING RESOURCES ............................................................................................................ 33

SSO RESOURCES ................................................................................................................................... 33 Usernames and Passwords ........................................................................................................... 33 Web GUI ....................................................................................................................................... 34 Browser SSO Extension ................................................................................................................. 34 Direct URL Access ......................................................................................................................... 35

PASSWORD RESOURCES ......................................................................................................................... 35

TROUBLESHOOTING ................................................................................................................... 37 CONNECTION IS NOT PRIVATE/CERTIFICATE ERRORS..................................................................................... 37 CANNOT CONNECT TO THE WEB UI .......................................................................................................... 37

Has the service started? ............................................................................................................... 37 Check firewall port forwarding ..................................................................................................... 38

HYPERSOCKET CLIENT DOESN’T REMEMBER THE SERVER URL ....................................................................... 38 BROWSER SSO EXTENSION DOES NOT CLICK LOG ON .................................................................................. 38 I HAVE A PROBLEM BUT IT’S NOT ANSWERED HERE ...................................................................................... 38

Preface This preface introduces the Hypersocket SSO Getting Started Guide. It has been broken down into the following sections:

Document Objective Document Convention Documentation Feedback Obtaining Technical Assistance

Document Objective The objective of this document is to provide the System Administrator with an overview of installing and configuring the Hypersocket SSO product from Hypersocket Software. Hypersocket SSO allows your users to automatically pass their credentials to any website and log them on.

Audience This guide is for anyone who wishes to successfully install and administrate the Hypersocket SSO product. Although this is often someone concerned with product installation and administration, it may also be a useful guide to managers whom may be considering deploying the Hypersocket SSO as a solution. This guide is expected to be useful if you are performing any of the following tasks

Installing an instance of the Hypersocket SSO Configuring an existing implementation of Hypersocket SSO

Document Organization For ease of reference this guide has been broken down into sections that match the workflow of installing and configuring the Hypersocket SSO. These are:

Introduction Installing Hypersocket SSO Installing the Hypersocket Client Installing the Browser SSO Extension Setting up Resources Launching Resources Troubleshooting

in this format

Document Convention The following conventions are used in this document:

Bold font denotes either User Interface components to interact with (e.g. Click the Create button) or for extra emphasis.

UI navigation is denoted by menu items in bold separated by -> (e.g navigating to System->Configuration->SSL is done by clicking System in the left hand menu, followed by Configuration in the secondary menu at the top, finally clicking on the SSL tab).

Typed user input into the UI is shown in italic font. Tips or summaries are displayed as below:

This is a summary

Commands typed into a shell are shown

Documentation Feedback We appreciate your comments on this technical documentation and invite you to send feedback to use at support@hypersocket.com.

Obtaining Technical Assistance For all customers, resellers, distributors or partners who hold a valid support agreement with Hypersocket Software Limited technical support is available by sending an email to support@hypersocket.com. You may also find useful documentation and articles on our knowledgebase https://support.hypersocket.com.

Introduction

This chapter provides the user with an overview of what a SSO is and the benefits of using Hypersocket SSO

What is a SSO? Single sign-on, or SSO, is a service that permits a user to use one set of login credentials to access multiple separate resources. The SSO service passes authentication automatically to the resources that the user has been given rights to.

Key benefits of Hypersocket SSO Hypersocket SSO allows your users to connect to web sites using a username and password (both HTML forms as well as HTTP authentication). Hypersocket SSO also supports SAML for password free authentication to services. The key benefits of using Hypersocket SSO are:

Installable client that is easy to use, configure and update. All data via a single port, easy to configure for firewalls. Single click sign-on to any configured web site. All user credentials for web sites are stored centrally on the SSO server inside your

network. Reduce help desk costs as users do not have to memorize long lists of passwords for

different web sites. Multiple methods of strong authentication to keep your network more secure.

Installing Hypersocket SSO

This chapter provides a basic overview of the installation of Hypersocket SSO. For more detailed coverage of the different installation types you

should download the Hypersocket Installation Guide from https://www.hypersocket.com

Network Deployment Hypersocket SSO is typically deployed inside the corporate LAN, but can be installed in a DMZ if required. Both of these scenarios are covered below.

LAN Installing Hypersocket SSO in the corporate LAN is the simplest deployment. Only a single port (443 by default) needs to be forwarded through the external firewall for your external users and the SSO has direct access to any internal corporate resources.

Hypersocket SSO

Firewall

LOCAL AREA NETWORK

INTERNETWebsite

Website

Website

Website

DMZ An alternative scenario is to install Hypersocket SSO in a DMZ. The same single port needs to be forwarded through the external firewall for your external users, but for every LAN resource required, extra ports need to be opened up on the internal LAN firewall. Hypersocket SSO can be configured to use one or two network cards with a simple change in the VM configuration.

INTERNET

Firewall

LOCAL AREA NETWORK

Website

Hypersocket SSOFirewall

DMZ

Website

Website

Website

Firewall Rules Hypersocket SSO communicates over a few different ports. Here are the port forwarding rules you need to configure on your network firewall, assuming you choose to use the default ports:

Port Direction Destination IP Notes

443 In <SSO IP> Web interface (for management and users)

80 In <SSO IP> Optional: HTTP redirect to management interface

443 Out 81.139.47.195 Optional: Used for opening a tunnel to our support

Supported Platforms Hypersocket SSO comes pre-built as a virtual appliance. We have images available for the following Hypervisors:

VMware ESX/vSphere Microsoft Hyper-V Oracle VirtualBox KVM Vagrant

We also have images for the following cloud based Hypervisors:

Amazon EC2 Microsoft Azure Google Compute Engine Oracle Compute Docker

We even have an installable ISO in case you did not want to use a VM, but install directly on to your own hardware. A final option are installers so you can deploy Hypersocket as a software service on Windows, Linux or OSX hosts. The installers can be downloaded from https://www.hypersocket.com/en/products/single-sign-on. You will need a license key to activate the software, if you are evaluating the product then you must register before downloading to receive your evaluation license key.

Installing Hypersocket Please refer to our Hypersocket ONE Installation Guides on our knowledge base at: https://support.hypersocket.com/hc/en-us/sections/200839385-Installing-Hypersocket

The Setup Wizard We can now continue the configuration in a web browser. When connecting to the management interface for the first time, you will be asked to run through the setup wizard to finalize the installation. Connect your browser using a suitable URL for the settings you have input during the installation. https://<hostname>:[port] For example, if you have installed the server on hostname gateway.corp.local on the standard ports your URL will be https://gateway.corp.local

Please note that when connecting for the first time you will receive a warning in your browser stating that the certificate is untrusted. You will have a chance to upload your own certificate shortly. For now, you should accept the untrusted certificate.

Your browser will load the setup wizard. Simply run through the following steps to finalize your installation.

Step 1 – License Agreement

Before continuing you must accept the license agreement of the software. Click ‘I accept..’ and click Next.

Step 2 – Set Password

Next you should provide a password for the admin user account. The admin account has full system privileges and is to be used for initial administration of the server.

Step 3 – Upload License Key

As discussed earlier you cannot install the server without a license key, which you should already have done from the website. Click Choose file to select your Hypersocket license file.

Step 4 – Download/Install Components

The Hypersocket server will now need to download the core components is needs in order to start up. If you use an outbound proxy server, tick the option and enter the relevant details, or just click Next to continue if there is no proxy.

Step 5 – Configure SSL Certificate You now have the opportunity to upload an existing SSL certificate. For example, you may have a wildcard certificate for your domain. This section can be skipped at this time if you prefer to configure the certificate later. There are multiple formats supported. You can upload a PKCS12 / PFX file that contains the complete certificate, or you can upload separate PEM encoded files.

Uploading PKCS12 / PFX Select your PKCS12 / PFX file in the Private Key field. Enter the files passphrase in the Passphrase field. You can ignore the Certificate File and CA Bundle fields as PKCS12/PFX files do not have or require any other external files. Your private key and certificate are contained within the single PFX file.

Uploading PEM You should have a number of PEM files. At a minimum you should have a private key file and a certificate file. Upload the files into the appropriate fields. If your private key file is encrypted with a passphrase enter it into the Passphrase field. You may omit the CA bundle if you do not have this. These are typically provided by your CA when you purchased your SSL certificate.

Step 6 – Complete Setup

You are now ready to complete the setup. Click Complete to start the final configuration.

Your server is now ready to use, after which you will be redirected to the login page.

Logging in for the First Time Once the Setup Wizard is complete, clicking Start will direct your browser to the logon page. Here you should enter the username admin and the password that you created during Step 2 of the Setup Wizard.

After entering the admin credentials, click Logon button to log into the Hypersocket SSO.

Installing SSO Extensions

This chapter describes how to install the SSO features that are needed to run the server.

As the server is based on our Hypersocket Prime build, you must first install the features required in order to add the SSO services needed. There are many features which are applicable to all Hypersocket Prime products, but we shall detail only the SSO specifics here. Log on to the server with the admin account.

In the Nav bar at the top right of the screen, click the Updates, Features & Licensing icon.

The Features page starts with a list of all currently installed features. The other tabs are grouped into broad categories.

To install a feature, navigate to the relevant tab, find the feature required and click on the blue cloud Download icon and accept the License Agreement that appears.

The feature will download. Once completed a server restart notification appears.

Restart the service now using the Shutdown/restart icon in the top navbar.

Available Features Following is a list of all features you can download that relate to the SSO part of the Hypersocket Server.

Passwords->Browser Password Manager Adds support for single sign on to web sites by storing and sending credentials to sites automatically. This requires the Browser SSO Plugin to be installed on client browsers. When this extension is installed, it automatically installs the Password Server feature below.

Passwords->SAML Identity Provider Allows you to connect to websites using the SAML protocol instead of user/password. SAML is a secure, password free method of authenticating and is supported by many web based services.

Passwords->Password Server Securely store passwords and share account credentials by creating and assigning password resources to users. Acts as a password vault.

Setting up Resources

This chapter will give a brief overview of the different resource types and get you started with creating the resources that your users will be

launching.

With Hypersocket SSO there is one main type of resource you can give your users access to, but using three different authentication methods. These are Browser Credentials, SAML and HTTP Authentication. The sections below will cover an explanation of these resources and include an example of each to help get you started.

Realms Before any resources are set up, it is worth briefly touching on the subject of Realms. Hypersocket SSO can support multiple User Databases at the same time and each User Database is assigned its own Realm. When you create resources, you create the resource for the realm you are currently managing. This allows you to create separate sets of resources for people on different user databases (and is a good model for a Managed Service Provider environment). For this Getting Started Guide, we have chosen to use the default local user database called System, but in a production environment you will likely have at least two realms (System - where the admin account exists and possibly also an Active Directory).

Note that if you have a single User Database you wish to use, it is also possible to alter the configuration of the default System Realm to point it

at an Active Directory for example. See the Administrator’s Guide for more information.

It is important to be aware of which realm you are creating your resources on. When you have more than one realm a new icon appears at the top.

You can click the User Realms button, then select the realm you wish to manage from the list that appears.

At any time, you can see which realm you are currently managing by looking in the footer at the bottom left of the screen.

Here we can see that we are logged in as the admin account and are currently managing the System realm.

Browser Credentials Resources

What is a Browser Credentials Resource? Likely to be the most common type of resource you will configure on Hypersocket SSO, a Browser Credential resource is used where you have a web site that prompts a user for credentials using a form built into the web page.

Configuring form detection The easiest way for creating a Browser Credential resource is to use the form detection feature of the SSO Extension. This option is turned on by default, but if it has been disabled, here is how turn it on.

First, left click the SSO Extension icon next to the URL bar in the browser. The extension asks for the username and password, so enter the credentials for the admin account and click Logon.

A menu appears immediately after logging on. Click on Options.

The options web page opens in a new tab. Turn on the Form Detection button at the bottom and click Save. This tab can now be closed.

An example browser credential configuration For this example we shall use Twitter.

Navigate to www.twitter.com and click Log in. Because we are logged in to the SSO Extension as admin and the form detection option is turned on, we can see here that the Extension has added controls to the Login fields. Click one of the Hypersocket logos to start creating the new resource. The Add Current Site wizard starts.

Leave Create For as Assignment to Others if you want to create this resource for your users, or change it to Personal Use if it is just for your own use. Accept or alter the suggested Name for the site. For Username and Password Scope, change both of these to User.

Add a name for a category that this site’s attributes will be held under and click Next. See the full Administrator’s Guide for a description of the three Scope types. For this example, we are allowing the users to be able to set their own username and password for this resource. This part of the wizard creates Profile Attributes that users can edit in their My Profile section of the Web UI.

To assign which sets of users can access this resource, we need to add a Role. We shall use the built-in Role called Everyone here. Click Everyone, then click the right arrow to move it to the Included column. Click Next.

This next screen prompts for the values of the detected attributes for the current user (admin). Enter admin’s Twitter credentials here (optional), then click Create to finish making the resource.

The resource has been created and if you added your own credentials, it will now automatically log you on.

We will cover launching resources in the next chapter. For now, you can see the configured Browser Credentials Resource in the web UI, by navigating to Single Sign On->Browser Credentials.

SAML Resources

What is a SAML Resource? SAML (Security Assertion Markup Language) is an open-standard data format for authentication that was created to address web browser single sign on. For the purposes of Hypersocket SSO, it means that you can allow your users’ Hypersocket credentials to automatically authenticate to third party web sites, without needing to ever input the username and password for this third party service. The target website effectively trusts the Hypersocket SSO as a valid authentication source. For a more detailed explanation of SAML, please refer to this Wikipedia article.

An example SAML configuration For this example, we will show how to set up SAML authentication to a corporate Google account.

Creating the resource in Hypersocket Log into your server as admin and navigate to Single Sign On -> SAML. Google SAML has already had some of the hard work done for you, so click on the Search Templates button.

Select Google SAML and click Next.

Enter the primary domain name of your Google account, for example 'hypersocket.com' and click Next.

Edit the resource that has been created and click on the Roles tab. Add in the Everyone role in the same way we did for the Browser Credentials resource we created earlier and Update the resource.

Getting SAML data The resource has now been created, but we need to get some information from the Hypersocket SSO server and then use that to configure Google. The newly created resource should now be visible. Click the green gears icon, then click Download Metadata and save the file.

Now navigate to Configuration->Certificates and click the green gears icon next to the SAML RSA entry. Select Download Certificate.

Now edit the Metadata XML file that was downloaded. We need to get two items of information out of this file. Look for the entries that begin with SingleLogoutService and SingleSignOnService and copy the URLs from the location part of the lines. You should get URLs similar to the following: https://demo.hypersocket.com/hypersocket/api/sso/logon/123456 https://demo.hypersocket.com/hypersocket/api/sso/logoff/123456

Configuring Google

You will now need to log into your Google account as the administrator so that you can configure Google Security to use a third party Identity Provider. First, once logged in, select Manage this Domain in the dropdown menu.

In the Admin console that appears, click on the Security section.

Now click the Set up single sign-on (SSO) option. You will then be presented with 2 options.

We will need to configure Option 2, so tick the check box next to Setup SSO with third party identity provider. For the Sign-in page URL and Change password URL fields, enter the logon URL we extracted from the metadata XML document earlier. In the Sign-out page URL setting, enter the logoff URL we extracted.

Click Save Changes to commit the settings. Finally, whilst still on the same page, click the Replace certificate link in the Verification certificate setting and upload the SAML RSA certificate we downloaded from the Hypersocket server earlier. The SAML resource is now ready to use. Note that each user’s email address must match their Google logon email as this is the primary link between accounts.

Password Resources

What is a Password Resource? Hypersocket SSO also provides a secure password store that can be used to store sets of passwords (and optionally usernames) that your users can access as required. Passwords are stored in a tree view by clicking on Passwords in the left hand navbar and can be organized into folders. This password resource can then be assigned to user roles as per the other above resources.

A password resource example

Right click the root level of the password tree and select New Folder.

A new folder appears, give it a name and press enter (here we called it Windows Servers).

Right click on the new folder and select New Password.

Give the resource a name, here we are creating a resource for the Active Directory domain admin account. A username is optional, but can be added to remind you which account this password is for (or can be sent to resources such as web sites via SSO). Type in the password and confirm. For Mode, View Use allows users to access this password, System Use hides the password from the user (which can then be used for SSO resources without the user ever knowing the password). Set the Mode to View Use.

For this example, we will not be setting any of the Options tab, but you may use options to set an Expiration Date and/or a Host Address for this password resource.

Click on Notes and add some text to remind you what this password resource is for. Here we just make a note stating that it is the main domain admin account.

Click on Roles and add which Roles will be able to access this password. Click Create to complete the creation.

Your new password is now shown in the tree view.

Pleasant Password Server support

What is Pleasant Password Server? Pleasant Password Server is a third party enterprise password management server which is compatible with KeePass Password Safe and can be run on another server within your own network. If you already have this server installed, then rather than using Hypersocket SSO’s own password server, you have the option of connecting to the Pleasant Password Server and use it for your source of stored passwords instead.

An example configuration Pre-requisites: You must have the Pleasant Passwords feature installed from Updates, Features & Licensing->Passwords.

Navigate to Configuration->General->Pleasant Passwords to start the configuration.

Enter the Server URL for your server install, ensuring you use port 10001. For Service Username and Password enter the details of an account that has read access to all of the passwords you wish to import The other settings can be left as default for now.

Click Apply to save the changes, your pleasant passwords will now be available to use in the Hypersocket server.

To access your passwords, these will now be available as attribute replacements when creating resources anywhere you see the ${} icon. You can get access to the password as well as any username or hostname you defined for that resource.

Installing the Browser SSO Extension

This brief chapter provides links to separate articles relating to installation of the Hypersocket Browser SSO plugin which can be used for launching

resources.

For instructions on installing the SSO Browser Plugin, please refer to the following article: https://support.hypersocket.com/hc/en-us/articles/204173319

Launching Resources

SSO Resources There are several different ways in which your users can launch resources, but note that the Browser SSO Extension is required to be installed for SSO Resources as it is this which actually performs the authentication to web sites.

Usernames and Passwords Before we launch resources, a quick note on setting usernames and passwords for users will be useful as these will need setting before any resource is launched.

If the resource was set with a credentials scope of User, then the user will be able to set their own details. They can see this in My Profile->My Details in the web UI.

Admin can also set the user’s credentials by navigating to Access Control->Users and clicking the edit icon.

In the Update User dialog, click the Custom link to see the user’s web site credential attributes. Make any required changes and click Update to save.

Web GUI

When a user logs on to the web GUI, when they click on My Resources in the left menu they are able to see what resources they have available. Click the green rocket icon to launch a resource.

Browser SSO Extension You can also launch resources directly from the SSO Extension in your browser

First, make sure the SSO Extension is logged on to the server. Click the extension icon next to the URL bar, then click Logon and enter your credentials. Now click the icon again, then click on My Sites. This will show the list of resources that you can launch. Note that SAML resources do not appear in this view.

Direct URL Access The Browser SSO Extension is always looking out for the URLs that have been defined in resources, so another method of performing single sign on is just to type in the URL directly into your web browser. If the SSO Extension finds a matching URL, it will automatically attempt to authenticate for you.

The URL was typed in here for Twitter and you can see that the extension has automatically pre-filled the user’s credentials and is about to log on.

Password Resources Password Resources can only be accessed via the Web GUI. Log on as a user and navigate to My Resources->My Passwords. Any passwords you have access to will be shown here showing the name of the resource and any username attached to it.

You may click the Search icon to see the options and note that were added to the resource, but to access the password, click the green Gears icon.

Clicking the gears shows two options, Copy to Clipboard and Reveal Password.

Clicking Copy to Clipboard shows a popup which must be confirmed by clicking the copy action, after which the password should be available on your clipboard to paste wherever you need it.

Reveal Password shows a similar popup but displays the password. You may still click the Copy action to place the password in your clipboard.

Troubleshooting

Connection is not private/certificate errors If you chose to skip step 5 of the setup wizard, then Hypersocket SSO installs a self-signed localhost SSL certificate. Web browsers will correctly flag this certificate as untrusted. The resolution is purchase and install a signed SSL certificate from a Certificate Authority, please see the full administrator guide for more details. Note: you will likely also have problems connecting natively to WebDAV file shares with a self-signed certificate. The resolution is the same as above.

Cannot connect to the Web UI When you start up the Virtual Machine, if you cannot connect to the web UI, here are a couple of things to look at:

Has the service started? Look at the console of the VM, where you will find VMCentre running. Click on the Gear icon on the left hand side. If the Hypersocket One service is running, there will only be a Stop button. If the button says Start, click it.

Check firewall port forwarding If you have followed this guide, Hypersocket SSO will be listening for connections on port 443. Double check the port forwarding rules on your firewall to ensure that it is passing data on this port through to the Hypersocket SSO server. If you chose not to forward the optional port 80, then double check you are trying to access the server with https:// rather than http://.

Hypersocket Client doesn’t remember the server URL

Every time you disconnect the client, you have to enter the Server URL every time you reconnect. This is the default behavior. To force the client to remember the connection URL, click the green power plug icon, then tick the Save connection box before clicking on the disconnect icon next to the URL.

Browser SSO Extension does not click Log On You may find a situation where you launch a resource and the extension inserts the user’s credentials but does not actually click the log on button so you stay on the login page. The extension by default only attempts to authenticate the user once per session (this is configurable on a per resource basis). This is to stop cases where you might end up an endless loop if a page happens to redirect you back to the initial URL after logging on.

I have a problem but it’s not answered here If your problem is not covered by this troubleshooting guide or you need more information or advice about anything to do with the Hypersocket SSO product, there are many troubleshooting articles available on our Knowledgebase, which you can find here: https://support.hypersocket.com/hc/en-us If you cannot find your answer there, please contact our support team by email at support@hypersocket.com