Plugin Information View Azure AD 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:
Setup In Azure Active Directory
Make sure your Jenkins server has enabled HTTPS. If your Jenkins instance is created by the Jenkins Solution Template, you can update your NGINX config file at /etc/nginx/sites-available/default. More configuration details can be found here.
Open Azure Active Directory, in
Properties
, copy Directory ID, it will be used astenant
in Jenkins.- Register an application in AAD, copy the
Application ID
, it will be used asClient ID.
- In Application setting page, add a Reply URL https://{your_jenkins_host}/securityRealm/finishLogin. Make the variable jenkinsURL set as https://{your_jenkins_host} for the file jenkins.model.JenkinsLocationConfiguration.xml in the $JENKINS_HOME folder.
- In Application setting page, click
Keys
, generate a new key, copy thevalue
, it will be used asClient Secret
in Jenkins. - To configure Azure Active Directory Matrix-based security, you have to add your user/group value with pattern userName|groupName (principalName). The pattern userName|groupName (objectId) still works to make compatible with previous versions.Below two steps are optional since version 1.0.0. Without these steps:
- You are not able to have autocompletion when adding user/group in Azure Active Directory Matrix.
- You do not have the same privileges as the groups you belonged to.
- In Application setting page, click
Required Permissions
and selectWindows Azure Active Directory
, then selectRead directory data
permissions in Application permissions section. - Click
Grant Permissions
. If you are not an admin in your tenant, please contact admin to grant the permissions which declared asrequire admin
inEnable Access
page. Wait for the permissions taking effects.
Setup In Jenkins
Click Manage Jenkins
in the left menu, then click Configure Global Security
, check Enable security
Enable Azure Authentication
To enable Azure Authentication, check Azure Active Directory
and fill in the credential.
Click Verify Application
to make sure your input is valid.
Enable Azure Authorization
To enable Azure Authentication, check Azure Active Directory Matrix-based security
Version 1.0.0 Migration Instruction
In version 1.0.0, this plugin upgrades from Microsoft identity platform v1.0 to v2.0. Before you upgrade ad plugin to version 1.0.0, please read following items first.
- Make sure your Jenkins server has enabled HTTPS. Microsoft identity platform v2.0 forces using HTTPS schema in reply uri for its applications. Please update the reply uri for your AAD application. You also need to update the url setting in `jenkins.model.JenkinsLocationConfiguration.xml` file and restart your Jenkins instance. If your Jenkins instance is created by the Jenkins Solution Template, you can update your NGINX config file at /etc/nginx/sites-available/default. More configuration details can be found here.
- Go to your related AAD application, click `Manifest` to open the inline manifest editor. Replace the `optionalClaims` value as below. You can find more information about this.
"optionalClaims": { "idToken": [ { "name": "family_name", "essential": false }, { "name": "given_name", "essential": false }, { "name": "upn", "essential": false } ] },
Q: How to recovery if Jenkins keeps failing during the login phase?FAQ
A: You can disable the security from the config file (see https://wiki.jenkins.io/display/JENKINS/Disable+security)
Q: Why getting a error "insufficient privileges to complete the operation" even having granted the permission?
A: It takes rather long time for the privileges to take effect, which could be 10-20 minutes. So just wait for a while and try again.
Change Log
1.0.0 (2019-05-30)
This release includes breaking changes for Azure Identity platform, please follow up wiki to migrate.
- Bump Jenkins version to 2.138.3
- Upgrade Microsoft identity platform from v1.0 to v2.0
- Add support for configuration as code
- Admin permission for tenant is no more necessary
- Jenkins server must enable HTTPS
0.3.4 (2019-04-30)
0.3.3 (2019-04-11)
- Support named groups and users
0.3.2 (2019-01-18)
- Fix seed authentication issue
0.3.1 (2018-09-19)
- Upgrade Azure commons to 0.2.7
- Use UPN as Jenkins user id
0.3.0 (2018-02-09)
Jenkins under version 2.60 is not supported any more!
- Upgrade the dependency of matrix-auth to 2.2
0.2.0 (2018-01-18)
- Support project-based authorization
- Improve security
0.1.1 (2017-12-07)
- Fixed the CSRF protection issue.
0.1.0 (2017-12-01)
- Initial release
12 Comments
Unknown User (fatal_exception)
Thanks for the awesome plugin! Are there any instructions on how to do the Azure Active Directory App Registration setup using Azure CLI? We would like to automate this end-to-end, but docs on how to grant the required permissions to a registered app, seem to be absent on the Azure side
Cheers
Unknown User (badalk)
I have documented the complete steps in my blog http://cloud.badalkotecha.com/2018/09/jenkins-role-based-access-control-rbac-with-azure-ad-step-by-step.html
Unknown User (jieshe)
You can check this doc for Azure CLI commands to manage Azure Active Directory. Commands az ad app create and az ad app update may be suitable for your case.
Unknown User (tonydeck)
Dear All,
does anyone know whether there has some way out that if we cannot do step 6 due that we do not find the right team/person as admin? I found that most of the apps integrate with AAD do not need 'Read directory data' privilege.
any reply are highly appreciated.
Tony
Unknown User (jieshe)
For now, you cannot skip the step. I will investigate whether we can use it without the privilege in next version.
Unknown User (tonydeck)
Hi, Jie Shen,
Thanks. We just need do authentication with AAD. "Sign in and read user profile" and "Read all users' basic profiles" privileges might be enough. These 2 privileges are already delegated to the application owners.
Just in case you need.
thanks in advance.
Tony
Unknown User (oletolshave)
Hello and thanks for a great plugin!
I have been using this plugin without any issues for about 2 months. Yesterday without any changes I can no longer log on at all to Jenkins. I can still log on with the same Azure account to both the azure portal and other resources protected by SSO.
I get the jenkins error page and this stakc trace, when I log on using Azure SSO:
Stack trace
...
..
It kind of sounds like certificate has expires, because it just started failing without any changes on my side. Are anybody else seeing this?
/Ole
Unknown User (azure_devops)
thanks for reporting the issue. we'll look at it after back from some national holiday. meanwhile, could you pls try to open an issue at JIRA (https://issues.jenkins-ci.org) with component=azure-ad-plugin for better tracking? thanks.
Unknown User (oletolshave)
Thank you - issue JENKINS-53859 have been created: JENKINS-53859 - Getting issue details... STATUS .
Unknown User (badalk)
I am facing multiple challenges with this plugin when invoking Jenkins API remotely when RBAC is configured with this plugin
Are there ways to get around this?
Badal
Unknown User (jieshe)
Related Jira issue JENKINS-54115 - Getting issue details... STATUS
Unknown User (davegoodine)
The workaround on this issue (adding 2 users to the azure ad matrix) allows me to use jenkins job builder (https://docs.openstack.org/infra/jenkins-job-builder/) with our jenkins master using azure ad plugin.