Azure Active Directory SAML2 SSO

Introduction

To connect Flexopus with your Entra Active Directory (formerly known as Azure Active Directory) via a SAML2 Single Sign-On (SSO) integration:

1. Manage User Access
   Through your Active Directory, control which users have access to Flexopus, requiring them to log in using their Microsoft AD credentials.
2. User Profile Creation
   In Flexopus, configure a SAML2 setting to automatically create user profiles after their first successful SAML2 SSO login attempt. This eliminates the need for manual user creation in Flexopus.

This integration simplifies user management and ensures secure, centralized access.

Setup Instruction Manual

Follow the step by step introduction manual to configure the integration. The manual also includes best practices and solutions for some commonly made errors during the configuration. Still, if you require help with the setup, feel free to reach out to our support team via support@flexopus.com.

STEP 1 - Crate a new enterprise application

Go to your Azure Active Directory and navigate to the Enterprise Applications list. In the list view, click in the left top corner on the New application button.

On the new screen, click on the Create your own application button:

In the popup for integrating Flexopus with Entra Active Directory:

1. Enter the name: Flexopus SSO / SCIM (or any name of your choice).
2. Keep the selection on, integrate any other application you don't find in the gallery (non-gallery).
3. Do not select anything else at the bottom.

This setup allows you to proceed with the SAML2 SSO and SCIM integration for Flexopus.

STEP 2 - Configure SAML2

Navigate to the Single sign-on menu item on the left side and select the SAML box:

On the Basic SAML Configuration page, click on the Edit button:

To proceed with the SAML2 SSO integration for Flexopus, you need to enter the following details:

1. Identifier (Entity ID)
   This is the unique identifier for Flexopus in your SSO setup.
2. Reply URL (Assertion Consumer Service URL)
   This is the URL where the SAML responses (assertions) are sent after authentication.

These values are typically provided by Flexopus during the SSO setup process. Make sure to enter them correctly to ensure proper integration.

To find the necessary URLs for the SAML2 SSO integration:

1. Navigate in Flexopus as an administrator to Dashboard > Settings > Authentication.
2. Click the Add provider button and select the SAML2 SSO option.
3. You will find the Entity ID and the Callback (ACS) URL at the top of the page.

Optionally, you can also configure the Relay State and the Sign-on URL if needed for your setup.

STEP 3 - Configure Attributes

Go to the Attributes and claims section and click on the Edit button.

Select in the list the …/claims/name row by clicking on the row:

To change the source attribute for SAML2 SSO in Flexopus:

1. Navigate to the attribute mapping section in your Identity Provider (IdP) settings.
2. Change the source attribute from user.userprinciplename to user.displayname.
3. Save the change.

This adjustment will ensure that the display name is used for user identification within Flexopus.

In the list view, click on the Add new claim button:

Add the following claims as listed below. Please only fill out the listed name and source attribute parameters. Leave the namespace field empty for these attributes!

Once you finished the attribute mappings, it should look like this:

STEP 4 - Configure Flexopus

In the third configuration box of your Identity Provider (IdP) settings, locate the App Federation Metadata URL:

1. Copy the URL.
2. Go to Flexopus.
3. Use the URL within Flexopus to complete the SAML2 SSO configuration.

This URL allows Flexopus to fetch the necessary configuration data from your IdP.

To complete the SAML2 configuration in Flexopus:

1. Navigate to Dashboard > Settings > Authentication.
2. Select the created SAML2 Provider.
3. Paste the App Federation Metadata URL into the Metadata URL field.
4. Enable the SAML2 module.

This will activate SAML2 Single Sign-On for your Flexopus application.

To finalize the SAML2 setup in Flexopus:

1. Enter the name for the SAML2 Login button that will appear on the login page.
   Recommendation: Use SSO Login for clarity.
2. (Optional) Enable the synchronization of the optional fields (e.g., jobtitle or department) that you configured in the SAML2 settings. This ensures that these fields are updated in Flexopus when changes occur in the Identity Provider (IdP).

Once these steps are complete, the SSO login will be ready for use.

In the security settings for SAML2 SSO in Flexopus:

1. Set the allowed domains for SSO by entering a * (star) and pressing ENTER. This allows any user configured in your Active Directory to log in.
2. By default, SAML2 SSO users are automatically registered after their first login attempt. This eliminates the need to manually create user profiles beforehand.

While you can disable this automatic registration, it is not recommended for ease of user management.

Always SAVE your settings at the bottom.

STEP 5 - Configure who can log in

If you try to log into Flexopus now, you will see the following error message displayed by Microsoft:

If a user is unable to log in to Flexopus, it's likely that Microsoft is blocking the login due to restrictions in your configuration.

Flexopus allows anyone authorized through your Identity Provider (IdP) using the SAML2 Single Sign-On protocol to log in. The number of possible users is limited by those in your Active Directory. Therefore, you need to determine which users are allowed to access Flexopus via SSO.

To enable broader access:

1. Go to your Enterprise Application within Azure Active Directory.
2. Open the created Flexopus app.
3. Navigate to the Properties page.
4. At the bottom, you'll find the option Assignment required, which is set to YES by default.
5. Set this option to NO.

This allows all users in your organization to use Flexopus without needing specific user assignments. It's recommended to set this to NO unless you have a specific reason to restrict login to certain employees. By doing so, you won't have to manually maintain user access for SSO login.

If you want to restrict login to a specific set of users, follow these steps:

1. Leave the Assignment required setting to YES in your Flexopus app within Azure Active Directory.
2. Navigate to the Users and groups menu.
3. Here, you can assign groups or users individually, managing exactly who is allowed to log in to Flexopus.

This approach allows you to control access for selected users while keeping others restricted from logging in.

Once you decided who can log in, you are done with the configuration. Go and test the login in an incognito window.

STEP 6 - Test SSO

To test the SAML2 Single Sign-On integration:

1. Open Flexopus in a new incognito window.
2. Go to the URL: https://{your-company}.flexopus.com/ (or your custom domain, if applicable).
3. Attempt to log in using an existing or new user, depending on how you configured the access rights in your Azure Active Directory and Flexopus.

This allows you to verify that the SSO login is working correctly with your configured settings.

Once you've successfully configured SAML2 SSO, you can optionally enforce Single Sign-On for all users by disabling the email and password login. To do this:

1. Navigate to Dashboard > Settings > Authentication.
2. You’ll see two options:
   • Disable password login
     Disables all email and password login forms, requiring users to use SSO.
   • Hide login form
     Hides the login form on the main login page. However, a secondary login form at ../dashboard/auth/login remains accessible, which can be used as a backup for admin users.

This setup ensures secure SSO while keeping a fallback login option for administrators.

Trouble Shooting / FAQ