omniauth-entra-id 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12d51e6e7781fc58e98afb3631c673ffe033f6b606ddb549df20e8baaae1c5af
-  data.tar.gz: 8b507bae0a8bbf2e72601e3e3be9c9d0513977528988ee04f9f70b5a8ce1672d
+  metadata.gz: ddd915751370dcbd9611821ce2e0c853737f92b9a4a3c0751199787dd41af788
+  data.tar.gz: 72b7bde2f8365d41b6c2f8429410df3cd9a2ceb4b7c820cb53ab4626c45b59c1
 SHA512:
-  metadata.gz: 3595a1f659a7429216de6f00a39949b4a70655e4505bf6d126e9ea158569b977f0a7af8ebddb3df7791f89e85ad1ca35b53d926fc8bc6727d5477a06b20fc18a
-  data.tar.gz: c090da890e3c2c2edd5a4f36e922f5eadae2caf498c5cd9ba398eaba6c62c2ef055ff4cf4da487dc353cf79438abd8004c2c6cb09e9fe8024184c51b2e77642d
+  metadata.gz: c78e6a6790f3ecdfc8e81381a7873fa7f389d1289ae56666e278ccc965f2fab090ae41de88c7eabcac4d3542f9678e2aee74c70e42dfd7b445fc6d646c459ece
+  data.tar.gz: 32a9a37f322f690b09653db3161c0400c435400b3f8a3670f0e673ca3a83451d42d629f69efd339ee7132bd540aba6cb80b93babf435868a59f1eda8a8aa80f5

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Change Log
 
+## v3.1.0 (2025-06-17)
+
+* Provides a way to ignore TID when constructing a user UID, easing migration from v2.x, via the new `ignore_tid` option, resolving #42 (reported by @s-andringa)
+* Handles a missing (`nil`) TID, via #46 (thanks to @frenkel)
+* Ruby 3.4 "officially" supported through coverage in CI, via #47 (thanks to @hakeem0114)
+* Supports JWT gem v2.9.x or v3.x, via #48 (thanks to @djpremier)
+
+## v3.0.1 (2024-11-21)
+
+* Fixes a minor error in [`UPGRADING.md`](UPGRADING.md) reported in #38, via #40 (thanks to @kennethgeerts)
+* Fixes incorrect attempt to verify JWT token issuer when the AD FS tenant `adfs` is specified, via #39 (thanks to @washu)
+
 ## v3.0.0 (2024-10-22)
 
 * To upgrade from the Azure ActiveDirectory V2 gem, please see [`UPGRADING.md`](UPGRADING.md)

data/README.md

