M-FILES CORPORATION

USING FEDERATED AUTHENTICATION

WITH M-FILES
LAST UPDATED MARCH 30, 2020

VERSION 1.2
Abstract

This article provides an overview of federated identity management and an introduction on using federated
authentication with M-Files. The text covers key concepts that are closely or directly related to user authentication and
federated identity, and briefly describes the federated authentication protocols and mechanisms that are compatible
with M-Files. Finally, the article gives a rundown of the different M-Files identity federation solutions that enable the
use of federated authentication with M-Files.

Keywords: AD FS, Azure AD, LDAP, OAuth, authentication, federation, identity, user provisioning
Contents
1. Introduction ........................................................................................................................................................................ 5

1.1 Glossary and Acronyms............................................................................................................................................. 5

1.2 Prerequisites ............................................................................................................................................................. 6

1.2.1 M-Files Software Requirements ...................................................................................................................... 6

2. Overview ............................................................................................................................................................................. 6

2.1 Login Types ............................................................................................................................................................... 6

2.2 Key Concepts............................................................................................................................................................. 7

2.2.1 Computational Trust ........................................................................................................................................ 7

2.2.2 Digital Certificates ............................................................................................................................................ 8

2.2.3 Identity Providers ............................................................................................................................................ 8

2.2.4 Claims and Tokens ........................................................................................................................................... 8

2.3 Authentication and User Provisioning ...................................................................................................................... 8

2.4 Benefits ..................................................................................................................................................................... 9

3. Protocols ........................................................................................................................................................................... 10

3.1 OAuth ...................................................................................................................................................................... 10

3.2 LDAP ........................................................................................................................................................................ 11

3.3 WS-Federation ........................................................................................................................................................ 11

3.4 Comparison ............................................................................................................................................................. 12

4. Solutions ........................................................................................................................................................................... 12

4.1 Azure AD ................................................................................................................................................................. 13

4.2 AD FS ....................................................................................................................................................................... 13

4.3 PingFederate ........................................................................................................................................................... 14

4.4 Comparison ............................................................................................................................................................. 14

5. Summary ........................................................................................................................................................................... 15

6. Change History .................................................................................................................................................................. 15

7. Reference Documents....................................................................................................................................................... 16
1. Introduction

In case your organization has been looking for a way for the users to authenticate themselves in M-Files by using, say, their
Google account or some other commonly used online service, you found the right document. Authentication is needed, for
instance, in logging in to M-Files vaults, as well as in electronic signing of workflow state transitions. The aim of this article is
to describe the various ways for your organization to start using federated identity management, or federated
authentication, with M-Files.

Traditionally, the need to verify user identity has been met by using software-specific credentials or Windows credentials.
Federated authentication offers organizations the possibility to use an authentication system that is completely external to
M-Files. In many cases, having a centralized repository for all the M-Files user credentials completely outside the M-Files
system can be very useful. Federated identity management also enables single sign-on, and provides the opportunity for the
users to utilize their pre-existing credentials.

This article is mainly targeted for M-Files system administrators or other personnel responsible for your organization's IT
management and security. This and the following chapter, however, might also be useful for the M-Files end users.

This chapter provides a general introduction to this document, along with a glossary and a list of prerequisites. The second
chapter, Overview, explains 1) why you should consider using federated identity management, and 2) the relevant key
concepts related to federated authentication. This is followed by the chapter Protocols, offering a technical description of
the protocols behind the Solutions for federated authentication in M-Files. Finally, there is a brief Summary recapping the
topics discussed in the article. There is also a list of helpful reference documents at the very end of the article.

1.1 Glossary and Acronyms

This table explains the essential, subject-specific terminology and acronyms used in this article.

TERM DEFINITION

Federation The concept of two or more security domains agreeing to interact with each other, specifically letting users
of one security domain access services in another security domain.

Identity provider / The party that identifies and authenticates the user requesting access to a service provider resource.
Authorization server

Service provider / The party providing the service or a resource that the user wants to access.
Resource server

5
1.2 Prerequisites

Please make sure your environment meets these requirements before moving forward.

1.2.1 M-Files Software Requirements

To be able to use the technologies described in this document with M-Files, make sure your M-Files software meets the
requirements specified in the table below.

