Github OAuth Plugin

Skip to end of metadata
Go to start of metadata

About GitHub Authentication Plugin

The GitHub Authentication Plugin provides a means of using GitHub for authentication and authorization to secure Jenkins. GitHub Enterprise is also supported.

Plugin Information

Plugin ID github-oauth Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
0.22.2 (archives)
Jul 25, 2015
1.586
mailer (version:1.4)
github-api (version:1.69)
git (version:2.0.3)
Source Code
Issue Tracking
Pull Requests
Maintainer(s)
GitHub
Open Issues
Pull Requests
Sam Gleske (id: sag47)
Usage Installations 2014-Jul 3299
2014-Aug 3362
2014-Sep 3538
2014-Oct 3638
2014-Nov 3775
2014-Dec 3763
2015-Jan 4019
2015-Feb 4058
2015-Mar 4440
2015-Apr 4544
2015-May 4568
2015-Jun 4547

On this page:

Setup

Before configuring the plugin you must create a GitHub application registration.

  1. Visit the following page to create a GitHub application registration: https://github.com/settings/applications/new.
  2. The values for application name, homepage URL, or application description don't matter. They can be customized however desired.
  3. However, the authorization callback URL takes a specific value. It must be http://myserver.com:8080/securityRealm/finishLogin where myserver.com:8080 is the location of a Jenkins server.
    The important part of the callback URL is /securityRealm/finishLogin
  4. Finish up by clicking Register application.
The Client ID and the Client Secret will be used to configure the Jenkins Security Realm. Keep the page open to the application registration so this information can be copied to your Jenkins configuration.

Security Realm in Global Security

The security realm in Jenkins controls authentication (i.e. you are who you say you are). The GitHub Authentication Plugin provides a security realm to authenticate Jenkins users via GitHub OAuth.

  1. In the Global Security configuration choose the Security Realm to be Github Authentication Plugin.
  2. The settings to configure are: GitHub Web URI, GitHub API URI, Client ID, Client Secret, and OAuth Scope(s).
  3. If you're using GitHub Enterprise then the API URI is https://ghe.acme.com/api/v3.
    The GitHub Enterprise API URI ends with /api/v3.
  4. The recommended minimum GitHub OAuth scopes are read:org,user:email.
    The recommended scopes are designed for using both authentication and authorization functions in the plugin. If only authentication is being used then the scope can be further limited to (no scope) or user:email.
In the plugin configuration pages each field has a little next to it. Click on it for help about the setting.

Authorization in Global Security.

The authorization in Jenkins controls what your users can do (i.e. read jobs, execute builds, or have administer permissions, etc.). The GitHub OAuth Plugin supports multiple ways of configuring authorization.

It is recommended to configure the security realm and log in via GitHub OAuth before configuring authorization. This way Jenkins can look up and verify users and groups if configuring matrix-based authorization.
Github Commiter Authorization Strategy

Control user authorization using the Github Commiter Authorization Strategy. This is the simplest authorization strategy to get up and running. It handles authorization based on the git URL of a job and what type of access a user has to that project (i.e. Admin, read/write, read only).

There is a way to authorize the use of the /github-webhook callback url to receive post commit hooks from Github. This authorization strategy has a checkbox that can allow GitHub POST data to be received. You still need to run the Github Plugin to have the message trigger the build.
Logged-in users can do anything

There's a few ways to configure everyone on your team being an admin.

  1. Choose Logged-in users can do anything authorization strategy.
  2. Choose one of the matrix-based authorization strategies. Set authenticated users to overall administer permissions. Set anonymous users to have overall read permissions and perhaps the ViewStatus permission.
Matrix-based Authorization strategy

Control user authorization using Matrix-based security or Project-based Matrix Authorization Strategy. Project-base Matrix Authorization Strategy allows one to configure authorization globally per project and, when using Project-based Matrix Authorization Strategy with the Cloudbees folder plugin, per folder.

