This plugin adds a Github realm to Sonatype Nexus OSS and enables you to authenticate with Github Users and authorize with Github Orgs and Teams.
The plugin does not implement a full OAuth flow, instead you use your github user name + an OAuth token you generated in your account to log in to the nexus. This works through the web as well as through tools like maven, gradle...
- JDK 8 is installed
- Apache Maven is installed
- Sonatype Nexus OSS 3.2.x is installed
When Nexus gets downloaded and unzipped, there are typically two directories created:
- nexus-3.2.1-01
- sonatype-work/nexus3
To avoid confusion, the conventions of the Sonatype reference will be used in the following descriptions:
- nexus-3.2.1-01 will be referred to as $install-dir
- sonatype-work/nexus3 will be referred to as $data-dir
See https://books.sonatype.com/nexus-book/reference3/install.html#directories for reference.
Build and install the into your local maven repository using the following commands:
./mvnw install
cp -ra ~/.m2/repository/com/larscheidschmitzhermes $install-dir/system/com
Append the following line to $install-dir/etc/karaf/startup.properties
Please replace [PLUGIN_VERSION] by the current plugin version.
mvn\:com.larscheidschmitzhermes/nexus3-github-oauth-plugin/[PLUGIN_VERSION] = 200
Create $install-dir/etc/githuboauth.properties
Within the file you can configure the following properties:
| Property | Description | Default |
|---|---|---|
github.api.url |
URL of the Github API to operate against. | none |
github.principal.cache.ttl |
Duration for how long a given Access will be cached for. This is a tradeoff of how quickly access can be revoked and how quickly a Github user's rate limit will be reached for the Github User API. Note: Github Enterprise does not have a rate limit! | PT1M (1 Minute) |
This is what an example file would look like:
github.api.url=https://github.example.com/api/v3 #note: no trailing slash!!!
github.principal.cache.ttl=PT1MRestart your Nexus instance to let it pick up your changes.
Log in to your nexus and go to Administration > Security > Realms. Move the Github Realm to the right. The realm order in the form determines the order of the realms in your authentication flow. We recommend putting Github after the built-in realms.
When logged in through Github, all organizations and teams the user is a member of will be mapped into roles like so:
organization name/team name e.g. dummy-org/developers
You need to manually create these roles in Administration > Security > Roles in order to assign them the desired priviliges. Note that anybody is allowed to login (authenticate) with a valid Github Token from your Github instance, but he/she won't have any priviledges assigned with their teams (authorization).
The following steps need to be done by every developer who wants to login to your nexus with Github.
In your github account under Settings > Personal access tokens generate a new OAuth token. The only scope you need is read:org
When logging in to nexus, use your github user name as the username and the oauth token you just generated as the password. This also works through maven, gradle etc.
The whole project is heavily influenced by the nexus3-crowd-plugin.