@@ -104,19 +104,20 @@ To have your application authenticate with Entra via a client secret, specify `c
 
 If you're using the client assertion flow, you need to register your certificate in the Entra portal. For more information, please see [the documentation](https://learn.microsoft.com/en-us/entra/identity-platform/certificate-credentials).
 
-| Option | Use |
-| ------ | --- |
-| `client_id`        | **Mandatory.** Client ID for the 'application' (integration) configured on the Entra side. Found via the Entra UI. |
-| `client_secret`    | **Mandatory for client secret flow.** Client secret for the 'application' (integration) configured on the Entra side. Found via the Entra UI. Don't give this if using client assertion flow. |
-| `certificate_path` | **Mandatory for client assertion flow.** Don't give this if using a client secret instead of client assertion. This should be the filepath to a PKCS#12 file. |
-| `tenant_id`        | **Mandatory for client assertion flow.** Entra Tenant ID for multi-tenanted use. Default is `common`. Forms part of the Entra OAuth URL - `{base}/{tenant_id}/oauth2/v2.0/...` |
-| `base_url`         | Location of Entra login page, for specialised requirements; default is `OmniAuth::Strategies::EntraId::BASE_URL` (at the time of writing, this is `https://login.microsoftonline.com`). |
-| `tenant_name`      | For what is currently known by its old name of "Azure ActiveDirectory B2C" (and only active if `custom_policy` is also provided - see below), set the tenancy name to constructs the correct B2C endpoint of `{tenant_name}.b2clogin.com/{tenant_name}.onmicrosoft.com/{custom_policy>}" and uses that for auth calls. This is a convenience feature; the `base_entra_url` option could also be manually built up in the same way. |
-| `custom_policy`    | Custom policy. Default is nil. Used in conjunction with `tenant_name`- see above. |
-| `authorize_params` | Additional parameters passed as URL query data in the initial OAuth redirection to Microsoft. See below for more. Empty Hash default. |
-| `domain_hint`      | If defined, sets (overwriting, if already present) `domain_hint` inside `authorize_params`. Default `nil` / none. |
-| `scope`            | If defined, sets (overwriting, if already present) `scope` inside `authorize_params`. Default is `OmniAuth::Strategies::EntraId::DEFAULT_SCOPE` (at the time of writing, this is `'openid profile email'`).  |
-| `adfs`             | If defined, modifies the URLs so they work with an on premise ADFS server. In order to use this you also need to set the `base_url` correctly and fill the `tenant_id` with `'adfs'`. |
+| Option                        | Use |
+| ----------------------------- | --- |
+| `client_id`                   | **Mandatory.** Client ID for the 'application' (integration) configured on the Entra side. Found via the Entra UI. |
+| `client_secret`               | **Mandatory for client secret flow.** Client secret for the 'application' (integration) configured on the Entra side. Found via the Entra UI. Don't give this if using client assertion flow. |
+| `certificate_path`            | **Mandatory for client assertion flow.** Don't give this if using a client secret instead of client assertion. This should be the filepath to a PKCS#12 file. |
+| `tenant_id`                   | **Mandatory for client assertion flow.** Entra Tenant ID for multi-tenanted use. Default is `common`. Forms part of the Entra OAuth URL - `{base}/{tenant_id}/oauth2/v2.0/...` |
+| `base_url`                    | Location of Entra login page, for specialised requirements; default is `OmniAuth::Strategies::EntraId::BASE_URL` (at the time of writing, this is `https://login.microsoftonline.com`). |
+| `tenant_name`                 | For what is currently known by its old name of "Azure ActiveDirectory B2C" (and only active if `custom_policy` is also provided - see below), set the tenancy name to constructs the correct B2C endpoint of `{tenant_name}.b2clogin.com/{tenant_name}.onmicrosoft.com/{custom_policy>}" and uses that for auth calls. This is a convenience feature; the `base_entra_url` option could also be manually built up in the same way. |
+| `custom_policy`               | Custom policy. Default is nil. Used in conjunction with `tenant_name`- see above. |
+| `authorize_params`            | Additional parameters passed as URL query data in the initial OAuth redirection to Microsoft. See below for more. Empty Hash default. |
+| `domain_hint`                 | If defined, sets (overwriting, if already present) `domain_hint` inside `authorize_params`. Default `nil` / none. |
+| `scope`                       | If defined, sets (overwriting, if already present) `scope` inside `authorize_params`. Default is `OmniAuth::Strategies::EntraId::DEFAULT_SCOPE` (at the time of writing, this is `'openid profile email'`). |
+| `ìgnore_tid?` or `ignore_tid` | If set to `true`, tenant ID (TID) is *not* included for a user's UID from Entra. Use if you are confident that an Entra OID will be globally unique and have existing OID-only UIDs in use. Default is `false`; both TID and OID are used to form a UID. Note that the option name variation without the question mark only works for directly-specified options; provider classes must always define an override method called `ignore_tid?`. |
+| `adfs?` or `adfs`             | If set to `true`, modifies the URLs so they work with an on-premise AD FS server (Active Directory Federation Services). In order to use this you also need to set the `base_url` correctly and fill the `tenant_id` with `'adfs'`. Note that the option name variation without the question mark only works for directly-specified options; provider classes must always define an override method called `adfs?`. |
 
 In addition, as a special case, if the request URL contains a query parameter `prompt`, then this will be written into `authorize_params` under that key, overwriting if present any other value there. Note that this comes from the current request URL at the time OAuth flow is commencing, _not_ via static options Hash data or via a custom provider class - but you _could_ just as easily set `scope` inside a custom `authorize_params` returned from a provider class, as shown in an example later; the request URL query mechanism is just another way of doing the same thing.
 

data/UPGRADING.md

@@ -45,7 +45,7 @@ https://example.com/v1/auth/azure_activedirectory_v2/callback
 ...is now:
 
 ```