M-FILES PRODUCT VERSION

M-Files Desktop M-Files 2015.1

M-Files Server M-Files 2015.1

M-Files Mobile for iOS M-Files Mobile for iOS Q2/2015 Release (1.7.0)

M-Files Mobile for Android M-Files Mobile for Android Q2/2015 Release (2.4.0)

M-Files Mobile for WP M-Files Mobile for Windows Phone Q2/2015 Release (2.6.100.1)

2. Overview

M-Files offers a wide variety of ways for organizations to use federated identity management. These solutions are presented
in the chapter Solutions, but let's first consider why your organization should probably start using federated authentication –
and how it actually works.

2.1 Login Types

There are basically three ways of authenticating an M-Files user:

• Software-specific credentials (M-Files username and password)
• Windows credentials
• Federated authentication

The traditional way of managing access rights to M-Files is by giving each user a login account with an M-Files username and
password. These login accounts are stored on the M-Files server computer and may be associated with Windows
credentials, thus enabling users to authenticate themselves in M-Files with the same credentials they use for logging in to
Windows or their organization's domain. This also means that the user does not need to re-enter the credentials after
logging in to Windows, and that no additional passwords are needed.

In addition to these methods, the authentication data may be located outside M-Files Server. The login information may 1)
be managed and synchronized by the organization's IT staff in an external repository, such as Azure AD, or 2) consist of
purely external login details, such as credentials for Microsoft or Google accounts. In this document, we refer to this method
as federated identity management, or federated authentication.

6
2.2 Key Concepts

There are a few recurrent concepts tightly related to federated authentication that might help you better understand the
technologies and solutions presented further below. Let's spend a few minutes getting to know these basics.

Here is a brief overview of what happens when a user logs in to M-Files using federated authentication:
1. The user attempts to log in to M-Files and sends a login request to M-Files Server.
2. M-Files Desktop requests the identity provider to authenticate the user, and the identity provider requests for the
user's credentials if they have not been previously provided.
3. M-Files Desktop delivers the access token from the identity provider to M-Files Server, and M-Files Server logs in the
user after making sure the token can be trusted.

Image 1: The authentication sequence and key concepts.

2.2.1 Computational Trust

Trust is a big deal in relationships. Similarly in information technologies, whenever external actors are involved, one party
must be able to trust the other so that cooperation can be undertaken with complete confidence. Computational trust
largely corresponds to the notion we humans have when we speak of trust. That is to say, when we trust someone, we can
expect them to speak the truth and deliver what was agreed upon.

7
Trust in the digital world is established via the authentication of the identities of the parties involved. For one party to
perform an operation that everyone affected can trust upon, we need a trusted third party, a definite authority, to authorize
the operation and tell everyone that the agent and the action can be trusted. Such authorization is generally orchestrated in
the digital domain via digital certificates issued by a certification authority.

2.2.2 Digital Certificates

The trust between an identity provider, such as Google or PingFederate, and the target application, in our case M-Files
Server, is established by using a digital certificate. The certificate, issued by a trusted certification authority, and installed on
both ends of a digital transaction, is a kind of electronic "passport" in the form of a cryptographic key proving that the
information delivered by the identity provider to M-Files Server is legitimate. When the identity provider delivers an access
token to M-Files Server, a digital certificate makes sure the information can be trusted.

2.2.3 Identity Providers

Identity providers, or identity assertion providers, offer authentication for users requiring to log in to a system by providing
identifiers that the system uses to authenticate the user. On top of that, they assert that the identifier carried by the user is
genuine. Let's say that you have a Google account and want to use your Google credentials to log in to M-Files. In such a
case, Google acts as the identity provider and supplies evidence of your successful authentication to M-Files, which in turn
accepts the evidence as a form of authentication and lets you in without further validation.

Some of the common identity providers include:

• Microsoft account
• Google
• PingFederate
• LinkedIn
• Twitter
• Yahoo!

2.2.4 Claims and Tokens

