Configure Azure Active Directory with Jenkins
This article is a short summary of what you need to do in order to enable SSO using Azure Active Directory with Jenkins.
Pre-requisites:
- You need to be an Azure admin or have the admin rights to add the API permissions required for this setup.
- Your Jenkins server has enabled HTTPS
1- Initial Jenkins setup
Go to Manage Jenkins then Manage Jenkins, and find Azure AD plugin. For further details on the plugin, here is the link for the plugin. Once installed, you need to restart your Jenkins.
2- Azure AD setup
- Go to your Azure Portal and select Azure Active Directory, then click on App registrations, then New registration
- Give a name to your application. If you have many Jenkins running, name your Jenkins accordingly (see above) so you can make a difference between the different settings.
- Choose who can use the application. In a private IT environment, you should only allow your AAD (single tenant) tenant to be used.
- Choose Client Application (Web, iOS, ..) and finally register your application.
- In the application page, go to Authentication and add the URI of your Jenkins instance. If your Jenkins URI is internal, just put the internal URI that your internal DNS can resolve.
- Select ID tokens and make sure you have selected a single tenant in the supported account types section.
- Go to API permissions, and add the following permissions:
Azure Active Directory Graph: Directory.Read.All / Delegated
Azure Active Directory Graph: Directory.Read.All / Application
Azure Active Directory Graph: User.Read / Delegated
Microsoft Graph: Directory.Read.All / Delegated
Microsoft Graph: Directory.Read.All / Application
Microsoft Graph: User.Read / Delegated
- Click on Grant admin consent for your company tenant
- Go to Certificates & secrets and generate a new client secret.
Note: the secret is visible only once. Copy it and keep in your notes to finalize the Jenkins setup. In addition to the secret, note the Application ID (Client ID) and Directory ID (Tenant)
Now, your Azure AD is setup.
3- Finalize the Jenkins setup
- Go to your Jenkins, Manage Jenkins, and then Configure Global Security.
- In the Authentication section, choose Azure Active Directory within the Security Realm bloc.
- From the notes above, insert the Client ID, Client Secret, and Tenant. Click on Apply (do not save yet! You can lock yourself if your settings are wrong)
- In order to make sure your settings are fine, in the Authorization section, select Azure Active Directory Matrix-based security, and type a username or group name that exists in your AAD. The user or group should appear in the suggestion list.
- Once you can see Jenkins suggesting the autocompletion, your settings are fine, you can now save.
If you face any issues with the security, you can always go to your config.xml file and disable the security realm by following these steps:
- Stop Jenkins
- Go to $JENKINS_HOME in the file system and open config.xml.
- Look for the false element in this file.
- Replace true with false
- Remove the elements authorizationStrategy and securityRealm
- Start Jenkins
At this step, your Jenkins is in the unsecured mode where everyone gets full access. Fix the issue and enable again the authorizationStrategy and securityRealm.
Thanks for following this guide, and happy Jenkins!