Configuration Settings

This section describes the RPort OAuth configuration settings needed to enable OAuth authentication for RPort. The settings required depend on whether the more traditional web app type flow (e.g. for the RPort UI) or the more CLI based device style flow (e.g. for the rportcli) is required.

Primary Settings

The following primary configuration settings are used to control the OAuth provider.

provider = "sample-provider"
token_url = "https://sample-provider.com/oauth/access_token"
redirect_uri = "http://sample-rport-host:3000/oauth/callback"
client_id = "sample-client-id"
client_secret = "sample-client-secret"
# when using the web app style flow
authorize_url = "https://sample-provider.com/authorize"
# when using the device style flow
device_authorize_url = "https://sample-provider.com/authorize/device"
# only when using the device style flow with google
device_client_id = "sample-google-client-id"
device_client_secret = "sample-google-client-secret"

provider (Required)

The provider setting indicates which OAuth provider is being used.

Currently must be one of:

github
microsoft
google

client_id (Required - if not using device style flow with google)

The client_id is the identifier assigned to the RPort ‘app’ configured as part of the OAuth provider setup. For more information on provider setups, see the related OAuth provider specific section included as part of the RPort OAuth section.

client_secret (Required - if not using device style flow with google)

The client_secret is a secret provided by the OAuth provider to be used when exchanging an authorization code for OAuth provider tokens. This secret must be kept private and should NOT be included in any source code repo check-ins, unencrypted cloud backups, etc.

device_client_id (Required - only if using device style flow with google)

The device_lient_id is the identifier assigned to the RPort ‘app’ configured as part of the OAuth provider (google) setup. This setting is only used with Google as they use separate client id and secrets with their device flow implementation. The other providers use the same client ids and secrets for both web app and device flows.

device_client_secret (Required - only if using device style flow with google)

The device_client_secret is a secret provided by the OAuth provider (google) to be used when check if a user has authorized yet. This secret must be kept private and should NOT be included in any source code repo check-ins, unencrypted cloud backups, etc. This setting is only used with Google as they use separate client id and secrets with their device flow implementation.

authorize_url (Required - web app style flow only)

The authorize_url setting is the OAuth provider base url used for handling the user’s authorization.

If the user hasn’t previously given permission then the OAuth provider authorization screens will ask the user to confirm (and if required will ask the user to authenticated themselves).

device_authorize_url (Required - device style flow only)

The device_authorize_url setting is the OAuth provider base url used to obtain the login info required from the OAuth provider for the device login. Typically the CLI (or similar app) will need to display some of this info to the user, who will then need to proceed separately to an OAuth provider web page to authorize their identity for use with RPort.

token_url (Required)

For the web app style flow, the token_url setting is the OAuth provider base url used for exchanging an authorization code (received as part of the redirect_uri callback) for OAuth related tokens.

For the device style flow, the token_url setting is used to check whether the user has authorized yet or not. If the user has authorized then OAuth related tokens are returned to RPort.

redirect_uri (Required - web app style flow only)

The redirect_uri setting is the OAuth provider base url where the OAuth provider will redirect (with an authorization code) after completing the user’s authorization.

If using the RPort UI then this setting must be set to http://localhost/oauth/callback.

Access Control Settings

The following settings control how RPort authorizes users presented by the OAuth provider.

# for GitHub only
required_organization = "sample-organization"
# for Microsoft and Google only
required_group_id = "sample-group-id"
# for both
permitted_user_list = true
permitted_user_match = ""

When setting up RPort with an OAuth provider, it must be decided how to constrain the users who are allowed to use RPort (otherwise all users of the OAuth provider would be able to access the server).

For GitHub, an existing organization (via required_organization) or a list of valid users (via either permitted_user_list or the permitted_user_match settings) must be specified.

For Microsoft and Google, the app registration will limit the users to a specific organization and then the permitted users can be further limited by required_group_id, permitted_user_list or permitted_user_match.

The permitted_user_match setting allows usernames to be matched by regular expression. If the identified username matches the regex then the user will be permitted access to RPort, otherwise if doesn’t match then the user will be denied access. This allows admins more control of permitted users without having to add them individually to the api auth mechanism. Note that permitted_user_match cannot be used when the permitted_user_list setting is being used.

required_organization (Required - GitHub only)

The required_organization setting specifies an existing GitHub organization who’s users have permission to access the RPort server. Optional if permitted_user_list is being used.

required_group_id (Optional - Microsoft and Google only)

The required_group_id setting specifies an existing Microsoft group (by id) or Google group (by email address) who’s users have permission to access the RPort server.

Note that when using the device style flow with google, limiting by required_group_id is not supported (as group queries are not supported by google when using their device flow implementation).

permitted_user_list (Optional - although see below)

The permitted_user_list setting indicates whether RPort OAuth will only allow users configured via the existing RPort ‘api auth’ mechanism (see API Authentication).

This can be used with the required_organization or required_group_id settings to limit users to a permitted set. If permitted_user_list is set to false then all users as permitted by the default OAuth provider setup will be allowed access.

For GitHub, either permitted_user_list or required_organization must be set and required_organization and permitted_user_list can be combined. Setting permitted_user_list to false and not setting required_organization is not allowed.

For Microsoft and Google, permitted_user_list is always Optional.

The usernames specified via the existing ‘api auth’ mechanism are derived from the OAuth provider user details. For more information, see the individual OAuth provider sections.

permitted_user_match (Optional)

The permitted_user_match setting provides further control of the permitted users via a regex value. For example

permitted_user_match="cloudradar.io$"

Will only match and permit usernames that end with cloudradar.io.