Skip to content

Latest commit

 

History

History
333 lines (222 loc) · 12.1 KB

azure-ad.adoc

File metadata and controls

333 lines (222 loc) · 12.1 KB
Raw

Azure AD

Configure Azure

Important

We will be using https://cloudbees-core.example.com as the example url for CloudBees Core. Please replace the domain to your actual domain in all the examples!

Steps to execute

We will have to do the following steps on Azure side.

  • create the Azure Active Directory

  • create users / groups

  • create App Registration

  • url: https://cloudbees-core.example.com/cjoc/securityRealm/finishLogin

  • replace example.com with your domain, and change protocol if you’re not using https (https is recommended)

  • update manifest (for groups)

  • change: "groupMembershipClaims": null, (usually line 11)

  • to: "groupMembershipClaims": "SecurityGroup",

  • create SP ID / App ID URI

  • grant admin consent

Note

If you’re going to use the Azure AD plugin, you also create a client secret.

Information To Note Down

The following information will be unique to your installation, so you need to record them as you go along.

  • App ID URI

  • Object ID’s of Users and Groups you want to give rights

  • Federation Metadata Document Endpoint

  • Azure AD → App Registrations → <your app registration> → Endpoints (circular icon on top)

  • you can use either the URL or the document contents

  • make sure the URL contains the Tenant ID of your Azure Active Directory

  • URL example: https://login.microsoftonline.com/${TENANT_ID}/federationmetadata/2007-06/federationmetadata.xml

  • You can find your Tenant ID in Azure Active Directory → Properties → Directory ID (different name, same ID)

Visual Guide

Below will be a visual guide with screenshots.

There will be hints in the screenshots where you should pay attention to.

  • red: this is the main thing

  • orange: this is how we got to the current page/view

  • blue: while you’re in this screen, there might be other things you could do

Create New App Registration

If you have an Azure account, you will have an Azure Active Directory (Azure AD) pre-created.

This guide assumes you have an Azure AD ready to use.

That means, the next step is to create an Application Registration.

azure ad azure new app reg

Give the registration a useful name, select who can authenticate and the redirect URL.

This URL needs to be configured and MUST be the actual URL of your CloudBees Core installation.

azure ad azure new app reg2

App Reg Data

Depending on the plugin you’re going to use (SAML or Azure AD) you need information from your Azure AD / App Registration.

  • Tentant ID

  • Object ID

  • Client ID

  • Federation Metadata Document (you can use the document or the URL, up to you)

azure ad azure data2

Click on the Endpoints button to open the side-bar with the links.

azure ad azure data1

App ID

We need the App ID - even if the SAML plugin doesn’t mention it.

You can let Azure generate one for you, but as CloudBees Core has a nice URL (which is the type required), you can also use that as the application URL, eg

Note

App ID must match in both Azure AD (set as "App ID URI") and the SAML plugin (set as "Entity ID")
azure ad azure app id1

This is the generated API URI. But you can replace it with your installation’s URL. Just remember to note this URI down, we will need this when we configure Jenkins.

azure ad azure app id2

API Permissions

Of course, things wouldn’t be proper IAM/LDAP/AD without giving some permissions.

If we want to retrieve group information and other fields, we need to be able to read the Directory information.

azure ad azure api perm1

The Directory information can be found via the Microsoft Graph api/button.

azure ad azure api perm2

We select Application Permissions and then check Directory.Read.All. We don’t need to write.

azure ad azure api perm3

The Permissions have changed, so we require an Administrator account to consent with the new permissions.

Note

To those working with the CloudBees Azure subscription from PS. No, we as PS cannot consent this.

So either we need someone else to do this for us, or you have to use your own Azure Account’s Azure AD.
azure ad azure api perm4

Update Manifest

As with the permissions, the default Manifest doesn’t give us all the information we want.

We want the groups, so we can configure RBAC, and thus we have to set the groupMembershipsClaims claim attribute.

azure ad azure manifest1

We change the null to "SecurityGroup", please consult the Microsoft docs (see reference below) for other options.

We can download, edit and upload the manifest file. Or, we can edit inline and hit save on top.

azure ad azure manifest2

Retrieve Group Object ID

If we want to assign Azure AD groups to groups or roles in Jenkins' RBAC, we need to use Object ID’s.

Each Group and User will have an Object ID, which should have a handy Copy this button!

azure ad azure group info

Configure Jenkins

Steps

Visual Guide

Below will be a visual guide with screenshots.

There will be hints in the screenshots where you should pay attention to.

  • red: this is the main thing

  • orange: this is how we got to the current page/view

  • blue: while you’re in this screen, there might be other things you could do

