What is it?
Single sign-on (SSO) allows users to sign in automatically without having to input their username and password each time they log in.
With SSO, the organizational details of each user, coming from your organization's active directory, are synchronized with your ITONICS application. This allows mapping user roles and groups so that users are signed in to the appropriate roles, groups, and permissions.
Our professional services team will guide and instruct your IT department on the initial one-time configuration that is necessary to configure the standard SSO protocol SAML 2.0.
How does it work?
Login with SSO
Use the ITONICS system URL from any web browser
When you land on the ITONICS Login Page, click on the button Login for <client> employees. You will be redirected to your SAML Identity Provider (e.g. Active Directory Federation Services, Azure ADFS or OneLogin. Most SAML Identity Providers are compatible). An automated redirection when hitting the URL is also configurable.
You will be asked to authenticate with your credentials at the Identity Provider.
The defined SAML token is sent back to ITONICS.
The SAML data is verified by ITONICS and if successful, you are authenticated.
When you complete this process for the first time, the system assigns a defined standard user role, creates a user account in the ITONICS user management, and imports the data defined in SAML claims. This includes attributes like User ID, Username, E-Mail, Firstname, Surname, Location, etc.
The above described the ITONICS standard procedure for setting up SSO, but you can also assign user roles in these two ways:
User role is assigned by the Application Owner manually.
User role is assigned via SSO claims based on pre-defined Active Directory Groups on the client-side.
Integrate SSO (initial setup)
Integrating SSO is a little more technical. We recommend getting your IT department to work with ITONICS for the initial setup. Please get in touch with your Customer Success Manager to initiate the integration.
For a smooth integration, the following prerequisites are required:
Clarify if you need/have a custom URL
Get a test user for ITONICS to test the SAML Integration (optional, recommended)
The following steps describe the ITONICS standard integration of SSO/SAML for the initial setup:
ITONICS sends out the SAML metadata for the production system
The Customer IT Team imports the metadata in their ADFS
The Customer sends the metadata back to ITONICS
ITONICS integrates the metadata of the customer
After the metadata exchange is done, the login must be tested
If the login works fine, the default login of the system will be changed to SAML
Maintain SSO (configuration self-service)
The initial SSO Setup might be subject to change occasionally. Therefore, ITONICS offers a self-service SSO/SAML Configuration accessible to Administrators, Application Owners, or users assigned the dedicated SAML Manager role.
SAML Manager role
Automatically created by ITONICS if the SSO module is enabled
Intention: provide a separate configuration access for clients’ IT teams or integration experts, as the (business responsible) Application Owners are not necessarily responsible for the technical setup
The SAML Manager role can merely view and manage the SAML Configuration, while prevented from accessing other system locations/content.
-
Initial assignment:
Sign in as Application Owner and navigate to the User Management.
Create a new or edit an existing user account and assign (only) the SAML manager role, and save.
Under Roles, enable SAML Manager and save.
Maintaining the SSO/SAML Configuration
Navigate to Settings > System Administration > SAML > SAML Configuration. You will see a table overview, listing the active/inactive IDPs. Once the initial setup has been finalized in alignment with the ITONICS team, a particular IDP item will appear in the table view, with the configuration ready to be managed. For each item, permitted users can either edit or delete the configuration, download the current meta data file (if existent), or upload new client-side metadata file/configuration.
Uploading metadata file
To facilitate the management and maintenance of existing SSO configurations, you can upload your updated metadata file in self-service. Note: You will likely find the metadata URL or metadata file within your IDP portal, e.g., in Azure.
Click on the upload icon for a particular IDP item to open the Upload SAML Metadata for Client pop-up modal. Here, you will have the option to either
import the metadata XML file from a dedicated file URL (folder), or
upload the file directly without the provision for a target URL.
Once you have chosen the upload method, confirm your action by clicking Import Metadata.
After the successful import of the metadata, click the edit icon for the respective IDP item to now configure the Attribute Mapping based on the uploaded metadata. These will be the attributes you have configured on your IDP portal. The configuration consists of two separate tabs:
Basic Configuration:
Client Title: Use a descriptive title to help administrators distinguish between multiple SSO providers in the system.
Sign-In Button Label: Define the text displayed on the SSO button on the sign-in page (e.g. Sign-in with SSO).
Identity Provider Metadata URL: Provide the metadata URL or endpoint of your Identity Provider (e.g., Azure AD, Okta, etc.).
Service Provider Entity ID: The unique identifier for this application (Service Provider) as registered within your Identity Provider.
Identity Provider (Metadata) Entity ID: Specify the unique ID used to validate the authenticity of the metadata provided by the IDP (e.g. https://app.onelogin.com/saml/metadata/{unique_key})
SSO Service Binding: Select the protocol binding (e.g., HTTP-POST) used to transmit SAML authentication requests, defining the communication method.
SSO Service Location: Enter the Identity Provider endpoint URL where the system sends users to initiate the sign-in process.
SLO Service Binding: Select the protocol binding (e.g., HTTP-Redirect) used to transmit SAML logout requests.
SLO Location: Enter the IDP endpoint URL where the system sends logout requests to terminate the user session.
Primary Certificate Data: The public key data required to ensure that authentication responses are legitimately signed by your Identity Provider. Note: If there is only a single certificate, the certificate is used for both encryption and signing.
Enabled Signed Authentication Request: Enable this to allow ITONICS to digitally sign outgoing SAML authentication requests for enhanced security.
Sign Logout Request: When enabled, the system will digitally sign all SAML logout requests sent to the Identity Provider. Note: This will only work when a single certificate is enabled. For double certificates, the logout request is automatically signed and cannot be disabled.
Encrypt SAML Assertion: Require the Identity Provider to encrypt assertion data (SAML responses) to ensure maximum privacy of user attributes during transmission. Note: works only if double certification is enabled.
Secondary Certificate Data: The backup public key data used to verify SAML responses if the primary certificate fails or expires.
Attribute Mapping:
-
What is the unique identifier for SAML Login?: Specify the primary, unique attribute used to identify users during sign-in/SAML login. Choosing Email will automatically synchronize the ITONICS username with the IdP email address, and vice versa.
Update user attributes?: Enable this option if you want to update the user's email or username in ITONICS based on the value selected above and kept in sync with the Identity Provider.
Which attribute from simpleSAMLphp should be used as unique identifier for the user?: Accepts a string value which is the key from the SAML response, whose value is used as the user’s unique identifier. Enter the attribute name from your IdP that acts as a unique ID (e.g., eduPersonPrincipalName or eduPersonTargetedID). If the attribute is multi-valued, the first value will be processed.
Which attribute from simpleSAMLphp should be used as user's name?: Accepts a string value which is the key from the SAML response, whose value is used as the user's name. Enter the attribute name from your IdP that acts as a unique ID (e.g., eduPersonPrincipalName or eduPersonTargetedID). If the attribute is multi-valued, the first value will be processed.
Which attribute from simpleSAMLphp should be used as user's mail address?: Accepts a string value which is the key from the SAML response whose value is used as the user's mail address. Enter the IdP attribute key corresponding to the user’s Email Address (e.g., mail).
Which attribute from simpleSAMLphp should be used as user's first name?: Accepts a string value which is the key from the SAML response, whose value is used as the user’s first name. Enter the IdP attribute key corresponding to the user’s First Name.
Which attribute from simpleSAMLphp should be used as user's last name?: Accepts a string value which is the key from the SAML response, whose value is used as the user’s last name. Enter the IdP attribute key corresponding to the user’s Last Name.
Which roles should be provided to the SAML user?: Default role that will be assigned to the SAML user. Select the ITONICS roles that will be automatically assigned to users when they are logged in via SSO.
Note: Ensure that the mandatory attribute mappings are filled out, while you can optionally map further SAML attributes to corresponding ITONICS user configuration fields.
Once the configuration is finalized, do not forget to click Save to confirm your configuration changes. To see the changes in affect, you will need to log out and re-login (respectively the changes will be applied to subsequent user registrations/logins).
Logs
To trace configuration changes and potential sync issues, the following log capabilities are exposed:
SAML Audit Logs = configuration changes who changed what
SAML Logs = debug logs