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 linking these components:

configured with GitHub OpenID Connect (OIDC) identity
for GitHub Actions
matching your credential type
for the target service

Configure the action

Add the Aembit GitHub Action to your workflow with the appropriate configuration for your credential type. The credential-type input names the Credential Provider type in your Access Policy and decides which step outputs the action sets.

Optionally, add the resource-set-id input if your Trust Provider lives in a custom Resource Set.

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 }}'
          credential-type: 'ApiKey'
          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.

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 }}'
          credential-type: 'OAuthToken'
          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.

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 }}'
          credential-type: 'UsernamePassword'
          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.

permissions:
  id-token: write
  contents: read

jobs:
  call-aws:
    runs-on: ubuntu-latest
    steps:
      - name: Get AWS credentials from Aembit
        id: aembit
        uses: Aembit/get-credentials@v1
        with:
          client-id: '${{ secrets.AEMBIT_CLIENT_ID }}'
          credential-type: 'AwsStsFederation'
          server-host: 's3.amazonaws.com'
          server-port: '443'

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ steps.aembit.outputs.aws-access-key-id }}
          aws-secret-access-key: ${{ steps.aembit.outputs.aws-secret-access-key }}
          aws-session-token: ${{ steps.aembit.outputs.aws-session-token }}
          aws-region: us-east-1

      - name: Use the credentials
        run: aws sts get-caller-identity

The action provides temporary AWS credentials as the aws-access-key-id, aws-secret-access-key, and aws-session-token step outputs. Pass them to aws-actions/configure-aws-credentials so that later steps in the job use them through the AWS CLI and AWS SDKs.

Select among multiple AWS STS Credential Providers

An Access Policy can hold multiple AWS STS Federation Credential Providers, each with its own Access Key ID selector. For how Aembit uses the selector, see Using multiple AWS STS Credential Providers. To choose one, add the aws-access-key-id input with the selector of the Credential Provider you want. The input requires version 1.3.0 or later of the action:

      - name: Get AWS credentials from Aembit
        id: aembit
        uses: Aembit/get-credentials@v1.3.0
        with:
          client-id: '${{ secrets.AEMBIT_CLIENT_ID }}'
          credential-type: 'AwsStsFederation'
          server-host: 's3.amazonaws.com'
          server-port: '443'
          aws-access-key-id: 'AKIADUMMYFORROLEA'

Selector values use uppercase characters only. Omit the input when the Access Policy has a single AWS STS Credential Provider. A selector that matches no Credential Provider in the Access Policy fails the step. Omitting the input when the Access Policy holds more than one also fails the step, because Aembit returns no credential rather than choosing for you.

Verify it works

After running your workflow:

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

In your , go to Reporting > Access Authorization Events.
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:

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 }}'
          credential-type: 'OAuthToken'
          # Server workload details passed from the calling workflow
          server-host: '${{ inputs.server-host }}'
          server-port: '${{ inputs.server-port }}'

Other workflows call it with:

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:

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: Your Trust Provider is in a custom Resource Set, but the action isn’t configured to use it.

Solution: Add the resource-set-id input. See Configure the action.

Wrong AWS role assumed

Symptom: The step succeeds, but aws sts get-caller-identity reports an IAM role you didn’t expect. Or, the step fails when the Access Policy has more than one AWS STS Credential Provider.

Cause: The aws-access-key-id input is missing, or its value doesn’t match the Access Key ID selector of the Credential Provider you want.

Solution: Set aws-access-key-id to the selector shown on the Credential Provider, in uppercase, and pin Aembit/get-credentials@v1.3.0 or later. See Select among multiple AWS STS Credential Providers.

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
AWS STS Federation: aws-access-key-id, aws-secret-access-key, and aws-session-token

See the Action output reference for the complete list.

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