-https://example.com/v1/auth/entra/callback
+https://example.com/v1/auth/entra_id/callback
 ```
 
 ### URL generation
@@ -65,17 +65,19 @@ omniauth_authorize_url('resource_name_eg_user', 'entra_id', scope: '...')
 
 
 ## Updates due to other breaking changes
-
-### Critical breaking change for all gem users
+### Change affecting all gem users
+#### UIDs will change
 
 This change is for UIDs and is the main reason for creating a V3 gem, whether or not it included the Entra name change.
 
 * The UID returned by OmniAuth for a user previously depended upon the `oid` (object ID) returned by Microsoft. As noted in #33 and fixed in #34, this _might not be unique_ and tenant ID (`tid`) is supposed to be considered too.
 * Out-of-box, Entra ID will do this. If you were an Azure ActiveDirectory V2 (old-name gem, version 2.x) user, then you will have been receiving different UIDs based only on the `oid` from Microsoft.
 * **The change of OID might break the connection between a previously-registered and logged in user and a new login** as usually, you need to store the OmniAuth UID somewhere alongside or within your User records when a user is "connected to" an external OAuth service such as Entra ID.
+* **However, there is a strong argument that TID is not needed** - see https://github.com/pond/omniauth-entra-id/issues/42 for a good argument to that end.
 
-You have two options, should the issue affect you (and it almost certainly will).
+You have three options, should the issue affect you (and it almost certainly will).
 
+* If you are confident that you still only need the OID, set the `ignore_tid` option to `true` alongside `client_id` and `client_secret` in your OmniAuth Entra ID initialiser or your custom provider class given to that initialiser, if you use one. See the top-level `README.md` for more.
 * If you can determine the tenant IDs for all users in your database, you can just migrate the UIDs. The new UID is just a simple concatenation of tenant ID and object ID, so treating the UID as a string, add the tenant ID as a prefix without any other changes in your migration and things should work fine thereafter.
 * Otherwise, you should lazy-migrate:
   - As usual, in your OAuth callback handler, `request.env['omniauth.auth'].uid` gives the UID - but now that's the "new" Entra gem's value which includes tenant ID.
@@ -85,13 +87,68 @@ You have two options, should the issue affect you (and it almost certainly will)
   - For better security add something like an indexed boolean column indicating whether or not the user has been thus migrated and only perform old OID lookups on users which have not yet been migrated.
   - If the user can't be found by either means, then they've not been connected to your system yet. Your existing handling path for such a condition applies.
 
-### Applications that handle multiple OAuth providers
+#### Applications that handle multiple OAuth providers
 
 If your user records contain users that have 'connected' to more than one kind of OAuth provider, then as well as the third party's UID being stored for future logins, you'll most likely have stored the OmniAuth provider name too so that the UID can be looked up in a provider's context (there's no guarantee, of course, that UIDs are unique *between providers* since they're entirely independent entities with their own strategies for allocating unique IDs).
 
 In that case, you will need to migrate records from the old `azure_activedirectory_v2` name to `entra_id`. **Zero-downtime deployment of this change would be very hard since your codebase would need to update from the Azure ActiveDirectory V2 gem to the Entra ID gem with the migration running simultaneously**, so if you need to do such a migration, then you probably should plan for a small maintenance window. At the scheduled time, go into maintenance mode, migrate, deploy, and restore normal service. Even without this, though, the 'worst that can happen' (in theory!) would be temporary user login failures. Either the Entra gem will be causing you to look for a user with an `entra_id` provider but the migration to set this hasn't run yet, or the other way round, with the old gem looking for the old provider name but it's already updated.
 
-### Breaking changes that depend on whether or not you use a certain feature
+#### Example migration code
+
+Suppose you support multiple providers and your User table stores their chosen provider in a column `auth_provider`, with their UID in `auth_uid`. An (irreversible) database migration might do this:
+
+```ruby
+def up
+  add_column :users, :migrated_to_entra, :boolean
+
+  User
+    .where(auth_provider: 'azure_activedirectory_v2')
+    .update_all(
+      auth_provider:     'entra_id',
+      migrated_to_entra: false
+    )
+end
+
+def down
+  raise ActiveRecord::IrreversibleMigration
+end
+```
+
+This means the `migrated_to_entra` column is only ever `false` for existing users that were linked using the V2 gem. Everything else will be at `NULL`. Now you lazy-move those users to the new UID format in the code you use to look up a user in your OmniAuth OAuth 2 callback handler, e.g. via a method such as this:
+
+```ruby
+# Here, "raw_info" comes from e.g.:
+#
+#   request.env['omniauth.auth'].extra&.dig('raw_info') || {}
+#
+def find_user_for_omniauth(auth_provider:, auth_uid:, raw_info:)
+  found_user = User.find_by(
+    auth_provider: auth_provider,
+    auth_uid:      auth_uid
+  )
+
+  if found_user.nil? && auth_provider == 'entra_id'
+    found = User.find_by(
+      auth_provider:     'entra_id',
+      auth_uid:          raw_info['oid'],
+      migrated_to_entra: false
+    )
+
+    if found
+      found.update_columns(
+        auth_uid:          auth_uid,
+        migrated_to_entra: true
+      )
+    end
+  end
+
+  return found_user
+end
+```
+
+Once there are no rows with a `migrated_to_entra` value of `false` for _active_ users, you will be able to drop the column and remove the lazy migration code.
+
+### Other changes that might affect you
 
 * If you refer to `OmniAuth::Strategies::AzureActivedirectoryV2` at all, then this becomes `OmniAuth::Strategies::EntraId` (note lower case "d").
 * `base_azure_url` option renamed to just `base_url` with corresponding rename of `OmniAuth::Strategies::AzureActivedirectoryV2::BASE_AZURE_URL` to `OmniAuth::Strategies::EntraId::BASE_URL`.

data/lib/omniauth/entra_id/version.rb

@@ -1,8 +1,8 @@
 module OmniAuth
   module Entra
     module Id
-      VERSION = "3.0.0"
-      DATE    = "2024-10-22"
+      VERSION = "3.1.0"
+      DATE    = "2025-06-17"
     end
   end
 end

data/lib/omniauth/strategies/entra_id.rb

@@ -9,13 +9,15 @@ module OmniAuth
 
       option :name,            'entra_id'
       option :tenant_provider, nil
+      option :ignore_tid,      false
       option :jwt_leeway,      60
 
       DEFAULT_SCOPE    = 'openid profile email'
       COMMON_TENANT_ID = 'common'
+      AD_FS_TENANT_ID  = 'adfs'
 
-      # The tenant_provider must return client_id, client_secret and,
-      # optionally, tenant_id and base_url.
+      # The tenant_provider argument is how the provider class is eventually
+      # passed to us, if one is used instead of an options Hash.
       #
       args [:tenant_provider]
 
@@ -57,6 +59,7 @@ module OmniAuth
         options.custom_policy                = provider.custom_policy    if provider.respond_to?(:custom_policy)
         options.authorize_params             = provider.authorize_params if provider.respond_to?(:authorize_params)
         options.authorize_params.domain_hint = provider.domain_hint      if provider.respond_to?(:domain_hint) && provider.domain_hint
+        options.ignore_tid                   = provider.ignore_tid?      if provider.respond_to?(:ignore_tid?) && provider.ignore_tid?
         options.authorize_params.prompt      = request.params['prompt']  if defined?(request) && request.params['prompt']
 
         options.authorize_params.scope = if defined?(request) && request.params['scope']
@@ -87,14 +90,32 @@ module OmniAuth
 
       uid do
         #
-        # https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization
+        # Note 1:
+        #
+        #   https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization
         #
         # OID alone might not be unique; TID must be included. An alternative
         # would be to use 'sub' but this is only unique in client/app
         # registration context. If a different app registration is used, the
-        # 'sub' values can be different too.
+        # 'sub' values can be different too...
+        #
+        # Note 2:
+        #
+        #   https://github.com/pond/omniauth-entra-id/issues/42
         #
-        raw_info['tid'] + raw_info['oid']
+        # ...but not everyone agrees on the necessity of a TID and if migrating
+        # from an earlier version of this gem where user data already includes
+        # OID-only identifiers, you might elect to avoid a difficult migration
+        # by opting out - set the "ignore_tid" option to 'true'.
+        #
+        # NB: If the TID is missing or blank the UID uses only the OID, just as
+        # if the "ignore_tid" option were set.
+        #
+        if options.ignore_tid? || raw_info['tid'].nil?
+          raw_info['oid']
+        else
+          raw_info['tid'] + raw_info['oid']
+        end
       end
 
       info do
@@ -135,9 +156,17 @@ module OmniAuth
 
           # For multi-tenant apps (the 'common' tenant_id) it doesn't make any
           # sense to verify the token issuer, because the value of 'iss' in the
-          # token depends on the 'tid' in the token itself.
+          # token depends on the 'tid' in the token itself. We should also skip
+          # for AD FS local instances, as we don't put a valid tenant ID in its
+          # place, but "adfs" (see AD_FS_TENANT_ID) instead.
           #
-          issuer = if options.tenant_id.nil? || options.tenant_id == COMMON_TENANT_ID
+          do_not_verify = (
+            options.tenant_id.nil? ||
+            options.tenant_id == COMMON_TENANT_ID ||
+            options.tenant_id == AD_FS_TENANT_ID
+          )
+
+          issuer = if do_not_verify
             nil
           else
             "#{options.base_url || BASE_URL}/#{options.tenant_id}/v2.0"
@@ -145,16 +174,14 @@ module OmniAuth
 
           # https://learn.microsoft.com/en-us/entra/identity-platform/id-tokens#validate-tokens
           #
-          JWT::Verify.verify_claims(
-            id_token_data,
-            verify_iss:        !issuer.nil?,
-            iss:               issuer,
-            verify_aud:        true,
-            aud:               options.client_id,
-            verify_expiration: true,
-            verify_not_before: true,
-            leeway:            options[:jwt_leeway]
-          )
+          verify_params = {
+            aud: options.client_id,
+            exp: { leeway: options.jwt_leeway },
+            nbf: { leeway: options.jwt_leeway }
+          }
+          verify_params[:iss] = issuer unless issuer.nil?
+
+          ::JWT::Claims.verify_payload!(id_token_data, verify_params)
 
           auth_token_data = begin
             ::JWT.decode(access_token.token, nil, false).first

data/omniauth-entra-id.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |s|
   s.authors               = [ 'RIPA Global'        ]
   s.email                 = [ 'dev@ripaglobal.com' ]
   s.licenses              = [ 'MIT'               ]
-  s.homepage              = 'https://github.com/RIPAGlobal/omniauth-entra-id'
+  s.homepage              = 'https://github.com/pond/scimitar/'
 
   s.required_ruby_version = Gem::Requirement.new('>= 3.0.0')
   s.require_paths         = ['lib']
@@ -39,15 +39,16 @@ Gem::Specification.new do |s|
   }
 
   s.metadata = {
-    'homepage_uri'    => 'https://www.ripaglobal.com/',
-    'bug_tracker_uri' => 'https://github.com/RIPAGlobal/omniauth-entra-id/issues/',
-    'changelog_uri'   => 'https://github.com/RIPAGlobal/omniauth-entra-id/blob/master/CHANGELOG.md',
-    'source_code_uri' => 'https://github.com/RIPAGlobal/omniauth-entra-id'
+    'homepage_uri'    => s.homepage,
+    'bug_tracker_uri' => 'https://github.com/pond/omniauth-entra-id/issues/',
+    'changelog_uri'   => 'https://github.com/pond/omniauth-entra-id/blob/master/CHANGELOG.md',
+    'source_code_uri' => 'https://github.com/pond/omniauth-entra-id'
   }
 
-  s.add_runtime_dependency('omniauth-oauth2', '~> 1.8')
+  s.add_runtime_dependency 'jwt',             '>= 2.9.2'
+  s.add_runtime_dependency 'omniauth-oauth2', '~> 1.8'
 
-  s.add_development_dependency('debug', '~>  1.9 ')
-  s.add_development_dependency('rake',  '~> 13.2 ')
-  s.add_development_dependency('rspec', '~>  3.13')
+  s.add_development_dependency 'debug', '~>  1.10'
+  s.add_development_dependency 'rake',  '~> 13.3'
+  s.add_development_dependency 'rspec', '~>  3.13'
 end

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-entra-id
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - RIPA Global
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-22 00:00:00.000000000 Z
+date: 2025-06-17 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.9.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.9.2
 - !ruby/object:Gem::Dependency
   name: omniauth-oauth2
   requirement: !ruby/object:Gem::Requirement
@@ -30,28 +43,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '1.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '1.10'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.2'
+        version: '13.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.2'
+        version: '13.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -66,7 +79,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
-description:
 email:
 - dev@ripaglobal.com
 executables: []
@@ -86,15 +98,14 @@ files:
 - lib/omniauth/entra_id/version.rb
 - lib/omniauth/strategies/entra_id.rb
 - omniauth-entra-id.gemspec
-homepage: https://github.com/RIPAGlobal/omniauth-entra-id
+homepage: https://github.com/pond/scimitar/
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://www.ripaglobal.com/
-  bug_tracker_uri: https://github.com/RIPAGlobal/omniauth-entra-id/issues/
-  changelog_uri: https://github.com/RIPAGlobal/omniauth-entra-id/blob/master/CHANGELOG.md
-  source_code_uri: https://github.com/RIPAGlobal/omniauth-entra-id
-post_install_message:
+  homepage_uri: https://github.com/pond/scimitar/
+  bug_tracker_uri: https://github.com/pond/omniauth-entra-id/issues/
+  changelog_uri: https://github.com/pond/omniauth-entra-id/blob/master/CHANGELOG.md
+  source_code_uri: https://github.com/pond/omniauth-entra-id
 rdoc_options: []
 require_paths:
 - lib
@@ -109,8 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: OAuth 2 authentication with the Entra ID API.
 test_files: []