What is essentially happening in Image 1 (see further above), boils down to delivering a claim to M-Files Server: the identity
provider claims that the user is who he or she declares to be, in other words, authenticates the user. M-Files Server trusts
this claim as long as M-Files Server is capable of verifying the token with the same digital certificate. In a simple case, there
is a single claim – for instance one about the identity of a user – but there could also be various others. This is why we need
an "envelope", a token. The identity provider packages one or more claims to a token, signs the package and sends it to the
requesting application, in this case M-Files Desktop. Finally, M-Files Desktop delivers the token to M-Files Server.

2.3 Authentication and User Provisioning

User provisioning is a means to gather, store, manage and distribute user information across multiple systems. Provisioning
is bidirectional, outbound and inbound, meaning that user data can be either provisioned from a user provisioning system to
other systems or gathered from other applications to the user provisioning system.

A user provisioning system consists of inbound and outbound connectors and an internal database where user data is
represented as user objects. These objects are maintained with provisioning processes, such as auto-provisioning, auto-

8
deactivation and identity synchronization, in which user data is created, erased or updated automatically via monitoring
inbound connections to the provisioning system and with user-initiated requests, such as self-service change or access
requests and delegated access requests.

A user provisioning system assigns access rights to users but it itself does not authenticate a user, i.e. verify that the user is
who he claims to be. It is therefore important to make a distinction between user provisioning and authentication.

User authentication is a process that establishes the identity of a user attempting to log in to a system, so that appropriate
privileges can be granted to the user for accessing the system. Or, conversely, access to the system can be denied from
unauthorized users. The authentication process, in the simplest terms, is a comparison of the credentials that a user has
provided and user attributes stored in a provisioned user object. Therefore authentication and user provisioning go hand in
hand.

"Welcome to the party!"

We can use a private party as an analogy. The person managing the guest list and the invitations is the one in charge of user
provisioning, and the person waiting at the door, checking people's identification and comparing it with the names on the
guest list is responsible for authentication. Without the guest list, there is nothing to authenticate against, and without the
person at the door – or the identification – everyone, including unwelcome guests, would be allowed to join the party.

2.4 Benefits

The current and future benefits of federated authentication are numerous. Perhaps the most obvious user benefit is that
you do not need to create a separate user account to log in to M-Filer per se, as you can use your existing Google, AD,
Microsoft or some other account to log in. That way also external users can take advantage of their existing accounts and
gain immediate access to M-Files – if they are authorized to do so, of course.

Another important user benefit and user experience improvement is that with federated authentication and SSO logins, user
sessions can be retained after a single login from one service to another, which offers a more streamlined user experience
when users are not interrupted by login screens.

Heightened privacy and security is also an advantage, as when you log in using federated authentication, you only present
your user credentials to the identity provider, and never to M-Files itself. We take great pride in making sure that your user
account or your files are never compromised, and with federated authentication, your credentials are never even passed to
M-Files in the first place.

If you consider knowledge-based authentication to be insufficient, you can also augment the security level by utilizing multi-
factor authentication, a security token, or any form of strong authentication. You yourself are in full control of all the aspects
of identity management.

From the developer's perspective, federated authentication protocols separate the security infrastructure from the software
architecture, meaning that federated authentication essentially provides a cross-platform authentication solution since the
security layer is always abstracted from specific platform implementations.

Then again, from the administrative perspective, costs of maintaining user accounts are reduced when authentication and
user account maintenance is transferred from the service provider to the identity provider. Similarly, the risk of user account
information being compromised is transferred from the service provider to the identity provider.

9
3. Protocols

OAuth, WS-Federation, and LDAP are protocols for communicating authentication data between an identity provider and a
client application, essentially meaning that by using these protocols you can "outsource" your organization's identity
management to the employees. In this chapter we give a rundown of each protocol and finally compare the protocols by
highlighting key differences.

3.1 OAuth

OAuth is an open-standard protocol used for authorizing access to resources on behalf of the user. The protocol allows, with
the permission of the user, access tokens (in binary or JSON format) to be issued to clients by authorization servers, or
identity providers. The user can then use the token to access a third-party resource without providing their user credentials
directly to the resource.

The OAuth framework is designed specifically to work with the HTTP protocol. OAuth 2.0 authentication is supported in
M-Files 2015.1 and newer for M-Files Desktop, M-Files Web and M-Files Admin, and in M-Files Mobile Q2/2015 releases.

The OAuth authentication flow:

