Injecting credentials into Jenkins Pipelines with Aembit

Aembit provides many different deployment options you can use to deploy Aembit Edge Components in your environment. Each of these options provides similar features and functionality; however, the steps for each of these options are specific to the deployment option you select.

This page describes the process to use the Aembit CLI in Jenkins Pipelines (recommended) and Freestyle projects, providing step-by-step instructions for each approach.

Configure Jenkins to authenticate with Aembit using OpenID Connect (OIDC) tokens, enabling secure access to your infrastructure without managing static credentials in your CI/CD pipelines.

This configuration allows Jenkins jobs to obtain temporary credentials from Aembit using OIDC tokens that Jenkins issues. The process eliminates the need to store long-lived secrets in Jenkins, improving your security posture.

Prerequisites

Before you begin, ensure you have:

• Jenkins installation with administrator access
• Aembit Tenant with the following items configured:
  • OIDC ID Token Trust Provider and associated Client Workload
  • Access Policy with the OIDC ID Token Trust Provider and Client Workload configured

Set up Aembit OIDC ID Token Trust Provider

Configure Aembit to trust tokens issued by your Jenkins instance:

1. Log in to your Aembit Tenant.

2. Go to Trust Providers in the left nav menu.

3. Click + New. This displays the Trust Provider form.

4. Give the Trust Provider a Name and optional Description.

5. Select OIDC ID Token as the TRUST PROVIDER.

6. Configure the following Match Rules to validate incoming tokens by clicking + New Rule:

   • aud - Enter the Audience value you configured in the Jenkins credential.
   • iss - Enter the Issuer value, which should match your Jenkins base URL, such as: https://jenkins.my-company.com/oidc.
   • sub - Optionally specify patterns to match specific jobs or leave blank to accept any subject. The subject claim in Jenkins OIDC tokens typically contains job information, allowing for fine-grained access control.

7. For Attestation Method, select OIDC Discovery. This allows Aembit to automatically discover the OIDC configuration from Jenkins. The discovery endpoint URL should be the same as your Issuer URL.

8. Click Save to create the Trust Provider.

   Aembit displays your new Trust Provider in the list, showing its ID and other details.

Configure Access Policy

In the Aembit UI, create or update an Access Policy to use your new Trust Provider.

1. Go to Access Policies and select an existing policy or create a new one.
2. Click Edit to modify the policy.
3. In the Trust Provider section, select the Jenkins OIDC ID Token Trust Provider you just created.
4. Configure the remaining policy settings (Client Workload, Server Workload, Credential Provider) as needed.
5. Save and activate the Access Policy.

Install the Jenkins OIDC plugin

Now switch to the Jenkins Dashboard.

This procedure requires a third-party plugin to issue OIDC tokens.

1. In the Jenkins UI, go to Manage Jenkins -> Plugins.

2. Select the Available plugins tab.

3. Search for “OIDC Provider” and install the plugin from this URL: https://plugins.jenkins.io/oidc-provider/.

   Tip

   Multiple OIDC-related plugins exist. Ensure you install the “Open ID Connect Provider” plugin specifically, which enables Jenkins to issue its own OIDC tokens. The other common plugin, “OpenID Connect authentication,” typically handles Single Sign-On (SSO) into Jenkins and doesn’t issue tokens.

4. Restart Jenkins when prompted to complete the installation.

Configure Jenkins system settings

The Jenkins base URL is critical for OIDC token verification and you must configure it by following these steps:

1. In the Jenkins UI, go to Manage Jenkins -> System.

2. Locate the Jenkins Location section.

