lex-identity-entra 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec4cedd630cdcaaf6941ad0fe0c7c9b56b0ab0311f442406b5e32992ea8d15df
+  data.tar.gz: a4024c49a2819dfa4a7b12a3243a39bedc93dd8eecf458acffee62f69b4a6909
+SHA512:
+  metadata.gz: 7307e9b1ecb97fcbdcdc77672b8a7054fc851eb3289c2050a89e93336057fbdcf0cf160c4df2c33b84b7dc65d6465e036acdb5ec837c688e9d96feffee395996
+  data.tar.gz: eb935f1d0ce6e0dac4bf81001100b5a97025e894e884d2d8da4aa031974a9853d8d65f5af09417199967c3cf349a4150ff9ee6118940f028734ef81b6c1330dc

data/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: '0 9 * * 1'
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  excluded-files:
+    uses: LegionIO/.github/.github/workflows/excluded-files.yml@main
+
+  security:
+    uses: LegionIO/.github/.github/workflows/security-scan.yml@main
+
+  version-changelog:
+    uses: LegionIO/.github/.github/workflows/version-changelog.yml@main
+
+  dependency-review:
+    uses: LegionIO/.github/.github/workflows/dependency-review.yml@main
+
+  stale:
+    if: github.event_name == 'schedule'
+    uses: LegionIO/.github/.github/workflows/stale.yml@main
+
+  release:
+    needs: [ci, excluded-files]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.rspec_status
+Gemfile.lock
+*.gem

data/.rubocop.yml

@@ -0,0 +1,20 @@
+inherit_gem:
+  rubocop-legion: config/lex.yml
+  
+Style/ModuleFunction:
+  Exclude:
+    - 'lib/legion/extensions/identity/entra/helpers/token_manager.rb'
+    - 'lib/legion/extensions/identity/entra/helpers/graph_client.rb'
+    - 'lib/legion/extensions/identity/entra/helpers/account_discovery.rb'
+
+Legion/Extension/EveryActorRequiresTime:
+  Enabled: false
+
+ThreadSafety/ClassInstanceVariable:
+  Exclude:
+    - 'lib/legion/extensions/identity/helpers/'
+    - 'lib/legion/extensions/identity/entra/helpers/'
+    - 'lib/legion/extensions/identity/entra/helpers/'
+    - 'lib/legion/extensions/identity/entra/client.rb'
+    - 'lib/legion/extensions/identity/entra/helpers/scope_gate.rb'
+

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.3.0] - 2026-05-14
+
+### Added
+- Delegated token persistence to HashiCorp Vault at `kv/data/users/<identity>/entra/delegated/auth`; disk file used only as fallback when Vault is unavailable.
+- Automatic backfill: existing disk tokens are migrated to Vault on next load and the disk file is deleted once Vault write succeeds.
+- `delete_local` cleans up the on-disk token file whenever Vault becomes authoritative.
+- `AuthValidator` calls `Legion::Identity::Broker.register_provider` after successful auth so any extension can call `Legion::Identity::Broker.token_for(:entra_delegated, qualifier: :delegated)`.
+- `AuthValidator` calls `Legion::Identity::Resolver.upgrade!` after auth to promote the Entra-verified identity into `Legion::Identity::Process` state.
+- MD5 scope fingerprint stored with token across all backends; mismatch or missing fingerprint forces re-authentication.
+- In-memory token store as tertiary fallback (vault → disk → memory).
+- Delegated scopes expanded to full org-granted permission set: Teams, Chat, Channel, OnlineMeetings, OneNote, SharePoint, Yammer, Files, Presence, and core OpenID/profile scopes.
+- OAuth callback page auto-closes after 10-second JavaScript countdown.
+
+### Changed
+- Vault read skipped at boot until process identity is trusted (prevents 403 during resolver race).
+- Vault read/write now use `Legion::Crypt.get`/`Legion::Crypt.write` via the `kv` mount directly, matching the policy path.
+- `AuthValidator` delay reduced from 90s to 9s.
+
+## [0.2.0] - 2026-05-07
+
+### Added
+- Browser OAuth with PKCE, local callback handling, and device-code fallback for delegated Entra auth.
+- Microsoft identity OAuth runner for client credentials, authorization code, device code, and refresh-token grants.
+- CLI auth entrypoint and manifest metadata for `legion lex exec entra auth login/status`.
+- Refresh-aware token persistence with Vault, local file, and Broker fallback lookup.
+- Multi-account Entra discovery for delegated, secondary, and privileged account token qualifiers.
+
+### Changed
+- `resolve_all` now uses discovered Entra token qualifiers instead of wrapping only the default delegated account.
+- `provide_token` includes qualifier and scope metadata from the persisted token record.
+
+## [0.1.0] - 2026-04-24
+
+### Added
+- Initial Entra identity provider scaffold with cached-token Graph `/me` resolution.

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :development, :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-legion', '~> 0.1'
+  gem 'simplecov', '~> 0.22'
+end

