OAuth2 Authentication

This page provides more information about the OAuth2 authentication plugin.

The plugin can be used to authenticate FileRun users against a remote server via the OAuth 2.0 protocol.

If you are new to OAuth2, here is a good introduction: https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2

You can also check out this article for more in-depth information: https://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified

Using the plugin, FileRun acts as an OAuth2 client, utilizing the Authorization Code grant type to verify the user's identities and retrieve basic information, using to automatically create the FileRun account.

Before you can begin the OAuth2 process, you must first register a new OAuth2 client (also known as app or application) with the OAuth2 server.

When registering a new client, you usually register basic information such as application name, website, a logo, etc.

In addition, you must register a redirect URI to be used for redirecting users back to FileRun. You can retrieve the correct URI from FileRun's control panel. It will be displayed on the same page where you configure the FileRun OAuth2 plugin, under the “Authentication” section, after you select “OAuth2” for the enabled plugin.

Important note: OAuth2 servers require an HTTPS redirect URI, so your web server needs to be configured with an SSL certificate. Unsecured HTTP connections will be refused, as it represents a serious security vulnerability. Get a free SSL certificate here: https://letsencrypt.org

Armed with the Client ID (sometimes referred to as app id or app key) and Client Secret provided by the OAuth2 server at the step above, open FileRun's control panel and navigate to the Authentication section.

Select OAuth2 from the Enabled plugin list and start configuring below.

The following fields will be filled with information you get from the OAuth2 server provider: Client ID, Client Secret, Authorization URL, Access Token URL.

Some OAuth2 server issue OAuth2 authorization tokens with limited lifetime. In that case, FileRun will need to refresh these tokens from time to time. If that is the case, configure Access token needs refresh with the value yes, instead of no.

The field User info HTTP method can take two possible values POST or GET. The correct value (HTTP method) can be found in the OAuth2 server provider's API documentation.

The List of scopes is a list of scopes, as defined by the remote API provider, that might be required for retrieving the user's information. The appropriate values can be found in the OAuth2 server provider's API documentation.

After the user's consent and confirming the user's identity, FileRun will retrieve the user's basic information, in order to create a local user account. The mandatory fields are Username mapping and First name mapping.

FileRun will call the configured User info API URL, which in most cases, returns a JSON object with information about the authenticated user account.

In order to pick the correct data and map it to the FileRun fields, JSONPath selectors are being used.

Here's an example JSON output (taken from the Dropbox API):

{
    "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
    "name": {
        "given_name": "Franz",
        "surname": "Ferdinand",
        "familiar_name": "Franz",
        "display_name": "Franz Ferdinand (Personal)",
        "abbreviated_name": "FF"
    },
    "email": "franz@dropbox.com",
    "email_verified": true,
    "disabled": false,
    "locale": "en",
    "referral_link": "https://db.tt/ZITNuhtI",
    "country": "US"
}

In order to map the data from name > given_name to the FileRun First name field, you'll be using the JSONPath selector $.name.given_name. Let's break that down:

Root object ($)

Returns the value of the whole object.

"$" // {account_id: "[...]", { name: { [...] }} [...] }

Property

Returns the whole value of the name property on the root object.

"$.name" // { name: {"given_name": "Franz", [...] } }

Nested property

Returns the value of given_name on the name property of the root object.

"$.name.given_name" // "Franz"

After typing in the configuration parameters, please press the Test settings button.

This will provide you with a link to test out the OAuth2 server's authorization process. We strongly recommend you to right-click the link and open it in a new “private”/“incognito” browser window, so that it does not interfere with your current FileRun session.

If the configuration is correct, you will be presented either with a login page or a consent page from the remote server.

Do not press to confirm/consent just yet. Instead, switch back to the FileRun browser window, and click Save changes.

If you proceed now with the confirmation/consent, you should be redirected to FileRun, where you should find yourself signed in.

Note: It is recommended that at this point you keep the FileRun option Allow local user accounts to login enabled, so that you can still sign in with your FileRun superuser account, at least until making sure everything works fine and you have adjusted the FileRun superuser account to match the appropriate username from the OAuth2 system.

When disabling the FileRun option Allow local user accounts to login, make sure you configure Redirect URL after logout otherwise logging out will redirect users back to the OAuth2 consent screen.

Loggoing out will clear the OAuth2 access token from the user's session, which means the user will be shown the OAuth2 consent page next time he logs in. For a better user experience, it is recommended to either enable the FileRun setting Hide the logout option or configure Logout URL with the logout URL used by the remote system so that the user actually logs from there and not just from FileRun.