Open topic with navigation

Administer > Security > Authentication > Setting up Authentication

Setting up Authentication

ClosedAbout Single Sign-On

The goal of federated single sign-on is to enable users to maintain secure access across a range of external systems and web applications. HEAT supports the use of various protocols that help organizations accomplish this goal. Through the use of ADFS (Microsoft Active Directory Federated Services) and SAML (Security Assertion Markup Language), HEAT customers can use their existing windows authentication credentials to sign on to their HEAT Service Management tenant without having to enter a new password.

Single sign-on was originally designed to handle identity management within a network domain or other closed system, allowing users to log in once to get into their system and carry those credentials through to other systems within their environment. However, with HEAT computing, single sign-on has become more difficult to manage as users typically access many systems and applications that cross different companies and domains.

Many companies have designed proprietary protocols to meet the challenge of web browser single sign-on, leading to interoperability between providers. There must be trust established between the principal (user), the identity provider (initial authentication source), and the service provider (web application).

Open source security protocols seek to exchange authorization and authentication between security domains, such as an identity provider (that is, the customer domain) and the service provider (that is, HEAT). At the request of the user, credentials are passed to the application. This type of protocol is not concerned with how the user was authenticated initially.

Microsoft's ADFS is a claims based identity tool, using Active Directory Domain Services to authenticate the user and issue a token that contains identity information. Federation servers located within both security domains exchange tokens without storing any user names or passwords. The user has to only enter their user name and access is granted without direct authentication to the system.

SAML uses an identity provider and a service provider to grant access to an application through web browser. The identity provider in this case is ADFS running on the domain of the customer.

ClosedA Sample Data Flow in ADFS SAML Authentication

Sample Data Flow

1. The user browses to their URL, such as <tenant>.saasit.com, enters their user name, and clicks login. The user does not enter a password.
2. HEAT sends a redirect to the browser pointing to the identity provider (ADFS) based on the information configured in the SAML authentication provider record.
3. The user lands on their ADFS endpoint for logging in. This is a different page than is hosted on the side of the customer.
4. On successful authentication through ADFS, ADFS renders a page to the user that does nothing but post the SAML assertion to HEAT's SAML.
5. The browser posts the SAML response back to the HEAT endpoint with the SAML assertion, and a session for the user is created.
6. HEAT sends a redirect to the browser of the user pointing them at the home page of the application (as if they had logged in as usual).
7. The browser of the user asks for the resource.
ClosedSetting Up Authentication in HEAT

Before you begin, ensure the following:

  • ADFS Release 2.0 (or latest) must be installed.
  • You must have valid certificates for the HEAT application server and for the ADFS server.
  • The websites for both servers should be SSL site binding (https, 443).
ClosedExporting ADFS Server Certificate with Public Key
1. Within the ADFS server, open the IIS Manager. See http://msdn.microsoft.com/en-us/library/bb763170.ASPX on how to access this.
2. Double-click to open Server Certificates in features view. Click the certificate that is assigned to IIS. Ensure this certificate has a private key.

Server Certificates

3. Click the Details tab, then click Copy to File.
4. Click Next.
5. Select No, do not export the private key, then click Next.
6. Select DER encoded binary X.509, then click Next.
7. Enter the file name with the full path, then click Next.
8. Click Finish.
9. Copy this certificate and paste it into the HEAT Application Server, which sets up the authentication provider.
ClosedConfiguring the HEAT Application Server
1. Upload the HEAT Application Server certificate for the HEATSM tenant. The certificate should include the private key and usually the file extension is .pfx. This certificate will be downloaded later for setting the ADFS signature.
2. Log into the HEAT Configuration Database and open the Tenants workspace. The list of tenants appears.
3. Double-click the HEATSM tenant. The details page appears.
4. Click Add Certificate.

Add Certificate

5. Navigate to the certificate location. This certificate is the same that was used to set up SSL in IIS.
6. Highlight the certificate and click Open.
7. Enter the password for the certificate in the Certificate Password field.

Enter the Certificate Password

8. Click Save.
9. Check to ensure that the certificate has a private key in the Actions pane in IIS.

Check the Certificate Private Key

ClosedSetting Up the ADFS Server

The process for setting up ADFS to work with HEAT is:

ClosedI. Adding New Relying Party on the ADFS System

Configure the ADFS server of the tenant.

Ensure that you install ADFS version 2.0. ADFS version 2.0 is installed from a separate downloadable package. Using the Add Roles Wizard from server manager only installs ADFS version 1.0, which does not include all the required features. Make sure that you install ADFS as a Federation Server.
ClosedII. Ensuring ADFS Forms is on IIS Authentication Types

Ensure that the ADFS form is located in your IIS Manager, after installing ADFS. From the Start menu, choose Control Panel > AdministrativeTools > ADFS 2.0 Management Wizard.

