Skip to main content

Troubleshooting Azure Managed Identity Connection Issues with Liquibase

Lora Griffin
Updated

Applies to

  • Liquibase Secure (Pro)
  • Liquibase Community (Open Source)

Conditions

  • Azure SQL Database or Azure SQL Managed Instance 
  • Azure Managed Identity

 

Issue Summary

When attempting to connect Liquibase to Azure SQL Database or Azure SQL Managed Instance using Managed Identity authentication, the connection fails. This typically occurs even when the Liquibase configuration appears correct, because the Azure-side configuration for Managed Identity is incomplete or misconfigured.

Error Messages

Login failed for user '<token-identified principal>'.

 

Cannot open server '<server-name>' requested by the login. Client with IP address 'x.x.x.x' is not allowed to access the server.

 

ClientConnectionId: xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

 

The server principal "<identity-name>" is not able to access the database "<database-name>" under the current security context.

 

Failed to authenticate the user '<identity-name>' in Active Directory (Authentication option is 'ActiveDirectoryMSI').

 

Potential Root Causes

Azure Managed Identity authentication failures are usually caused by Azure-side configuration issues rather than Liquibase configuration problems. To troubleshoot this issue:

  1. First, verify the Azure compute resource has Managed Identity enabled - This is the most common oversight
  2. Second, verify the Azure SQL firewall rules allow your connection - Network access must be configured
  3. Third, verify the Managed Identity has been granted database access - The identity needs explicit permissions
  4. Finally, verify your Liquibase connection string is correctly formatted - Ensure the authentication parameter is set properly

 

Troubleshooting

Step 1: Enable Managed Identity on Your Azure Compute Resource

Before Liquibase can use Managed Identity authentication, your Azure compute resource must have Managed Identity enabled.

For Azure Virtual Machines:

  1. Navigate to your VM in the Azure Portal
  2. Select Identity from the left-hand menu
  3. Under the System assigned tab, toggle Status to On
  4. Click Save
  5. Note the Object ID that appears - you'll need this later

For Azure App Service:

  1. Navigate to your App Service in the Azure Portal
  2. Select Identity from the left-hand menu
  3. Under the System assigned tab, toggle Status to On
  4. Click Save
  5. Note the Object ID that appears - you'll need this later

For Azure Container Instances or AKS:

Refer to Azure documentation for enabling Managed Identity on container services, as the process varies by orchestration method.

To verify Managed Identity is enabled:

Run this Azure CLI command from within your compute resource:

curl 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://database.windows.net/' -H Metadata:true

If Managed Identity is properly configured, you should receive a JSON response containing an access token.

 

Step 2: Configure Azure SQL Firewall Rules

Your Azure compute resource must be allowed to connect to your Azure SQL server through firewall rules.

Option A: Add specific IP address (recommended for production):

  1. Navigate to your Azure SQL Server in the Azure Portal
  2. Select Networking (or Firewalls and virtual networks) from the left-hand menu
  3. Under Firewall rules, click + Add a firewall rule
  4. Enter a rule name and the IP address of your Azure compute resource
  5. Click Save

Option B: Allow Azure Services (easier for testing):

  1. Navigate to your Azure SQL Server in the Azure Portal
  2. Select Networking from the left-hand menu
  3. Under Exceptions, check Allow Azure services and resources to access this server
  4. Click Save

Note: Option B is less secure and should only be used for development/testing environments.

 

Step 3: Grant Database Access to the Managed Identity

The Managed Identity must be created as a database user and granted appropriate permissions.

Connect to your Azure SQL Database using SQL Server Management Studio, Azure Data Studio, or the Azure Portal Query Editor with an admin account, then run:

For System-assigned Managed Identity:

-- Replace 'your-vm-name' with your Azure resource name
CREATE USER [your-vm-name] FROM EXTERNAL PROVIDER;

-- Grant appropriate permissions (adjust as needed)
ALTER ROLE db_owner ADD MEMBER [your-vm-name];

For User-assigned Managed Identity:

-- Replace 'your-identity-name' with your user-assigned identity name
CREATE USER [your-identity-name] FROM EXTERNAL PROVIDER;

-- Grant appropriate permissions (adjust as needed)
ALTER ROLE db_owner ADD MEMBER [your-identity-name];

To verify that the user was created successfully:

SELECT name, type_desc, authentication_type_desc 
FROM sys.database_principals 
WHERE name = 'your-vm-name';

You should see a result with type_desc as EXTERNAL_USER and authentication_type_desc as EXTERNAL.

Common permission configurations:

For read/write access (typical Liquibase usage):

ALTER ROLE db_ddladmin ADD MEMBER [your-identity-name];
ALTER ROLE db_datawriter ADD MEMBER [your-identity-name];
ALTER ROLE db_datareader ADD MEMBER [your-identity-name];

For read-only access:

ALTER ROLE db_datareader ADD MEMBER [your-identity-name];

 

Step 4: Verify Your Liquibase Connection Configuration

Ensure your Liquibase connection string includes the correct authentication parameter.

For Liquibase 5.0 and newer (liquibase-azure.jar extension is included):

In your liquibase.properties file:

url=jdbc:sqlserver://your-server.database.windows.net:1433;database=your-database;authentication=ActiveDirectoryMSI;

For Liquibase 4.33 and older (requires additional extension):

  1. Download the liquibase-azure-deps-4.33.0.jar
  2. Place it in your Liquibase lib directory
  3. Use the same connection string as above

Important connection string notes:

  • The authentication=ActiveDirectoryMSI parameter is required
  • Leave username and password empty or omit them
  • For user-assigned Managed Identity, add msiClientId=<client-id> to the connection string:
    • url=jdbc:sqlserver://your-server.database.windows.net:1433;database=your-database;authentication=ActiveDirectoryMSI;msiClientId=your-client-id;

Test your connection:

liquibase connect

 

Step 5: Verify End-to-End Configuration

If you're still experiencing issues after completing the previous steps, verify the entire configuration:

Checklist:

  • Managed Identity is enabled on your Azure compute resource
  • You can retrieve a token from the metadata endpoint (Step 1 verification)
  • Azure SQL firewall rules allow your compute resource's IP address
  • The Managed Identity exists as a user in your database
  • The Managed Identity has appropriate permissions (db_owner or specific roles)
  • Your connection string includes authentication=ActiveDirectoryMSI
  • For Liquibase 4.33 and older, the liquibase-azure-deps-4.33.0.jar is in the lib directory
  • You're running Liquibase from within the Azure compute resource (not locally)

Common mistake: Attempting to use Managed Identity from your local development machine. Managed Identity only works when running from within Azure resources.

 

Step 6: Enable Detailed Logging for Additional Troubleshooting

If issues persist, enable detailed logging to capture more diagnostic information:

Add to your liquibase.properties:

loglevel=FINE

Or run Liquibase with the debug flag:

liquibase --log-level=FINE update

Look for authentication-related messages in the output. Common issues revealed by debug logging:

  • Token retrieval failures (indicates Managed Identity not properly enabled)
  • Connection timeout errors (indicates firewall/network issues)
  • Authentication errors with specific error codes (indicates permission issues)

 

Related Article(s)

Related to

Related articles

Comments

0 comments

Article is closed for comments.