Azure KeyVault Integration

AL-Go for GitHub supports Azure KeyVault for centralized secret management, allowing you to store sensitive credentials like authentication contexts and tokens securely in Azure instead of GitHub.

Benefits of Azure KeyVault

Centralized Management

Store all secrets in one secure location accessible across repositories

Enhanced Security

Use Azure’s enterprise-grade security features and HSM support

Audit & Compliance

Track secret access and meet compliance requirements

Prerequisites

Before integrating Azure KeyVault with AL-Go, ensure you have:

Completed AL-Go repository setup
An Azure KeyVault instance created
Azure Active Directory app registration with KeyVault access
Appropriate permissions to configure service principals

If you need Hardware Security Module (HSM) support, you must use a Premium SKU KeyVault. See Microsoft’s documentation for more information.

Setup Overview

Integrating Azure KeyVault with AL-Go involves two main steps:

Create Azure service principal - Set up authentication between GitHub and Azure
Configure AL-Go settings - Connect your repository to the KeyVault

Step 1: Create Service Principal

Follow Microsoft’s guide on connecting from GitHub to Azure to create a service principal with KeyVault access.

Create App Registration

In Azure Portal, create a new App Registration:

Navigate to Azure Active Directory > App registrations
Click “New registration”
Name your application (use a verified domain, e.g., https://myapp.mydomainname.com)
Select appropriate account type

Create Client Secret

Generate a client secret for the app registration:

Open your app registration
Go to “Certificates & secrets”
Create a new client secret
Copy the secret value (you won’t be able to see it again)

Grant KeyVault Access

Assign permissions to access your KeyVault:

Open your KeyVault in Azure Portal
Go to “Access policies”
Add access policy with “Get” and “List” secret permissions
Select the service principal you created
Save the access policy

Create AZURE_CREDENTIALS JSON

Build the authentication JSON with the following structure:

{
  "clientId": "<your-client-id>",
  "clientSecret": "<your-client-secret>",
  "tenantId": "<your-tenant-id>",
  "subscriptionId": "<your-subscription-id>",
  "keyVaultName": "<your-keyvault-name>"
}

Compress this JSON (remove whitespace) before adding it as a secret.

Step 2: Configure GitHub Repository

Once your Azure resources are ready, configure your GitHub repository to use KeyVault.

Add AZURE_CREDENTIALS Secret

Add the compressed JSON from Step 1 as a repository secret:

Go to your repository Settings > Secrets and variables > Actions
Click “New repository secret”
Name: AZURE_CREDENTIALS
Value: The compressed JSON containing service principal details and KeyVault name

Optional: Add KeyVault Name to Settings

Alternatively, you can specify the KeyVault name in .github/AL-Go-Settings.json:

{
  "keyVaultName": "<your-keyvault-name>"
}

If specified in settings, you don’t need to include keyVaultName in the AZURE_CREDENTIALS JSON.

Migrating Secrets to KeyVault

Move your existing GitHub secrets to Azure KeyVault for centralized management.

Add Secrets to KeyVault

Transfer your GitHub secrets to Azure KeyVault:

Azure Portal
Azure CLI
PowerShell

Navigate to your KeyVault in Azure Portal
Go to “Secrets” section
Click “Generate/Import”
Add each secret with the same name used in GitHub

# Add authContext secret
az keyvault secret set \
  --vault-name <your-keyvault-name> \
  --name authContext \
  --value '<your-auth-context-json>'

# Add ghTokenWorkflow secret
az keyvault secret set \
  --vault-name <your-keyvault-name> \
  --name ghTokenWorkflow \
  --value '<your-github-token>'

# Import Azure module if not already loaded
Import-Module Az.KeyVault

# Connect to Azure
Connect-AzAccount

# Add authContext secret
$secretValue = ConvertTo-SecureString '<your-auth-context-json>' -AsPlainText -Force
Set-AzKeyVaultSecret -VaultName '<your-keyvault-name>' -Name 'authContext' -SecretValue $secretValue

# Add ghTokenWorkflow secret
$tokenValue = ConvertTo-SecureString '<your-github-token>' -AsPlainText -Force
Set-AzKeyVaultSecret -VaultName '<your-keyvault-name>' -Name 'ghTokenWorkflow' -SecretValue $tokenValue

Remove GitHub Secrets

After confirming KeyVault access works, remove the secrets from:

Repository secrets (Settings > Secrets and variables > Actions)
Environment secrets (Settings > Environments > [environment] > Secrets)

Test KeyVault integration before removing GitHub secrets to ensure continuity.

Common Secrets to Store

These are typical secrets to migrate to Azure KeyVault:

Authentication
GitHub Integration
Deployment
Custom Delivery

authContext

Business Central environment authentication
Format: Compressed JSON with authentication details
Used by: Deployment workflows

[Environment]_AuthContext

Environment-specific authentication contexts
Format: Compressed JSON
Used by: Deploy to specific environments

Verification

Verify that AL-Go can successfully access secrets from Azure KeyVault.

Run CI/CD Pipeline

Trigger a CI/CD workflow to test basic KeyVault integration:

Push a commit or manually trigger the workflow
Monitor the workflow execution for authentication success
Verify that builds and tests complete without authentication errors

Test Deployment

If you migrated deployment secrets, test environment deployment:

Trigger a deployment to a configured environment
Verify the workflow retrieves authContext from KeyVault
Confirm successful deployment to target environment

Test AL-Go Updates

Run “Update AL-Go System Files” to verify ghTokenWorkflow access:

Navigate to Actions > Update AL-Go System Files
Run the workflow
Verify it can access the token from KeyVault
Confirm successful completion

Secret Naming Conventions

AL-Go looks for secrets in this order:

Environment secrets (if deploying to a specific GitHub environment)
Repository secrets
Azure KeyVault secrets (if AZURE_CREDENTIALS is configured)

Secret names in KeyVault should match exactly the names AL-Go expects (e.g., authContext, ghTokenWorkflow). Secret names are case-sensitive.

KeyVault Secret Format Examples

authContext Secret

{
  "tenantID": "<your-tenant-id>",
  "clientID": "<your-client-id>",
  "clientSecret": "<your-client-secret>",
  "scopes": "https://api.businesscentral.dynamics.com/.default",
  "authority": "https://login.microsoftonline.com"
}

ghTokenWorkflow Secret

ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Store just the token value as a string, not as JSON.

Advanced Configuration

Multiple KeyVaults

You can use different KeyVaults for different purposes:

{
  "keyVaultName": "<default-keyvault>",
  "environments": ["Production", "Staging"],
  "DeployToProduction": {
    "keyVaultName": "<production-keyvault>"
  },
  "DeployToStaging": {
    "keyVaultName": "<staging-keyvault>"
  }
}

KeyVault with Firewall

If your KeyVault has network restrictions:

Ensure GitHub Actions IP ranges are allowed
Or use a self-hosted runner within your network
Configure KeyVault firewall to allow your runner’s IP addresses

Managed Identity (Self-Hosted Runners)

For self-hosted runners in Azure, you can use Managed Identity instead of service principal:

Enable Managed Identity

Enable system-assigned managed identity on your runner VM in Azure Portal.

Grant KeyVault Access

Add the managed identity to your KeyVault access policies with appropriate permissions.

Configure AL-Go

Add KeyVault name to settings (AZURE_CREDENTIALS not needed when using Managed Identity):

{
  "keyVaultName": "<your-keyvault-name>",
  "useAzureManagedIdentity": true
}

Troubleshooting

Authentication failed to KeyVault

Verify:

Service principal credentials are correct in AZURE_CREDENTIALS
Service principal has access policy in KeyVault
KeyVault name is correct
Tenant ID and subscription ID are correct

Secret not found in KeyVault

Check:

Secret name exactly matches what AL-Go expects (case-sensitive)
Secret exists in the specified KeyVault
Access policy grants “Get” permission for secrets

Network connectivity issues

Investigate:

KeyVault firewall settings
GitHub Actions IP ranges if using firewall restrictions
Self-hosted runner network connectivity to Azure

Workflow uses GitHub secret instead of KeyVault

Remember:

GitHub secrets take precedence over KeyVault
Remove GitHub secrets after confirming KeyVault works
Environment secrets override repository secrets

Security Best Practices

Use Least Privilege

Grant only necessary permissions:

KeyVault: Only “Get” and “List” for secrets
Service principal: Only KeyVault access, no broader permissions

Rotate Secrets Regularly

Implement secret rotation:

Set expiration dates on client secrets
Rotate service principal credentials periodically
Update KeyVault secrets when rotating credentials

Enable Audit Logging

Monitor KeyVault access:

Enable Azure Monitor for KeyVault
Review access logs regularly
Set up alerts for suspicious activity

Use Premium SKU for HSM

For sensitive workloads:

Use Premium KeyVault with HSM support
Store encryption keys in HSM-backed keys
Implement key versioning

Next Steps

Enable Telemetry

Monitor KeyVault access and workflow performance

Self-Hosted Runners

Use managed identity with Azure-hosted runners

Getting Started

Setup & Configuration

Core Workflows

Development

Deployment

AppSource Publishing

Advanced Topics

Migration

Benefits of Azure KeyVault

Centralized Management

Enhanced Security

Audit & Compliance

Prerequisites

Setup Overview

Step 1: Create Service Principal

Step 2: Configure GitHub Repository

Migrating Secrets to KeyVault

Common Secrets to Store

Verification

Secret Naming Conventions

KeyVault Secret Format Examples

authContext Secret

ghTokenWorkflow Secret

Advanced Configuration

Multiple KeyVaults

KeyVault with Firewall

Managed Identity (Self-Hosted Runners)

Troubleshooting

Security Best Practices

Next Steps

Enable Telemetry

Self-Hosted Runners

Build docs developers (and LLMs) love

Getting Started

Setup & Configuration

Core Workflows

Development

Deployment

AppSource Publishing

Advanced Topics

Migration

​Benefits of Azure KeyVault

Centralized Management

Enhanced Security

Audit & Compliance

​Prerequisites

​Setup Overview

​Step 1: Create Service Principal

​Step 2: Configure GitHub Repository

​Migrating Secrets to KeyVault

​Common Secrets to Store

​Verification

​Secret Naming Conventions

​KeyVault Secret Format Examples

​authContext Secret

​ghTokenWorkflow Secret

​Advanced Configuration

​Multiple KeyVaults

​KeyVault with Firewall

​Managed Identity (Self-Hosted Runners)

​Troubleshooting

​Security Best Practices

​Next Steps

Enable Telemetry

Self-Hosted Runners

Build docs developers (and LLMs) love

Benefits of Azure KeyVault

Prerequisites

Setup Overview

Step 1: Create Service Principal

Step 2: Configure GitHub Repository

Migrating Secrets to KeyVault

Common Secrets to Store

Verification

Secret Naming Conventions

KeyVault Secret Format Examples

authContext Secret

ghTokenWorkflow Secret

Advanced Configuration

Multiple KeyVaults

KeyVault with Firewall

Managed Identity (Self-Hosted Runners)

Troubleshooting

Security Best Practices

Next Steps