Trustelem administration

Summary

WALLIX Trustelem provides Identity-as-a-Service (IDaaS) including a cloud Single Sign-On (SSO) and Multi-Factor Authentication (MFA).

The goal is to unify, secure and simplify user access to their applications

SSO.png SSO with or without mfa, using web protocols LDAP-Radius.png LDAP or Radius authentication, with or without MFA, but with no possibilities of SSO

Wallix Trustelem has an offer dedicated to WALLIX products (Bastion and Access Manager) which is named WALLIX Authenticator.

When you start with WALLIX Trustelem, you receive a domain.
This domain is used for:

In order to do this setup, there are 3 major steps:

In addition, Trustelem offers a lot of other features like passwordless authentication, self-service password reset, api...
Finally, you have tools to follow each event of your subscription.

Users created on Trustelem
Users from Azure AD
Users from GSuite

For the moment, the documentation is only available directly on the directory settings, on Trustelem admin console.

Users from Active Directory
Notes

There are different kinds of applications:

SAML and OpenID Connect

These protocols are used for Single Sign On authentications.
To authenticate to your application, you need to authenticate to Trustelem with a browser first.
Then, if you go to another application using SAML/OpenID Connect, you are already authenticated to Trustelem so you don't have to provide your credentials again.
Consequently, you have a single sign on.
To setup these applications, you need to establish a trust relationship between the application and Trustelem.
The goal is to give to the application the ability to verify the identity of Trustelem and the URL needed to communicate.
When a user wants to authenticate, the application can redirect him to Trustelem then use the attributes received without risks.
So implementing SSO authentication for a client application consists in:

Example for Google application:

apps.png

Note: you can find the documentation of each application on their settings page, or on this website.

Basic without SSO

The authentication on these applications is only possible by providing a username and a password stored by the application.
That means Trustelem can't provide the users identity to the application.
Consequently, add an application like that allows to have a redirection link on the user dashboard but not to authenticate.
Note: Trustelem is working on a passwords keeper in order to improve the security and the user experience for these applications.

LDAP and Radius

With these protocols, the authentication on Trustelem has to be done for each authentication on the application.
So the credentials used are still unique, and still the same as for other Trustelem authentications, but it's not a single sign on.
LDAP and Radius can be activated on each kind of generic models, or on specific pre-integrated models (WALLIX Bastion, VPN...).
Note: you can find the documentation on the pre-integrated applications settings page, and you have a global documentation about LDAP and Radius on this website.

When you have users and applications, you can create access-rules in order to define how users will authenticate to an application.
Documentation about access rules: https://trustelem-doc.wallix.com/books/trustelem-administration/page/access-rules
Documentation about multi factors authentication: https://trustelem-doc.wallix.com/books/trustelem-administration/page/multi-factors-authentication

Integrated Windows Authentication (IWA)

Integrated Windows Authentication (IWA) is an authentication using the Kerberos token of the user Windows session.
For a user point of view, it's a passwordless authentication.
Documentation: https://trustelem-doc.wallix.com/books/trustelem-administration/page/integrated-windows-authentication

Self Service Password Reset (SSPR)

The Self Service Password Reset (SSPR) allows user to reset his password using Trustelem login page.

sspr.png

Documentation: https://trustelem-doc.wallix.com/books/trustelem-administration/page/self-service-password-reset

Replace the password by a certificate

By uploading a root certificate or users' certificates on to Trustelem, it is possible to remove the first authentication (login+password authentication).
Documentation: coming soon

API

Using APIs, you can create your own tools to manage your subscription: synchronize users from local files, build your own form for user creation, create alerts based on the logs...
Documentation: https://trustelem-doc.wallix.com/books/trustelem-administration/page/api

Admin Dashboard

https://admin-mydomain.trustelem.com/app#/dashboard

The dashboard provides a summary of the subscription state:

admin-dashboard.png

Logs

https://admin-mydomain.trustelem.com/app#/logs

Every interaction with Trustelem from administrators, users or directories is visible here.

logs.png

Alerts

https://admin-mydomain.trustelem.com/app#/alert

When a user requests help (for an authentication or a self-service password reset), administrators receive an email to notify them of the new alert.
The admin can generate a code/link required to unlock the user.

alerts.png

Sessions

https://admin-mydomain.trustelem.com/app#/sessions

Users logged in Trustelem are visible here.
The red trash allows the administrators to kill the session.
Note: killing a Trustelem session doesn’t mean users will be disconnected from their applications.

sessions.png

1/ Add users and groups
2/ Setup Multi Factor Authentication
3/ Add applications
4/ Setup access rules
5/ Activate the needed advanced features 
6/ Get prepared for production phase
7/ Switch to production
8/ Follow-up

Access rules

Contents

What access rules are?

If possible, an access rule should always apply to a group.
Doing that you only have to add users to the right groups to manage the access.
It is also a way to have a limited number of access rules and a better visibility.
Of course you can still search for a user in the Access rules tab to see which permissions are applied, even if they are related to a group.

Priorities

When a user / group is affected by more than one access rule for a single application, the following priorities apply:

In summary:

Access forbidden (user) > 2 factors (user) > 1 factor (user) > Access forbidden (group) > 2 factors (group) > 1 factor (group)

Example

John Doe is in groups "Customer Success" and "Support" and he wants to authenticate on salesforce.

Permissions defined:

No permission is set to the default value, so this setting doesn't apply.
For internal zone we have 1 factor (customer success) and 2 factors (support) for groups and no rule specified for his account --> the authentication will use 2 factors
For external zone we have 2 factors (customer success) and forbidden (support) for groups and 2 factors for his account --> the authentication will use 2 factors again.

