Authentication¶

Stamus Central Server provides different authentication methods to authenticate users: * local database (default) * Active directory with local database fallback * Generic LDAP (also with will local database fallback) * SAML protocol (Single sign on)

Hint

After any configuration change in this section is submitted (via the Apply button at the bottom of the form), you need to click on apply changes on the left hand side panel under Action - to make it active.

Local Authentication¶

By default, SCS users are authenticated on a local database.

The Manage Accounts menu under the Stamus Logo dropdown lets you manage users to:

create new accounts
edit existing accounts
delete existing accounts
reset passwords
specify account roles

Add/Create User¶

In order to Add/Create a New User: in the upper left corner click on Stamus Networks logo drop down icon -> Manage Accounts.

On the User Management page, in the Action panel -> click on Add.

Edit User¶

In order to edit an existing user: in the upper left corner click on Stamus Networks logo drop down icon -> Manage Accounts.

On the User Management Page, in the User list -> click on the Username of the user you wish to edit.

In the Actions panel -> click on Edit user.

Change User Password¶

In order to change user password: in the upper left corner click on Stamus Networks logo drop down icon -> Manage Accounts.

On the User Management Page, in the User list -> click on the Username of the user whose password you wish to change.

In the Actions panel -> click on Change user password.

Change User Password From The Command Line¶

In order to change user password from the shell command line:

Log onto the SCS via the shell.
Execute the command:

$ sudo stamus_config

In the System configuration menu, scroll down until you see Reset SCS password -> hit the Enter key.
In the sub menu type the username you want to change the password for then -> select it and hit the Enter key.
A new menu will appear labeled Password reset for user <username> (WARNING: nothing will be echoed)
Type the new password, then -> hit the Down key -> repeat the new password -> hit the Enter key.
A success message should appear: Password changed successfully.

Delete User¶

In order to delete a user: in the upper left corner click on Stamus Networks logo drop down icon -> Manage Accounts.

On the User Management Page, in the User list -> click on the Username of the user you wish to delete.

In the Actions panel -> click on Delete user.

User Permissions (RBAC - Role-based access control)¶

The Stamus Central Server (SCS) allows for a RBAC styled system. RBAC assigns permissions based on roles within the system. It enables segregation of duties by limiting access based on the principle of least privilege.

There are three default roles as described below:

User is allowed to connect to SCS but has only read permission
Staff can make changes in SCS (appliance/probe additions , ruleset push, …)
Superuser has full unrestricted access, including editing user authentication settings and user creation in the local database.

Hint

The difference between Staff and Superuser roles is that the Superuser has the Configuration Auth permission and the ability to change the authentication settings and create/edit login accounts on the system.

There can be also custom roles created. Inside the User Management Page -> click on Add Role under the Actions category. Give the role a name and fill in all the permission levels that are going to attach to this new role.

Configuration Auth: Access to authentication settings. Configuration Edit: Ability to edit system configurations. Configuration View: Permission to view configurations. Events Edit / View / Kibana / Ryod: Permissions to edit/view event logs, including special interfaces like Kibana or Ryod. Ruleset Policy Edit / View / Update Push: Rights to edit, view, or push updated rulesets. Source Edit / View: Rights related to editing or viewing sources.

In order to handle permission levels: in the upper left corner click on Stamus Networks logo drop down icon -> Manage Accounts.

On the User Management Page, in the User list -> click on the Username of the user whose permission levels you wish to change.

In the Actions panel -> click on Edit user and set permission levels by enabling/disabling the Active , Staff User and Superuser checkboxes.

Authentication (LDAP, local)¶

Hint

There is a fall back on local database but one should keep a user with admin privilege in the local database which username is not available/existing in the Active Directory. This way there is one access which is not depending on Active Directory.

Active directory with local database fallback (LDAP)¶

To turn on the Active directory with local database fallback, open Global Appliance Settings under the Stamus Logo dropdown and then select the Authentication tab. Inside click on the AD/LDAP tab and under the Authentication method drop down select Active directory with local database fallback.

Generic LDAP¶

To turn it on open Global Appliance Settings under the Stamus Logo dropdown and then select the Authentication tab. Inside click on the AD/LDAP tab and under the Authentication method drop down select Generic LDAP. The Generic LDAP is an implementation of the LDAP authentication that is more customizable and enables more options specific from LDAP to be configured such as: In LDAP User: - User search scope - User search filter In LDAP Group Type: - Group Type - Group param In LDAP Group: - Group search scope

Hint

