omniauth-microsoft_business_central 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a38f823b02c38e3b8db8913c56926d15a3cade2183884e2d922c29d1fb814764
+  data.tar.gz: b0c0a1dfea3a7a14d262537a0a4809d656abd7dce164a0116ae9b0416c19f78c
+SHA512:
+  metadata.gz: e18b93493ca79fd49738448e6b245c7a40a6b51b4dc1a8e501c5615465a111c30dd78bece29e255f0a10619751ee37d3353800e25aa4641ccee05bc07dbb1cd3
+  data.tar.gz: e5eec82f7a78d05b8edaa6cdc4eb7b2d671ee375adbbc0022e1bae1fc920b4c614d667142a7c6007d045e0d727bc7b4fa17aa03c0057574c0b1941e65766c100

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.1.0] - 2026-08-27
+
+Initial release. Replaces the [dropstream fork of omniauth-microsoft_graph](https://github.com/dropstream/omniauth-microsoft_graph),
+which had repointed the `omniauth-microsoft_graph` strategy at Business Central while
+keeping the Graph gem name, module names and provider key.
+
+### Added
+
+- `OmniAuth::Strategies::MicrosoftBusinessCentral`, registered as
+  `:microsoft_business_central` (callback path
+  `/auth/microsoft_business_central/callback`).
+- A `tenant_id` option (default `common`) that derives the Microsoft identity
+  platform v2.0 authorize/token endpoints; explicit `client_options` URLs still win.
+- `uid`, `info` (name/email) and `extra` (`tenant_id`, `claims`), decoded from the
+  `id_token` when an OpenID scope was granted, otherwise from the access token JWT.
+- Scope normalization carried over from the fork: bare scope names are qualified
+  against `https://api.businesscentral.dynamics.com/`, OpenID scopes and absolute
+  URLs pass through, comma- and space-separated lists are accepted. The default
+  scope remains `https://api.businesscentral.dynamics.com/user_impersonation offline_access`.
+- Per-request passthrough of the whitelisted authorize options (`scope`, `prompt`,
+  `login_hint`, `domain_hint`, `response_mode`).
+- A `callback_url` override that drops the callback's query string (the Microsoft
+  identity platform requires an exact `redirect_uri` match) and honors a configured
+  `:callback_url`.
+- Integration specs covering the request phase, tenant selection, scope
+  normalization, the token exchange, and the auth hash; CI on Ruby 3.2–3.4 with a
+  weekly `bundle-audit`, and releases via the GitHub Releases UI with RubyGems
+  trusted publishing (OIDC, no stored API key).
+
+### Changed
+
+- **Breaking (relative to the fork):** requires `omniauth ~> 2.0` and
+  `omniauth-oauth2 ~> 1.9` (the fork pinned `omniauth ~> 1.1`, which carries
+  CVE-2015-9284). Host applications must upgrade to OmniAuth 2.x; Rails apps also
+  need [`omniauth-rails_csrf_protection`](https://github.com/cookpad/omniauth-rails_csrf_protection)
+  because OmniAuth 2 only accepts `POST` for the request phase.
+- Pinned the token endpoint to `auth_scheme: :request_body` (`client_secret_post`),
+  matching what the Microsoft identity platform expects; `oauth2` 2.x would default
+  to HTTP basic auth.
+- Requires Ruby >= 3.2.
+
+### Removed
+
+- The Graph-era code inherited via omniauth-google-oauth2: the custom
+  `build_access_token` (AJAX/JSON-body code paths) and `verify_token`, which called
+  the Microsoft Graph `/me` endpoint and could not work with a Business Central
+  token. The strategy is now a plain OAuth2 authorization-code flow.
+- The Google-specific `access_type`, `display`, `score` and `auth_type` authorize
+  options, and the ability to override `state` or `redirect_uri` from request params.
+
+[0.1.0]: https://github.com/dropstream/omniauth-microsoft_business_central/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dropstream
+
+Portions derived from omniauth-microsoft_graph
+(https://github.com/synth/omniauth-microsoft_graph),
+Copyright (c) 2014 Josef Šimánek and contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,195 @@
+# Omniauth::MicrosoftBusinessCentral
+
+This is an OmniAuth strategy for authenticating to
+[Microsoft Dynamics 365 Business Central](https://learn.microsoft.com/en-us/dynamics365/business-central/)
+through the Microsoft identity platform (Entra ID, formerly Azure AD). It obtains an
+access token (and refresh token) for the Business Central API on behalf of the
+signed-in user.
+
+Requires Ruby >= 3.2, OmniAuth 2.x and `omniauth-oauth2` 1.9.x.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'omniauth-microsoft_business_central'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install omniauth-microsoft_business_central
+
+## Usage
+
+OmniAuth 2 only accepts `POST` for the request phase. In a Rails app, add
+[`omniauth-rails_csrf_protection`](https://github.com/cookpad/omniauth-rails_csrf_protection)
+to your Gemfile and link to the provider with `button_to` or `link_to ..., method: :post`:
+
+```ruby
+gem 'omniauth-rails_csrf_protection'
+```
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :microsoft_business_central,
+           ENV['AZURE_APPLICATION_CLIENT_ID'],
+           ENV['AZURE_APPLICATION_CLIENT_SECRET']
+end
+```
+
+The auth hash carries the tokens under `credentials` and the user's identity —
+decoded from the Entra ID token claims — under `uid`/`info`:
+
+```ruby
+auth = request.env['omniauth.auth']
+auth['credentials']['token']         # Business Central access token
+auth['credentials']['refresh_token'] # present because of the default offline_access scope
+auth['uid']                          # the Entra object id (oid claim)
+auth['info']['name']
+auth['info']['email']
+auth['extra']['tenant_id']           # the Entra tenant the user signed in from
+auth['extra']['claims']              # all decoded token claims
+```
+
+## Configuring
+
+### Scopes
+
+The default scope is:
+
+    https://api.businesscentral.dynamics.com/user_impersonation offline_access
+
+`user_impersonation` grants delegated access to the Business Central API, and
+`offline_access` makes Microsoft return a refresh token. Bare scope names are
+qualified against `https://api.businesscentral.dynamics.com/`; OpenID Connect scopes
+(`openid`, `email`, `profile`, `offline_access`) and absolute URLs pass through
+untouched:
+
+```ruby
+provider :microsoft_business_central, client_id, client_secret,
+         :scope => 'user_impersonation offline_access openid email profile'
+```
+
+Requesting `openid` makes Microsoft return an `id_token`, which the strategy then
+prefers over the access token when populating `uid`/`info`.
+
+### Restricting sign-in to one tenant
+
+`tenant_id` defaults to `common`, which lets users from any Entra tenant sign in
+(what a multi-tenant app registration needs). Set it to a tenant GUID or domain to
+pin the strategy to a single directory:
+
+```ruby
+provider :microsoft_business_central, client_id, client_secret,
+         :tenant_id => 'contoso.onmicrosoft.com'
+```
+
+### Per-request authorize params
+
+`login_hint`, `domain_hint`, `prompt`, `response_mode` and `scope` may also be
+supplied per request and are passed through to Microsoft's authorize endpoint:
+
+```
+/auth/microsoft_business_central?login_hint=user@example.com
+```
+
+(With OmniAuth 2 the request phase is a `POST`; the params can be in the query
+string or the form body.)
+
+### Configure the callback URL
+
+The strategy overrides `callback_url` to drop the query string that OmniAuth would
+otherwise append, because the Microsoft identity platform rejects a `redirect_uri`
+that does not match the registered one exactly. Pass `callback_url` to override it
+outright:
+
+```ruby
+  :callback_url => 'https://app.example.com/users/auth/microsoft_business_central/callback'
+```
+
+Otherwise it is derived from the request, including the mount prefix — a strategy
+mounted under Devise's `/users` produces
+`https://app.example.com/users/auth/microsoft_business_central/callback`.
+
+### Client credentials in the token request
+
+`client_options[:auth_scheme]` is pinned to `:request_body`, because the Microsoft
+identity platform expects `client_id` and `client_secret` in the token request body
+(`client_secret_post`). This was `oauth2` 1.x's default; `oauth2` 2.x defaults to
+`:basic_auth`.
+
+## Migrating from the dropstream fork of omniauth-microsoft_graph
+
+This gem replaces [dropstream/omniauth-microsoft_graph](https://github.com/dropstream/omniauth-microsoft_graph),
+a fork that pointed the `omniauth-microsoft_graph` gem's strategy at Business
+Central while keeping the Graph name. What changes:
+
+- The provider is `:microsoft_business_central`, so routes move from
+  `/auth/microsoft_graph` to `/auth/microsoft_business_central`. Update the
+  redirect URI on the Azure app registration to the new callback path.
+- Requires OmniAuth 2.x: the request phase is `POST`-only, and Rails apps need
+  `omniauth-rails_csrf_protection`.
+- The auth hash now has `uid`, `info` and `extra['claims']`, decoded from the
+  token claims. `extra['params']` (the raw token response) is still there.
+- The Graph-era `verify_token`/`access_token`-in-params flows and the JSON-body
+  code path were dropped; the strategy is a plain OAuth2 authorization-code flow.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bundle exec rake spec` to run the tests. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+Run `bundle exec bundle-audit check --update` to check the locked dependency tree
+against the advisory database; CI runs the same check weekly.
+
+## Releasing
+
+Releases are cut from the [GitHub Releases UI](https://github.com/dropstream/omniauth-microsoft_business_central/releases/new);
+GitHub Actions builds and publishes the gem to [rubygems.org](https://rubygems.org) via
+[RubyGems trusted publishing](https://guides.rubygems.org/trusted-publishing/), so no API
+key is stored in the repo and the gemspec can keep `rubygems_mfa_required`.
+
+1. Bump `VERSION` in `lib/omniauth-microsoft_business_central/version.rb` and add a
+   `CHANGELOG.md` section for it, along with a link definition for the new heading at
+   the bottom of that file. Commit both on `main`.
+2. Draft a new release with the target set to `main` and the tag set to the version
+   prefixed with `v` — `v0.1.0`, not `0.1.0`. The prefix is stripped before comparing
+   against `version.rb`; the gem version itself carries no `v`.
+3. Click **Generate release notes** — the preferred method — then publish. The generated
+   notes list the merged pull requests; `CHANGELOG.md` carries the curated prose and
+   links back to each release.
+
+Publishing creates the tag, which fires the `Release` workflow: it reruns the full test
+matrix, refuses to continue if the tag and `version.rb` disagree, and pushes the gem.
+Note that RubyGems versions are immutable — a bad release can be yanked, never replaced,
+so the version bump has to be committed before the release is published.
+
+### One-time RubyGems setup
+
+Needed before the first release from CI, and again only if the gem is renamed or moved.
+Because the gem does not exist on rubygems.org yet, register a
+[pending trusted publisher](https://guides.rubygems.org/trusted-publishing/pushing-a-new-gem/):
+on rubygems.org open your profile -> **Trusted publishers** -> **Create**, with gem name
+`omniauth-microsoft_business_central`, owner `dropstream`, repository
+`omniauth-microsoft_business_central`, workflow `release.yml`, and environment `release`.
+Pending publishers expire after 12 hours, so do this shortly before publishing the first
+release. The repo also needs an environment named `release`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/dropstream/omniauth-microsoft_business_central.
+
+## License
+
+Available as open source under the terms of the [MIT License](LICENSE.txt). Portions
+derived from [omniauth-microsoft_graph](https://github.com/synth/omniauth-microsoft_graph)
+(MIT).

data/lib/omniauth/strategies/microsoft_business_central.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'omniauth-oauth2'
+
+module OmniAuth
+  module Strategies
+    class MicrosoftBusinessCentral < OmniAuth::Strategies::OAuth2
+      # The Business Central API audience; bare scope names are qualified against it.
+      SCOPE_PREFIX = 'https://api.businesscentral.dynamics.com/'
+      DEFAULT_SCOPE = "#{SCOPE_PREFIX}user_impersonation offline_access"
+      # OpenID Connect scopes that must be passed through unqualified.
+      OPENID_SCOPES = %w[openid email profile offline_access].freeze
+
+      option :name, 'microsoft_business_central'
+
+      # 'common' lets any Microsoft Entra tenant sign in, which is what a
+      # multi-tenant app registration needs. Set it to a tenant id (GUID) or
+      # domain to restrict sign-in to a single directory.
+      option :tenant_id, 'common'
+
+      option :client_options, {
+        site: 'https://login.microsoftonline.com/',
+        # The Microsoft identity platform expects the client credentials in the
+        # token request body (client_secret_post); oauth2 2.x defaults to
+        # HTTP basic auth.
+        auth_scheme: :request_body
+      }
+
+      option :authorize_options, %i[scope prompt login_hint domain_hint response_mode]
+
+      option :scope, DEFAULT_SCOPE
+
+      uid { user_claims['oid'] }
+
+      info do
+        {
+          name: user_claims['name'],
+          email: user_claims['email'] || user_claims['preferred_username'] || user_claims['upn']
+        }
+      end
+
+      extra do
+        {
+          'params' => access_token.params,
+          'tenant_id' => user_claims['tid'],
+          'claims' => user_claims
+        }
+      end
+
+      def client
+        client_options = deep_symbolize(options.client_options)
+        tenant = options.tenant_id || 'common'
+        client_options[:authorize_url] ||= "#{tenant}/oauth2/v2.0/authorize"
+        client_options[:token_url] ||= "#{tenant}/oauth2/v2.0/token"
+        ::OAuth2::Client.new(options.client_id, options.client_secret, client_options)
+      end
+
+      def authorize_params
+        super.tap do |params|
+          # Any whitelisted authorize option can also be supplied per request:
+          # /auth/microsoft_business_central?login_hint=user@example.com
+          options[:authorize_options].each do |key|
+            value = request.params[key.to_s]
+            params[key] = value unless value.nil? || value == ''
+          end
+
+          params[:scope] = normalize_scope(params[:scope] || DEFAULT_SCOPE)
+        end
+      end
+
+      # OmniAuth::Strategy#callback_url appends the callback request's own query
+      # string, and the Microsoft identity platform requires redirect_uri to match
+      # the registered value exactly. omniauth 2's `callback_path` already carries
+      # SCRIPT_NAME, so mount prefixes must not be added again.
+      def callback_url
+        options[:callback_url] || (full_host + callback_path)
+      end
+
+      private
+
+      # Qualifies bare scope names ('user_impersonation') against the Business
+      # Central API audience, leaving OpenID scopes and absolute URLs alone.
+      # Accepts space- and/or comma-separated lists.
+      def normalize_scope(raw_scope)
+        raw_scope.split(/[,\s]+/).map do |scope|
+          next scope if scope.match?(%r{\Ahttps?://}) || OPENID_SCOPES.include?(scope)
+
+          "#{SCOPE_PREFIX}#{scope}"
+        end.join(' ')
+      end
+
+      # Claims for the signed-in user: from the id_token when an OpenID scope was
+      # granted, otherwise from the access token itself (Business Central access
+      # tokens are Entra ID JWTs). The payload is read without verifying the
+      # signature, which is acceptable only because the token arrives directly
+      # from login.microsoftonline.com over TLS, never from the browser.
+      def user_claims
+        @user_claims ||= decode_jwt_claims(access_token.params['id_token']) ||
+                         decode_jwt_claims(access_token.token) ||
+                         {}
+      end
+
+      def decode_jwt_claims(jwt)
+        payload = jwt.to_s.split('.')[1]
+        return nil if payload.nil? || payload.empty?
+
+        # Base64url-decode by hand; the base64 gem left Ruby's default gems in 3.4.
+        json = (payload.tr('-_', '+/') + '=' * (-payload.length % 4)).unpack1('m')
+        claims = JSON.parse(json)
+        claims.is_a?(Hash) ? claims : nil
+      rescue ArgumentError, JSON::ParserError, EncodingError
+        nil
+      end
+    end
+  end
+end

data/lib/omniauth-microsoft_business_central/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Omniauth
+  module MicrosoftBusinessCentral
+    VERSION = "0.1.0"
+  end
+end

data/lib/omniauth-microsoft_business_central.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "omniauth-microsoft_business_central/version"
+require "omniauth/strategies/microsoft_business_central"

data/omniauth-microsoft_business_central.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "omniauth-microsoft_business_central/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "omniauth-microsoft_business_central"
+  spec.version       = Omniauth::MicrosoftBusinessCentral::VERSION
+  spec.authors       = ["Karl Falconer"]
+  spec.email         = ["karl.falconer@getdropstream.com"]
+
+  spec.summary       = "OmniAuth strategy for Microsoft Dynamics 365 Business Central"
+  spec.description   = "An OmniAuth OAuth2 strategy that authenticates against the " \
+                       "Microsoft identity platform (Entra ID) and obtains tokens for " \
+                       "the Dynamics 365 Business Central API."
+  spec.homepage      = "https://github.com/dropstream/omniauth-microsoft_business_central"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"]      = spec.homepage
+  spec.metadata["source_code_uri"]   = spec.homepage
+  spec.metadata["changelog_uri"]     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Ship only the library itself; development scaffolding stays out of the gem.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:spec|bin|pkg|\.github)/}) ||
+        f.match(%r{\A(?:\.gitignore|\.rspec|\.ruby-version|\.ruby-gemset|Gemfile|Gemfile\.lock|Rakefile)\z})
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "omniauth", "~> 2.0"
+  spec.add_dependency "omniauth-oauth2", "~> 1.9"
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: omniauth-microsoft_business_central
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Karl Falconer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omniauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: omniauth-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+description: An OmniAuth OAuth2 strategy that authenticates against the Microsoft
+  identity platform (Entra ID) and obtains tokens for the Dynamics 365 Business Central
+  API.
+email:
+- karl.falconer@getdropstream.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/omniauth-microsoft_business_central.rb
+- lib/omniauth-microsoft_business_central/version.rb
+- lib/omniauth/strategies/microsoft_business_central.rb
+- omniauth-microsoft_business_central.gemspec
+homepage: https://github.com/dropstream/omniauth-microsoft_business_central
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/dropstream/omniauth-microsoft_business_central
+  source_code_uri: https://github.com/dropstream/omniauth-microsoft_business_central
+  changelog_uri: https://github.com/dropstream/omniauth-microsoft_business_central/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: OmniAuth strategy for Microsoft Dynamics 365 Business Central
+test_files: []