data/README.md

@@ -0,0 +1,120 @@
+# lex-identity-entra
+
+LegionIO identity provider extension for Microsoft Entra ID (Azure AD). Implements the unified
+identity provider contract for delegated (user), application (client credentials), managed identity,
+and workload identity authentication patterns.
+
+## Features
+
+- **Delegated auth** — OAuth2 PKCE browser flow with local callback server; device-code fallback
+- **Token persistence** — Vault-first (`kv/data/users/<identity>/entra/<qualifier>/auth`), disk fallback, in-memory fallback; disk file deleted once Vault write succeeds
+- **Scope fingerprinting** — MD5 fingerprint of active scopes stored with token; any scope change forces re-authentication on next boot
+- **Identity integration** — `AuthValidator` upgrades `Legion::Identity::Process` via `Resolver.upgrade!` and registers with `Legion::Identity::Broker` for cross-extension token access
+- **Application credentials** — client credentials flow for service-to-service auth
+- **Managed Identity** — Azure IMDS token acquisition for hosted workloads
+- **Workload Identity** — federated credential support for Kubernetes and CI/CD
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'lex-identity-entra'
+```
+
+## Configuration
+
+```yaml
+# ~/.legionio/settings/identity.yml
+identity:
+  entra:
+    auth:
+      tenant_id: "your-tenant-id"
+      client_id: "your-client-id"
+    delegated:
+      browser_auth:
+        auto_authenticate: false   # set true to open browser automatically at boot
+        callback_timeout: 120
+      token:
+        refresh_buffer: 60
+        refresh_interval: 900
+      scopes:
+        enabled_categories:
+          - microsoft_graph
+          - teams
+          - one_note
+          - sharepoint
+          - azure_communication_services
+          - yammer
+```
+
+## Usage
+
+### Delegated (user) authentication
+
+```bash
+# Via CLI
+legion lex exec entra auth login
+legion lex exec entra auth status
+```
+
+The `AuthValidator` actor fires 9 seconds after boot. If `auto_authenticate: true` is set,
+it opens a browser window automatically. Otherwise trigger login via the CLI.
+
+### Accessing tokens from another extension
+
+```ruby
+token = Legion::Identity::Broker.token_for(:entra_delegated, qualifier: :delegated)
+```
+
+### Application (client credentials)
+
+```yaml
+identity:
+  entra:
+    application:
+      tenant_id: "your-tenant-id"
+      client_id: "your-client-id"
+      client_secret: "your-client-secret"  # or use Vault
+```
+
+## Scope categories
+
+| Category | Description |
+|----------|-------------|
+| `microsoft_graph` | Core Graph API: User.Read, Files, Devices, OpenID scopes |
+| `teams` | Teams, Chat, Channel, OnlineMeetings, Presence, Activity |
+| `one_note` | OneNote notebook read/write |
+| `sharepoint` | SharePoint/OneDrive files and sites |
+| `azure_communication_services` | Teams calls and chat management |
+| `yammer` | Viva Engage / Yammer communities and conversations |
+
+## Token storage
+
+| Backend | Path | Priority |
+|---------|------|----------|
+| HashiCorp Vault | `kv/data/users/<identity>/entra/delegated/auth` | 1 (preferred) |
+| Local disk | `~/.legionio/tokens/entra_delegated.json` | 2 (fallback, deleted when Vault succeeds) |
+| Memory | In-process store | 3 (runtime fallback) |
+
+## Identity provider contract
+
+```ruby
+{
+  canonical_name:    "jdoe",       # normalized from onPremisesSamAccountName or mailNickname
+  kind:              :human,
+  source:            :entra_delegated,
+  provider_identity: "object-id-guid",
+  profile:           { ... }           # full Graph /me response
+}
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+**GitHub**: https://github.com/LegionIO/lex-identity-entra

