Microsoft Entra ID Plugin (previously Azure Active Directory Plugin)

Important: This plug-in is maintained by the Jenkins community and won’t be supported by Microsoft as of February 29, 2024.

A Jenkins Plugin that supports authentication & authorization via Microsoft Entra ID (previously known as Azure Active Directory).

Setup In Microsoft Entra ID

1. Open Microsoft Entra ID, click App registrations

2. Click New registration

3. Add a new Reply URL https://{your_jenkins_host}/securityRealm/finishLogin. Make sure "Jenkins URL" (Manage Jenkins => Configure System) is set to the same value as https://{your_jenkins_host}.

4. Click Certificates & secrets

   • To use a client secret: Under Client secrets, click New client secret to generate a new key. Copy the value, it will be used as Client Secret in Jenkins.

   • To use a certificate: Under Certificates, click Upload certificate to upload your certificate. This certificate will be used for client certificate authentication in Jenkins. You will need to use the corresponding private key associated with this certificate in PEM format.

5. Click Authentication, under 'Implicit grant and hybrid flows', enable ID tokens.

6. (optional) To enable Microsoft Entra ID group support: Click Manifest and modify the "groupMembershipClaims": null value to "groupMembershipClaims": "SecurityGroup", then 'Save' it.

Setup Microsoft Entra ID permissions (optional, but recommended)

In order for Jenkins to be able to lookup data from Microsoft Entra ID it needs some Graph API permissions.

This is used for:

• Autocompleting users and groups on the 'Security' page
• Jenkins looking up the user, e.g. when you use the Rest API
• Group display name support (rather than just object ID)

Note: You can skip this part and just use the claims returned when authenticating.

1. Click API permissions

2. Add a permission

3. Microsoft Graph

4. Application permissions

5. Add 'User.Read.All', 'Group.Read.All' and 'People.Read.All'

6. Click Grant admin consent. If you are not an admin in your tenant, please contact an admin to grant the permissions.

Setup In Jenkins

Click Manage Jenkins in the left menu, then click Security

Authentication

1. Check Azure Active Directory and fill in the credential.

2. Click Verify Application to make sure your input is valid.

3. Save the configuration, (logged-in users will have permission to do anything)

4. Log in with Microsoft Entra ID

5. Return to 'Security' to configure authorization

Note: if you haven't setup Graph API permissions, verify application will fail, skip over this step

Authorization

Jenkins will match permissions based on the Object ID of a user or group.

This plugin extends the traditional Matrix Authorization Strategy with the ability to search by users / groups by display name when configuring the authorization rules.

To use this feature:

1. Click Azure Active Directory Matrix-based security
2. Search for user in 'Azure User/group to add' and click Add
3. Select the permission(s) in the table
4. Click 'Apply'

You can still use other authorization strategies such as:

• Matrix Authorization Strategy
• Folder-based Authorization Strategy
• Role-based Authorization Strategy

The following can normally be used:

• Object ID of user or group
• Display name of group (Only if Graph API permissions granted)
• preferred_username claim which is normally the 'User principal name', but not always.
• User principal name (Rest API authentication only)

Configuration as Code and Job DSL support

The plugin has full support for use in Configuration as Code and Job DSL.

For an example combining the two, see the configuration-as-code.yml test resource.

FAQ

Q: How to recover if Jenkins keeps failing during the login phase?

A: You can disable the security from the config file (see https://www.jenkins.io/doc/book/security/access-control/disable/)

Q: Why am I getting an error "insufficient privileges to complete the operation" even after having granted the permission?

A: It can take a long time for the privileges to take effect, which could be 10-20 minutes. Just wait for a while and try again.