How to retrieve credentials with the Aembit GitHub Action

Retrieve credentials from Aembit in your GitHub Actions workflow using the Aembit GitHub Action.

Prerequisites

Before configuring the action, ensure you have an active Access PolicyAccess Policy: Access Policies define, enforce, and audit access between Client and Server Workloads by cryptographically verifying workload identity and contextual factors rather than relying on static secrets.Learn more linking these components:

• Client WorkloadClient Workload: Client Workloads represent software applications, scripts, or automated processes that initiate access requests to Server Workloads, operating autonomously without direct user interaction.Learn more configured with GitHub OpenID Connect (OIDC) identity
• Trust ProviderTrust Provider: Trust Providers validate Client Workload identities through workload attestation, verifying identity claims from the workload's runtime environment rather than relying on pre-shared secrets.Learn more for GitHub Actions
• Credential ProviderCredential Provider: Credential Providers obtain the specific access credentials—such as API keys, OAuth tokens, or temporary cloud credentials—that Client Workloads need to authenticate to Server Workloads.Learn more matching your credential type
• Server WorkloadServer Workload: Server Workloads represent target services, APIs, databases, or applications that receive and respond to access requests from Client Workloads.Learn more for the target service

Configure the action

Add the Aembit GitHub Action to your workflow with the appropriate configuration for your credential type:

API Key

permissions:
  id-token: write
  contents: read

jobs:
  call-api:
    runs-on: ubuntu-latest
    steps:
      - name: Get API Key from Aembit
        id: aembit
        uses: Aembit/get-credentials@v1
        with:
          client-id: '${{ secrets.AEMBIT_CLIENT_ID }}'
          server-host: 'api.example.com'
          server-port: '443'

      - name: Use the credential
        env:
          API_KEY: ${{ steps.aembit.outputs.api-key }}
        run: |
          curl -H "X-API-Key: $API_KEY" \
            https://api.example.com/endpoint

The action provides the API key as the api-key step output.

OAuth Token

permissions:
  id-token: write
  contents: read

jobs:
  call-api:
    runs-on: ubuntu-latest
    steps:
      - name: Get OAuth Token from Aembit
        id: aembit
        uses: Aembit/get-credentials@v1
        with:
          client-id: '${{ secrets.AEMBIT_CLIENT_ID }}'
          server-host: 'oauth.example.com'
          server-port: '443'

      - name: Use the credential
        env:
          TOKEN: ${{ steps.aembit.outputs.token }}
        run: |
          curl -H "Authorization: Bearer $TOKEN" \
            https://api.example.com/endpoint

For Open Authorization (OAuth) credentials, Aembit handles the token exchange. The action provides the access token as the token step output.

Username/Password

permissions:
  id-token: write
  contents: read

jobs:
  call-api:
    runs-on: ubuntu-latest
    steps:
      - name: Get credentials from Aembit
        id: aembit
        uses: Aembit/get-credentials@v1
        with:
          client-id: '${{ secrets.AEMBIT_CLIENT_ID }}'
          server-host: 'service.example.com'
          server-port: '443'

      - name: Use the credentials
        env:
          USERNAME: ${{ steps.aembit.outputs.username }}
          PASSWORD: ${{ steps.aembit.outputs.password }}
        run: |
          curl -u "$USERNAME:$PASSWORD" \
            https://service.example.com/endpoint

The action provides username/password credentials as the username and password step outputs.

Verify it works

After running your workflow:

1. Check the GitHub Actions logs for successful credential retrieval. A successful run shows output similar to:

   Run Aembit/get-credentials@v1
   Requesting credentials from Aembit...
   ✓ Successfully authenticated with Aembit
   ✓ Credential retrieved for server workload: api.example.com:443
   ✓ Credential available as step output
   ✓ Credential masked in logs

2. In your Aembit TenantAembit Tenant: Aembit Tenants serve as isolated, dedicated environments within Aembit that provide complete separation of administrative domains and security configurations.Learn more, go to Reporting > Access Authorization Events.