There are a few built-in authorizations to consider.

  • anonymous - is anyone who has not logged in. Recommended permissions are just overall read.
  • authenticated - is anyone who has logged in. You can configure permissions for anybody who has logged into Jenkins.
    anonymous and authenticated usernames are case sensitive and must be lower case. This is a consideration when configuring authorizations via Groovy. Keep in mind that anonymous shows up as Anonymous in the Jenkins UI.

You can configure authorization based on GitHub users, organizations, or teams.

  • username - give permissions to a specific GitHub username.
  • organization - give permissions to every user that belongs to a specific GitHub organization. You have to be a public member of the organization for the authorization to work correctly.
  • organization*team - give permissions to a specific GitHub team of a GitHub organization. Notice that organization and team are separated by an asterisk (*).

Other usage

Calling Jenkins API using GitHub Personal Access Tokens

You can make Jenkins API calls by using a GitHub personal access token. One can still call the Jenkins API by using Jenkins tokens or use the Jenkins CLI with an SSH key for authentication. However, the GitHub OAuth plugin provides another way to call the Jenkins API by allowing the use of a GitHub Personal Access Token.

  1. Generate a GitHub Personal Access Token and give it only read:org scope.
  2. Use a username and GitHub personal access token to authenticate with the Jenkins API.

Here's an example using curl to start a build using parameters (username samrocketman and password using the personal access token).

curl -X POST http://localhost:8080/job/_jervis_generator/build --user "samrocketman:myGitHubPersonalAccessToken" --data-urlencode json='{"parameter": [{"name":"project", "value":"samrocketman/jervis"}]}'

Autoconfigure security realm via script console

Configuration management could be used to configure the security realm via the Jenkins Script Console. Here's a sample configuring plugin version 0.22.

import hudson.security.SecurityRealm
import org.jenkinsci.plugins.GithubSecurityRealm
String githubWebUri = 'https://github.com'
String githubApiUri = 'https://api.github.com'
String clientID = 'someid'
String clientSecret = 'somesecret'
String oauthScopes = 'read:org'
SecurityRealm github_realm = new GithubSecurityRealm(githubWebUri, githubApiUri, clientID, clientSecret, oauthScopes)
//check for equality, no need to modify the runtime if no settings changed
if(!github_realm.equals(Jenkins.instance.getSecurityRealm())) {
    Jenkins.instance.setSecurityRealm(github_realm)
    Jenkins.instance.save()
}

Autoconfigure authorization strategy via script console

Configuration management could be used to configure the authorization strategy via the Jenkins Script Console. Here's a sample configuring plugin version 0.22.

import org.jenkinsci.plugins.GithubAuthorizationStrategy
import hudson.security.AuthorizationStrategy

//permissions are ordered similar to web UI
//Admin User Names
String adminUserNames = 'samrocketman'
//Participant in Organization
String organizationNames = ''
//Use Github repository permissions
boolean useRepositoryPermissions = true
//Grant READ permissions to all Authenticated Users
boolean authenticatedUserReadPermission = false
//Grant CREATE Job permissions to all Authenticated Users
boolean authenticatedUserCreateJobPermission = false
//Grant READ permissions for /github-webhook
boolean allowGithubWebHookPermission = false
//Grant READ permissions for /cc.xml
boolean allowCcTrayPermission = false
//Grant READ permissions for Anonymous Users
boolean allowAnonymousReadPermission = false
//Grant ViewStatus permissions for Anonymous Users
boolean allowAnonymousJobStatusPermission = false

AuthorizationStrategy github_authorization = new GithubAuthorizationStrategy(adminUserNames,
    authenticatedUserReadPermission,
    useRepositoryPermissions,
    authenticatedUserCreateJobPermission,
    organizationNames,
    allowGithubWebHookPermission,
    allowCcTrayPermission,
    allowAnonymousReadPermission,
    allowAnonymousJobStatusPermission)

//check for equality, no need to modify the runtime if no settings changed
if(!github_authorization.equals(Jenkins.instance.getAuthorizationStrategy())) {
    Jenkins.instance.setAuthorizationStrategy(github_authorization)
    Jenkins.instance.save()
}

