Microsoft AD FS SAML2 SSO
Introduction
The Microsoft AD FS (Active Directory Federation Services) is an Identity Provider (IdP) developed by Microsoft to provide a Windows based self-hosted (on premise) version. You can connect an enterprise application over SAML2 to AD FS and manager, who can log in to view Single Sign On in the connected application. Define which user attributes you want to synchronize between AD FS and the connected application. Flexopus supports a Microsoft AD FS integration via SAML for Single Sign On.
SAML2 Instruction Manual
STEP 1 - Trust party setup
Go to your Microsoft AD FS management console as an AD FS administrator and select the Relying Party Trusts
folder.
In the Actions sidebar, click on the default setting Relying Party Trust
and click Start
. This opens the Add Relying Party Trust Wizard.
Select in the popup as a data source, the first option:Import data about the relying party published online or on a local network
.
https://{your-flexopus-domain}/internal-api/auth/integrations/saml2/metadata
To find your Federation metadata address
navigate to your provided Flexopus instance to Dashboard > Settings > Authentication
and click on Add provider
. You can find the URL at the top of the page at Metadata URL
.
Display Name: Flexopus
Choose Access Control Policy: Permit Everyone
(Depending on your internal policies, you can also select another suitable policy.)
Ready to add Trust: You can skip this step and the 2 following steps. Complete the wizard afterward.
STEP 2/A - Setting the “Claim Rule”
On the right side, select Edit Claim Issuance Policy...
Select the option Add rule
and select the option Send Claims Using a Custom Rule
Enter the rule name Basic attributes
and set the following custom rule:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "jobtitle", "department"), query = ";userPrincipalName,displayName,givenName,sn,mail,title,department;{0}", param = c.Value);
Click on Finish
Let's repeat it once again:
On the right side, select Edit Claim Issuance Policy...
Select the option Add rule
and select the option Send Claims Using a Custom Rule
Enter the rule name NameIDFormat
and set the following custom rule:
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent");
Click on Finish
STEP 2B - Manual setting of assignments
On the right side, select Edit Claim Issuance Policy...
Select the option Add rule
Next, select Custom Rule Type: Send LDAP Attributes and claims
Enter the as name: basic attributes
Select the option for the Attribute Store: Active Directory
.
Then set the attributes mappings as listed below. Note that the fields jobtitle
and department
as optional, however we recommend connecting them as well.
LDAP Attribute | Outgoing Claim | Note |
---|---|---|
User-Principal-Name | UPN | required |
Display-Name | Name | required |
Given-Name | Given Name | required |
Surname | Surname | required |
E-Mail-Address | E-Mail Address | required |
Department | Department | optional |
Jobtitle | Jobtitle | optional |
Afterward, select Add rule
again.
Then select Transform an Incoming Claim
.
In the last step, you set the Name ID
assignment.
Incoming claim type: UPN
Outgoing claim type: Name ID
Outgoing name ID format: Persistent Identifier
Click Finish
.
STEP 3 - Configure Flexopus for the SSO
Navigate to AD FS > Service > Endpoints
and copy the Federation Metadata
(metadata-endpoint-path). Based on this path you can create your metadata URL which will look like this:
https://{your-adfs-server-url}/{metadata-endpoint-path}
In Flexopus navigate to Dashboard > Settings > Authentication
and select the previously 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 4 - 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.
(Optional) Sending groups
Microsoft AD FS unfortunately do not offer the possibility to synchronize user groups through the SCIM API, however you can apply a workaround through a SAML2 attribute to send groups. You can send the groups associated to a user via the memberOf
SAML2 attribute. Through the memberOf
attribute, we can receive an array of groups that the user suppose to be associated with.
STEP 1 - Configure AD FS
Select the option Edit Claim Issuance Policy...
Click on Add rule
.
In case you did the configuration with the 2A Method:
Create a rule with the name group membership
and paste the following rule:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("memberOf"), query = ";memberOf;{0}", param = c.Value);
In case you did the configuration with the 2B Method:
Custom Rule Type: Send LDAP Attributes as Claims
Create rule with the name group membership
Attribute Store: Active Directory
.
Add the following attribute:
LDAP Attribute | Outgoing Claim | Note |
---|---|---|
Is-member-Of-DL | memberOf | required |
Your Issuance Transform Rules
suppose to look like this:
STEP 2 - Configure Flexopus
To receive and process the additional attribute at Flexopus as well, you need to follow these steps:
Go to Dashboard > Settings > Authentication
and select the previously create SAML2 SSO provider. Change the setting for the Synchronize groups
option from Off to AD FS
.
Save
the setting in the bottom.
memberOf
attribute has an upper limit. You can not send an unlimited number of groups through this array. If the limit is reached, no groups will be sent. Learn more here.STEP 3 - Test configuration
Assign groups to your test user in the AD FS. The assigned groups suppose to be sent to Flexopus, when you try to log in with your user.
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 need to initiate a new login, otherwise the groups will be not exchanged. The SAML2 protocol exchange data between your IdP and Flexopus only then when you try to log in.
Dashboard > Settings > Data Privacy Settings > Session time
After the login, the groups received via memberOf
will be assigned as external groups to the users and the other external groups already assigned to the user will be detached. The internal groups managed in Flexopus will stay the same.
Groups are identified based on names. Group names are always unique. In case Flexopus receives a group with a name that already exist as an internal group, the internal group will become an external group. In case we receive a new group, we create that group as an external group.
Learn more about the groups here:
Trouble Shooting and FAQ
Metadata can not be shared outside the companies network and VPN.
In some cases, the AD FS server is restricted to be accessed only from the local network. In this, configuring the metadata URL in Flexopus will lead to 500 server errors, since the Flexopus server can not reach the information on the restricted server. You can test it easily by trying to open the metadata URL from your private phone from your private mobile network. The file should be readable and accessible. If you can not reach the file, you have this problem.
In this case, we recommend configuring the metadata in Flexopus with a file and not with a URL, however in this case we can not update the certificated and signatures automatically in case you change them. In case you change it, you will need to upload a new metadata file in Flexopus to ensure a seamless SSO experience. No worries: this is usually a rare case happening in every 3-5 years depending on your IdP settings, and it can be solved fast, if it happens.
I am getting a 500 server error.
Please check the configuration steps once again, if you can not find the issue, contact us. For the 500 server error, we have server logs, which helps to locate the issue faster. support@flexopus.com