Azure Active Directory SAML2 SSO
Introduction
Connect Flexopus with your Entra Active Directory (formerly known as Azure Active Directory) via a SAML2 Single Sign On integration. With the integration, you can manage through your Active Directory which users should have access to Flexopus and force them to use their Microsoft AD credentials for the login. Based on a SAML2 setting in Flexopus you can let the user profiles be created after the first successful SAML2 SSO login attempt to avoid a manual user creation process at Flexopus.
Setup Instruction Manual
Follow the step by step introduction manual to configure the integration. The manual also includes best practices and solution for some commonly made errors during the configuration. Still, if you need 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, enter the name: Flexopus SSO / SCIM
You can also enter another name of your choice.
Leave the selection on the Integrate any other application you don't find in the gallery (non-gallery)
. Do not select anything else in the bottom.
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:
You need to enter the Identifier (Entity ID)
and the Reply URL (Assertion Consumer Service URL)
.
The URLs can be found within your Flexopus application. Navigate in Flexopus as an administrator to Dashbaord > Settings > Authentication
page. Click in the Add provider
button and select the SAML2 SSO
option. You can find the Entity ID
and the Callback (ACS) URLs
on the top of the page. Optionally, you can configure the Relay State and the Sign on URL as well.
Visible to users
in the Enterprise Application Properties.STEP 3 - Configure Attributes
Go to the Attributes & Claims
section and click on the Edit
button.
Select in the list the ../claims/name
row by clicking on the row:
Change the source attribute from user.userprinciplename
to user.displayname
.
Save the change.
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!
Name | Source attribute | Note |
---|---|---|
upn | user.userprincipalname | required |
jobtitle | user.jobtitle | optional |
department | user.department | optional |
extensionAttribute1 extensionAttribute2 … extensionAttribute10 |
any attribute you need | optional |
department
, jobtitle
, and extensionAttribute[1-10]
parameters are optional fields, they are only information fields within Flexopus. You can skip the configuration of them. Still, we recommend connecting them even if they are only partly maintained in the IdP.Once you finished the attribute mappings, it should look like this:
STEP 4 - Configure Flexopus
In the third configuration box, you can find the App Federation Metadata URL
. Copy the URL and go to Flexopus.
In Flexopus navigate to Dashboard > Settings > Authentication
and select the created SAML2 Provider. Paste the URL in the Metadata URL
field and enable the SAML2 module.
Enter the name of the SAML2 Login button, which will be displayed on the login page. Recommendation: SSO Login
(optional) Enable the synchronization of the fields that you configured in the SAML2 settings: jobtitle
or department
In the security settings, set at the allowed domains for SSO a *
(star) and press ENTER
. By this, you allow every user to log in that is configured in your Active Directory for the login.
By default, the SAML2 SSO user are registered after the first login attempt automatically. This is good for you, since you don't need to create the user profiles manually one by one before the first login, however you can disable this setting (not recommended).
At the SAVE
your settings in the bottom.
STEP 5 - Configure who can log in
If you try to log in now into Flexopus, you will see the following error message displayed by Microsoft:
This means that your user is not allowed to log in into Flexopus. Microsoft is not allowing to proceed with the login.
As you can see in the security setting above, Flexopus allows to log in anybody who is authorized to log in through your IdP via the configured SAML2 Single Sign On protocol. The number of possible users is limited to the number of users that are in your Active Directory, which means you need to decide which user you want to allow t use the SSO login.
Go to your enterprise application within your Azure Active Directory, open the created Flexopus app and go to the Properties
page. Here you can see an option in the bottom: Assignment required
, which is set to YES
. By setting this setting to false, you can enable the login to every user within your organization to use Flexopus. This setting is recommended to be set to NO
, in case you have no reason to limit the login in your organization to the employees. In this case, you don't need to maintain the users for the login.
However, in some cases you only want to enable the login for a set of users. In this case, leave the Assignment required
setting on YES
and navigate to the Users and groups
menu point. Here, you can assign groups and users one by one to manage who can log 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
Open Flexopus in a new incognito window and test the login:https://{your-company}.flexopus.com/
or in case you have a custom domain, then go to the custom domain.
You should be able to log in with an existing or a new user, depending on how you configured the access rights in your Azure Active Directory and Flexopus.
Once the SAML2 SSO configured successfully, you can optionally disable the E-Mail and Password login and enforce all users to user Single Sign On. Navigate to Dashboard > Settings > Authentication
. You can find two options here:
- Disable password login
You can disable all email and password login forms. - Hide login form
You can hide the login form on the main login page with it, but there is a secondary login form../dashboard/auth/login
which you can leave open to use it for a backup admin user.
Trouble Shooting / FAQ
I got a 500 Error during the login.
In case you get a 500 error, you may misconfigure the URLs or the attributes. Check the settings based on the manual once again. If you can not find the issue, contact us via support@flexopus.com. We have server logs to see where the problem lies.
Can I change the UPN of the users?
As you may know, UPN stand for UNIQUE principal names. Unique attributes shall never change, especially the UPN of the user shall remain the same. It can be a number or anything else. External application are identifying users based on their UPN, if you change you may risk creating a new user within Flexopus. Still, you may have a reason to change the UPN. In this case, contact us via support@flexopus.com. We can assist you by deleting the UPNs and the External IDs of the user to allow you the change of the UPNs in your IdP.
Which groups are assigned to the users after the first login?
After the first Single Sign On login, or after you manually created a user, we will assign only the all
system group to the user. In case you want to assign external groups to the users as well, you can do or via SCIM or with a special SAML2 user attribute called memberOf
. We recommend using the SCIM API. Visit the article for more details.
Can I also synchronize the user profile pictures?
Unfortunately, the SAML2 SSO protocol is not supporting the synchronization of profile pictures. We are planning to develop a way via the Microsoft Graph API to synchronize the user profile pictures.
I saw an attribute costcenters. What is it doing?
Indeed, we have an additional attribute, which is called costcenters. The feature is currently in a BETA testing phase. More information will follow.
I can not see the SAML configuration option.
In some cases, customers report that this page is not allowing the selection of SAML or showing this message: "OIDC Applications require custom signing keys to customize claims. Please check the security considerations before customizing the claims for the application"
This is mostly the case, if you skip in the manual STEP 1 and try to configure and automatically created application. In case you configured an OAuth SSO login, Exchange Online or Microsoft Teams connection as first, you will see an already existing Flexopus application in the enterprise application list. The integrations are creating an extra application automatically. Unfortunately, we can not fuse all the integration into one enterprise application. If you configure all the integration you will have one application for SAML2 / SCIM, one for Exchange Online and one for Microsoft Teams. In case you are currently switching from from an OAuth2.0 SSO to SAML2, you can delete the OAuth SSO app after switching. Long story, short, stick to the manual and create a new Enterprise app.
Does Flexopus support Identity Provider (IdP) Initiated single sign on login?
Yes and No. We provide a workaround for the IdP initiated logins. You need to configure the initiate-sp-login
parameter for the RelayState. This will convert the IdP initiated login request into an SP initiated login. In this way, we can ensure a secure login process.
Reason: A classical IdP initiated login would enable a man in the middle attack for hackers. Through an SP initiated login, we can avoid it. This article explains the reasons in more details: https://www.identityserver.com/articles/the-dangers-of-saml-idp-initiated-sso
R0051