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.

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:

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.

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.

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:

User groups

Introduction Here you can see a list of action you can do with user groups to use and manage them as an administrator: How to manage the user groups? * Manage groups manually * Manage groups via the SCIM API * Manage groups via SAML2 (memberOf) * Import users and groups (CSV and XLSX)

Flexopus Help CenterDaniel Fafula

Trouble Shooting and FAQ