3. Look for events matching your Client Workload. Verify the status shows Authorized.

If the action fails, you’ll see error output like:

Run Aembit/get-credentials@v1
Requesting credentials from Aembit...
✗ Authorization failed: Access Policy not matched
  Client ID: abc123...
  Server Workload: api.example.com:443
Error: Unable to retrieve credentials. Check your Access Policy configuration.

Scaling across workflows

Use a reusable workflow pattern to standardize credential retrieval across multiple workflows in your repository.

Reusable workflow pattern

Create a reusable workflow that other workflows can call:

.github/workflows/get-aembit-credentials.yml

name: Get Aembit Credentials

# Allow other workflows to call this workflow
on:
  workflow_call:
    inputs:
      server-host:
        description: 'Hostname of the target server workload'
        required: true
        type: string
      server-port:
        description: 'Port of the target server workload'
        required: false
        type: string
        default: '443'
    # Define outputs that calling workflows can access
    outputs:
      token:
        description: 'The retrieved credential'
        value: ${{ jobs.get-creds.outputs.token }}

jobs:
  get-creds:
    runs-on: ubuntu-latest
    # Pass the token output to the workflow output
    outputs:
      token: ${{ steps.aembit.outputs.token }}
    # Required for GitHub to issue OIDC tokens
    permissions:
      id-token: write
    steps:
      - name: Get credentials
        id: aembit
        uses: Aembit/get-credentials@v1
        with:
          # Client ID from your Trust Provider (store as repository secret)
          client-id: '${{ secrets.AEMBIT_CLIENT_ID }}'
          # Server workload details passed from the calling workflow
          server-host: '${{ inputs.server-host }}'
          server-port: '${{ inputs.server-port }}'

Other workflows call it with:

Example workflow calling the reusable workflow

jobs:
  my-job:
    # Reference the reusable workflow file
    uses: ./.github/workflows/get-aembit-credentials.yml
    with:
      server-host: 'api.example.com'
    # Pass secrets to the reusable workflow
    secrets: inherit

Monitoring at scale

Log Streams aggregate credential access events across all workflows. Use Log Streams for centralized Continuous Integration/Continuous Deployment (CI/CD) monitoring and alerting.

Troubleshooting

Permission denied

Symptom: The action fails with a permission error.

Cause: The workflow lacks the required OIDC permissions.

Solution: Add the id-token: write permission to your workflow:

Required permissions

permissions:
  id-token: write
  contents: read

Credential not found

Symptom: The step output is empty when accessed via ${{ steps.aembit.outputs.<name> }}.

Cause: The credential request failed authorization, or you’re using the wrong output name.

Solution:

• Verify the client-id matches your Trust Provider’s Edge Software Development Kit (SDK) Client ID
• Check that your Access Policy is active
• Confirm the Server Workload host and port match your configuration
• Use the correct output name for your credential type (see Action output reference)

Invalid audience

Symptom: The action fails with an audience validation error.

Cause: Using a custom Resource Set without specifying it in the action.

Solution: Add the resource-set-id parameter:

Action inputs with resource-set-id

with:
  client-id: '${{ secrets.AEMBIT_CLIENT_ID }}'
  resource-set-id: '${{ secrets.AEMBIT_RESOURCE_SET_ID }}'
  server-host: 'api.example.com'
  server-port: '443'

Credential format mismatch

Symptom: The credential works but isn’t in the expected format.

Cause: The Credential Provider type doesn’t match how you’re using the credential.

Solution: Verify your Credential Provider type matches your usage. Each credential type provides different step outputs:

• API Key: api-key
• Username/Password: username and password
• OAuth: token

See the Action output reference for the complete list.

Related

• Tutorial - Step-by-step first setup
• Reference - All action parameters
• GitHub Trust Provider - Trust Provider configuration
• Access Authorization Events - Viewing credential request logs