Jenkins : GitHub OAuth Plugin

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

View GitHub Authentication on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

On this page:

Setup

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

  1. Visit https://github.com/settings/applications/new to create a GitHub application registration.
  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 https://jenkins.example.com/securityRealm/finishLogin where jenkins.example.com is the location of the Jenkins server.

    The important part of the callback URL is /securityRealm/finishLogin

  4. Finish 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.example.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 (question) next to it. Click on it for help about the setting.

Authorization in Global Security.

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

It is highly recommended that you 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 Committer Authorization Strategy

Control user authorization using the Github Committer 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 the 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 will still need to run the GitHub Plugin to have the message trigger the build.

Logged-in users can do anything

There are a few ways to configure the plugin so that everyone on your team has Overall/Administer access.

  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-based 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 Job/Discover and Job/ViewStatus.
  • authenticated - is anyone who has logged in. You can configure permissions for anybody who has logged into Jenkins. Recommended permissions are Overall/Read and View/Read.

    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.
  • 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 https://jenkins.example.com/job/_jervis_generator/build --user "samrocketman:myGitHubPersonalAccessToken" --data-urlencode json='{"parameter": [{"name":"project", "value":"samrocketman/jervis"}]}'

Automatically configure 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()
}

Automatically configure 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)

Key Summary T Created Updated Due Assignee Reporter P Status Resolution
JENKINS-66302 Prepare GitHub Authentication for core Guava upgrade Improvement Aug 07, 2021 Aug 29, 2021 Sam Gleske Basil Crow Major In Review Unresolved
JENKINS-66292 Jenkins sessions with GitHub OAuth time out quickly, breaking usability Bug Aug 06, 2021 Aug 06, 2021 Sam Gleske Jim Klimov Minor Open Unresolved
JENKINS-66128 Github OAuth plugin should allow disabling rate limit checks Task Jul 13, 2021 Jul 13, 2021 Sam Gleske Brian Saville Major Open Unresolved
JENKINS-65937 Github Committer Authorization Strategy: user repository permissions Bug Jun 20, 2021 Jun 20, 2021 Sam Gleske Samuel Minor Open Unresolved
JENKINS-64162 Github Deprecating OAuth Authorization API Bug Nov 07, 2020 Nov 10, 2020 Sam Gleske Shayne Clausson Critical Open Unresolved
JENKINS-64090 Plugin authorization is not correctly handling case Task Oct 30, 2020 Oct 30, 2020 Sam Gleske Pierre Beitz Major Open Unresolved
JENKINS-63565 Receive HTTP 403 error authenticating with Github personal token Bug Aug 31, 2020 Oct 22, 2020 Sam Gleske Lyndon Washington Blocker Open Unresolved
JENKINS-63421 Agent/Connect and other Agent permissions New Feature Aug 18, 2020 Jul 01, 2021 Andreas Nygard Andreas Nygard Major In Progress Unresolved
JENKINS-63051 Child teams should inherit rights granted to parent group Improvement Jul 13, 2020 Oct 28, 2020 Sam Gleske Clover BT Minor Open Unresolved
JENKINS-61963 Authenticate github pull requester and trigger the build as him/her New Feature Apr 18, 2020 Jun 04, 2020 Kanstantsin Shautsou Michael Who Minor Open Unresolved
JENKINS-60767 Make configurable call to authorize service New Feature Jan 14, 2020 Jan 14, 2020 Sam Gleske Seweryn Habdank-Wojewodzki Major Open Unresolved
JENKINS-60472 Jenkins authentication with GitHub not working Bug Dec 13, 2019 Dec 13, 2019 Unassigned giby Alex Major Open Unresolved
JENKINS-60200 More control over cache Improvement Nov 18, 2019 Nov 18, 2019 Sam Gleske poh koh Minor Open Unresolved
JENKINS-59372 Support cctray-xml plugin Story Sep 13, 2019 Sep 13, 2019 Sam Gleske Chris Griego Minor Open Unresolved
JENKINS-58479 Failing to retrieve teams Bug Jul 12, 2019 Aug 26, 2019 Sam Gleske Kote Mushegiani Blocker Open Unresolved
JENKINS-52528 Update github-api plugin from 1.77 to 1.93 Bug Jul 12, 2018 Aug 10, 2019 Sam Gleske Duncan Mak Minor Open Unresolved
JENKINS-52382 Can't stop / cancel private repository builds Bug Jul 05, 2018 Aug 06, 2019 Sam Gleske Clement Gautier Major Open Unresolved
JENKINS-52218 Creating a Multibranch pipeline job as an authenticated user via GitHub Committer Authorization Strategy results in error Bug Jun 27, 2018 Jun 27, 2018 Sam Gleske steve bussetti Major Open Unresolved
JENKINS-50122 Incorrect permissions with non Multibranch based Pipeline jobs Bug Mar 12, 2018 May 01, 2019 Sam Gleske Brice Figureau Major Open Unresolved
JENKINS-48601 Warn admin if he tries to configure GitHub authorization without authentication Improvement Dec 18, 2017 Dec 19, 2017 Sam Gleske Wadeck Follonier Minor Open Unresolved
Authenticate to retrieve your issues
Showing 20 out of 29 issues

Release notes

See CHANGELOG.