Open Tickets (bugs and feature requests)

Release notes

Version 0.22.2 (Released July 25, 2015)

  • The wiki page was having issues rendering plugin information. Unless I renamed it back (tracked by JENKINS-29636). I renamed the wiki page back to "Github OAuth Plugin" so plugin info would be rendered. I released 0.22.2 to revert release 0.22.1.

Version 0.22.1 (Released July 25, 2015)

  • I renamed the wiki page to "Github Authentication Plugin" which caused the plugin to disappear from the update center (tracked by JENKINS-29636). I released the plugin with the new wiki link.

Version 0.22 (Released July 24, 2015)

  • Bugfix Java 7 compatibility. The plugin now compiles and tests with Java 7 (pull request #42)
  • Scripting feature: equals() method available for idempotent groovy configuration (pull request #43)
  • Allow limited oauth scopes (pull request #45)
  • Allow Jenkins email to be set using GitHub private email (pull request #47)
  • Private GitHub organization memberships can be used for authorization (pull request #48)

Version 0.21.2 (Released July 20, 2015)

Version 0.21.1 (Released July 12, 2015)

Version 0.21 (Released July 11, 2015)

  • Fewer github api calls for performance (pull request #27)
  • Fix for when user enters a badly formed github url for repo (pull request #32)
  • Make Github OAuth scopes configurable in Security Realm of Global Security configuration (pull request #35)
  • Default GitHub OAuth scope is now read:org (pull request #39)
  • Include GitHub teams as groups when doing matrix based authorization strategies (pull request #41)
  • Allow username and GitHub Personal Access Token to be used to access Jenkins API instead of requiring a Jenkins token to be generated (pull request #37)

Version 0.20 (Released Sept 30, 2014)

  • Minor code comments and updated GitHub API dependency.

Version 0.19 (Released July 2, 2014)

Version 0.15 (Released March 21, 2014)

  • Don't attempt to set email address property for a user upon login (pull request #14)
  • Use hasExplicitlyConfiguredAddress instead of getAddress(which scans all projects and builds to find users's email address) (committed directly)
  • Fix API token usage on Jenkins core 1.551 (pull request #18)

Version 0.14 (Released July 11, 2013)

Version 0.12 (Released June 13, 2012)

  • Removed the GitHub V2 API dependency.

Version 0.10 (Released March 4, 2012)

  • Thanks to virtix for reporting a bug with the plugin not working with github enterprise.
  • Note that you also have to upgrade the github-api plugin to version 1.17

Version 0.9 (Released January 8, 2012)

  • Thanks to Kohsuke Kawaguchi for several commits that allow github organizations to be specified using the matrix-based security.

Version 0.8.1 (Released November 1, 2011)

  • Fix the custom XStream Converter to allow the configurations to be saved correctly.

Version 0.8 (Released November 1, 2011)

  • Use custom XStream Converter to let < 0.7 configurations to still work.

Version 0.7 (Released October 29, 2011)

  • Adds support for Github Enterprise/Firewall installs.

Version 0.6 (Released September 17, 2011)

  • Adds checkbox to the AuthorizationStrategy configuration page to enable the anonymous read permission. (default is false: no anonymous reads).

Version 0.5 (Released September 10, 2011)

  • Fixes a problem where all users of the plugin would see a stack trace instead of Jenkins. The regex for detecting the github-webhook url was reworked to support that text appearing anywhere in the request URI.

Version 0.4 (Released September 9, 2011)

  • Thanks to vkravets for testing and contributing a patch to fix the regex so that it actually works for the github-wehook.

Version 0.3 (Released September 8, 2011)

  • Adds support for github-plugin's /github-webhook which can be enabled to allow anonymous READ access to this url. This permits a post commit hook in Github to notify Jenkins to build the related projects.

Version 0.2 (Released July 25, 2011)

  • Fixes serialization issue that prevented plugin from working after Jenkins was restarted.

Version 0.1 (Released July 16, 2011)

Labels

Edit
plugin-user plugin-user Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment