Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

Custom Authentication Extra Installation and Administration Guide

By default, SimpleRisk uses locally defined user accounts to authenticate with the system. This means that each user must have an individual account created within SimpleRisk, allowing for straightforward management and access control. However, recognizing the diverse needs of our users, this extra provides support for users to authenticate with SimpleRisk using an LDAP, which allows for centralized management of user accounts and seamless integration into existing directory services. Additionally, users can authenticate through an Active Directory repository, commonly used in enterprise environments, ensuring that organizations can leverage their existing infrastructure for user management. Furthermore, the inclusion of SAML allows for single sign-on capabilities, enabling users to sign in once and gain access to multiple applications without needing to re-enter their credentials. The plan is to eventually expand this Extra to include functionality for multi-factor authentication vendors as well, further enhancing security by requiring additional verification steps, such as a mobile authentication app or a hardware token, to confirm user identities. This will provide our users with a more robust and secure authentication process while maintaining flexibility in how they choose to manage their access to SimpleRisk.

The Custom Authentication Extra offers a variety of configuration options that you can access by clicking on “Configure” in the Navigation Menu on the left side. Next, select “Extras” from the dropdown menu. You will then see a list of all available Extras for purchase. Locate the “Custom Authentication” Extra in the list and click on “Yes” in the Enabled column to activate it. The configurations are organized by “LDAP” and “SAML.”

LDAP

This section provides the necessary configuration to enable user authentication in Simplerisk via LDAP, rather than relying on Simplerisk's internal password system. Once this feature is activated, you'll see a new "LDAP" user type available when adding users in "User Management." It's important to ensure that the username you specify corresponds exactly with the user's LDAP username.

  • BIND FIRST: When checked, this tells the Custom Authentication Extra that you will need to use a special service account to bind to the LDAP server first in order to search for the full path to the user who is logging in.  After checking, you will have the option to provide the BIND ACCOUNT and BIND ACCOUNT PASS.
  • BIND ACCOUNT: This parameter specifies the full path to the service account that you would like to use to bind to LDAP.
  • BIND ACCOUNT PASS: This parameter specifies the password to use with the BIND ACCOUNT to bind the LDAP.
  • TLS: When checked, this tells PHP to use the ldap_start_tls function for the connection.  This should be set to false unless you are trying to upgrade the security of a plain LDAP connection to an encrypted channel.  This is not the same as using ldaps:// on port 636 and the two methods should not be used together.
  • SASL: When checked, this tells PHP to use the ldap_sasl_bind function which uses SASL to bind to the LDAP server.  When unchecked, this tells PHP to use the regular ldap_bind function to bind to the LDAP server.
  • CHASE_REFERRALS: This parameter specifies whether referrals should be followed by PHP when connecting to the LDAP server.  As long as you are specifying the direct path to the User DN, you can leave this unchecked.  If you need it to chase referrals, then go ahead and check it.
  • LDAP_VERSION: This parameter specifies the LDAP protocol to be used by PHP when connecting to the LDAP server.  PHP uses LDAP version 2 by default, but LDAP version 3 is preferable as long as your LDAP server supports it.
  • LDAPHOST: This parameter specifies the LDAP server that you would like SimpleRisk to use to try to authenticate a user with.  You can specify a server name without the protocol (i.e. “ldap.mydomain.com”) or with the protocol included (i.e. “ldaps://ldap.mydomain.com”).
  • LDAPPORT: This parameter specifies the port that the LDAP server is running on.  Typically this would be set to “389” for LDAP or “686” for LDAPS.
  • USERDN: This parameter specifies the full path to where the users exist within your LDAP repository. 

SAML

This section outlines the steps needed to enable SAML authentication for users in Simplerisk, replacing the use of internal passwords. After this feature is activated, you'll notice a new user type labeled “SAML” when you add a user in the “User Management” section. 

To set up SAML using a metadata XML export from Simplerisk for your Identity Provider (IDP), navigate to the configure menu on the left side of the screen. Then, select Extras and click the “Yes/No” option next to Custom Authentication. Next, go to the SAML tab, enter the trusted domain value or your IDP's domain, and save it at the bottom of the page. Once this is done, you can click on the “Download SAML 2.0 Metadata” link located near the top of the page. If you prefer to manually configure your IDP, please refer to the information provided below.

On your SAML identity provider (IdP), you will need to configure the following parameters:

  • Single Sign On URL: https://your_simplerisk_domain/vendor/simplesamlphp/simplesamlphp/www/module.php/saml/sp/saml2-acs.php/default-sp
  • Recipient URL: https://your_simplerisk_domain/vendor/simplesamlphp/simplesamlphp/www/module.php/saml/sp/saml2-acs.php/default-sp
  • Destination URL: https://your_simplerisk_domain/vendor/simplesamlphp/simplesamlphp/www/module.php/saml/sp/saml2-acs.php/default-sp
  • Audience URI (SP Entity ID): https://your_simplerisk_domain/vendor/simplesamlphp/simplesamlphp/www/module.php/saml/sp/metadata.php/default-sp
  • Default Relay State: https://your_simplerisk_domain/extras/authentication/login.php

To complete the setup of SimpleRisk for the Custom Authentication Extra, please ensure that you configure the following parameters if you haven't done so already:

  • TRUSTED DOMAINS: This a comma-separated list of domains that SimpleRisk will be allowed to authenticate with via SAML.  Typically, this is just the domain name of your SAML identity provider (IdP).
  • METADATA URL: This is the URL provided by your IdP containing the metadata for your SAML provider.  If a metadata url is not available, you can paste the metadata directly into the metadata xml field instead.  The major benefit to using a URL over the XML is that it will be dynamically updated if the configuration is changed.
  • METADATA XML: This is the metadata provided by your IdP for your SAML provider.  You may also select “Choose File” in order to upload a file containing the metadata.  You do not need to provide this if you have provided a working metadata url.
  • USERNAME MATCH: SimpleRisk can authenticate a user via two different methods. If you select the “Authenticated Username” method, SimpleRisk will compare the username authenticated at the IdP to the usernames configured in SimpleRisk.  If you select the “Authenticated Attribute” method, SimpleRisk will compare the value of the attribute in the “Username Attribute” parameter to the usernames configured in SimpleRisk.  This allows you to have a different username in SimpleRisk than in your SAML provider, but still authenticate properly.  Most configurations will use the “Authenticated Username” method of authentication.

 Azure AD Users: You may need to use the following as your Username attribute “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”. This scheme may also apply to your other assertions as well.

  • USRNAME ATTRIBUTE: This parameter is used only when the “Authenticated Attribute” method is selected for the “Username Match” parameter.  It is used to specify the name of the attribute provided by the IdP that you will use to compare against the SimpleRisk usernames.

** NOTE: If you are looking to integrate SimpleRisk with ADFS as your SAML provider, please be aware that the ADFS Identity Provider (IdP) will not accept the NameID parameter from SimpleRisk by default. This is due to the NameID being provided in a transient format (urn:oasis:names:tc:SAML:2.0:nameid-format:transient). To resolve this, you will need to collaborate with your Active Directory (AD) team to establish a custom rule that translates NameIDs specifically for the SimpleRisk application. For detailed instructions on this process, refer to the following document from Cisco, particularly step 11:

https://www.cisco.com/c/en/us/support/docs/unified-communications/unified-communications-manager-callmanager/118771-configure-samlsso-00.html