--> John needs 2 factors to access salesforce for both internal and external zone.

Web authentication - Apps SAML, OpendID Connect, and No SSO

Permissions for this apps may depend on the user's public IP address.
In this case, the internal IPs must be defined on Security settings / General / Internal network.
Internal IPs are usually the public IPs of the company offices.
If the user has a known public IP, the access rule for internal zone applies, if not the access rule for external zone applies

Possible values:

LDAP authentication

LDAP applications do not provide users public IP, so there are no internal and external permissions.
1 factor or 2 factors LDAP permissions allow the application to:

If a user doesn't have a LDAP 1 or 2 factors permission, the application can't find him with a search request

Possible values:

Radius authentication

Radius applications do not provide users public IP, so there are no internal and external permissions.

Possible values:

Active Directory users - Trustelem ADConnect

Contents

How does it work?

The goal is to use Active Directory as an identity provider for Trustelem.
To do so, a connector, Trustelem ADConnect, is installed on a customer Virtual Machine.

Using this connector, Trustelem can synchronize and authenticate users selected by Trustelem administrators, based on their AD memberOf.

schema-tlm-adconnect.PNG

1/ During the setup, Trustelem ADConnect opens a websocket to admin.trustelem.com using port 443.
Note: with the websocket, information is encrypted by TLS protocol and with an additional symmetric encryption.

2/ Trustelem sends search / authentication requests to Trustelem ADConnect using the websocket.

3/ Trustelem ADConnect sends the request to Active Directory using LDAP(S) with the service account running the connector.

4/ Active Directory replies to the request from Trustelem ADConnect using LDAP(S).

5/ Trustelem ADConnect sends the answer to admin.trustelem.com using the websocket

Note: thanks to this connector Trustelem does not store any password for Active Directory users.

Prerequisites

Setup on Windows

Setup on Linux

Debug

The connector doesn't appear in the setup page on the admin page

There is no group when I click on Add on the field Sync groups

My group doesn't contain all users

Updating the connector

The connector Trustelem ADConnect can be updated without any service interruption:

API

APIs are available in the API / scripts tab:

https://admin-mydomain.trustelem.com/app#/api-scripts

Note: if you don't have access to this feature, please contact WALLIX Trustelem support.

Using APIs, you can create your own tools to manage your subscription: synchronize users from local files, build your own form for user creation, create alerts based on the logs...

Add a usable script

1-Add a new script

2-Add a new API key if required

3-Edit the API key

4-Provide the allowed IPs and select the new script

5-Click on the script to see a sample command

Example:

Name: create_user
Sample command:
  curl -X POST -H 'Authorization: Bearer ZPUAtMc...KYYAej4e' https://admin.trustelem.com/api/script/46e3xi...gtea/create_user

api.png

Edit the script

function handler: contains the script in TypeScript language

type Input: contains the parameters required to launch the script

type Output: contains the result which will be provided by the script

Note: you can start from scratch or load examples:

Example with the script simple_create_user

function handler contains:

//Create the input with the provided parameters
const input = req.ReadJSON(true);
//Call the API create user with the previous parameters
const result = api.createUser({
    email: input.email,
    firstName: input.firstname,
    lastName: input.lastname,
    passwordInit: { kind: 'temporaryPassword' }
});
//If there is an error, send it as the result
if (isError(result)) {
    w.JSON({ error: result.error })
} else {
//Else, provide the temporary password as the result
w.JSON({ password: result.temporaryPassword });
}

type Input contains the provided parameters:

{
    email: string;
    firstname: string;
    lastname: string;
}

type Output contains the result parameters:

{
    password: string;
    } | {
    error: string;
}

API request:

curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer yyhp3yD…lWfxfl8J' -d '{"email":"jdoe@test.com","firstname":"John","lastname":"Doe"}' https://admin.trustelem.com/api/script/wg5…qia/create_user

Response:

{"password":"mkrc2o6mo2ka"}

Datatype

interface User {
id: UserID;
firstName: string;
lastName: string;
UUID?: string;
userPrincipalName?: string;
email: string;
email2?: string;
mobilePhone?: string;
secondaryPhone?: string;
trustelemAdmin?: boolean;
suspended?: boolean;
accountExpiration?: string
primaryDirectory?: DirectoryID;
allDirectories?: DirectoryID[];
attributes?: AttributeManager;
groups?: {
    id: GroupID;
    name: string;
}[];
}

Note: the attributes can be request using getValue, getValues or list

interface AttributeManager { getValue(name: string): string | null; getValues(name: string): string[]; list: { name: string; value: string }[] };

Create a user

Create a new user, if sendActivationEmail is true, send a mail for setting password, InitPWD will be filled otherwise

createUser(args: {
    email: string;
    email2?: string;
    firstName?: string;
    lastName?: string;
    accountExpiration?: Date | number | string | null;
    isAdmin?: boolean;
    groups?: GroupID[];
    passwordInit?: { kind: 'temporaryPassword' } | { kind: 'link'; expireMinutes?: number; redirectURL?: string; openSession?: boolean };
}): { id: UserID; temporaryPassword: string; passwordInitURL: string } | { error: string };

Description:

Possible errors:

Read a user

Get a specific user by id, email or upn

getUser(args: {
    id?: UserID;
    email?: string;
    userPrincipalName?: string;
}): User | null;

Description:

Update a user

Update a specific user by id

updateUser(args: {
    id: UserID;
    firstName?: string;
    lastName?: string;
    email?: string;
    email2?: string;
    isAdmin?: boolean;
    suspended?: boolean;
    accountExpiration?: Date | number | string | null;
    groups?: GroupID[];
}): { error?: string; };

