Azure KeyVault Integration - AL-Go for GitHub

Azure KeyVault provides centralized, secure storage for secrets used by AL-Go for GitHub. Instead of storing secrets directly in GitHub, you can store them in Azure KeyVault and configure AL-Go to retrieve them automatically.

Benefits of Using Azure KeyVault

Centralized Management

Manage all secrets in one place across multiple repositories

Enhanced Security

Leverage Azure’s security features and access controls

Audit Logging

Track secret access and modifications

Rotation Support

Easily rotate secrets without updating multiple repositories

Prerequisites

Before setting up Azure KeyVault integration:

Azure KeyVault

Have an Azure KeyVault created and configured

Verified Domain

App registration name should use a verified domain of your organization

Premium SKU (Optional)

For Hardware Security Modules or app signing, upgrade to Premium SKU KeyVault

Upgrade an existing KeyVault to Premium SKU:

az keyvault update --set properties.sku.name=premium --name <KeyVaultName> --resource-group <ResourceGroupName>

Setup Instructions

1. Connect to Azure

Follow the Azure login action documentation to set up the connection.

2. Create Azure_Credentials Secret

Add a compressed JSON construct as a repository secret called AZURE_CREDENTIALS: Format:

{"keyVaultName":"{your-keyvault-name}","clientId":"<clientId>","clientSecret":"<clientSecret>","tenantId":"<tenantId>"}

You can also specify the KeyVault name in the AL-Go settings file instead of including it in the JSON construct.

3. Configure KeyVault Name (Optional)

Alternatively, add the KeyVault name to your settings file: .github/AL-Go-settings.json:

{
  "keyVaultName": "MyKeyVault"
}

Azure_Credentials (without keyVaultName):

{"clientId":"<clientId>","clientSecret":"<clientSecret>","tenantId":"<tenantId>"}

Authentication Methods

Managed Identity (Recommended)

Use Azure Managed Identity with federated credentials for the most secure setup: Azure_Credentials:

{"keyVaultName":"MyKeyVault","clientId":"<clientId>","tenantId":"<tenantId>"}

Setup:

Create Managed Identity

Create a managed identity in Azure

Configure Federated Credential

Add federated credential for your GitHub repository

Grant Permissions

Assign required KeyVault permissions (see below)

App Registration with Federated Credential

Azure_Credentials:

{"keyVaultName":"MyKeyVault","clientId":"<clientId>","tenantId":"<tenantId>"}

Setup:

Create App Registration

Create an app registration in Azure AD

Add Federated Credential

Under Certificates & Secrets, add federated credential for your GitHub repo

Grant Permissions

Assign required KeyVault permissions

App Registration with Client Secret

Azure_Credentials:

{"keyVaultName":"MyKeyVault","clientId":"<clientId>","clientSecret":"<clientSecret>","tenantId":"<tenantId>"}

Client secrets are less secure than federated credentials. Prefer managed identities or federated credentials when possible.

KeyVault Permissions

Configure permissions based on your KeyVault security model:

Role Based Access Control (RBAC) - Recommended

Assign these roles to your managed identity or app registration:

Task	Required Role
Read Secrets	Key Vault Secrets User
Sign Apps	Key Vault Crypto User + Key Vault Certificate User

Assign roles:

Navigate to KeyVault

Go to your KeyVault in Azure Portal

Access Control (IAM)

Select “Access control (IAM)” from the left menu

Add Role Assignment

Click “Add” → “Add role assignment”

Select Role

Choose the required role (e.g., “Key Vault Secrets User”)

Assign to Identity

Select your managed identity or app registration

Vault Access Policy

Alternatively, use vault access policies:

Task	Required Permissions
Read Secrets	Secret permissions: Get, List
Sign Apps	Cryptographic Operations: Sign Certificate permissions: Get

Configure access policy:

Navigate to Access Policies

Go to KeyVault → Access policies

Add Access Policy

Click “Add Access Policy”

Select Permissions

Choose required secret/certificate/key permissions

Select Principal

Select your managed identity or app registration

Save

Click “Add” then “Save”

Storing Secrets in KeyVault

1. Add Secrets to KeyVault

Add your AL-Go secrets to the KeyVault: Example secrets:

authContext - For environment deployment
ghTokenWorkflow - For updating AL-Go system files
licenseFileUrl - For Business Central license
appSourceContext - For AppSource delivery
Any other AL-Go secrets

Using Azure Portal:

Navigate to Secrets

Go to KeyVault → Secrets

Generate/Import

Click “Generate/Import”

Enter Details

Name: Secret name (e.g., “authContext”) Value: Secret value (compressed JSON if applicable)

Create

Click “Create”

Using Azure CLI:

az keyvault secret set --vault-name MyKeyVault --name authContext --value '{"tenantId":"...","scopes":"..."}'

2. Remove Secrets from GitHub

After adding secrets to KeyVault, remove them from GitHub repository secrets and environment secrets.

Keep the Azure_Credentials secret in GitHub - it’s needed to access the KeyVault.

Testing the Configuration

Test Secret Access

Run CI/CD Pipeline

Trigger a CI/CD workflow to test secret retrieval

Check Workflow Logs

Verify that secrets are being read from KeyVault

Test Deployment

Run a deployment to ensure authContext is retrieved correctly

Test System Update

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

App Signing with KeyVault

To use KeyVault for app signing:

1. Import Certificate to KeyVault

Using Azure Portal:

Navigate to Certificates

