{"id":15045322,"url":"https://github.com/jenkinsci/github-oauth-plugin","last_synced_at":"2025-05-16T11:04:58.904Z","repository":{"id":546495,"uuid":"2027943","full_name":"jenkinsci/github-oauth-plugin","owner":"jenkinsci","description":"Jenkins authentication plugin using GitHub OAuth as the source.","archived":false,"fork":false,"pushed_at":"2025-05-01T09:23:25.000Z","size":816,"stargazers_count":102,"open_issues_count":7,"forks_count":165,"subscribers_count":103,"default_branch":"master","last_synced_at":"2025-05-01T10:26:31.737Z","etag":null,"topics":["github","github-oauth","jenkins","oauth","security"],"latest_commit_sha":null,"homepage":"https://plugins.jenkins.io/github-oauth/","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2011-07-11T00:49:27.000Z","updated_at":"2025-05-01T09:23:22.000Z","dependencies_parsed_at":"2023-10-01T21:13:41.661Z","dependency_job_id":"72f04bb2-5e09-49ce-8f72-99c3f1360857","html_url":"https://github.com/jenkinsci/github-oauth-plugin","commit_stats":{"total_commits":480,"total_committers":68,"mean_commits":"7.0588235294117645","dds":0.80625,"last_synced_commit":"a4f60bda0e493fce48d4545732992b0717c632c2"},"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fgithub-oauth-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fgithub-oauth-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fgithub-oauth-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fgithub-oauth-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/github-oauth-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254518384,"owners_count":22084374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","github-oauth","jenkins","oauth","security"],"created_at":"2024-09-24T20:51:43.909Z","updated_at":"2025-05-16T11:04:53.884Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","readme":"# Jenkins GitHub OAuth Plugin\n\n* License: [MIT Licensed](LICENSE.txt)\n* Read more: [GitHub OAuth Plugin wiki page][wiki]\n* Latest build: [![Build Status][build-image]][build-link]\n* [Contributions are welcome](CONTRIBUTING.md).\n\n# Overview\n\nThe GitHub Authentication plugin provides a means of securing a Jenkins instance by\noffloading authentication and authorization to GitHub.  The plugin authenticates\nby using a [GitHub OAuth Application][github-wiki-oauth].  It can use multiple\nauthorization strategies for authorizing users.  GitHub users are surfaced as\nJenkins users for authorization.  GitHub organizations and teams are surfaced as\nJenkins groups for authorization.  This plugin supports GitHub Enterprise.\n\n## Setup\n\nBefore configuring the plugin you must create a GitHub application\nregistration.\n\n1.  Visit \u003chttps://github.com/settings/applications/new\u003e to create a\n    GitHub application registration.\n2.  The values for application name, homepage URL, or application\n    description don't matter. They can be customized however desired.\n3.  However, the authorization callback URL takes a specific value. It\n    must be `https://jenkins.example.com/securityRealm/finishLogin`\n    where jenkins.example.com is the location of the Jenkins server.\n\n    The important part of the callback URL is\n    `/securityRealm/finishLogin`\n\n4.  Finish by clicking *Register application*.\n\nThe *Client ID* and the *Client Secret* will be used to configure the\nJenkins Security Realm. Keep the page open to the application\nregistration so this information can be copied to your Jenkins\nconfiguration.\n\n#### Security Realm in Global Security\n\nThe security realm in Jenkins controls authentication (i.e. you are who\nyou say you are). The GitHub Authentication Plugin provides a security\nrealm to authenticate Jenkins users via GitHub OAuth.\n\n1.  In the Global Security configuration choose the Security Realm to be\n    **GitHub Authentication Plugin**.\n2.  The settings to configure are: GitHub Web URI, GitHub API URI,\n    Client ID, Client Secret, and OAuth Scope(s).\n3.  If you're using GitHub Enterprise then the API URI is\n    \u003chttps://ghe.example.com/api/v3\u003e.\n\n    The GitHub Enterprise API URI ends with `/api/v3`.\n\n4.  The recommended minimum [GitHub OAuth\n    scopes](https://developer.github.com/v3/oauth/#scopes) are\n    `read:org,user:email`.\n\n    The recommended scopes are designed for using both authentication\n    and authorization functions in the plugin. If only authentication is\n    being used then the scope can be further limited to `(no scope)` or\n    `user:email`.\n\nIn the plugin configuration pages each field has a little\n(❓) next to it. Click on it for help about the setting.\n\n#### Authorization in Global Security.\n\nThe authorization configuration in Jenkins controls what your users can\ndo (i.e. read jobs, execute builds, administer permissions, etc.). The\nGitHub OAuth Plugin supports multiple ways of configuring authorization.\n\nIt is highly recommended that you configure the security realm and log\nin via GitHub OAuth before configuring authorization. This way Jenkins\ncan look up and verify users and groups if configuring matrix-based\nauthorization.\n\n##### Github Committer Authorization Strategy\n\nControl user authorization using the **Github Committer Authorization\nStrategy**. This is the simplest authorization strategy to get up and\nrunning. It handles authorization based on the git URL of a job and the\ntype of access a user has to that project (i.e. Admin, Read/Write,\nRead-Only).\n\nThere is a way to authorize the use of the `/github-webhook` callback\nurl to receive post commit hooks from GitHub. This authorization\nstrategy has a checkbox that can allow GitHub POST data to be received.\nYou will still need to run the [GitHub\nPlugin](https://wiki.jenkins-ci.org/display/JENKINS/GitHub+Plugin) to\nhave the message trigger the build.\n\n##### Logged-in users can do anything\n\nThere are a few ways to configure the plugin so that everyone on your\nteam has `Overall/Administer` access.\n\n1.  Choose **Logged-in users can do anything** authorization strategy.\n2.  Choose one of the matrix-based authorization strategies. Set\n    `authenticated` users to `Overall/Administer` permissions. Set\n    `anonymous` users to have `Overall/Read` permissions and perhaps the\n    `ViewStatus` permission.\n\n##### Matrix-based Authorization strategy\n\nControl user authorization using **Matrix-based security** or\n**Project-based Matrix Authorization Strategy**. Project-based Matrix\nAuthorization Strategy allows one to configure authorization globally\nper project and, when using Project-based Matrix Authorization Strategy\nwith the CloudBees folder plugin, per folder.\n\nThere are a few built-in authorizations to consider.\n\n-   `anonymous` - is anyone who has not logged in. Recommended\n    permissions are just `Job/Discover` and `Job/ViewStatus`.\n-   `authenticated` - is anyone who has logged in. You can configure\n    permissions for anybody who has logged into Jenkins. Recommended\n    permissions are `Overall/Read` and `View/Read`.\n\n    `anonymous` and `authenticated` usernames are case sensitive and\n    must be lower case. This is a consideration when configuring\n    authorizations via Groovy. Keep in mind that `anonymous` shows up as\n    *Anonymous* in the Jenkins UI.\n\nYou can configure authorization based on GitHub users, organizations, or\nteams.\n\n-   `username` - give permissions to a specific GitHub username.\n-   `organization` - give permissions to every user that belongs to a\n    specific GitHub organization.\n-   `organization*team` - give permissions to a specific GitHub team of\n    a GitHub organization. Notice that organization and team are\n    separated by an asterisk (`*`).\n\n## Other usage\n\n#### Calling Jenkins API using GitHub Personal Access Tokens\n\nYou can make Jenkins API calls by using a GitHub personal access token.\nOne can still call the Jenkins API by using Jenkins tokens or use the\nJenkins CLI with an SSH key for authentication. However, the GitHub\nOAuth plugin provides another way to call the Jenkins API by allowing\nthe use of a GitHub Personal Access Token.\n\n1.  Generate a [GitHub *Personal Access\n    Token*](https://github.com/settings/tokens) and give it only\n    `read:org` scope.\n2.  Use a username and GitHub personal access token to authenticate with\n    the Jenkins API.\n\nHere's an example using curl to start a build using parameters (username\n`samrocketman` and password using the personal access token).\n\n``` syntaxhighlighter-pre\ncurl -X POST https://jenkins.example.com/job/_jervis_generator/build --user \"samrocketman:myGitHubPersonalAccessToken\" --data-urlencode json='{\"parameter\": [{\"name\":\"project\", \"value\":\"samrocketman/jervis\"}]}'\n```\n\n#### Automatically configure security realm via script console\n\nConfiguration management could be used to configure the security realm\nvia the [Jenkins Script\nConsole](https://wiki.jenkins.io/display/JENKINS/Jenkins+Script+Console).\nHere's a sample configuring plugin version 0.22.\n\n``` syntaxhighlighter-pre\nimport hudson.security.SecurityRealm\nimport org.jenkinsci.plugins.GithubSecurityRealm\nString githubWebUri = 'https://github.com'\nString githubApiUri = 'https://api.github.com'\nString clientID = 'someid'\nString clientSecret = 'somesecret'\nString oauthScopes = 'read:org'\nSecurityRealm github_realm = new GithubSecurityRealm(githubWebUri, githubApiUri, clientID, clientSecret, oauthScopes)\n//check for equality, no need to modify the runtime if no settings changed\nif(!github_realm.equals(Jenkins.instance.getSecurityRealm())) {\n    Jenkins.instance.setSecurityRealm(github_realm)\n    Jenkins.instance.save()\n}\n```\n\n#### Automatically configure authorization strategy via script console\n\nConfiguration management could be used to configure the authorization\nstrategy via the [Jenkins Script\nConsole](https://wiki.jenkins.io/display/JENKINS/Jenkins+Script+Console).\nHere's a sample configuring plugin version 0.22.\n\n``` syntaxhighlighter-pre\nimport org.jenkinsci.plugins.GithubAuthorizationStrategy\nimport hudson.security.AuthorizationStrategy\n\n//permissions are ordered similar to web UI\n//Admin User Names\nString adminUserNames = 'samrocketman'\n//Participant in Organization\nString organizationNames = ''\n//Use Github repository permissions\nboolean useRepositoryPermissions = true\n//Grant READ permissions to all Authenticated Users\nboolean authenticatedUserReadPermission = false\n//Grant CREATE Job permissions to all Authenticated Users\nboolean authenticatedUserCreateJobPermission = false\n//Grant READ permissions for /github-webhook\nboolean allowGithubWebHookPermission = false\n//Grant READ permissions for /cc.xml\nboolean allowCcTrayPermission = false\n//Grant READ permissions for Anonymous Users\nboolean allowAnonymousReadPermission = false\n//Grant ViewStatus permissions for Anonymous Users\nboolean allowAnonymousJobStatusPermission = false\n\nAuthorizationStrategy github_authorization = new GithubAuthorizationStrategy(adminUserNames,\n    authenticatedUserReadPermission,\n    useRepositoryPermissions,\n    authenticatedUserCreateJobPermission,\n    organizationNames,\n    allowGithubWebHookPermission,\n    allowCcTrayPermission,\n    allowAnonymousReadPermission,\n    allowAnonymousJobStatusPermission)\n\n//check for equality, no need to modify the runtime if no settings changed\nif(!github_authorization.equals(Jenkins.instance.getAuthorizationStrategy())) {\n    Jenkins.instance.setAuthorizationStrategy(github_authorization)\n    Jenkins.instance.save()\n}\n```\n\n## Troubleshooting Installation\n\nAfter installing, the `\u003csecurityRealm\u003e` class should have\nbeen updated in your `/var/lib/jenkins/config.xml` file. The value of\n`\u003cclientID\u003e` should agree with what you pasted into the admin UI. If it doesn't\nor you still can't log in, reset to `\u003csecurityRealm\nclass=\"hudson.security.HudsonPrivateSecurityRealm\"\u003e` and restart Jenkins from\nthe command-line.\n\n\n[build-image]: https://ci.jenkins.io/buildStatus/icon?job=Plugins/github-oauth-plugin/master\n[build-link]: https://ci.jenkins.io/job/Plugins/job/github-oauth-plugin/job/master/\n[github-wiki-oauth]: https://developer.github.com/v3/oauth/\n[wiki]: https://wiki.jenkins-ci.org/display/JENKINS/Github+OAuth+Plugin\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fgithub-oauth-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Fgithub-oauth-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fgithub-oauth-plugin/lists"}