Single Sign-On

Single Sign-On (SSO) is a technology that lets corporate networks use external user authentication services (also known as 'identity providers', or IdPs). It is used to set up access authorization within corporate services along with basic authentication methods provided with the local database.

The assigned IdP authenticates users by their logins and passwords. Certain network resources, like applications and servers, are configured to trust the user authentication performed by the IdP. In such cases, users do not need to enter their logins and passwords when accessing these resources.

With SSO enabled, when a user with no active ADFS logon session connects to a SimpleOne instance, they are redirected to the ADFS logon. After typing in their corporate Active Directory (AD) login and password, a user enters an instance with their relevant ID, configuration preferences, membership in groups, roles, and the rest of their personal user context. Every next time such a user connects to the instance before their ADFS logon session is over, they do not enter any login or password and get logged in automatically again.

Configure SSO

In SimpleOne, SSO relies on ADFS 2.0+ as the IdP and the XML-based Security Assertion Markup Language (SAML) 2.0 to exchange data with it. Therefore, as an administrator, you should complete the following tasks before enabling SSO on your instance:

1. Create a SAML connection.
2. Enable the SSO property.
3. Create ADFS Relying Party Trust:
   • through import from XML.
   • manually.
4. Create a SAML Assertion Consumer and Logout Endpoints.
5. Create ADFS relying party claim party rules.
6. Test SAML connection.

Create SAML connection

---

To configure a SAML connection, complete the steps below:

1. Navigate to Single Sign-On → SAML Settings.
2. Click New and fill in the fields.
3. Click Save or Save and exit to apply the changes.

General

Field	Mandatory	Description
Name	N	Specify a SAML connection name.
User field	Y	Specify a field in the User table containing information for user identification. Available options: Email Login ID
Query field	N	Specify the name of a custom attribute on the identity provider side to map the value of the User field.
Active	N	Select this checkbox to make this connection active.

Example of the correlation of the values User field = Name and Query field = SAM-Account-Name for the XML-responses collapse

<saml:Attribute FriendlyName="username"
    Name="SAM-Account-Name"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
  <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="xs:string">ad.viewer</saml:AttributeValue>
</saml:Attribute>

SAML Server Metadata

Field	Mandatory	Description
Metadata URL	Y	Specify the external URL provided by a service provider for authentication. By this address, an XML file containing the federation metadata is located. In most cases, this file is named federationmetada.xml. Most catalog services, like Active Directory, provide a link to this file via their management tools. Provide a public link to the file in this field. In case of a SimpleOne SAML connection, the link should look as follows: https://adfs.example.com/federationmetadata/2007-06/federationmetadata.xml
Metadata	N	This field contains an external service answer (SAML federation metadata) and is populated automatically by the federationmetadata.xml file content.

Additional Information

This tab contains record service information (who and when created or updated the record, and other).

When the record is created, the Open metadata UI action appears at the bottom of the form. Click it to open the https://instance.simpleone.ru/v1/saml/metadata page that allows you to download a metadata file. Import this file when creating a Relying Party Trust. 

Enable SSO

---

To enable SSO for your instance, do the following:

1. Configure at least one SAML connection as described above.
2. Change the simple.sso.active property value to true.

Until the steps above are completed, the authentication proceeds with the use of the local profile storage.

caution

1. The simple.sso.active property cannot be activated until you configure at least one SAML connection and turn it on.
2. Once you turn off all your SAML connections, the simple.sso.active value automatically changes to false.
3. Only one active SAML connection is possible at a time.

Use the simple.sso.active property to disable SSO and to make your instance to authenticate users by logins and passwords from the local profile storage. This may be required, for example, if user authentication data stops coming from the IdP, and users are unable to access the instance. 

tip

A user with the admin role can bypass SSO by logging in to the instance with the local login and password at https://instance.simpleone.ru/side-door, and change the simple.sso.active value to false.

Create an ADFS relying party trust

Import settings from XML file

---

To use a preset configuration data, prepare a metadata file. To do so, complete the steps below:

1. Navigate to https://instance.simpleone.ru/v1/saml/metadata.
2. To copy the metadata into a new file with the '.xml' extension (for example, ExampleComSSOMetadata.xml), right-click the page and select Save as.
3. Save the file.

To configure ADFS relying party, you need to:

1. Log in to your ADFS server and open the management console.
2. Select Relying Party Trusts.
3. Click Add Relying Party Trust on the top right, and then click Start.
4. Select the Import data about the relying party from a file option and attach the file with the metadata info that you previously saved. For example, ExampleComSSOMetadata.xml.
5. Specify a display name and type some notes if needed.
6. Do not select any encryption certificate.
7. Specify user permissions for this relying party. By default, all users are permitted. Click Next.
8. Click Next again, and click Close. A new relying party trust appears.

Field	Description
Import data about the relying party from file	Select the option to import the metadata file you saved earlier.
Federation metadata file location	Attach the metadata .xml file on your device. For example, ExampleComSSOMetadata.xml.
Display name	Specify the name of the relying party.
Notes	Type notes for the relying party you are creating.
Policy	Select the access control type. By default, all users have access to the application.

note