Configure Security

To go to Jenkins' security configuration, follow this route:

  • login with the current Admin user

  • go to the Operations Center

  • Manage Jenkins → Global Security Configuration

Configure RBAC

The SAML plugin configuration will pollute the screen with fields.

My advice, enable RBAC first.

If you haven’t got any groups/roles yet, I recommend using the Typical Initial Setup from the dropdown.

azure ad jenkins sec1 config
Important

Make sure you know the credentials of the current admin user.

It will automatically be added to the Administrators group, and it will be your go-to account when you mess up the SAML configuration and you have to reset security.

For how to reset the security configuration, see the For When You Mess Up paragraph.
Configure SAML

Select SAML 2.0 from the Security Realm options.

Here we need to first supply our Federation Metadata Document or it’s URL.

Each has its own Validate …​ button, hit it and confirm it says Success.

azure ad jenkins sec2 config
azure ad jenkins sec5 config
Note

You can leave Displayname empty, which will give you the default naming scheme from Azure AD.

I think this is fugly, as it amounts to something like ${EMAIL_ADDRESS}_${AD_DOMAIN}_${AZURE_CORP_DOMAIN}.

There are other options, I’ve settled for givenname, as it there isn’t a fullname by default, and well, I prefer Joost to some weird long string.

Configure RBAC Groups

Tip

Once Azure AD is configured and it works, you can configure groups for RBAC just as you’re used to.

Both for classic RBAC and Team Masters.

Just make sure you use the Azure AD `Object ID’s of the groups to map them.

Bonus tip, add every Azure AD group to Browsers, so you can directly map their groups to Team Master roles without problems.
azure ad jenkins group config1
azure ad jenkins group config2

XML Config

  <useSecurity>true</useSecurity>
  <authorizationStrategy class="nectar.plugins.rbac.strategy.RoleMatrixAuthorizationStrategyImpl"/>
 <securityRealm class="org.jenkinsci.plugins.saml.SamlSecurityRealm" plugin="[email protected]">
    <displayNameAttributeName>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname</displayNameAttributeName>
    <groupsAttributeName>http://schemas.microsoft.com/ws/2008/06/identity/claims/groups</groupsAttributeName>
    <maximumAuthenticationLifetime>86400</maximumAuthenticationLifetime>
    <emailAttributeName>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</emailAttributeName>
    <usernameCaseConversion>none</usernameCaseConversion>
    <usernameAttributeName>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name</usernameAttributeName>
    <binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect</binding>
    <advancedConfiguration>
      <forceAuthn>false</forceAuthn>
      <spEntityId>https://cloudbees-core.kearos.net</spEntityId>
    </advancedConfiguration>
    <idpMetadataConfiguration>
      <xml></xml>
      <url>https://login.microsoftonline.com/95b46e09-0307-488b-a6fc-1d2717ba9c49/federationmetadata/2007-06/federationmetadata.xml</url>
      <period>5</period>
    </idpMetadataConfiguration>
  </securityRealm>
  <disableRememberMe>false</disableRememberMe>

Logout URL

Depending on the requirements, you may want to specify a logout url in the SAML configuration to log you completely out of SAML, not just Core.

For When You Mess Up

This is the default config for security in Core Modern.

 <useSecurity>true</useSecurity>
  <authorizationStrategy class="hudson.security.FullControlOnceLoggedInAuthorizationStrategy">
    <denyAnonymousReadAccess>true</denyAnonymousReadAccess>
  </authorizationStrategy>
  <securityRealm class="hudson.security.HudsonPrivateSecurityRealm">
    <disableSignup>true</disableSignup>
    <enableCaptcha>false</enableCaptcha>
  </securityRealm>
  <disableRememberMe>false</disableRememberMe>

To rectify a failed configuration, execute the following steps:

  1. exec into the cjoc-0 container: kubectl exec -ti cjoc-0 — bash

  2. open config.xml: ` vi /var/jenkins_home/config.xml`

  3. replace conflicting lines with the above snippet

  4. save the changes

  5. exit the container: exit

  6. kill the pod: kubectl delete po cjoc-0

Tip

For removing a whole line, stay in "normal" mode, and press d d. To add the new lines, go into insert mode by pressing i. Go back to "normal" mode by pressing esc. And then save and quit, by writing: :wq followed by enter.

References

Note

The mapping of the object if to groups within is less than ideal visaually, this is however a limitation of this solution currently. When the Alternative Azure AD Plugin is approved this may provide a more satisfactory solution.