Set Forms Authentication Mode for ADFS

Forms-based authentication basically means that a forms-based .aspx page is presented to the user containing username and password fields. This page is fully customizable so you can add new sign-in logic or page customizations (logos, style sheet, and so on).

1. Open IIS Manager, select the adfs virtual directory and then click Explore.

IIS Manager Window

2. From the \adfs\ls folder, select web.config, then select Edit in Notepad.
3. Find <localAuthenticationTypes>.

There are four lines below <localAuthenticationTypes>. Each line represents one of the local authentication types.

4. Cut the entire Forms line and paste it to the top of the list under <localAuthenticationTypes>:

<localAuthenticationTypes>

     <add name="Forms" page="FormsSignIn.aspx" />

     <add name="Integrated" page="auth/integrated/" />

     <add name="TlsClient" page="auth/sslclient/" />

     <add name="Basic" page="auth/basic/" />

</localAuthenticationTypes>

5. Save and close the web.config file.
ClosedIII. Adding a New Relying Party to the ADFS Manager
1. Select Trust Relationships, right-click Relying Party Trusts, then select Add Relying Party Trust.

Add Relying Party Trust

2. Click Start to begin the wizard.
3. Select Enter data about the relying party manually.

Enter Data about the Relying Party Manually

4. Click Next to set Display Name.
5. Set Display Name. For example, Frontrange ADFS.
6. Click Next to choose your profile.
7. Click Next to Configure Certificate.

Configure Certificate is an optional step—only the Login name is transferred to Frontrange HEAT for authentication, which is also not normally required to be encrypted. However, you can encrypt it by adding the Frontrange SaaS.cer certificate file.

8. Click Next to Configure URL.

On the Configure URL page:

  • Check the Enable support for the SAML 2.0 WebSSO protocol option.
  • Enter the HEAT SAML 2.0 endpoint in the Relying party SAML 2.0 SSO service URL field, https://<tenant URL>/handlers/sso/SamlAssertionConsumerHandler.ashx

Enter the Tenant URL

9. Click Next to Configure Identifiers.
  • In the Relying party trust identifier field, enter <tenant.saasit.com/> and click Add.
Be sure to enter the forward slash at the end.

Enter the Identifier in the Relying Party Trust Identifier Field

  • In the Relying party trust identifiers text box, you can add URLs, as shown:

Add Multiple URLs

Other URLs can be added after you complete the wizard by selecting Properties and then clicking the Identifiers tab.

10. Click Next to Choose Issuance Authorization Rules.
11. Select the Permit all users to access this relying party.
12. Verify your settings and click OK.

A new entry appears under Relying Party Trusts in the ADFS Manager.

ClosedIV. Entering Claim Rule
1. Right-click the new entry that you just created in the ADFS Manager.
2. Select Edit Claim Rules.

Edit Claim Rules

3. Click Add Rule.
4. In the Claim rule template field, select Send LDAP Attributes as Claims.

Send LDAP Attributes as Claims

5. In the Claim rule name field, set a rule name, for example, UPN.
6. For Attribute store, select Active Directory.
7. In the Mapping of LDAP attributes to outgoing claim types section,
  • For LDAP Attribute, select User-Principal-Name.
  • For Outgoing Claim Type, select UPN.

Mapping of LDAP Attributes to Outgoing Claim Types

8. Click OK.
9. Add a second rule to map UPN and NAMEID.
  • Click Add Rule.
  • In the Claim rule template field, select Transform an Incoming Claim.

Map UPN and NAMEID

  • In the Claim rule name field, set a rule name, for example, "UPN and NameID".
  • Incoming claim type: Select UPN.
  • Outgoing claim type: Select NameID.
  • Outgoing name ID format: Select UPN.
  • Select Pass through all claim values.
To enable auto provisioning feature, the following claims should be issued: givenname, surname, and emailaddress.

Client Rule Name Window

10. Click OK.
ClosedV. Getting the Certificate

This is the certificate that you got in HEAT, as described in Supplying the HEAT Certificate File .

1. In ADFS Manager, double-click Service, then open Certificates.
2. Select the token-signing certificate for your site.

This can be a valid public certificate or a private self-signed certificate.

3. Click Copy to file.

Leave No, do not export private key as the default.

Do not select Yes, export private key.

You should not be asked for a password during copying.

Select DER coded binary X.509 (.CER).

Navigate a folder to save to.

If you are remotely connected to another computer, copy the file locally.

Click Finish.

4. Double-click and open the certificate, click the Details tab, and make a note of the serial number of the certificate.

You will need this number later.

ClosedVI. Setting the Properties of the Relay Agent

Before doing this procedure, ensure you have the HEAT certificate file.

1. Double-click the newly created Relying party, or right-click and select Properties.
2. Click the Signature tab.
3. Click Add.
4. Select and open the saas.cer file you just downloaded.

