USING FEDERATED AUTHENTICATION WITH M-FILES

M-FILES CORPORATION USING FEDERATED AUTHENTICATION WITH M-FILES VERSION 1.0

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, SAML, authentication, federation, identity, user provisioning

Contents 1. Introduction... 4 1.1. Glossary and Acronyms... 4 1.2. Prerequisites... 5 1.2.1 M-Files Software Requirements... 5 2. Overview... 5 2.1. Login Types... 5 2.2. Key Concepts... 6 2.2.1 Computational Trust... 6 2.2.2 Digital Certificates... 7 2.2.3 Identity Providers... 7 2.2.4 Claims and Tokens... 7 2.3. Authentication and User Provisioning... 7 2.4. Benefits... 8 3. Protocols... 9 3.1. SAML... 9 3.2. OAuth... 9 3.3. LDAP... 10 3.4. WS-Federation... 11 3.5. Comparison... 12 4. Solutions... 12 4.1. Azure AD... 12 4.2. AD FS... 13 4.3. PingFederate... 14 4.4. Comparison... 14 5. Summary... 14 6. Change History... 15 7. Reference Documents... 15

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 Federation Identity provider / Authorization server Service provider / Resource server DEFINITION 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. The party that identifies and authenticates the user requesting access to a service provider resource. The party providing the service or a resource that the user wants to access. 4

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. 5

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. 6

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- 7

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 multifactor 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. 8

3. Protocols SAML, 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. SAML Security Assertion Markup Language, or SAML for short, is an XML-based, open-standard data format for communicating authentication and authorization information between a party that provides user identities, i.e. an identity provider, and a party that provides the service that the user needs to log in to, i.e. a service provider. M-Files 2015.1 and later supports SAML V2.0 with HTTP POST Binding and HTTP Redirect Binding for M-Files Desktop and M-Files Web. HTTP POST Binding is a means of communication via HTML forms between the client, the service provider and the identity provider. HTTP Redirect Binding, on the other, communicates SAML data via URL query strings. SAML requests can be initiated by either the service provider or the identity provider. The figure below gives an overview of the authentication process using the SAML protocol: Image 2: Authentication flow with the SAML protocol. 1. Diego attempts to log in, and the client first sends an authentication request to the service provider. 2. The service provider creates an authorization request, which it sends to the identity provider. 3. Diego is redirected to the identity provider's login page where Diego provides their credentials and logs in. 4. After the credentials have been validated, the identity provider returns a response to the service provider in a SAML format that contains an assertion affirming that Diego has been authenticated. 5. The service provider verifies the SAML assertion and grants Diego access based on the authenticated token. 3.2. 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 9

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 is similar to the SAML authentication process: Image 3: 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. 3.3. 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. 10

Image 4: 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.4. 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, including SAML tokens. The WS-Federation authentication flow is, to all intents and purposes, very similar to the SAML authentication process: Image 5: 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. 11

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.5. 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 SAML Azure AD, AD FS, LDAP, PingFederate M-Files Desktop, M-Files Web, M- Files Admin SAML is typically used for enterprise SSO solutions within an enterprise, enterprise to partner, or enterprise to cloud scenarios. OAuth Azure AD, AD FS (since Windows Server 2012 R2), LDAP, PingFederate M-Files Desktop, M-Files Admin and M-Files Mobile OAuth is typically used with web and 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 with AD FS WS-Federation is typically used for 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. 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: SAML, OAuth and WS-Federation. Azure AD can be used as an identity provider for M-Files 2015 with the SAML and OAuth protocols. 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: 12

Image 6: 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, OAuth, and SAML 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: Image 7: 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. 13

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. SOLUTION DESCRIPTION SCOPE TYPE Azure AD A cloud solution from Microsoft for identity and access management. Azure AD is used for cloud-based identity federation. Cloud-delivered identity management AD FS A software component for Windows Server operating systems, providing federated identity management and single sign-on capabilities. AD FS is typically used to provide SSO across trusted domains. On-premises bridge component for federated authentication PingFederate A multi-protocol federation service that provides cross-domain SSO capabilities, identity management and API security. PingFederate is used as an external identity provider for web applications. Web-centric IDaaS (Identity as a Service) 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 SAML or OAuth compliant identity providers, 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. 14

6. Change History The table below describes the essential changes by document version. VERSION DATE ESSENTIAL CHANGES 1.0 2015-08-20 Initial published version. 7. Reference Documents Refer to these documents for instructions on how to configure a specific protocol or solution for M-Files authentication: Configuring OAuth 2.0 for M-Files Authentication Configuring AD FS for M-Files Authentication Configuring LDAP for M-Files Authentication Configuring SAML v2.0 Authentication Against Azure AD Configuring Azure Active Directory Synchronization Plugin 15