A Jenkins plugin which lets you login to Jenkins using your own, self-hosted or public openid connect server.
OpenID Connect is an authentication and authorization protocol that allow users to use single sign-on (SSO) to access an application (Jenkins in this case) using Identity Providers. In practice, with this plugin, Jenkins administrators can configure a provider which will authenticate users, provide basic information (email, username, groups) and let Jenkins grant rights accordingly.
After installing the plugin, the Jenkins administrator can choose "OpenID Connect" as Security Realm. The configuration involves the configuration of the provider and the related authorisation strategy.
Configurations for specific providers are documented:
OpenID Connect Authentication plugin is installed as other plugins:
- either using Jenkins plugin management from the web UI or the command line
- or using Jenkins Configuration as Code (JCasC)
In either case, choosing the plugin as Security Realm means that other authentication methods (Jenkins Database, LDAP, ...) will no longer be available and any misconfiguration or service availability issue will lock out the users. An escape hatch can be activated at configuration time to define a admin credential which can be used to recover access to Jenkins.
Configuration of this plugin takes a bit of effort as it requires some knowledge of the openid connect standard as well as the non-standard configuration of the various identity providers out there. Should you configure this plugin against a identity provider then please share your experiences and found caveats through a blog post or by adding it to the documentation.
In a nutshell, the configuration is done in three steps:
- Register Jenkins as an OIDC client in your provide. You will need these details:
- Login Redirect URI:
${JENKINS_ROOT_URL}/securityRealm/finishLogin - Logout Redirect URI:
${JENKINS_ROOT_URL}/OicLogout - scope: openid profile email
- Grant Type:
authorization_code - Response Types:
code, token, id_token
- Login Redirect URI:
- Generate Client ID and secret which are needed in plugin configuration
- Configure plugin with providers endpoints, security features and specific configuration.
Normally, providers expose .well-known/openid-configuration which has all the details client need to know.
Detailed instructions for Generic OpenID Connect configuration are provided in the documentation. Some HOWTO are provided for the various aspects of the configuration.
See the following screenshot utilizing the google well known endpoint for a minimal configuration example:
All of the fields can be configured as a JMES Path specification. Most of the time, the name of the field in the idtoken or userinfo is enough.
TLDR: use an API token instead as described here: Authenticating scripted clients
Using basic auth for authentication won't work. This is because jenkins has no knowledge of the password due to the way openid connect works: Identifying a user is a three way interaction between the user, Jenkins and the openid provider.
The plugin asks the configured openid provider to confirm the identity of the user is and does this in a way that both Jenkins and the provider are 'talking' about the same user. The openid connect provider will likely challenge the user to prove it's identity and might do this by requesting a username and password but this is entirely up to the provider. This part is between the user and the openid connect provider, Jenkins (using this plugin) delegates proving ones identity to the provider and will go with whatever conclusion the provider draws. This has the benefit that with openid connect the service your trying to access (in our case Jenkins) never sees a user password, so even if Jenkins is compromised an attacker can't intercept passwords or other secrets. Using basic auth would require one to send their password to Jenkins which would defeat this.
Scripted clients can still interact with Jenkins even when the openid connect plugin is active: they will have to use an API token. Authenticating scripted clients describes how to obtain one.
This plugin relies on the users and people of goodwill to improve and make the plugin evolve in the most useful way. All feedbacks and help are welcome. We can provide help and support but it is limited to the fair use of volunteers' free time.
GitHub issues is our main communication channel for issues and feature request. We will look at issues entered through Jenkins Jira but the response time may currently be spotty at best.
Before adding an issue, please search for any relevant entry in the FAQ or if the same issue has already be reported and avoid duplicating it. If it is a new issue and it not purely related to your environment, please provide relevant information (such as the version of Jenkins and the plugin).
If an issue or a feature request is unclear, it will be tagged with Need more info label. Without answer after a month, the issue will be closed.
Changelog file has been removed and CHANGELOG content can be review in the GitHub release panel of the plugin's repository. They also available in the Jenkins plugin panel.
Contributions are welcome, we are looking for:
- developers to implement the features, improve the code and whatever hackers do for a living
- anybody wanting to help sorting the issues, improve, translate document, participate in pull request review or test before release
- just anybody who wants to drop by and take an interest
Please refer to the separate CONTRIBUTING document for details on how to proceed!