To verify you have the correct certificate, select View, click the Details tab and view the certificate serial number: ‎

21 a6 74 1f 94 cc 59 b0 8c d4 33 aa d7 01 e1 4e.

Ensure that you have the correct certificate, otherwise it will not work and is difficult to troubleshoot.

This certificate has the public key used to encrypt the message to the frontrange system that the user is permitted

5. If your ADFS system is not configured specifically to support SHA-256 digital signatures, which by default it is not, do the following:

Double-click the newly created Relying party, or right-click and select Properties.

Click the Advanced tab.

For Secure hash algorithm, select SHA-I.

Click Apply.

6. Add the logout feature:

In the Properties window, click the Endpoints tab.

Click Add.

Endpoint Properties

For Endpoint type, select SAMLLogout.

For Binding, select POST.

For the URL field, enter https://<tenant URL>/handlers/sso/SamlLogoutHandler.ashx?message=LogoutRequest

For the ResponseURL field, enter https://<tenantURL>/handlers/sso/SamlLogoutHandler.ashx?message=LogoutResponse

Click OK.

Repeat to add a separate entry for each URL.

For example, for the URLs frontrange.saasit.com, frontrange-stg.saasit.com and frontrange-plt.saasit.com, your Endpoints configurations should look as follows:

Sample Endpoint Configurations

7. Click OK.
ClosedSetting Up the SAML Server

The following is a use case for configuring SAML using Okta.

1. Set up your account with Okta.
2. Go to your Okta site and click Administration at the top right-corner of the page.

OKTA Site

3. Click Add Applications.

Add Applications

4. In the Add Application page, enter SAML in the Search field, then choose SAML Service Provider.
5. Configure the general settings:

General Settings

For application label, enter a descriptive name.

You do not need to enter the exact URL for your tenant. You merely need to identify it from a list of applications.

Click Next

6. Configure the Sign On options:

Sign On Options

  • Enter the Assertion Consumer Service URL as https://<tenant URL>/handlers/sso/SamlAssertionConsumerHandler.ashx.
  • Enter the Service Provider Entity ID as an unique number.
  • Keep Okta username as the Default username.
  • Click Next.
7. In the Assign to People step, assign this to users or leave the default user information and select it, then click Next.

A confirmation message that your set up is complete appears.

8. Click Done.
ClosedGetting the Certificate
1. Click the Sign On tab.

Sign On Tab

2. Click the link provided for instructions.
3. Click the link to download the certificate from the identity provider.

Download the Certificate

4. Download and save your certificate.
Rename the file extension to .cer. In the Configuration Console, go to Settings > System > Attachment Extensions and ensure that .cer is a valid file extension. If not, add it to the system.
ClosedConfiguring the HEAT Site Certificate

ADFS authentication requires configuring a public-private key pair on the tenant. ADFS Release 2.0 should be installed on the ADFS computer.

Obtaining a Certificate File with a Private Key (.pfx file).

1. Run the mmc.exe.
2. From the File menu, select Add/Remove Snap-ins.
3. Select Certificates and click Add.
4. Select the default My user account option to add the Certificates snap-in for the current user, and then click Finish.
5. Select the created certificate from Personal certificates, click All Tasks > Export.
6. Select Yes, Export private key and enter your password.

Here you can also create also new .cer file, without private key, to use it on ADFS computer, if your original one contains private key.

On the Tenant Computer, Define the HTTPS Binding for Internet Information Services (IIS) and Add the .pfx File:

IIS > Default Web Site>Edit Binding>Configure HTTPS

Installing the Certificate on the Tenant

1. Log into the tenant configuration database.
2. Open the corresponding tenant record.
3. Select New Certificate and upload the .pfx file.
4. Set the certificate password.
Ensure that the PFX attachment is permitted to be uploaded.

Obtaining and Installing the Public Key for the Certificate

See Supplying the HEAT Certificate File .

This certificate should be provided to the ADFS instance administrator. You can use the public key on the ADFS computer if your original one contains the private key.
Closed Supplying the HEAT Certificate File
Before getting the certificate, ensure that you have configured your ADFS/SAML server. Prior to supplying the HEAT certificate, ensure that you have followed the procedure described in Configuring the HEAT Site Certificate.
1. From the Configuration Console, choose System Setup, then under the Security Settings column, click Get ADFS Certificate.
Some pop-up blockers might prevent the file from downloading. The link gives you the ability to download the Frontrange saasit.com .cer file. Temporarily save this file to your desktop. If for some reason the file does not download, contact FrontRange Support and they can provide the file to you.
2. Continue to configure the server.

Related Information

Authentication Configuration

Authentication Providers

Encryption Keys

Tasks

Password Policy

Reference

Login Priority

API Keys

Copyright © 2011-2014 FrontRange Solutions USA Inc. | All Rights Reserved