Image 2: Authentication flow with the OAuth protocol.

1. On login, Phoebe is redirected to the identity provider login page (authorization server) with a request for
authorization. Phoebe logs in and effectively authorizes the service provider to act on her behalf.
2. The service provider receives an authorization grant, which it forwards to the client.
3. The client uses the authorization grant to request an access token from the identity provider.
4. Provided that the authorization grant is valid, the identity provider grants an access token, which the client uses to
request access to the service.
5. The service provider receives the access token and it either sends the token to the identity provider for validation or
verifies the token against the identity provider certificate, depending upon the type of the token. If the token is valid,
the identity provider sends back user claims to the service provider.
6. Phoebe is granted access to the service.

10
3.2 LDAP

The Lightweight Directory Access Protocol (LDAP) is an application protocol for accessing and maintaining distributed
directory services that share information about users, services and applications in the network. It is commonly used for
implementing a SSO solution for users in a domain, so that a single set of user credentials are shared across several services
in the network.

LDAP can be used in M-Files for authentication in both on-premises and cloud environments. This is established by setting
up an LDAP server that serves directory data in a network. Authentication with such a setup is accomplished using a simple
bind operation where the credentials provided by the user are checked against a matching user object entry on the LDAP
server. The below figure gives an overview of the authentication process using an LDAP server.

Image 3: Authentication flow using an LDAP server.

1. Harald logs in to M-Files to use a cloud vault.

2. The M-Files client encrypts Harald's credentials and sends them via M-Files Server to the LDAP server.
3. The LDAP server receives the credentials and matches the user name with a corresponding one that it should have in
store. If a match is found, it validates the credentials and returns them to M-Files Server.
4. M-Files Server receives a confirmation about validated credentials and allows Harald to access the cloud vault.

3.3 WS-Federation

Web Services Federation Language (WS-Federation) is an identity federation protocol that offers cross-domain
authentication and authorization. It uses an approach based on WS-Trust, which is part of the Web Services Security set of
standards, to offer a flexible identity federation architecture that can employ a number of different types of tokens for user
authentication.

The WS-Federation authentication flow:

11
Image 4: Authentication flow with WS-Federation.

1. Laura wants to log in to M-Files.

2. She is redirected from M-Files to the identity provider login page.
3. Laura, if she hasn't done so already, provides her user credentials to the identity provider and logs in.
4. The identity provider authenticates Laura's credentials to determine whether Laura is truly who she claims to be, and
after successfully doing so, the identity provider sends a token to M-Files. The token includes user claims about
Laura, which basically helps the service to determine what Laura is authorized to do once she's logged in.
5. M-Files receives the token from the identity provider and Laura is free to use M-Files once it has verified that the
token is indeed authentic.

3.4 Comparison

From the end user's point of view, we can conclude that the protocols introduced in this chapter offer a similar login
experience. The crucial differences between the protocols therefore exist under the hood. The table below presents a
comparison of the protocols presented in this chapter, and pinpoints the most important differences between them.

PROTOCOL SOLUTION COMPATIBILITY M-FILES SUPPORT SCOPE

OAuth Azure AD, AD FS (since Windows M-Files Desktop, M-Files Web, OAuth is typically used with web and
Server 2012 R2), LDAP, PingFederate M-Files Admin, and M-Files Mobile mobile applications for delegated
authorization of resources.

LDAP AD FS, PingFederate M-Files Desktop and M-Files Web An LDAP server is typically used to
provide single sign-on capabilities
within a network.

WS-Federation Azure AD, AD FS, PingFederate M-Files Desktop and M-Files Web WS-Federation is typically used for
with AD FS identity federation in Microsoft
enterprise environments.

4. Solutions

This chapter lists and describes the various ways that allow you to start utilizing federated identity management with
M-Files. The solutions are presented one by one and are followed by a comparison chart.

12
4.1 Azure AD

Azure Active Directory (Azure AD) is a cloud-based identity management solution from Microsoft that offers comprehensive
identity and access management tools for single sign-on login procedures to cloud and on-premises applications. Azure AD
supports several different authentication and authorization protocols, including the ones introduced in this article: OAuth
and WS-Federation.