Go to KeyVault → Certificates

Generate/Import

Click “Generate/Import”

Import Certificate

Upload your .pfx certificate file with password

2. Configure AL-Go Settings

Add to your .github/AL-Go-settings.json:

{
  "keyVaultCodesignCertificateName": "MySigningCertificate"
}

3. Verify Permissions

Ensure your identity has:

RBAC: Key Vault Crypto User + Key Vault Certificate User roles
Access Policy: Cryptographic Operations: Sign + Certificate permissions: Get

Secret Name Mapping

AL-Go looks for secrets in this order:

Environment Secret (GitHub)

Check environment secrets in GitHub

Repository Secret (GitHub)

Check repository secrets in GitHub

Organization Secret (GitHub)

Check organization secrets in GitHub

Azure KeyVault

If Azure_Credentials exists, check KeyVault for the secret

Secret names in KeyVault should match the names AL-Go expects (e.g., “authContext”, “ghTokenWorkflow”). Names are case-insensitive.

Troubleshooting

Secret Not Found

Check secret name

Verify the secret name in KeyVault matches what AL-Go expects

Check permissions

Ensure the identity has “Get” and “List” permissions for secrets

Check Azure_Credentials

Verify the Azure_Credentials secret is correctly formatted and contains valid credentials

Check KeyVault name

Ensure the keyVaultName in Azure_Credentials or settings is correct

Authentication Failed

Federated credential

Verify the federated credential is configured for the correct repository, branch, or environment

Client secret expired

If using client secret, check if it has expired and create a new one

Identity permissions

Verify the managed identity or app registration has access to the KeyVault

Signing Failed

Premium SKU

Verify KeyVault is using Premium SKU (required for signing)

Certificate imported

Ensure the certificate is properly imported to KeyVault

Signing permissions

Verify the identity has cryptographic operation permissions

Best Practices

Use Managed Identities

Prefer managed identities with federated credentials for enhanced security

Separate KeyVaults

Use different KeyVaults for development, staging, and production

Enable Logging

Enable diagnostic logging on KeyVault to track secret access

Regular Audits

Regularly review KeyVault access logs and permissions

Least Privilege

Grant only the minimum required permissions

Soft Delete

Enable soft delete and purge protection on KeyVault

Example Complete Configuration

GitHub Secret: Azure_Credentials

{"keyVaultName":"MyALGoKeyVault","clientId":"12345678-1234-1234-1234-123456789012","tenantId":"87654321-4321-4321-4321-210987654321"}

KeyVault Secrets

authContext

{"tenantId":"87654321-4321-4321-4321-210987654321","scopes":"https://api.businesscentral.dynamics.com/","clientId":"12345678-1234-1234-1234-123456789012"}

ghTokenWorkflow
```
ghp_YourGitHubPersonalAccessToken
```

licenseFileUrl

https://example.com/licenses/license.flf?token=abc123

AL-Go Settings (.github/AL-Go-settings.json)

{
  "keyVaultName": "MyALGoKeyVault",
  "keyVaultCodesignCertificateName": "CodeSigningCert"
}

Secrets Overview - Understanding AL-Go secrets
GitHub Secrets Reference - Detailed secret documentation
Advanced Settings - KeyVault-related settings

Configuration

Secrets Management

​Benefits of Using Azure KeyVault

Centralized Management

Enhanced Security

Audit Logging

Rotation Support

​Prerequisites

​Setup Instructions

​1. Connect to Azure

​2. Create Azure_Credentials Secret

​3. Configure KeyVault Name (Optional)

​Authentication Methods

​Managed Identity (Recommended)

​App Registration with Federated Credential

​App Registration with Client Secret

​KeyVault Permissions

​Role Based Access Control (RBAC) - Recommended

​Vault Access Policy

​Storing Secrets in KeyVault

​1. Add Secrets to KeyVault

​2. Remove Secrets from GitHub

​Testing the Configuration

​Test Secret Access

​App Signing with KeyVault

​1. Import Certificate to KeyVault

​2. Configure AL-Go Settings

​3. Verify Permissions

​Secret Name Mapping

​Troubleshooting

​Secret Not Found

​Authentication Failed

​Signing Failed

​Best Practices

Use Managed Identities

Separate KeyVaults

Enable Logging

Regular Audits

Least Privilege

Soft Delete

​Example Complete Configuration

​GitHub Secret: Azure_Credentials

​KeyVault Secrets

​AL-Go Settings (.github/AL-Go-settings.json)

​Related Topics

Build docs developers (and LLMs) love

Benefits of Using Azure KeyVault

Prerequisites

Setup Instructions

1. Connect to Azure

2. Create Azure_Credentials Secret

3. Configure KeyVault Name (Optional)

Authentication Methods

Managed Identity (Recommended)

App Registration with Federated Credential

App Registration with Client Secret

KeyVault Permissions

Role Based Access Control (RBAC) - Recommended

Vault Access Policy

Storing Secrets in KeyVault

1. Add Secrets to KeyVault

2. Remove Secrets from GitHub

Testing the Configuration

Test Secret Access

App Signing with KeyVault

1. Import Certificate to KeyVault

2. Configure AL-Go Settings

3. Verify Permissions

Secret Name Mapping

Troubleshooting

Secret Not Found

Authentication Failed

Signing Failed

Best Practices

Example Complete Configuration

GitHub Secret: Azure_Credentials

KeyVault Secrets

AL-Go Settings (.github/AL-Go-settings.json)

Related Topics