Description:

Possible errors:

Delete users

Remove specific users by id

deleteUsers(args: { users: UserID[]; }): {
    deleted: {
        id: UserID;
        email: string;
    }[];
    errors?: string[];
};

Description:

Possible error:

Search users

Return the list of users in the organization

listUsers(args: {
    withGroups?: boolean;
    withAttributes?: boolean;
}): User[];

Description:

Add or Set Trustelem user attributes

Add a value (or several values) to a Trustelem user attribute.

addUserAttr(args: {
    userID: UserID;
    name: string;
    value: string;
} | {
    userID: UserID;
    name: string;
    values: string[];
}): { error?: string; };

Set the value (or the values) of a Trustelem user attribute.
This function deletes all previously existing values for this Trustelem attribute.

setUserAttr(args: {
    userID: UserID;
    name: string;
    value: string;
} | {
    userID: UserID;
    name: string;
    values: string[];
}): { error?: string; };

Description:

Possible errors:

Delete Trustelem user attributes

Delete one or more Trustelem attribute values from a user:

delUserAttr(args: {
    userID: UserID;
    name: string;
    all: true;
} | {
    userID: UserID;
    name: string;
    value: string;
} | {
    userID: UserID;
    name: string;
    values: string[];
}): { error?: string; };

Description:

Possible errors:

Reset a user password

Generate a code or a link allowing a user to reset its password

resetPassword(args: {
    id: UserID;
    method?: { kind: 'code'; expireMinutes?: number } | { kind: 'link'; expireMinutes?: number; redirectURL?: string; openSession?: boolean };
}): { resetCode: string; resetLink: string; expirationDate: string } | { error: string };

Description:

Possible errors:

Datatype

interface Group {
    id: GroupID;
    name: string;
    UUID: string;
    directoryID?: DirectoryID;
}

Create

Create a new group

createGroup(args: {
    name: string;
    users?: UserID[];
}): { id: GroupID } | { error: string };

Description:

Possible errors:

Read member

List users from groups

getGroupMembers(args: { id: GroupID; }): {
    users: {
        userID: UserID;
        email: string;
    }[];
};

Description:

Update

Add user(s)

Add a list of users to a group

addUsersToGroup(args: {
    id: GroupID;
    users: UserID[];
}): { Added: UserID[] } | { error: string };

Description:

Possible errors:

Remove user(s)

Remove a list of users from a group

removeUsersFromGroup(args: {
    id: GroupID;
    users: UserID[];
}): { Removed: UserID[] } | { error: string };

Description:

Possible errors:

Delete

Delete a group not synchronized from a directory

deleteGroup(args: { id: GroupID; }): { error?: string; };

Description:

Possible error:

Search

By id

Get a specific group by id

getGroup(args: {
    id?: GroupID;
    name?: string;
}): Group | null;

Description:

List

Return the list of groups in the organization

listGroups(args: {}): Group[];

Description:

Datatype

interface App {
    id: AppID;
    name: string;
}

List

Return the list of applications in the organization

listApps(args: {}): App[];

Description:

Search

Get a specific App by id

getApp(args: {
    id?: AppID;
    name?: string;
}): App | null;

Description:

Datatype

interface Perm {
    appID: AppID;
    groupID: GroupID;
    userID: UserID;
    internalZone: ZoneSecurityLevel;
    externalZone: ZoneSecurityLevel;
    ldapZone: ZoneSecurityLevel;
    radiusZone: ZoneSecurityLevel;
}

type ZoneSecurityLevel = '' | 'default' | '1_factor' | '2_factors' | 'forbidden';

Description:

The ZoneSecurityLevel can be one of the 5 following values:

Examples:

John Doe is in groups “Customer Success” and “Support”

Permissions defined:

For internal zone we have 1 factor and 2 factors for groups and not specified for user --> 2 factors For external zone we have 2 factors and forbidden for groups and 2 factors for user --> 2 factors

John needs 2 factors to access salesforce for both internal and external zone.

List

Return the list of permissions for a user, a group or an application

listPerms(args: {
    userID?: UserID;
    groupID?: GroupID;
    appID?: AppID;
}): { perms: Perm[] } | { error: string };

Description:

Possible errors:

Set

For group

Create or update a permission for a group

setGroupPerm(args: {
    groupID: GroupID;
    appID: AppID;
    internalZone: ZoneSecurityLevel;
    externalZone: ZoneSecurityLevel;
    ldapZone?: ZoneSecurityLevel;
    radiusZone?: ZoneSecurityLevel;
}): { error?: string; };

Description:

Possible errors:

For User

Create or update a permission on a user

setUserPerm(args: {
    userID: UserID;
    appID: AppID;
    internalZone: ZoneSecurityLevel;
    externalZone: ZoneSecurityLevel;
    ldapZone?: ZoneSecurityLevel;
    radiusZone?: ZoneSecurityLevel;
}): { error?: string; };

Description:

Possible errors:

Delete

Delete a permission for a user, or a group to an application

deletePerm(args: {
    userID?: UserID;
    groupID?: GroupID;
    appID: AppID;
}): { error?: string; };

Description:

Possible errors:

Read

For user

Return consolidated (computed from list of permissions) permissions for a user

getEffectiveAppsPermsForUser(args: { userID: UserID; }): {
    appID: AppID;
    appName: string;
    internalZone: EffectiveZoneSecurityLevel;
    externalZone: EffectiveZoneSecurityLevel;
    ldapZone: EffectiveZoneSecurityLevel;
    radiusZone: EffectiveZoneSecurityLevel;
}[];

