LDAP and OIDC Identity Integration

Centralize authentication across your enterprise by integrating Jenkins with directory systems and modern Single Sign-On (SSO) protocols.

What is Identity Integration in Jenkins?

Managing local user accounts directly inside Jenkins is completely unmanageable at scale. LDAP (Lightweight Directory Access Protocol)and OIDC (OpenID Connect) move user administration out of Jenkins entirely by delegating authentication to external corporate identity providers (IdPs).

While LDAP interacts with legacy directory systems (such as Microsoft Active Directory) via direct client queries, OIDC provides a cloud-native authentication layer built on top of OAuth 2.0. This allows users to authenticate seamlessly using modern providers like Okta, Azure AD (Entra ID), Keycloak, or GitHub Enterprise using cryptographically signed JSON Web Tokens (JWTs).

Key Authentication Concepts

Configuration and Pipeline Blueprint

Below is an enterprise example showing how an OIDC security realm is initialized inside a declarative Jenkins Configuration as Code (JCasC) manifest, followed by a pipeline that acts on the authenticated user claims:

1. JCasC Manifest Segment (`jenkins.yaml`)

jenkins:
  securityRealm:
    oic:
      clientId: "jenkins-prod-client-id"
      clientSecret: "\${OIDC_SECRET_VAR}"
      wellKnownOpenIDConfigurationUrl: "https://enterprise.com"
      tokenServerUrl: "https://enterprise.com"
      authorizationServerUrl: "https://enterprise.com"
      userInfoServerUrl: "https://enterprise.com"
      userNameField: "preferred_username"
      groupsField: "roles"

2. Declarative Pipeline Audit Wrapper

pipeline {
    agent any
    stages {
        stage('Identity & Context Audit') {
            steps {
                script {
                    // Extracting details about the user that manually kicked off the build execution
                    def buildCause = currentBuild.rawBuild.getCauses()[0]
                    if (buildCause != null && buildCause.getClass().getName().contains('UserIdCause')) {
                        def runningUser = buildCause.getUserId()
                        echo "Execution triggered by IdP-authenticated user identifier: \${runningUser}"
                    } else {
                        echo "Execution triggered by automated upstream hook or system event."
                    }
                }
            }
        }
    }
}

Identity Integration Exercise

1. Examine Active Configuration Realms: Navigate to Manage Jenkins → Security and look at the options listed under the Security Realm radio selection box.
2. Trace LDAP Attribute Paths: If test directory servers are available, look up the distinction between a User Search Base (`ou=users,dc=company,dc=com`) and a Group Search Base mapping parameter.
3. Simulate OAuth Callback URLs: Identify your controller's absolute root URL path and formulate the standard callback address required by OIDC configuration registration portals: `https://<your-jenkins-url>/securityRealm/finishLogin`.
4. Review the Security Escape Hatch: Locate your backing `config.xml` files inside `JENKINS_HOME` and find the xml section where you can manually restore the fallback security realm definition in the event of an identity network outage.