Security

The authentication and authorization settings of the platform are located in the Admin Center under the Misc tab. They are summarized under the topic Security.

When you open the page Security, a selection of login methods is provided here. These can be activated and configured. At the moment only Email and SAML methods are offered.

Email

Two factor authentication

Currently we offer a two-factor authentication via SMS (third party authentication). The first "factor" is your usual password that is standard for any account. The second "factor" is a verification code retrieved from a mobile device.

Platform configuration

Here the two-factor authentication (2FA) can be activated platform-wide. This means that every user can activate the 2FA on his account and configure it for himself. The platform administrator must first configure an SMS supplier here in the Admin Center, through which the SMS are sent.

In this Security E-Mail 2FA settings you can also set a SMS verification text and Recovery email subject and body, both on German and English language.

Workspace configuration

If two-factor authentication has been enabled and configured for the platform, every user can activate 2FA on his account settings. If you don't want to allow this, you can specifically disable two-factor authentication for each workspace. To do this, call the workspace configuration in the AdminCenter. Under the Team Details you will find the tab Security. There you can finally make the setting and disable 2FA.

User settings

After activating 2FA, every user has the possibility to set the two-factor authentication in his profile settings. There a new section for 2FA will appear. Only the mobile number must be entered and the authentication must be activated. Then a validation is done to make sure that the number has been entered correctly.

SAML

We support another option for authentication with the SSO (Single Sign On) standard SAML 2.0 (Security Assertion Markup Language). This can be configured and activated on the SAML page.

We provide an YAML editor for configuring the platform-wide settings. This web-based YAML editor lets you view and edit Yet Another Markup Language configs in the browser. It offers several configuration options, which are explained in the following section.

After the configuration has been made, it can be saved. In addition, the YAML can be validated in between. When saving, it is automatically validated again beforehand. If there are any errors, they will be output in the editor below.

SAML is activated by checking the checkbox Allow Sign In above. However, this does not mean that SAML is enabled for the platform. Before that, the application must be restarted with the button in the lower left corner.

YAML configuration

version (required)

The version of the YAML configuration. Currently version 1.0 is supported.

config (required)

The main settings are made in the config section. The value must always be present.

entityId (required)

The entityID attribute is the unique identifier of the entity. Note well that the entityID is an immutable name for the entity, not a location. These can usually be found in the metadata or federation files (EntityDescriptor node, attribute entityID).

singleSignOnServiceUrl (required)

The Single Sign-On Service endpoint. This endpoint is used by a service provider to route SAML messages, which minimizes the possibility of a rogue identity provider orchestrating a man-in-the-middle attack. This information can also be found in the metadata/federation file (SingleSignOnService node, attribute location).

spEntityId (required)

A unique identifier for a SAML entity. As a Service Provider (this means this platform), you define your Entity ID. You must specify the Entity ID, which must be unique within the IdP so that the IdP can identify your Service Provider.

certificate (required)

The public IdP certificate as Base64 format. This certificate can usually be found in the metadata or federation files.

claimEmail (required)

To be able to register and log in, a unique and persistent ID must be entered. For the platform it is the mail address. This can be supplied in the claims or passed as a NameID. In both cases the claim name must be specified. For standard claim names, the complete designation must be specified, e.g. for NameID claim: e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier.

claimFirstName

In addition, the first name claim can be passed. The passed value is entered during the registration process in the account settings. For standard claim names, the complete designation must also be specified, as for mail claim.

claimLastName

In the same way, the last name can be passed optionally. This is also entered once during registration. Standard claim names must be specified with the complete designation.

claimLanguage

The claim for the language setting can optionally be passed. The claim name is entered here. The passed value is entered during the registration process in the account settings. In addition, the registration process is displayed on the login page in the passed language.

Config example:

version: 1.0

config:
 entityId: https://idp.example.com/Metadata
 singleSignOnServiceUrl: https://idp.example.com
 spEntityId: https://app.tivity.one
 certificate: YKgAwIBAgIQzfcJCkM1YahDtRG...
 claimEmail: Email
 claimFirstName: FirstName
 claimLastName: LastName
 claimLanguage: Language

Login page

After SAML has been configured correctly, activated and the application has been restarted, a new option to log in with SAML appears on the login page.

Sign in script

The SAML configuration offers the possibility to create a script which is executed before a SAML based authentication. In this script claims can be used and offices and groups can be reconfigured. For this purpose, there is an option to create or edit a script in the lower section of the configuration window.

If no script has been created yet, the Create button appears. If a script already exists, an Open and Delete button is available. Clicking Create or Open will open the Script Designer. For a detailed description of the Designer, see the Scripting chapter. Existing scripts can be deleted with the Delete button.

The Script Designer for SAML is slightly different from the usual designer for application configuration. A different context variables is available. Furthermore, additional script actions are offered, which can also only be executed as administrator.

Context variables

Context.Claims List of received claims. Represented as a Dictionary with the claim name as the key. The access to a value is done by the script actions GetEntry or GetValue. All claim values are passed as a list of values to the script. A claim with none or one value is passed as a list. Type: Dictionary<String,List<String>>.

Context.User The user who is about to log in or execute the script. Represented as a Object (like instances in app scripting). Accessing or writing to a value is done by the script actions GetValue or SetValue. Type: Object

Context.UserId For faster access, the ID of the user is also available. This variable is probably needed more often in the script. Type: Guid

Context Script-Actions

• AddUserToGroup

• AddUserToOffice

• DeleteUserFromGroup

• DeleteUserFromOffice

For detailed description see in the reference of this actions.

Example 1 - Use of claims and reconfigure user

Suppose you want to get the last name from the SAML claims and enter the name in the Platform user. To make this possible at least 3 steps are necessary.

1. The first thing to do is to get the name from the sent claims. The best way to do this is to use GetEntry (optionally also with GetValue). As parameters the list of claims and the claim name that contains the required value.

2. With SetValue the determined claim value can be set in the user object. The object (Context.User) and name of the key are passed as parameters.

3. In order for the changes to take effect, the object (Context.User) must be saved with SaveInstance as the last step.

Example 2 - Add user to office or group

Let's assume that you want to add a user with a specific role, which can be read from the claims, to a specific workspace. In addition, the user is assigned to a group. The following steps are necessary for this:

1. As described in the first example, the role is fetched from the claims and written to a variable. GetEntry is used again and the claim name is extRole in the example.

2. The script action EqualTo compares the value from the role. If the queried value is equal, you get into the Then block (IfThenElse action).

3. Now you can easily add the user to an office or group. For this purpose there are the script actions AddUserToOffice and AddUserToGroup. These actions expect the ID of the user (available in variables) and the office or group ID (see tip below on GetSystemId).

4. In addition, you can also delete the added offices/groups again. For this purpose the actions DeleteUserFromOffice and DelelteUserFromGroup are provided, which are equipped with the same parameters as the Add* actions.

User Activities

On the page User Activities the platform administrator can see security-related activities of platform users. The following activities get logged:

• UserLogin: User successfully logs in

• UserLoginAttempt: User attempts to log in but fails

• UserLogoff: User logs off

• UserPasswortChangeRequest: User requests to change their password

• UserPasswordChange: User changes their password

• UserEmailChangeRequest: User requests to change their email

• UserEmailChange: User changes their email

On the Tab Detailed the user, their activity and the timestamp is shown as a list sorted descending by creation.

On the Tab Grouped, the activities are grouped by users. For each user their activities are shown with a count (how many times the specific activity occurred).

Only the activities of the last 90 days are shown or used for grouping.