Description:

Possible errors:

For app

Return consolidated (computed from list of permissions) permissions for an app

getEffectiveUserPermsForApp(args: { appID: AppID; }): {
    userID: UserID;
    internalZone: EffectiveZoneSecurityLevel;
    externalZone: EffectiveZoneSecurityLevel;
    ldapZone: EffectiveZoneSecurityLevel;
    radiusZone: EffectiveZoneSecurityLevel;
}[];

Description:

Possible errors:

Datatype

interface Log {
    id: LogID;
    date: string;
    level: string;
    msg: string;
    details?: string;
    userID?: UserID;
    userEmail: string;
    ip: string;
    useragent: string;
}

List

Return the list of logs in the organization

listLogs(args: { start?: Date, end?: Date, order?: 'fromEnd' | 'fromStart', pageSize?: number, pageToken?: string }): { logs: Log[]; nextPageToken: string } | { error: string; };

Description:

Possible errors:

Datatype

interface Alert {
    id: AlertID;
    date: string;
    msg: string;
    userID: string;
    read: boolean;
}

List

List the alerts

listAlerts(args: {
    unreadOnly?: boolean;
    since?: string;
}): Alert[];

Description:

Acknowledge

Update an alert to be marked as read

markAlertAsRead(args: { alertID: AlertID; }): { error?: string; };

Description:

Possible errors:

Datatype

interface Session {
    id: SessionID;
    kind: string;
    userID: UserID;
    created: string;
    modified: string;
    expires: string;
    deleted: boolean;
    ip: string;
    userAgent: string;
}

List

List the sessions

listSessions(args: {
    showDeleted?: boolean;
    since?: string;
    limit?: number;
}): Session[];

Description:

Datatype

interface AuthToken {
    id: AuthTokenID;
    userID: UserID;
    kind: TokenKind;
    name: string;
}

List

List the second factors of a user

listAuthTokens(args: { id: UserID; }): { authTokens: AuthToken[] } | { error: string };

Description:

Possible errors:

Issue

Send a challenge to a second factor

issueAuthToken(args: {
    userID: UserID;
    tokenID: AuthTokenID;
    message?: string;
}): { challengeID: ChallengeID } | { error: string };

Description:

Possible errors:

Verify

Verify the answer to a second factor challenge

verifyAuthToken(args: {
    userID: UserID;
    challengeID?: ChallengeID;
    tokenID?: AuthTokenID;
    passCode?: string;
}): { status: 'success' | 'waiting' | 'rejected' | 'timeout' | 'failed' } | { error: string };

Description:

Possible errors:

Example

List the available authtokens

Script used:

let res: Output = api.listAuthTokens({
    id: "u68446589",
});

Response:

{"authTokens":[
{"id":"at1798391","userID":"u68446589","kind":"GA","name":"default"},
{"id":"at1954553","userID":"u68446589","kind":"TLM_AUTH","name":"samsung"},
{"id":"at1954598","userID":"u68446589","kind":"SMS","name":""}
]}
Use API to verify the factor Google Authenticator

Code provided by Google Authenticator: 123456

Script used:

//{"ID":"at1798391","UserID":"u68446589","Kind":"GA","Name":"default"}
let res: Output = api.verifyAuthToken({
    userID: "u68446589",
    //challengeID: "",
    tokenID: "at1798391",
    passCode: "123456"
});

Response:

{"status":"success" }
Use API to verify the factor SMS

Script used:

{"ID":"at1954598","UserID":"u68446589","Kind":"SMS","Name":""}
let res: Output = api.issueAuthToken({
    userID: "u68446589",
    tokenID: "at1954598",  
});

Response:

{"challengeID":"c_6a809214faf216e33cfbc668a346f136"}

Sms received with the code: 123456

Script used:

let res: Output = api.verifyAuthToken({
    userID: "u68446589",
    challengeID: "c_6a809214faf216e33cfbc668a346f136",
    //tokenID: "",
    passCode: "123456"
});

Response:

{"status":"success" }
Use API to verify the factor Trustelem Authenticator

Script used:

{"ID":"at1954553","UserID":"u68446589","Kind":"TLM_AUTH","Name":"samsung"}
let res: Output = api.issueAuthToken({
    userID: "u68446589",
    tokenID: "at1954553",  
});

Response:

{"challengeID":"c_6a809214faf216e33cfbc668a346f137"}

Notification received then accepted on Trustelem Authenticator

Script used:

let res: Output = api.verifyAuthToken({
    userID: "u68446589",
    challengeID: "c_6a809214faf216e33cfbc668a346f137",
    //tokenID: "",
    //passCode: ""
});

Response:

{"status":"success" }

Application scripts

Add a script

script.png

Some examples for SAML applications

Add a constant attribute

msg.setAttr("attribute","value");

Add an attribute containing Trustelem groups

for(let g in groups){
    msg.addAttr("Groups",g);
}

Change the user email

if (user.email == 'john.doe@contoso.fr') {
    msg.setAttr("email","isabelle.doe@contoso.fr"); 
}

Some examples for OpenID Connect applications

Add a constant attribute

claims["attribute"] = "value";

Send a user attribute

claims["Profile"] = user.getAttr("profile");

Add an attribute containing Trustelem groups

claims["Groups"] = JSON.stringify(groups);

Associating Google accounts on mobile devices

Warning

For users having already migrated to Google for Work

For users who have not yet migrated to Google for Work

Authentication with an external IDP

In this page, we will see how to authenticate from an external IDP to a Trustelem subscription.