There are fields under each group of options that shows what the query will look like. Consult with your local system LDAP administrator what options need to be provided.

LDAP authentication methods¶

There are two LDAP authentication methods Dedicated Account and Authenticating User

When using the Dedicated Account LDAP authentication method needs the following to be provided: - The Distinguished Name Bind DN of an AD user and his associated Ldap bind password: this user is only used to do the initial query that try to find user to be logged in

CN=Administrator,CN=Users,DC=myaddomain,DC=com

Note

The user does not need to be AD administrator.

The base DNs to search users and groups Base DN of user search and Base DN of group search

These must be filled in with two DNs pointing to the node in the LDAP tree containing the users (resp. the groups).

Example:

CN=Users,DC=myaddomain,DC=com

The other authentication method is Authenticating User. Here the Bind user DN template attribute needs to be provided. A Bind user DN template refers to a template that defines the Distinguished Name (DN) of a user account that is used for binding (authenticating) to the LDAP directory server. The DN is a unique identifier for an entry in the LDAP directory.

CN=%(user)s,OU=users,DC=myaddomain,DC=com

Mapping LDAP groups¶

LDAP Groups can be mapped to the local roles. This could be done in the Role edit menu. Go to Global Appliance Settings -> Manage accounts -> click on a role in the Roles table. Here a Ldap group mapping can be provided.

The LDAP groups mapping settings allow the user to define which groups in the AD give privilege in SCS:

DN of active group is the DN of a group containing all users allowed to connect to SCS
DN of staff group is the DN of a group containing all users that can act on SCS (appliances edition, ruleset push, …)
DN of superuser group is the DN of a group containing all users that can act on the local user handling

Example:

CN=SCSActive,CN=Users,DC=myaddomain,DC=com
CN=SCSStaff,CN=Users,DC=myaddomain,DC=com
CN=SCSAdmins,CN=Users,DC=myaddomain,DC=com

Note

The groups SCSAdmins and SCSStaff need to be part of the group SCSActive otherwise members will not have an active status and would not be able to log into SCS.

Common LDAP configuration options¶

LDAP server URI is the URI of the LDAP server/Active directory server. It is in the form ldap://myad.domain.com:389 or ldaps://myad.domain.com.

Hint

LDAP User Attributes are attributes from the LDAP that will be mapped locally accordingly as First name, Last name and Email

If you use an LDAPS URI or enable STARTTLS then you need to select if you would like to verify the certificate or not. If you choose to verify/check that then you will probably have to upload a PEM certificate authority file corresponding to the one used in your AD. This can be done by clicking on Provide file for TLS certificate authority of LDAP server.

There are two options how you can configure LDAPS (example):

Use LDAP server URI ldap://myad.domain.com:389 and select Use STARTTLS command or
Use LDAP server URI ldaps://myad.domain.com and do not select Use STARTTLS command

Important

Importing mismatching certificate and key pair results in breaking Stamus Central Server. To fix this:

SSH on the Stamus Central Server (SCS)
launch _stamus_restore_default_certs as root (sudo /usr/local/bin/_stamus_restore_default_certs)

This command will reset to default certificates

To confirm that the LDAP/S server connectivity and can be queried remotely you can try the following:

On a domain Windows PC or server
Search for and start the windows ldp tool
(for LDAPS) click Connection then fill in the full LDAP enabled server name (example) WINSERV-DC1-LDAPSenabled.myaddomain.com. Then port fill in port 636 and select the SSL check box then click OK
(for LDAP) same as above but do not select the SSL check box and fill in port 389
you should have no errors

LDAP Troubleshooting¶

You can get info about remote authentication by clicking on Stamus menu icon -> System Logs. The Authentication log contains information about the authentication attempt.

Here is a few information about the possible messages.

If you have a message similar to this one:

Caught LDAPError while authenticating regit: INVALID_CREDENTIALS({'info': '80090308: LdapErr: DSID-0C0903C5, comment: AcceptSecurityContext error, data 52e, v23f0', 'desc': 'Invalid credentials'},)
Invalid login attempt for 'regit' from '192.168.1.137'

Then the bind parameter are not correct. The error is not on user side.

An invalid password entered by a correct user lead to:

search_s('CN=Users,DC=stamus,DC=com', 2, '(sAMAccountName=%(user)s)') returned 1 objects: cn=eric leblond,cn=users,dc=stamus,dc=com
Authentication failed for regit: user DN/password rejected by LDAP server.
Invalid login attempt for 'regit' from '192.168.1.137'

An attempt with a non existent login lead to:

