Introduction

RPort OAuth supports SSO / OAuth using 3 different providers (GitHub, Microsoft or Google - see note below). Using OAuth allows authorized users to sign into RPort with their OAuth provider credentials.

Additionally, RPort OAuth will allow you to optionally specify a required organization or group (depending on the OAuth provider) and automatically create and sign in those users to RPort. This can make life easier for RPort users and administrators.

The RPort OAuth implementation works by adding users who successfully authenticate with the OAuth provider to the list of allowed RPort users. For more information about user authentication in RPort, see API Authentication.

After authentication the user is granted an RPort bearer token which is then used for further authentication with rportd services. The OAuth access token supplied by the OAuth provider is then no longer used.

There are two OAuth authentication flows supported, 1) a flow similar to the traditional OAuth web app flow (used by web apps such as RPort UI) and 2) a flow similar to the OAuth device flow (used by non-browser apps such as the rportcli). These flows are not the same as the actual OAuth standards flows, but they are similar. For more detailed technical information, see the RPort OAuth Dev Guide

Only a single provider can be used at any time.

Users that have successfully authenticated via OAuth can be created on the RPort user database on-the-fly. You can turn this function off, so only those users can authenticate that have been added to the user list manually.

If users are created on-the-fly they are added to the group of Administrators by default. You can turn this off by assigning new user to an unprivileged user group using the default_user_group setting.

If you decide not to add new users to the Administrators group, you must assign at least one user to this group manually by manipulating the database.

Bear in mind, once OAuth is enabled, the default admin user created at install gets disabled. Make sure at least one OAuth user is a member of the Administrator user group.

Learn how to add group members via SQL directly on the database:

# Open the database console
$ sqlite3 /var/lib/rport/auth.db
# On the database console
sqlite> INSERT INTO groups VALUES('<USERNAME>','Administrators');
sqlite> .headers on
sqlite> SELECT * FROM groups;
sqlite> .exit

👉 Note: Your user database file might have a different name.

By default, all users that have passed the OAuth authentication will get access to your rport server unless you require all user to be added manually (see above).

Large organisations almost never want all staff having access to rport. Consider using one of the following conditions:

Applies to Microsoft and Google only. Use required_group_id to specify a Microsoft or Google group id whose members have permission to access the RPort server. Users who are not members of the group will be denied access. Note that not used when using the device style flow with google.

GitHub only. Use required_organization to specifies a GitHub organization whose users have permission to access the Rport server. The required_organization must match the organization name as displayed in the GitHub URL for the organization or as under the list of organizations for which the user is a member. Optional if permitted_user_list or permitted_user_match (see below) are used.

Use permitted_user_list to control whether Rport OAuth will only allow users configured via the existing Rport ‘api auth’ mechanism. This can be used with the required_organization or required_group_id settings to limit users to a permitted set in the organization or group. If permitted_user_list is set to false then all users in an OAuth provider organization will be allowed access, subject to the permitted user config settings. For GitHub one of either required_organization, permitted_user_list or permitted_user_match must be set. The options can be combined. Setting permitted_user_list or permitted_user_match to false and not setting required_organization is not allowed. For Microsoft or Google permitted_user_list is always optional.

Using permitted_user_match provides further control of the permitted users via a regex value. E.g. permitted_user_match="sample-org.com$" will match usernames ending in “sample-org.com$”. Cannot be used at the same time as permitted_user_list.

OAuth can be used on both, the web UI and the rportcli version >= 0.4.2.

If planning to use OAuth on the rportcli then follow the individual guides for your OAuth provider making sure to additionally configure the settings for the so-called “device style flow”.

Once OAuth is activated on the rport server all clients (Web UI, raw API calls, rportcli) must use it. If you don’t want to activate the device style flow non-UI clients, you can still generate API tokens and authenticate rportcli and your API scripts with these tokens.