data/lex-identity-entra.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/identity/entra/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-identity-entra'
+  spec.version       = Legion::Extensions::Identity::Entra::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Identity: Entra ID (Azure AD) provider'
+  spec.description   = 'LegionIO identity provider that resolves Entra ID (Azure AD) identity ' \
+                       'via Microsoft Graph API into the unified identity contract'
+  spec.homepage      = 'https://github.com/LegionIO/lex-identity-entra'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']          = spec.homepage
+  spec.metadata['source_code_uri']       = 'https://github.com/LegionIO/lex-identity-entra'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-identity-entra'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-identity-entra'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-identity-entra/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+
+  # Core framework dependencies
+  spec.add_dependency 'concurrent-ruby', '>= 1.2'
+  spec.add_dependency 'faraday',         '>= 2.0'
+  spec.add_dependency 'legion-crypt',    '>= 1.5.13'
+  spec.add_dependency 'legion-json',     '>= 1.2.1'
+  spec.add_dependency 'legion-logging',  '>= 1.5.3'
+  spec.add_dependency 'legion-settings', '>= 1.3.14'
+end

data/lib/legion/extensions/identity/entra/application/actors/token_refresher.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Entra
+        module Application
+          module Actor
+            class TokenRefresher < Legion::Extensions::Actors::Every
+              DEFAULT_REFRESH_INTERVAL = 2700
+
+              def runner_class    = self.class
+              def runner_function = 'manual'
+              def use_runner?     = false
+              def check_subtask?  = false
+              def generate_task?  = false
+              def run_now?        = false
+
+              def time
+                Legion::Settings.dig(:identity, :entra, :application, :token, :refresh_interval) ||
+                  DEFAULT_REFRESH_INTERVAL
+              end
+
+              def enabled? # rubocop:disable Legion/Extension/ActorEnabledSideEffects
+                true
+              end
+
+              def manual
+                log.debug('Application TokenRefresher tick')
+                data = Legion::Extensions::Identity::Entra::Helpers::TokenManager.token_data(:application, refresh: false)
+
+                if data && !Legion::Extensions::Identity::Entra::Helpers::TokenManager.expired?(data)
+                  log.debug('Application token still valid')
+                  return
+                end
+
+                log.info('Application token nearing expiry, re-acquiring')
+                auth_settings = Legion::Extensions::Identity::Entra::Helpers::TokenManager.settings_auth
+                runner = Object.new.extend(Legion::Extensions::Identity::Entra::Application::Runners::Credential)
+                result = runner.acquire_token(
+                  tenant_id:     auth_settings[:tenant_id],
+                  client_id:     auth_settings[:client_id],
+                  client_secret: auth_settings[:client_secret]
+                )
+
+                body = result&.dig(:result)
+                unless body&.dig(:access_token)
+                  log.warn('Application token re-acquisition failed')
+                  return
+                end
+
+                Legion::Extensions::Identity::Entra::Helpers::TokenManager.save_token(
+                  :application,
+                  access_token: body[:access_token],
+                  expires_in:   body[:expires_in],
+                  scopes:       body[:scope] || 'https://graph.microsoft.com/.default',
+                  tenant_id:    auth_settings[:tenant_id],
+                  client_id:    auth_settings[:client_id]
+                )
+                Legion::Extensions::Identity::Entra::Client.reset!(pattern: :application)
+                log.info('Application token refreshed successfully')
+              rescue StandardError => e
+                log.error("Application TokenRefresher: #{e.message}")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/identity/entra/application/client.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Entra
+        module Application
+          class Client < Legion::Extensions::Identity::Entra::Client
+            def pattern = :application
+
+            private
+
+            def authenticate
+              settings = auth_settings
+              return unless settings[:tenant_id] && settings[:client_id] && settings[:client_secret]
+
+              requested = Legion::Extensions::Identity::Entra::Helpers::Scopes.resolve(pattern: :application)
+              registry.record_requested(requested)
+
+              runner = Object.new.extend(Legion::Extensions::Identity::Entra::Application::Runners::Credential)
+              result = runner.acquire_token(
+                tenant_id:     settings[:tenant_id],
+                client_id:     settings[:client_id],
+                client_secret: settings[:client_secret]
+              )
+              body = result&.dig(:result)
+              return unless body&.dig(:access_token)
+
+              granted = body[:scope] || 'https://graph.microsoft.com/.default'
+              registry.record_granted(granted)
+              Legion::Extensions::Identity::Entra::Helpers::TokenManager.save_token(
+                :application,
+                access_token: body[:access_token],
+                expires_in:   body[:expires_in],
+                scopes:       granted,
+                tenant_id:    settings[:tenant_id],
+                client_id:    settings[:client_id]
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/identity/entra/application/runners/credential.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'legion/extensions/identity/entra/helpers/scopes'
+
+module Legion
+  module Extensions
+    module Identity
+      module Entra
+        module Application
+          module Runners
+            module Credential
+              include Legion::Logging::Helper
+              include Legion::Settings::Helper
+
+              DEFAULT_SCOPE = 'https://graph.microsoft.com/.default'
+
+              def acquire_token(tenant_id:, client_id:, client_secret:,
+                                scope: DEFAULT_SCOPE, **)
+                log.debug("Credential.acquire_token: tenant=#{tenant_id}")
+                result = credential_post(tenant_id,
+                                         grant_type:    'client_credentials',
+                                         client_id:     client_id,
+                                         client_secret: client_secret,
+                                         scope:         scope)
+                log.info('Credential.acquire_token: token acquired') if result[:access_token]
+                { result: result }
+              rescue StandardError => e
+                handle_exception(e, level: :error, operation: 'application.credential.acquire_token')
+                { error: 'request_failed', description: e.message }
+              end
+
+              def acquire_token_with_certificate(tenant_id:, client_id:, client_assertion:,
+                                                 scope: DEFAULT_SCOPE, **)
+                log.debug("Credential.acquire_token_with_certificate: tenant=#{tenant_id}")
+                result = credential_post(tenant_id,
+                                         grant_type:            'client_credentials',
+                                         client_id:             client_id,
+                                         client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+                                         client_assertion:      client_assertion,
+                                         scope:                 scope)
+                log.info('Credential.acquire_token_with_certificate: token acquired') if result[:access_token]
+                { result: result }
+              rescue StandardError => e
+                handle_exception(e, level: :error, operation: 'application.credential.acquire_token_with_certificate')
+                { error: 'request_failed', description: e.message }
+              end
+
+              def credential_post(tenant_id, form)
+                log.debug("Credential.credential_post: tenant=#{tenant_id}")
+                response = credential_connection(tenant_id).post('oauth2/v2.0/token',
+                                                                 URI.encode_www_form(form.transform_keys(&:to_s)))
+                body = response.body.to_s.empty? ? {} : json_load(response.body)
+                unless response.success?
+                  body[:error] ||= "http_#{response.status}"
+                  body[:error_description] ||= response.reason_phrase
+                  log.debug("Credential.credential_post: error=#{body[:error]} status=#{response.status}")
+                end
+                body
+              end
+
+              private
+
+              def credential_connection(tenant_id)
+                Faraday.new(url: "https://login.microsoftonline.com/#{tenant_id}/") do |f|
+                  f.headers['Accept'] = 'application/json'
+                  f.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+                  f.options.open_timeout = 5
+                  f.options.timeout = 15
+                end
+              end
+
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex, false)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/identity/entra/application/scope_registry.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/identity/entra/helpers/scope_registry'
+
+module Legion
+  module Extensions
+    module Identity
+      module Entra
+        module Application
+          ScopeRegistry = Legion::Extensions::Identity::Entra::Helpers::ScopeRegistry.new(pattern: :application)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/identity/entra/application/scopes.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Entra
+        module Application
+          module Scopes
+            CATEGORIES = {
+              microsoft_graph: %w[
+                User.Read.All
+                Application.Read.All
+                Directory.Read.All
+                Group.Read.All
+                Mail.Read
+                Mail.ReadBasic.All
+                Mail.Send
+                Calendars.Read
+                Sites.Read.All
+                Files.Read.All
+                TeamMember.Read.All
+                Channel.ReadBasic.All
+                ChannelMessage.Read.All
+                Chat.Read.All
+                ChatMessage.Read.All
+                OnlineMeetings.Read.All
+                OnlineMeetingTranscript.Read.All
+                OnlineMeetingRecording.Read.All
+                CallRecords.Read.All
+              ],
+              one_note:        %w[
+                Notes.Read.All
+                Notes.ReadWrite.All
+              ],
+              sharepoint:      %w[
+                Sites.Read.All
+                Sites.ReadWrite.All
+                Files.Read.All
+                Files.ReadWrite.All
+              ]
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/identity/entra/application.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'application/scopes'
+require_relative 'application/scope_registry'
+require_relative 'application/runners/credential'
+require_relative 'application/actors/token_refresher'
+require_relative 'application/client'
+
+module Legion
+  module Extensions
+    module Identity
+      module Entra
+        module Application
+          extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core, false)
+
+          def self.identity_provider? = false
+          def self.remote_invocable?  = false
+
+          def self.default_settings
+            {
+              logger:  { level: 'info' },
+              workers: 1,
+              runners: {},
+              auth:    {
+                tenant_id:     nil,
+                client_id:     nil,
+                client_secret: nil,
+                certificate:   nil
+              },
+              scopes:  {
+                enabled_categories: [:microsoft_graph],
+                category_overrides: {}
+              },
+              token:   {
+                vault_path:       nil,
+                local_token_path: nil,
+                refresh_buffer:   60,
+                refresh_interval: 2700
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end