search_s('CN=Users,DC=stamus,DC=com', 2, '(sAMAccountName=%(user)s)') returned 0 objects:
Authentication failed for gruick: failed to map the username to a DN.
Invalid login attempt for 'gruick' from '192.168.1.137'

Authentication using the SAML protocol¶

The Stamus Central Server can use the SAML protocol to authenticate. Security Assertion Markup Language (SAML) is an XML-based open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider (IdP) and a service provider (SP). The primary use case for SAML is in the context of web browser single sign-on (SSO).

To enable authentication with the SAML protocol: Go to Global Appliance Settings under the Stamus Logo dropdown and then select the Authentication tab. Inside click on the SAML tab and enable the checkbox Enable SAML/SSO authentication. A dedicated view with configuration options for SAML will open.

Hint

Consult your Identity Provider (IdP) for more details what configuration needs to be provided, like the Identity Provider URL and the Identity Provider metadata. An IdP is the entity that authenticates users and provides them with security assertions in the form of SAML tokens.

In order to configure SAML:

Put your Identity Provider URL in the form of https://samltest.id/
Upload the Identity Provider metadata XML metadata file that will be provided by the IdP
Fill in the Service Provider Name, for example (ProductionSCS)
Fill in the Service Provider URL. This should be the complete URL of the SCS. Example: https://production-scs.domain.com/
Enable debug output - this will enable verbosity for troubleshooting purposes. Enable only if SAML is failing.
Use name id as username - Some IdP’s (Such as Google and Azure) require this option to be enabled.
SAML session cookie samesite - None is the default option

Hint

Use name id as username option is required by Google and Azure Identity Providers

The SameSite attribute is a part of the HTTP cookies standard and is used to control whether cookies should be sent with cross-site requests. It is designed to mitigate the risk of cross-site request forgery (CSRF) attacks. The SameSite attribute can take three possible values: Strict, Lax, and None. It is commonly used in the context of web security and is relevant to the implementation of SAML (Security Assertion Markup Language) session cookies.

Here’s a brief explanation of each SameSite value:

Strict: Cookies are not sent with any cross-site requests. They are only sent if the request originates from the same site as the one that set the cookie. This is the most secure option but can lead to issues in scenarios where cross-site requests are legitimately required, such as when navigating from one site to another.

Lax: Cookies are sent with top-level navigations and cross-site requests initiated by a top-level navigation. Cross-site requests initiated by third-party elements (e.g., images, scripts) are not sent with cookies. This is a balance between security and usability. It allows cookies to be sent with navigations but provides some protection against cross-site request forgery.

None: Cookies are sent with all cross-site requests, including those initiated by third-party websites. This option is the least restrictive and is necessary for scenarios where cross-site requests need access to cookies, such as when implementing single sign-on (SSO) with SAML.

SAML session cookie secure - “SameSite=None” attribute MUST also have the “Secure” attribute, which is required in order to use “SameSite=None”, otherwise the cookie will be blocked, so you must also set this flag to True.
Enable attributes mapping - Enable this to map SAML2 user attributes and SCS local user attributes that are in its database.

Hint

Please consult your Identity Provider documentation for filling the correct attributes to be mapped.

Under Organization and Contact categories, there are the following administrative options that must be given. (These are only example values):

Name - example: MyOrganization
Displayed name - example: My Organization
Website - example: https://www.my-organization.com/
Given name - example: John
Surname - example: Doe
Company name - example: My Organization
Email - example: admin@my-organization.com

After providing all the needed details, click the Apply button at the bottom and do an Apply changes on the SCS. After the System configuration task is finished go back inside the the SAML page and click the Download SP metadata button. A file named sp_saml2_metadata.xml shall be downloaded. Upload this file to your identity provider (IdP) SAML configuration page.

Note

Some IdP’s won’t need that SP metadata to be provided. Consult the documentation of the Identity Provider that is going to be used.

In order to make the authentication work correctly, all SAML accounts need to have a local counterpart created. Go to Global Appliance Settings -> Manage accounts -> Add user -> Enable the SAML2 User checkbox. Fill the Username field exactly the same as how it would be used to authenticate with the IdP

Note

If you have enabled the Enable attributes mapping option in SAML the fields First name, Last name and Email address will be populated the first time the user logs in.

On the main login page of the SCS, there’s now a SAML Auth button under the Sign in button. When clicked it should pass the authentication to the IdP. After successfully identifying with IdP, the user is forwarded back to the SCS and login is complete.

Hint

The Stamus Central Server allows SAML protocol and local authentication to be used at the same time.