3. Set the Jenkins URL to your actual domain name (for example, https://jenkins.my-company.com/oidc).

   Caution

   Don’t use localhost or 127.0.0.1 as the Jenkins URL. This causes token verification to fail because Aembit can’t reach localhost URLs to retrieve the public keys needed for token validation.

   For Aembit to successfully verify tokens, your Jenkins URL (which the OIDC Provider plugin uses as the default issuer) must be a publicly accessible domain name that Aembit can reach to retrieve public keys from the JWKS endpoint. The plugin’s JWKS endpoint might initially reference localhost:8080, requiring you to replace this with your actual public URL to enable external access.

4. Click Save to apply the changes.

Create OIDC credentials in Jenkins

Jenkins credentials store the configuration needed to issue OIDC tokens for your jobs.

1. In the Jenkins UI, go to Manage Jenkins -> Credentials.

2. Click on the Global domain (or create a new domain if needed).

   Tip

   Use the Global scope for credentials that need to be available to all jobs. Jenkins reserves System scope for internal operations like agent connections.

3. Click Add Credentials to create a new credential.

4. In the credential creation form, configure the following:

   • From the Kind dropdown, select OpenID Connect id token
   • Scope - Select Global to make the credential available to all jobs.
   • Issuer - Leave this field blank to use Jenkins as the token issuer (https://jenkins.aembit.io/oidc) The Jenkins OIDC Provider plugin automatically uses the Jenkins URL configured in system settings as the issuer.
   • Audience - Enter a custom identifier for your use case (for example, aembit-jenkins-prod).
   • ID - Leave this field blank to let Jenkins generate a unique ID. Jenkins uses this ID internally.
   • Description - Enter a descriptive name (this serves as the credential’s display name). This is important for the credential to appear in job dropdowns.

   Caution

   If you fill in the Default Issuer URI field, Jenkins won’t include this credential in its public key manifest, causing token verification to fail. Leave this field blank unless you’re using an external OIDC provider.

5. Click OK to save the credential.

   Jenkins displays your new credential in the credentials list and you can reference it in Jenkins jobs.

6. Record the ID of the credential you just created. You will use this ID in your Jenkins job configuration to reference the OIDC credential.

   Note

   The ID is a unique identifier for the credential, which you will use in your Jenkins job configurations. You can find this ID in the credentials list or by clicking on the credential to view its details.

Create a test Jenkins job

Return to the Jenkins UI to verify your configuration by creating a sample job that uses the OIDC credential.

This method injects the OIDC token into a Jenkins job environment variable for use by the Aembit CLI.

Pipeline

1. In Jenkins, click New Item.

2. Enter a job name and select Pipeline.

3. Click OK to create the job.

4. In the job configuration page, scroll to the Pipeline section.

5. Select Pipeline script as the Definition.

6. In the Script text area, paste the following pipeline code, making sure to replace the placeholder values with your actual Aembit configuration values:

   pipeline {
       agent any
   
       environment {
           // Set Aembit Agent CLI version
           AEMBIT_AGENT_VERSION = '1.24.3328'
   
           // Replace with your actual values from Aembit
           EDGE_SDK_CLIENT_ID = '<yourEdgeSdkClientId>'
           SERVER_WORKLOAD_HOST = '<yourServerWorkloadHost>'
           SERVER_WORKLOAD_PORT = '<yourServerWorkloadPort>'
       }
   
       stages {
           stage('Download Aembit CLI') {
               steps {
                   script {
                       // Download and extract Aembit Agent CLI
                       sh '''
                           echo "Downloading Aembit Agent CLI version ${AEMBIT_AGENT_VERSION}..."
                           curl -O "https://releases.aembit.io/agent/${AEMBIT_AGENT_VERSION}/linux/amd64/aembit_agent_cli_linux_amd64_${AEMBIT_AGENT_VERSION}.tar.gz"
   
                           echo "Extracting CLI..."
                           tar xf "aembit_agent_cli_linux_amd64_${AEMBIT_AGENT_VERSION}.tar.gz"
   
                           echo "Making CLI executable..."
                           chmod +x "aembit"
   
                           echo "CLI download complete"
                       '''
                   }
               }
           }
   
           stage('Get Aembit Credentials') {
               steps {
                   withCredentials([string(credentialsId: '<your-oidc-credential-id>', variable: 'OIDC_TOKEN')]) {
                       script {
                           sh '''
                               echo "Retrieving credentials from Aembit..."
   
                               # Capture the Aembit CLI output and evaluate it
                               AEMBIT_OUTPUT=$(./aembit credentials get \
                                   --client-id "${EDGE_SDK_CLIENT_ID}" \
                                   --server-workload-host "${SERVER_WORKLOAD_HOST}" \
                                   --server-workload-port "${SERVER_WORKLOAD_PORT}" \
                                   --log-level=debug \
                                   --id-token "${OIDC_TOKEN}")
   
                               echo "Aembit CLI output:"
                               echo "$AEMBIT_OUTPUT"
   
                                # Evaluate the export commands to set environment variables
                               eval "$AEMBIT_OUTPUT"
   
                               # Write credentials to a file that can be sourced in later stages
                               echo "$AEMBIT_OUTPUT" > aembit_credentials.env
   
                               echo "Successfully retrieved credentials from Aembit"
                           '''
                       }
                   }
               }
           }
   
           stage('Use Retrieved Credentials') {
               steps {
                   script {
                       sh '''#!/bin/bash
                           # Source the credentials from the previous stage
                           source aembit_credentials.env
   
                           echo "Using retrieved credentials for authenticated operations..."
                           echo "Available credential variables:"
                           env | grep -E '^(TOKEN|ACCESS_TOKEN|API_KEY)' || echo "No standard credential variables found"
   
                           # Example: Use with curl
                           # curl -H "Authorization: Bearer $TOKEN" https://api.example.com/data
   
                           # Example: Use with your application
                           # ./your-application --token="$TOKEN"
   
                           echo "Authenticated operations completed successfully"
                       '''
                   }
               }
           }
       }
   
       post {
           always {
               // Clean up downloaded files
               sh '''
                   echo "Cleaning up downloaded files..."
                   rm -f aembit_agent_cli_linux_amd64_*.tar.gz
                   rm -rf aembit_agent_cli_linux_amd64_*
               '''
           }
           success {
               echo 'Pipeline completed successfully!'
           }
           failure {
               echo 'Pipeline failed. Check the logs for details.'
           }
       }
   }

   Caution

   Replace 'your-oidc-credential-id' with the actual ID of the OIDC credential you created earlier. You can find this ID in the Jenkins credentials page.

   File-based credential sharing

   This pipeline uses a file-based approach (aembit_credentials.env) to share dynamic credentials between stages.

   In Jenkins Pipelines, environment variables set in one stage don’t automatically carry over to other stages because each stage runs in a separate shell session. Writing credentials to a file and sourcing it in subsequent stages is the most reliable method for sharing dynamic credentials between pipeline stages and is considered a best practice.

7. Click Save.

   Jenkins takes you to the job’s main page, where you can see the configuration summary.

Freestyle Project

1. In Jenkins, click New Item.

2. Enter a job name and select Freestyle project.

3. Click OK to create the job.

4. In the job configuration page, scroll to the Build Environment section.

5. Check Use secret text or file.

6. Click Add -> Secret text.

7. Configure the secret text binding:

8. In the Environment section, check Use secret text(s) or file(s), and enter the following:

   • Variable - Enter OIDC_TOKEN (or your preferred environment variable name).
   • Credentials: Select Specific credentials and choose the OIDC credential you created earlier. This sets up the OIDC discovery URL for the Aembit CLI to use.

9. In the Build Steps section, click Add build step, and select the appropriate execution method:

   • Execute shell (Linux/macOS)
   • Execute Windows batch command (Windows)

10. Add commands to download and use the Aembit CLI:

    #!/bin/bash
    # Set Aembit Agent CLI version
    AEMBIT_AGENT_VERSION=1.24.3328
    # Download Aembit Agent CLI from official releases
    curl -O "https://releases.aembit.io/agent/$AEMBIT_AGENT_VERSION/linux/amd64/aembit_agent_cli_linux_amd64_$AEMBIT_AGENT_VERSION.tar.gz"
    tar xf "aembit_agent_cli_linux_amd64_$AEMBIT_AGENT_VERSION.tar.gz"
    cd "aembit_agent_cli_linux_amd64_$AEMBIT_AGENT_VERSION"
    
    # Base64 encode the OIDC token for debugging (optional)
    echo $OIDC_TOKEN | base64
    
    # Use the OIDC token to get credentials from Aembit
    ./aembit credentials get \
      --client-id aembit:qa:bc74ee:identity:oidc_id_token:468ffc01-4306-48ad-97cc-7a4e1a10c945 \
      --server-workload-host graph.microsoft.com \
      --server-workload-port 443 \
      --log-level=info \
      --id-token $OIDC_TOKEN
    
    # Example: Use the retrieved credentials
    echo "Successfully retrieved credentials"
    # Your application logic would use these credentials here
    # For example, making an authenticated API call

11. Save the job configuration.

    Jenkins takes you to the job’s main page, where you can see the configuration summary.

Run and verify the job

Now that you’ve configured the Jenkins job, you can run it to verify that it retrieves credentials from Aembit using the OIDC token.

To run and verify the job, follow these steps:

1. On the job’s main page, click Build Now to trigger a build.

2. Wait for the build to complete. You can monitor the build progress in the Build History section.

3. Click on the build number to view the build details.

4. In the build details, click on Console Output to see the job’s execution log.

   The console output should show the following:

   • The Aembit Agent CLI downloading successfully
   • The OIDC token being retrieved and used
   • The Aembit CLI successfully authenticating using the OIDC token
   • Credentials being retrieved as expected

   If you see these messages, your Jenkins job is correctly configured to use Aembit OIDC authentication. The output should look similar to the following example console output:

   Started by user Jenkins Admin
   Running as SYSTEM
   Agent default-zdbrp is provisioned from template default
   ---
   ...
   ... omitted for brevity ...
   ...
   2025-07-29T00:03:03.912925Z INFO aembit_assessment::gather Detected AWS platform.
   2025-07-29T00:03:03.913054Z INFO aembit_assessment::gather Getting AWS EC2 metadata.
   2025-07-29T00:03:03.913058Z INFO aembit_assessment::aws Getting AWS EC2 assessment.
   2025-07-29T00:03:04.210428Z INFO aembit_controlplane::commands Received credentials for access policy. Context ID: c8fe6a20-cb6c-4bd6-b1eb-2cdd9b87bd76.
   export TOKEN=my_secure_api_key_abc123xyz789
   Successfully retrieved credentials
   Finished: SUCCESS

   You’ll know the job is successful if you see the export TOKEN=<your_secret_here> line in the output, indicating that the Aembit CLI successfully retrieved credentials using the OIDC token.

Troubleshooting common issues

Token verification failures

Problem - Aembit reports that it can’t verify the OIDC token.

Possible causes and solutions:

• Jenkins URL is localhost - Update your Jenkins base URL to use a publicly accessible domain name. Even when the Jenkins instance is public, the plugin’s JWKS endpoint might initially reference localhost:8080, which needs to be replaced with your actual public URL for Aembit to reach it.
• Default Issuer URI has content - Leave the Default Issuer URI blank in the Jenkins credential configuration.
• Discovery endpoint unreachable - Verify that https://your-jenkins-url/.well-known/openid_configuration provides access from the internet.

Missing public keys

Problem - Aembit can’t retrieve public keys to verify tokens.

Solution - Check that your Jenkins instance exposes the JWKS (JSON Web Key Set) endpoint at:

https://your-jenkins-url/.well-known/jwks.json

This endpoint should return a JSON object containing the public keys used to sign OIDC tokens.

Credential not appearing in dropdown

This only applies to Jenkins Freestyle projects.

Problem - Your OIDC credential doesn’t appear in the job’s credential selection dropdown.

Solution - Ensure you provided a Description when creating the credential. Jenkins uses the description as the display name, and credentials without descriptions may not appear in selection lists.

Deployment considerations

Standard Jenkins installations

For traditional Jenkins installations, apply the configuration steps listed earlier directly.

Ensure your Jenkins instance provides access from the internet for OIDC discovery to work correctly.

Generic nature of the OpenID Connect Provider plugin

The Jenkins OIDC Provider plugin operates generically. The resulting JSON Web Token (JWT) functions consistently whether you deploy Jenkins as a VM or otherwise, or if the token originates from other providers like GitHub or GitLab. This highlights the broad applicability of the generated tokens and the standard implementation of the plugin.

Understanding terminology

The integration involves multiple identifiers that serve different purposes:

• OIDC Client ID - The identifier for the Jenkins credential (configured in the credential’s audience field)
• Client Workload ID - The Aembit identifier for the requesting application (used in CLI commands)
• Edge SDK Client ID - The identifier from your OIDC Trust Provider in your Aembit Tenant (used in CLI commands)

These are distinct values that serve different parts of the authentication flow.

Next steps

With Jenkins and Aembit OIDC integration configured, you can:

• Set up additional CI/CD integrations
• Configure multiple credential providers for complex workflows
• Implement access conditions for enhanced security