You can get a metadata link like https://instance.simpleone.ru/v1/saml/metadata on every instance with the active SSO, regardless of any SAML connection existing.

Create relying party trust manually

---

To create relying party trust manually, complete the steps below:

1. Log into your ADFS server and open the management console.
2. Select Relying Party Trusts.
3. Click Add Relying Party Trust at the top right corner and click Start with the Claims aware option selected.
4. Select the Enter data about the relying party manually option.
5. Specify a display name and type some notes if needed.
6. From the Configure Certificate step, click Next. Do not select any encryption certificate.
7. On the Configure URL step, select the Enable support for the SAML 2.0 WebSSO protocol.
   • Type https://instance.simpleone.ru
8. Specify Relying party trust identifiers.
   • Relying party identifiers = https://instance.simpleone.ru. Click Add.
9. Specify user permissions for this relying party. By default, the Permit everyone option is selected. Click Next.
10. Click Next again, and click Close. A new relying party trust appears.

Field	Description
Enter data about the relying party manually	Select the option to input the data about the relying party organization manually.
Display name	Specify the name of the relying party.
Notes	Type notes for the relying party you are creating.
Relying party trust identifier	Specify the instance URL and click Add.
Policy	Select the access control type. By default, all users have access for the application.

You also need to configure the created party trust. To do so, complete the following steps:

1. Open the created trust in the ADFS management tool.
2. In the Monitoring tab fill in the following fields:
   • Monitoring relying party = true
   • Relying party's federation metadata URL = https://instance.simpleone.ru/v1/saml/metadata
   • Automaticaly update relying party = false
3. In the Endpoints tab you need to create endpoints. Instructions for creating endpoints are given below.

Create SAML endpoints

Generally, SAML endpoints are created automatically when the relying party trust is created via the setting import. You can create or edit them manually if needed. To create SAML Assertion Consumer Endpoint, complete the steps below:

1. Log into your ADFS server and open the management console.
2. Right-click the relying party trust created earlier.
3. Select the Endpoints tab.
4. Click Add SAML.
5. Enter values as listed below:
   • Endpoint type = SAML 
   • Binding = Redirect
   • Trusted URL = https://instance.simpleone.ru/auth-sso
6. Click OK.

To create SAML Logout Endpoint, complete the following steps:

1. Log into your ADFS server and open the management console.
2. Right-click the relying party trust created earlier.
3. Select the Endpoints tab.
4. Click Add SAML.
5. Enter values as listed below:
   • Endpoint type = SAML Logout
   • Binding = Redirect
   • Trusted URL = https://instance.simpleone.ru/logout
6. Click OK.

List of endpoints specific to SSO

---

An instance configured to use SSO has the following endpoints available for HTTP requests related to signing users in and out:

Endpoint URL	HTTP method	Purpose
https://instance.simpleone.ru/v1/saml/metadata	GET	Metadata .xml file.
https://instance.simpleone.ru/auth-sso	HTTP-Redirect (GET)	User authorization with SSO.
https://instance.simpleone.ru/logout	HTTP-Redirect (GET)	User logout with SSO.
https://instance.simpleone.ru/v1/saml/post	POST	The authentication request.

Create ADFS relying party claim rules

Relying party claim rules allow the system to establish communication with ADFS infrastructure.

There are two main claim rules that should be configured:

• Send LDAP Attribute as Claims – select attributes from the Active Directory to send as claim to the relying party. 
• Transform an Incoming Claim – select an incoming claim, change its claim type and its claim value.

Send LDAP Attribute as Claims

---

To configure the Send LDAP Attribute as Claims rule, complete the steps below:

1. Log into your ADFS server and open the management console.

2. Right-click the relying party trust created earlier.

3. Select the Edit Claim Issuance Policy item.

4. Click Add Rule.

5. Select the Send LDAP Attribute as Claims option in the Claim rule template field and click Next.

6. Name the claim. For example, Get LDAP Attributes.

7. Enter values as listed below:

   • Attribute store = Active directory
   • LDAP Attribute = E-Mail-Addresses
   • Outgoing Claim Type = E-Mail Address.
   note

   You can specify more attributes to be retrieved from AD.

8. Click Finish.

Transform an Incoming Claim

---

To configure the Transform an Incoming Claim rule, complete the steps below:

1. Click Add Rule again.
2. Select the Transform an Incoming Claim option in the Claim rule template field and click Next.
3. Name the claim. For example, Email2Name.
4. Set the Incoming claim type equal to the outgoing claim type in the previous rule. For example, E-mail Address.
5. Set the values as listed below:
   • Outgoing claim type = Name ID
   • Outgoing name ID format = Email
6. Select the Pass through all claim values option.
7. Click Finish.
8. Click Apply and then OK to close the window.

Test an Incoming Claim

To test the configuration, complete the steps below:

1. Navigate to your SimpleOne instance. For example, https://instance.simpleone.ru. If all configurations are set correctly, the system redirects you to https://adfs.example.com/adfs/ls/IdpInitiatedSignon.aspx?logintoRP=https://instance.simpleone.ru/.
2. Sign in to your instance. If the configuration is correct, you will be logged in automatically.
3. Select Logout from the profile menu to test the logout endpoint functionality.