Microsoft Entra ID (previously Azure AD)

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).

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.

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.

Click Manage Jenkins in the left menu, then click Security

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

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)

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.

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

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.