First, we will setup the authentication from an Azure subscription to a Trustelem subscription, then we will setup the authentication from a Trustelem subscription to another.

From Azure to Trustelem

In this chapter, we'll explain how to authenticate from an Azure subscription to a Trustelem subscription.
For the sake of clarity, we'll use the following terms:

Simple authentication (no Just In Time provisioning)

As there is no Just In Time provisioning yet, the user to authenticate must exist on Trustelem.

  1. Go on Trustelem and add an external IDP Identity Providers > Add
    Then copy the Redirect URI

    17-EXT-IDP.png

  2. Go on Azure, and add an application App registrations > New registration
    Then in the field "Redirect URI", select "Web" and paste the Redirect URI copied before.

14-EXT-IDP.png

  1. Add the following values from Azure, to the previous Trustelem external IDP:
    • ClientID:
      Copy the Application (client) ID from the Overview page
    • ClientSecret:
      Generate a new client secret from Manage > Certificates & secrets and copy its value
    • Metadata URI:
      Copy the OpenID Connect metadata document from Overview > Endpoints
      The Issuer will be automatically completed based on this URL.
    • Scopes:
      Remove "groups", the value should be: "openid profile email"

16-EXT-IDP.png

  1. Add API rights for the Azure app

    • Go to Manage > API permissions > Add a permission > Microsoft Graph > Delegated permissions
    • Tick email, openid and profile then save
    • Click "Grant admin consent"

  2. On Trustelem, verify if the user to authenticate exists.

  3. Try the authentication, on Trustelem

    • Click Azure button, you are redirected to Azure
    • Provide the login and password: you are now authenticated to Trustelem

Just-in-time provisioning

When just-in-time provisioning is implemented, step 5 in the previous chapter is no longer necessary.
In fact, when Provisioning is enabled, users will be able to authenticate on Trustelem even if they don't yet exist. In this case, an account will be created on the basis of OpenID Connect attributes.

19-EXT-IDP.png

3 additional options are available:

  1. User linking
    If this option is disabled, users who already exist locally will not be able to authenticate, as the 2 accounts (local + IDP) cannot be merged.

  2. Default group
    Users who authenticate via the external IDP will be added to this group.
    If the group does not exist yet, it will be automatically created.

  3. Group management
    Group management for IDP users (and all related local accounts) is based entirely on the OpenID Connect group attribute. The user is automatically added to these groups, which are created if they don't yet exist. In addition, the user is removed from all groups which are not present in the OpenID Connect groups.

    On Azure, the scope "groups" is not allowed, as a consequence you need to manually add the group attribute:

    • On your Azure app, go to Manage > Token configuration then add a groups claim
    • Tick "All groups"
    • For the field "Access", if the groups come from Active Directory, you can tick sAMAccountName and the attributes returned to Trustelem will be the group names. If some of the groups don't come from AD, then tick Group ID and the attributes returned to Trustelem will be the group IDs.
      You can now save the groups claim.
    • Add the claim "groups" on your Trustelem External IDP setup


    Finally, you can add a prefix to IDP groups, which will be created on Trustelem.
    You can also prevent certain groups from being used.
    For example, ^Internal.* will prevent the use of the OpendID Connect attribute beginning with Internal.

From Trustelem to Trustelem

In this chapter, we'll explain how to authenticate from one Trustelem subscription to another.
For the sake of clarity, we'll use the following terms:

In other words, we want to authenticate to Trustelem SP with Trustelem IDP.

Simple authentication (no Just In Time provisioning)

As there is no Just In Time provisioning yet, the user to authenticate must exist on Trustelem SP.

  1. Go on Trustelem External, and add an application Apps > Add an application
  2. Choose an OpenID Connect application
  3. Click on Display setup instructions, then copy:
    • ClientID
    • ClientSecret
    • Issuer

3-EXT-IDP.png

  1. Go on Trustelem Internal and add an external IDP Identity Providers > Add

4-EXT-IDP.png

  1. Paste the previous copied values

5-EXT-IDP.png

  1. Copy the Login URI and the Redirect URI then Save the configuration
  2. Return to the OpenID Connect app on Trustelem External, and paste the 2 copied values
    Then, save the configuration.
    Optionally, you can complete the scopes with “openid profile email groups” but if the field is empty, the same content will be used by default.

7-EXT-IDP.png

  1. Now on Trustelem External, create a permission for the user you want to authenticate.
    In my example, I want to create a 1 factor permission for my app "Trustelem IDP" for the user pchaudy@wallix.com
  2. On Trustelem Internal, verify if the user "pchaudy@wallix.com" exists.
  3. Try the authentication, on Trustelem Internal

10-EXT-IDP.png

Click Trustelem button, you are redirected to Trustelem External

11-EXT-IDP.png

Then after providing the login and password, you are authenticated to Trustelem Internal

Just-in-time provisioning

Just-in-time provisioning can be implemented after step 8 in the previous chapter. In this case, step 9 is no longer necessary.
In fact, when Provisioning is enabled, users will be able to authenticate on Trustelem, even if they don't yet exist. In this case, an account will be created on the basis of OpenID Connect attributes.

19-EXT-IDP.png

