GitHub Setup

To use GitHub users for RPort authentication you must add and configure a GitHub OAuth App. This App is created and fully controlled by the RPort administrator and permission for RPort access can be revoked at any time. When users first login to RPort via their GitHub user, they must allow this app to read their profile and org info.

For a detailed reference on the configuration settings mentioned in this section, see the Configuration Settings guide.

By specifying a required_organization in the rportd config, user access to RPort can be limited solely to the members of an individual GitHub organization without needing to set up the users in advance (see below).

If the permitted_user_list config option is true users must exist in the local user database where the username must match the GitHub username. Users won’t be created on-the-fly and access is denied. Use the option if the users don’t belong to a common GitHub organisation.

If the permitted_user_list config option is not set or set to false, then rportd will automatically create and add any user who successfully authenticates with GitHub to the list of allowed users for RPort. Note the required_organization config setting must be set for this to apply to prevent any GutHUb user can log in to your RPOrt server.

If you have two-factor authentication enabled on the rport server, you must turn it off before setting up OAuth. Use the supported two-factor authentications of GitHub instead.

Most steps apply when setting up both web style and device style flows. Where is a step only applies to one or the other than this will be indicated.

• Login to the GitHub account that you wish to use as the admin for the RPort Access App.
  Select Settings from the top-right GitHub menu.
  Select Developer Settings from the bottom of left sidebar menu.
  Select OAuth Apps from the Developer Settings left sidebar menu.
  Click Register a new application

  

• Enter the details requested on the Register new GitHub App screen

  • Enter the FQDN of the rport server as homepage URL.

  • For the Authorization callback URL enter https://<RPORT-SERVER-FQDN>/oauth/callback, so that the rport server can catch the returned authorization code.

  • If the device style flow (rport cli support) is required then click the Enable Device Flow checkbox.

  • Click Register application

  • Review the details presented for the newly created app. Note the client id.

    

In the section titled Client secrets, click Generate a new client secret. Copy and paste the generated secret and keep somewhere safe. Don’t forget to confirm with the green Update button on the bottom of the page.

The following information will be required in /etc/rport/rportd.conf:

[oauth]
  provider = "github"
  token_url = "https://github.com/login/oauth/access_token"
  redirect_uri = "https://<RPORT-SERVER-FQDN>/oauth/callback"
  client_id = "<your client id>"
  client_secret = "<your client secret>"
  authorize_url = "https://github.com/login/oauth/authorize"
  # If using the device style flow (OAuth for rportcli) additionally active the below line.
  # device_authorize_url = "https://github.com/login/device/code"

Set the rportd oauth access control config parameters as required

Depending on requirements, the following access control config parameters maybe set.

  # Users must be members of the 'example-org' organization
  required_organization="example-org"
  # All members are permitted to access RPort
  permitted_user_list=false

Note: 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. For example:

https://github.com/example-org

The organization name that must match the required_organization is example-org.

Both, permitted_user_list=true and required_organization=<SOME_ORG> can be used in combination.

Remember: You always need to restart the rportd after changing the configuration file.
Execute service rportd restart.

RPort OAuth for GitHub uses the login field from the GitHub API user details as the username for RPort. Please see Get the authenticated user for a description of this field.

When using permitted_user_list the usernames listed in the RPort API file or DB (see API Authentication) must match the value of the GitHub login field for the user.

If there isn’t any GitHub user on your database, insert one manually.

sqlite3 /var/lib/rport/auth.db<<EOF
.headers on
INSERT INTO users VALUES('<USERNAME>','',null,'','','');
INSERT INTO groups VALUES('<USERNAME>','Administrators');
SELECT * FROM users;
EOF

👉 Note: Your authentication database file might have a different name, e.g. users.db.

For the required organization check, RPort checks that the required_organization configuration value is one of the login values for the orgs of which the GitHub user is a member. Please see GitHub REST List organizations for the authenticated user API for more information. Note that RPort will only check the first 100 orgs that a user belongs to.