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

View GitHub Authentication on the plugin site for more information.

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
Loading...
Refresh

Release notes

See CHANGELOG.

20 Comments

  1. the new link to creat a application: https://github.com/settings/applications/new

    and where is the plugin help?

  2. github shuts down their api/v2 (https://github.com/blog/1160-github-api-v2-end-of-life). This broke the plugin.

    1. waiting on github-api to rebuild successfully for release (which accomodates for github v3 api), then github-oauth will change it's dependency to that, then it should be good to go :)

      https://jenkins.ci.cloudbees.com/job/plugins/job/github-api/

      kohsuke was working on it while on IRC yesterday, but had to go while it was building and it apparently had a failure. Should be fixed soon, I believe, but hard to say

      1. Thanks for the prompt action.

        1. Oh god, don't thanks me. It was all kohsuke. I'm just the messenger :)

  3. Version 0.12 of the plugin is listed here as the current version, but it is not suggested as an available update in our Jenkins update center. We currently have version 0.11 installed and are running on Jenkins 1.463. Any idea why the update does not appear?

    1. Just looked at the update center again, and the update is available now. Thanks!

  4. Hi, I'm trying to understand how much access checking the "Grant READ permissions for /cc.xml" gives to anonymous users? I want to enable it for CCMenu. However, we've run into problems in the past where we have builds that include code coverage reports that made our whole code base available to anonymous users.

    Thanks!

  5. Hi Devs. This page says "Further instructions are included in the plugin help" - but I can't find this help anywhere within Jenkins or on the net, and I can't find a configuration interface within Jenkins itself. Can someone point me to how I might actually get this plugin up and running? Sounds like it should be straightforward, frustrating not to find anything. Much appreciated.

    Thanks!

  6. Is there any way to give all users in an organization admin access (instead of just read and build)? It is a pain to add tens or hundreds or users to the admin list and keep it updated.

  7. We are getting duplicate users for the same GitHub account when they commit from two different machines. Any ideas? 

    One user has the name field and the other the github username field.

    Check it out here: http://ci.novoda.com/asynchPeople/

  8. Any chance of having Github Commiter Authorization Strategy work with https://wiki.jenkins-ci.org/display/JENKINS/Embeddable+Build+Status+Plugin ?

  9. This morning the Jenkins Plugin Manager page tells me that version 0.16 of this plugin is available (version 0.14 is installed) but warns me as follows:

    "Warning: the new version of this plugin claims to use a different settings format than the installed version. Jobs using this plugin may need to be reconfigured, and/or you may not be able to cleanly revert to the prior version without manually restoring old settings. Consult the plugin release notes for details."

    Where can I find the relevant release notes that give me details of what I need to do?

  10. How does the plugin determine which project/org to use for authz?  Does it use the "GitHub project" setting"  The Git "Repository URL?"

    1. Yes this would be nice to work. Since we're now 2 days after this date:

      Breaking changes coming on February 24

      https://developer.github.com/changes/2015-01-07-prepare-for-organization-permissions-changes/

      1. We just installed this and it still works.

        Please note that the restriction mentioned in the Readme above is INCORRECT:

        "You have to be a public member of the organization for the authorization to work correctly."

        It works fine with private membership.

        Also the documentation says that you should add an Application under:  https://github.com/settings/applications/new

        However if you're going to use this with a github organization you should add the application under https://github.com/organizations/ORGANIZATION/settings/applications/new

        Also, if you get a 404 when trying to login because the callback URL is not working in the browser. Make sure your firewall is open towards the clients trying to login (as well as to github ofcourse). Or simply put the internal IP/DNS name of your Jenkins server in the Github callback URL.

  11. Hi, Is there any option in this plug in to allow non-admin users(logged in, anonymous or any non-admins) to create\update\delete credentials? In 'matrix based authorization' we have role based access, same way, do we have any option here or can i add matrix based auth along with my git hub auth ? Currently we are using github Oauth and credentials are accessable only to the 'admins'. Our requirement is to keep it open for all so anybody can create their own domain\credentials so others can use it in jobs without seeing the password.

  12. I'm trying to get teams to work, but when I add a team in the format: organisation*team it does a strikethrough of the name.
    Am I missing something in the documentation?
    Using username or organisation works great, but using teams would take a considerable amount of user management off our hands.

     

    1. I was seeing a strikethrough before the latest LTS release. Now I see the following:

      org.kohsuke.github.GHException: Failed to retrieve https://git.mydomain.com/api/v3/orgs/myorg/myteam

      It's just odd because the members of that team does appear to be provisioned access, just the ui is showing that some API call failed. It's not very intuitive of an error for a user, especially when the error didn't prevent the access being provisioned.