AzIdentity

Gem Version CI

Azure identity and authentication library for Ruby.

Provides credential acquisition for Azure services including Workload Identity and Managed Identity.

:warning: Not Supported by Microsoft

This library is not supported by Microsoft. It is developed and maintained by GitLab.

Microsoft provides official Azure Identity libraries for Ruby:

If you encounter issues with this library, please file issues on the GitLab issue tracker, not Microsoft support channels.

Installation

Add this line to your application's Gemfile:

gem 'az-identity'

And then execute:

$ bundle install

Or install it yourself:

$ gem install az-identity

Usage

require 'az_identity'

# Get credentials using default chain (Workload Identity -> Managed Identity)
credentials = AzIdentity.credentials(environment: 'AzureCloud')

# Or use specific client directly
client = AzIdentity::Identity::WorkloadIdentityClient.new(environment: 'AzureCloud')
credentials = client.fetch_credentials_if_needed

Environment Variables

Workload Identity

  • AZURE_TENANT_ID - Your Azure tenant ID
  • AZURE_CLIENT_ID - Your client/application ID
  • AZURE_FEDERATED_TOKEN_FILE - Path to the OIDC token file
  • AZURE_AUTHORITY_HOST - (Optional) Override authority URL

Managed Identity

  • AZURE_CLIENT_ID - (Optional) Specific managed identity client ID
  • IDENTITY_ENDPOINT - (Optional) Custom IMDS endpoint
  • IDENTITY_HEADER - (Optional) Custom header for IMDS

Azure Environment

  • AZURE_ENVIRONMENT - (Optional) Azure cloud: AzureCloud, AzureChinaCloud, AzureUSGovernment

Supported Azure Environments

  • AzureCloud (default)
  • AzureChinaCloud
  • AzureUSGovernment

Sovereign clouds

The OAuth resource/audience (https://storage.azure.com, https://redis.azure.com) is the same in every Azure cloud; only the Microsoft Entra authority (login host) differs. Cloud selection therefore only affects the authority:

  • Workload identity: the authority comes from AZURE_AUTHORITY_HOST, which AKS injects with the correct per-cloud value, so it works in sovereign clouds without further configuration. The AZURE_ENVIRONMENT fallback is used only when that variable is unset.
  • Managed identity: uses the IMDS endpoint, which is the same in every cloud, so it is cloud-agnostic.

Only Azure Public and Azure US Government have been exercised; other clouds rely on the mechanisms above rather than dedicated testing.

Development

After checking out the repo, run bundle install to install dependencies. Then, run bundle exec rake test to run the tests.

Contributing

Bug reports and pull requests are welcome on GitLab at https://gitlab.com/gitlab-org/ruby/gems/az-identity.

License

The gem is available as open source under the terms of the MIT License.