Azure AD can be used as an identity provider for M-Files 2015 with the OAuth protocol. M-Files also has an Azure AD
synchronization plugin that can be used to import users and user groups from Azure AD to M-Files. The below figure
illustrates how Azure AD serves as an identity provider, or an authorization server, for M-Files via the OAuth protocol:

Image 5: M-Files authentication flow with Azure AD using the OAuth protocol.

4.2 AD FS

Active Directory Federation Services (AD FS) is an identity management service for Windows Server that uses a claims-based
authentication to allow users to gain single sign-on access across trusted domains. In M-Files, AD FS can be used as an
identity provider in a cloud environment where M-Files clients and user accounts reside in one domain and M-Files Server
resides in another. AD FS enables cross-domain authentication so that M-Files Server can authenticate users from a different
domain. AD FS uses WS-Federation and OAuth as sign-in and authentication protocols and for issuing user claims.

The below figure illustrates the cross-domain authentication procedure in M-Files using an AD FS server and an AD FS plugin
on the M-Files Server side:

13
Image 6: AD FS authentication flow.

This type of approach that AD FS offers allows users from another domain to access M-Files without direct authentication
and without the need for the server and the client side to share distributed user account information.

4.3 PingFederate

PingFederate is an identity provider and a federation service that provides cross-domain SSO capabilities, identity
management and API security. Its multiprotocol capability provides support for all the authentication protocols introduced
in this article and it can also be integrated with other identity stores and cloud directory services, such as Active Directory
and Azure AD.

PingFederate is a full-fledged, highly configurable federation service offering high level of availability and integrability. It
allows access decisions based on contextual data, such as device, time of day or location, and offers augmented
authentication data with user information from other external data stores, among other things.

PingFederate is well-suited for authentication in M-Files as it supports all the authentication protocols that are also
compatible with M-Files, meaning that it can be used as an external identity provider for M-Files Desktop, Web, Admin and
Mobile applications.

4.4 Comparison

The table below highlights the capabilities of the solutions presented in this chapter.

14
 SOLUTION DESCRIPTION SCOPE TYPE

Azure AD A cloud solution from Microsoft for identity and Azure AD is used for cloud-based Cloud-delivered identity
access management. identity federation. management

AD FS A software component for Windows Server AD FS is typically used to provide On-premises bridge component
operating systems, providing federated identity SSO across trusted domains. for federated authentication
management and single sign-on capabilities.

PingFederate A multi-protocol federation service that PingFederate is used as an Web-centric IDaaS (Identity as a
provides cross-domain SSO capabilities, identity external identity provider for web Service)
management and API security. applications.

5. Summary

Federated identity management allows user authentication to be handled by a third-party service provider. Federated
authentication is based on a trust relationship between the identity provider and the service provider where user
identification, authentication and requests between the parties are communicated with security tokens and authorization
grants. Such an approach offers many benefits for end users, administrators as well as developers.

Federated authentication offers a streamlined and highly configurable login experience for users, who can sign in to services
using SSO and use different types of access control, including multi-factor authentication solutions. The use of external
identity providers entails that user credentials are never stored in the client application, which improves security
considerably. With federation, also the costs of maintaining user accounts are reduced since authentication and user
provisioning are outsourced to the identity provider.

M-Files 2015 and newer offer federated authentication support via several authentication and authorization mechanisms
that enable you to use various federated authentication solutions with M-Files. You can delegate M-Files user authentication
to OAuth compliant identity provider, or, if you are deeply invested in Active Directory, you can take advantage of the
federation solutions offered by Microsoft to extend your Active Directory presence into the cloud for M-Files.

6. Change History

The table below describes the essential changes by document version.

15
 VERSION DATE ESSENTIAL CHANGES

1.0 2015-08-20 Initial published version.

1.1 2018-03-12 Reviewed the comparison table in chapter 3.5 and modified the document to match the current,
official template.

1.2 2020-03-30 Removed references to SAML (deprecated).

7. Reference Documents

Refer to these documents for instructions on how to configure a specific protocol or solution for M-Files authentication:

• Configuring OpenID Connect and OAuth 2.0 for M-Files Authentication

• Configuring AD FS for M-Files Authentication

• Configuring LDAP for M-Files Authentication

• Configuring Azure Active Directory Synchronization Plugin

16