# 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**. ![Misc tab](https://2608258621-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M8HTRblOKav_qm4KEx6%2F-MUyBdU5TQeouW6DspCn%2F-MUyKbquWs-7bC0W-uxJ%2FAdminCenter-MiscSecurity.png?alt=media\&token=ab78782f-1485-427d-85d2-9b4d468493bf) 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. ![Security](https://2608258621-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M8HTRblOKav_qm4KEx6%2F-MUyBdU5TQeouW6DspCn%2F-MUyMTkXrxMQwOSLLuqG%2FAdminCenter-Security.png?alt=media\&token=6daaa084-f87a-4afc-97ef-4f01d2aed627) ## 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. ![Team Security](https://2608258621-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M8HTRblOKav_qm4KEx6%2F-MV2I3cLtckZqYW10Li_%2F-MV2S3H3qeakJdSrQyjb%2FAdminCenter-TeamSecurity.png?alt=media\&token=a88be58f-85e9-414e-b783-ad33f89c2350) #### 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. ![](https://2608258621-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M8HTRblOKav_qm4KEx6%2F-MLmsdY48vFmmrvi_10R%2F-MLnLaSeYRk_krDycxx1%2FUserAccount-2FA-green.png?alt=media\&token=4db39716-7236-42bb-9a5d-c5000855b280) ## 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. ![Security SAML](https://2608258621-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M8HTRblOKav_qm4KEx6%2F-MV2I3cLtckZqYW10Li_%2F-MV2Vmw452fXdKJUjClq%2FAdminCenter-SecSaml.png?alt=media\&token=a14f0f42-233b-4482-8c0e-345af3729689) 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. {% hint style="warning" %} To enable SAML for the platform, the application must be restarted. {% endhint %} ### 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](https://en.wikipedia.org/wiki/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. . `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: ```yaml 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. ![](https://2608258621-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M8HTRblOKav_qm4KEx6%2F-MYG4I433cVp5c13TPve%2F-MYGA-2sL9JkBvUP3Pa9%2FLogin-Saml.png?alt=media\&token=2b1364d3-5a63-401c-973c-020c2ec79afe) ### 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. ![Script configuration](https://2608258621-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M8HTRblOKav_qm4KEx6%2F-M_1GZSVBYzF9qrFLpAi%2F-M_1MwJfA5Kl8i0HP1bq%2FAdminCenter-SamlScipt.png?alt=media\&token=73f936b1-3a01-4676-97a5-d37471e374a7) 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](https://docs.tivity.one/building-an-application/execution/scripting) chapter. Existing scripts can be deleted with the *Delete* button. {% content-ref url="../building-an-application/execution/scripting" %} [scripting](https://docs.tivity.one/building-an-application/execution/scripting) {% endcontent-ref %} 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\>. ***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](https://docs.tivity.one/building-an-application/execution/scripting/functions/admin). {% content-ref url="../building-an-application/execution/scripting/functions/admin" %} [admin](https://docs.tivity.one/building-an-application/execution/scripting/functions/admin) {% endcontent-ref %} #### 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. ![Use of claims and reconfigure user](https://2608258621-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M8HTRblOKav_qm4KEx6%2F-M_6ceRwp4usFY6v6NdL%2F-M_6gdqpqMXRVOPOTURg%2FSecurity-SamlScript.png?alt=media\&token=709eb2bf-1411-40dc-bcde-1e62b5308228) {% hint style="info" %} **Tip**: In order to enter the key name correctly, you should determine the key with the inline action **GetSystemName**. Simply write 'user' or 'field' in the search field. After that all available keys of the user are listed.

{% endhint %} #### 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. ![](https://2608258621-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M8HTRblOKav_qm4KEx6%2F-M_M85A8iF9Sf8L89yw_%2F-M_MCR9NFtIcaap2U4fc%2FSecurity-SamlScript2.png?alt=media\&token=e2efbc26-12c7-487b-9066-62ec9eae0ecc) {% hint style="info" %} **Tip**: To be able to enter the office or group ID correctly, you should get the ID with the inline action **GetSystemId**. Just write 'office' or 'group' in the search field. All available offices or groups will be listed. Of course, you can also search for the corresponding name.

{% endhint %} ## 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.