3 additional options are available:

  1. User linking
    If this option is disabled, users who already exist locally will not be able to authenticate, as the 2 accounts (local + IDP) cannot be merged.

  2. Default group
    Users who authenticate via the external IDP will be added to this group.
    If the group does not exist yet, it will be automatically created.

  3. Group management
    Group management for IDP users (and all related local accounts) is based entirely on the OpenID Connect group attribute. The user is automatically added to these groups, which are created if they don't yet exist. In addition, the user is removed from all groups which are not present in the OpenID Connect groups.

    To operate, you need to configure the OpendID Connect attribute, or claim, which will contain the groups. For Trustelem "groups" is usually used.

    Finally, you can add a prefix to IDP groups, which will be created on Trustelem.
    You can also prevent certain groups from being used.
    For example, ^Internal.* will prevent the use of the OpendID Connect attribute beginning with Internal.

Azure AD users

Contents

How does it work?

The goal is to use Azure Active Directory as an identity provider for Trustelem.
It requires the creation of an "app" in Azure AD admin console for authorizing Trustelem to request Azure AD data using API.
For the synchronization, Trustelem uses the Microsoft API to list the groups and their members.
For the authentication, Trustelem sends an authentication request using Microsoft API and if it is validated, authenticates the user on Trustelem.

Prerequisites

No prerequisite, every steps of the setup are listed in the following chapter.
Note: it is not possible to authenticate users with their AzureAD password if Azure delegates the authentication to an external Identity Provider such as Trustelem.

Setup

Notes:

Certificate renewal

If you received and email like the following one, that means the certificate used by some applications will expired soon or has already expired:

You receive this message because you are a Trustelem administrator for -Trustelem subscription-.
The following applications are federated using the certificate -Name of the certificate- that has expired on 2021-12-18 at 14:14.
• MyApp 1
• MyApp 2
It is recommended that you reconfigure those applications as soon as possible to use a more recent certificate to avoid any service outage.

The applications might refuse the authentication if the certificate used has expired, so it is important to fix this situation.

Generate a new certificate

Go to your Trustelem admin page, then Security settings, then Application certificates and click on +Create.

Change the applications certificate

OpenID Connect applications

Note: with OpenID Connect, you shouldn' have to change the certificate in the application directly. But in some rare cases it might happen. So if the authentication isn't working, get back to the old certificate on the Trustelem application, then go to the application and verify if the certificate is provided in the setup.

SAML applications

Note: the applications rarely use the URL for the certificate. So you will probably have to change the certificate or the metadata manually. The consequence will be a short indisponibility between the change on Trustelem and the change on the application.

For O365

Office doesn't have a web interface to change the certificate : you will need Powershell.

Custom themes

The aspect of users login pages and users dashboard can be change.

The settings are done in the tab Graphical themes or using the URL:

https://admin-mydomain.trustelem.com/app#/themes

Note: right now, this feature is not activate by default. If you want to customize your login page / dashboard, please email support-trustelem@wallix.com.

What can I do?

On this page you can:

theme1.png

By creating a theme, you can:

theme2.png

theme3.png

How does it work?

The edit page is divided in 3 parts:

To add a new file, just click on +Add on one of the 3 parts. Then select the file needed or import your own file.

theme4.png

In order to know what does each file, you have some documentation:

theme5.png

Finally, if you click on the eye buttons, you will have a preview of your pages.

Delegated administration

The delegated administration is a tool which offers the possibility to let non-Trustelem admin users administrate only Trustelem groups.
This new kind of administrator can do the following things on the administered groups:

dav2.PNG

To enable this tool, you need to send an email to your WALLIX sales contact.
This tool can be easily customized: change the logo or the background, remove a feature...

How to setup the Delegated administration

Once the tool enabled, you will have a new app on Trustelem named "Delegated administration". You can change its name and logo.

delegated-admin2.PNG

The first step for the setup is to give access for the selected users to this app using Trustelem tab Access rules

delegated-admin3.PNG

As usual, you can give individual rights for each delegated administrator but it's better to create a group for all of them and add a unique permission.

Then you need to go on the Trustelem profile of your delegated administrators, and add one attribute per group :

dav2_4.PNG

Instead of providing a group name, you can also use regular expressions to select multiple groups.
For instance regexp:.* will select all existing groups.

Still for the value field, you can add ;max:X to limit to X the maximum users number in the group, managed by this delegated administrator.

Finally, still on the same field, you can add assignableGroups:group1,group2,groupN to offer the possibility to add other groups to the users.

delegated-admin4.PNG

The first example let the administrator manage Trustelem group named TMA-Bastion with no additional features.
The second example let the administrator manage all Trustelem groups with a maximum of 3 users inside them.

editableGroups.PNG In the screenshot, there is "editableGroups" instead of "assignableGroups", because it changed --> this image will be modify. The right value is "assignableGroups".

The third example let the administrator manage Trustelem group named Supplier1 with a maximum of 5 users inside and the possibility to add the groups rdp and ssh to the 5 users.

Use case 1

One group on Trustelem is dedicated to one Supplier and gives all the requested access to applications.
This group is named Supplier1.
To handle license abuses, this group is limited to 10 users.
In this case the attribute groupManager should have the value: Supplier1;max:10

dav2_1.PNG

Use case 2

One group on Trustelem gives access to Google for users coming from Supplier2 and Supplier3.
This group is named Google
Another group on Trustelem gives access to SalesForce for users coming from Supplier2 and Supplier3.
This group is named SalesForce
I have 2 other groups: one name Suppliers2 with users coming from Suppliers2 and one name Suppliers3 with users coming from Suppliers3
To handle license abuses, the 2 suppliers are limited to 10 users.
In this case the attribute groupManager should have the value:

dav2_2.PNG Note: in this example, the buttons add user to the group and remove user from the group have been removed

How to use the Delegated administration

Once the delegated administrator is authenticated to the application, he can create new user using the Create user button.

delegated-admin5.PNG

Notes:

Then the delegated administrator can use the different buttons to:

Integrated Windows Authentication

Integrated Windows Authentication (IWA) is a Trustelem authentication using the Kerberos token of the user Windows session.
The point is to authenticate on Trustelem to access the apps, not to add MFA on Windows login.
For a user point of view, it's a passwordless authentication:

Trustelem admin configuration

The option « Integrated Windows Authentication » under security tab ( https://admin-mydomain.trustelem.com/app#/security) must be enabled.
In addition, you need to check the following points:

Server configuration

setspn -s HTTP/mydomain.trustelem.com trustelem-user

Client configuration

Enabling IWA on your clients is a browser-specific operation.

iwa_google_gpo.png

iwa_chrome_add_adm.png

iwa_chrome_select.png

iwa_chrome_whitelist.png

iwa_chrome_auth.png

Note: with the new Edge based on Chromium, you have to go here: https://www.microsoft.com/en-us/edge/business/download?form=MA13FJ and click on Download Windows XX-bit policy. Then follow the Google GPO process.

iwa_ie_gpo.png

iwa_ie_sites.png

iwa_ie_logon.png

iwa_firefox_gpo.png

iwa_firefox_select.png

LDAP-Radius - Trustelem Connect

Contents

How does it work?

The goal is to use Trustelem database to provision and or authenticate users on an application using LDAP or Radius.
To do so, a connector, Trustelem Connect, is installed on a local customer server and has the role of LDAP server / Radius server. When it receives a request (LDAP search, LDAP bind, Radius Access request, Radius Challenge request) then it sends the request to Trustelem.

schema-tlm-connect.png

1/ During the setup, Trustelem Connect opens a websocket to Trustelem services using port 443.
Note: with the websocket, information is encrypted by TLS protocol and with an additional symmetric encryption.
Trustelem Connect also opens on the local machine, TCP or UDP ports on a specified local IP, based on the Trustelem setup.
One opened port matches one protocol for one application on Trustelem
For instance, I made the setup of Trustelem Connect, linked a Bastion application, and choose to use the port 5214 on the IP IP-Server2 for the protocol LDAP

portLDAP-RADIUS.png

2/ The application makes a search/authenticate request and sends it to Trustelem Connect on the defined port using LDAP or Radius.
With the previous example, the protocol is LDAP, the IP of the LDAP server is IP-Server2, the port is 5214

3/ Trustelem Connect uses the websocket to send the request to Trustelem services:

4/ As said before, on Trustelem the port is associated to a specific protocol and application.
Trustelem examines the access rules related to these protocol and application, and returns the answer to Trustelem Connect using the websocket.

With the previous example:

5/ Trustelem Connect forwards the answer to the application using LDAP or Radius.

Prerequisites

Setup TrustelemConnect on a Windows machine

In your Trustelem administration page:

create_service.png

On your server:

setup_ldap.png

tls_cert = "C:\Program Files (x86)\Trustelem\connector.crt"
tls_cert_key = "C:\Program Files (x86)\Trustelem\connector.key"

In your Trustelem administration page

setup2_ldap.png

You now have a functional connector.

Setup Trustelem Connect on a Linux machine

In your Trustelem administration page:

create_service.png

On your server:

service_id = 2jy34wpcohrhdytr6hutym6qfi2l7nnw
state_dir = run/
# if there is a proxy
proxy = https://username:password@proxy_IP:proxy_port

tls_cert = run/connector.crt
tls_cert_key = run/connector.key

In your Trustelem administration page

setup2_ldap.png

You now have a functional connector.

Setup an application to use Trustelem Connect

Note: for WALLIX Bastion and WALLIX Access Manager, you should watch the dedicated documentation instead of this chapter.

On your Trustelem administration page:

ldap-app.png

setup3_ldap.png

Trustelem is now ready to reply to applications sending requests to TrustelemConnect with the correct port and IP.

Of course, you need to create the access rules to defined which users can use the application
https://trustelem-doc.wallix.com/books/trustelem-administration/page/access-rules

On your your application setup:

Add a LDAP and/or Radius setup, based on the information provided by Trustelem:

With the example used in the first chapter, the setup is:

setup5_ldap.png

Debug

The connector doesn't appear in the setup page on the admin page

The LDAP or Radius authentication is no working

Loss of a second factor

The following procedure may be used when a user needs to access a protected application, but doesn't have his second authentication factor available:

Multi factors authentication

Contents

What is a Multi factors authentication?

There are 3 kinds of authentication factors:

A Multi factors authentication is the combination of 2 factors. Example: login + password + email one time password = MFA

BUT a strong authentication is the combination of 2 different kinds of factors.
The previous example is not a strong authentication
Example: login + password + mobile phone application one time password = strong authentication

Existing 2nd factors on Trustelem

Trustelem factors, used in addition to the password, are:

mfa.png

Notes:

Possible authentications depending on the protocols

Web logging - Admin page + SAML / OpenID Connect applications

The user provides his Trustelem login + password, then the 2nd factor.
If he has multiple 2nd factors, he can choose to use another one:

LDAP applications

The LDAP protocol is not designed to do MFA. But with Trustelem, there are 2 ways of doing it:

Radius applications

Radius authentications have lot of possibilities:

Setup

To setup the allowed factors, , go on Trustelem admin page, Security settings and Authentication factors

The first part, Manage authentication factors, has 2 parameters: Login, and User can reset token authfactors.PNG

Login parameter

For a chosen factor, you can activate the option login for all users or for specific users.
When it's done:

User can reset token parameter

For a chosen factor, you can activate the option User can reset token for all users or for specific users.
When it's done, the defined users can use their dashboard to reset this factor:

https://mydomain.trustelem.com/#security

mfa3.png

When you have enabled the chosen factors, you can start the enrollment.

Manual enrollment using dashboard

This has to be done by a Trustelem administrator enroll1.PNG

Manual enrollment using email

This has to be done by a Trustelem administrator. You can send the enrollment link to Trustelem Primary Email or choose another one. enroll2.PNG

Enrollment campaign

mfa2.png

Create an access-rules for MFA

If you already have users and applications, you can now create access-rules in order to force multi factors authentication.
You can find the detail using the URL: access rules

On-premise SIEM

How to send Trustelem logs to an on-premise SIEM?

Here we'll explain how to connect Trustelem to a SIEM or an agent capable of receiving logs and hosted in your infrastructure.
To begin with, it's important to know that Trustelem sends new events every 30s, and has a queuing system if an error is detected during transmission.

Now, how to do the setup?

1/ Install Trustelem Connect.

More information is available here:
LDAP-Radius - Trustelem Connect
For this usecase, you don't need to add any applications to the Trustelem Service, just a connector capable of joining your infra. You can use an existing Trustelem

2/ Add or edit the config.ini file.

In the folder where Trustelem Connect service is installed, edit or create the config.ini file.
Add the following lines:

outgoing_allowed = "true"
[targert.choose_a_name]
addr = "The IP/FQDN of your SIEM"
port = "The port of your SIEM"

Don't forget to change the name, the IP/FQDN, and the port!

3/ Restart Trustelem AD Connect

4/ On the Trustelem Service enable the logs sending

Debug

Linux

Windows

Regular expressions

Some fields on the Trustelem administration pages allow the usage of regular expressions.

Self-Service-Password-Reset

The feature Self-Service-Password-Reset (or SSPR) allows Trustelem users to reset a lost password, even if they are from Active Directory.
The goal is to reduce the administrative workload by giving users autonomy.

sspr-00.png

The setup is done in the Security settings tab, then Password management:
https://admin-mydomain.trustelem.com/app#/security/passwords/edit --> Self-service password reset for users

When the feature is activated the administrator can select the number of required factors then select which factors will be required.

sspr-0.png

Notes:

Self-Service password Reset for Active Directory

If you want to activate the SSPR service for Active Directory, you should already have a directory setup with an AD Connect installed.
See: Active Directory synchronization First, you have to go on your Trustelem directory setting page and activate the feature Password recovery.
Then SSPR service requires the Trustelem connector service account to be granted with privilege delegation for user's password reset.

sspr-1.png

sspr-2.png

sspr-3.png

sspr-4.png

sspr-5.png

Self-Service password Reset for Azure Active Directory

If you want to activate the SSPR service for Azure Active Directory, you should already have a directory setup with Trustelem.
Note: Azure Active Directory passwords can only be used and reset by Trustelem if Office 365 is not federated.
First, you have to go on your Trustelem directory setting page and activate the feature Password recovery.
Then start PowerShell and execute the following script, with the correct value for the CLIENT ID of your Trustelem app on Azure AD:

Install-Module AzureAD
Connect-AzureAD
$app = Get-AzureADServicePrincipal -filter "AppId eq 'CLIENT ID'"
$role = Get-AzureADDirectoryRole | Where-Object { $_.DisplayName -eq "Helpdesk Administrator" }
Add-AzureADDirectoryRoleMember -ObjectId $role.ObjectId -RefObjectId $app.ObjectId
$role = Get-AzureADDirectoryRole | Where-Object { $_.DisplayName -eq "Directory Writers" }
Add-AzureADDirectoryRoleMember -ObjectId $role.ObjectId -RefObjectId $app.ObjectId

Trustelem local users

Contents

What Trustelem local users are?

Creation

Management

By clicking on the user, you can:

Temporary users

As said before, an administrator can define an expiration date for a user account:

account_expiration.PNG

updateUser(args: {
    id: UserID;
    firstName?: string;
    lastName?: string;
    email?: string;
    email2?: string;
    isAdmin?: boolean;
    suspended?: boolean;
    accountExpiration?: Date | number | string | null //Expiration parameter
    groups?: GroupID[];
}): { error?: string; };

When the date is reached, the account has a status Expired and the user can't authenticate on Trustelem anymore.

Trustelem password levels

Trustelem password levels

Trustelem passwords have 3 security levels : None - Medium - High

Trustelem uses a security framework, zxcvbn (https://github.com/dropbox/zxcvbn) developed by Dropbox, which evaluates password strength according to current best practices and dictionaries.

Basically, zxcvbn looks for patterns in the password, and searches for these patterns in current pattern/password dictionaries. We also add our own dictionary, which contains account information (login, domain, orga...). Based on this, it will define a security score.

Our Medium level = zxcvbn score of 3 (safely unguessable: moderate protection from offline slow-hash scenario.)
Our High level = zxcvbn score of 4 (very unguessable: strong protection from offline slow-hash scenario)

To this framework, we add the length defined on Trustelem.

Why is it secure ?

There are no explicit criteria such as "X capitals, Y special characters...", but rather a live calculation of password strength based on a constantly updated dictionary. This is much more secure.

Password creation requirements are generally the same on most websites. Hackers therefore know what patterns to look for, such as replacing letters with symbols (@ for a, for example). Traditional password security requirements would accept "P@ssw0rdSecure" as a password, even if it is not secure at all.

On Trustelem, administrators can easily enforce password requirements, as the feature enables employees to create secure passwords with ease. Companies can therefore ensure that their employees adopt better password habits, without disrupting their working day or the company.