Merge pull request #37 from RIPAGlobal/feature/v3-with-rename

Starting point for V3, with tidying and rename for Entra ID

.github/workflows/master.yml

@@ -22,7 +22,7 @@ jobs:
       with:
         ruby-version: ${{ matrix.ruby }}
         bundler-cache: true
-        rubygems: 3.5.11
+        rubygems: 3.5.12
 
     - name: Run tests
       run: bundle exec rspec --backtrace

CHANGELOG.md

@@ -1,63 +1,9 @@
 # Change Log
 
-## v2.4.0 (2024-10-17)
+## v3.0.0 (2024-10-22)
 
-Deprecation warnings for end-of-life of the gem under this name. No other changes. The GitHub repository is to be renamed and the gem released (starting at major version 3) as `omniauth-entra-id`, with some breaking changes but details of how to update will be provided in the new gem via an `UPGRADING.md` document.
-
-## v2.3.0 (2024-07-16)
-
-[Implements](https://github.com/RIPAGlobal/omniauth-azure-activedirectory-v2/pull/29) support for on-premise Active Directory installations via the `adfs` option; see `README.md` for details - thanks @frenkel!
-
-## v2.2.0 (2024-07-09)
-
-[Implements](https://github.com/RIPAGlobal/omniauth-azure-activedirectory-v2/pull/26) support for specifying `scope` via the authorisation URL, in addition to the prior support for static configuration or configuration via a custom provider class - thanks @nbgoodall!
-
-## v2.1.0 (2023-09-16)
-
-[Implements](https://github.com/RIPAGlobal/omniauth-azure-activedirectory-v2/pull/19) support for custom policies when using Microsoft Azure AD - thanks @stevenchanin!
-
-## v2.0.2 (2023-03-31)
-
-[Fixes](https://github.com/RIPAGlobal/omniauth-azure-activedirectory-v2/pull/16) inability to override prompt in authorisation parameters - thanks @lamroger!
-
-## v2.0.1 (2023-01-11)
-
-Renames:
-
-* RIPGlobal -> RIPAGlobal
-* Omniauth -> OmniAuth
-
-_No functional change._
-
-## v2.0.0 (2022-09-14)
-
-Makes compatible with OmniAuth 2 and requires it.
-
-Note: https://github.com/RIPAGlobal/omniauth-azure-activedirectory-v2/pull/6 for reasoning - Thanks @jessieay
-
-_Major version bump as no longer supports OmniAuth 1._
-
-## v1.0.0 (2020-09-25)
-
-Removes use of the https://graph.microsoft.com/v1.0/me API.
-
-* One of the key differences for the V2 API vs V1 is the differences
-  between who can sign with the addition of Personal Accounts - see:
-  https://nicolgit.github.io/AzureAD-Endopoint-V1-vs-V2-comparison/
-
-  - In testing we found that these accounts may not have access to
-    this endpoint
-  - All the data provided in `info` exists in the JWT anyway, so this
-    cuts down on API calls
-
-* Conforms to the OmniAuth Auth Hash Schema (1.0 and later) - see:
-  https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema
-
-  - Expose `raw_info`
-  - Remove `id` from `info`
-    - *NB: This could be a breaking change for some, but most will
-           already be using the correct property name of `uid`.*
-
-## v0.1.1 (2020-09-23)
-
-- First release.
+* To upgrade from the Azure ActiveDirectory V2 gem, please see [`UPGRADING.md`](UPGRADING.md)
+* Branched from `omniauth-entra-id` version 2.4.0 and renamed to `omniauth-entra-id`
+* Can specify `tenant_name` in options via #31 (thanks to @Jureamer) for B2C login
+* Supports authenticating with a certificate instead of client secret via #32 (thanks to @juliaducey)
+* ID token extraction and validation is improved; long-standing fault with UID generation from OIDs (see #33) addressed via #34 (thanks to @tom-brouwer-bex)

Gemfile

@@ -1,5 +1,5 @@
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in omniauth-azure-activedirectory-v2.gemspec
+# Specify your gem's dependencies in omniauth-entra-id.gemspec
 #
 gemspec

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 Jesse Whitham
+Copyright (c) 2024 RIPA Global
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

UPGRADING.md

@@ -0,0 +1,97 @@
+# Upgrading from `omniauth-azure-activedirectory-v2`
+
+This guide assumes you were on v2.3 or v2.4 of the old-named gem. The basic steps are:
+
+* Update your code to account for the rename
+* Update your code to account for breaking changes
+
+
+
+## Updates due to the gem rename
+
+All gem users will likely need to follow these steps.
+
+* In general, searching project-wide for `azure_activedirectory_v2` and replacing with `entra_id` and, likewise, for the hyphenated `azure-activedirectory-v2` and replacing with `entra-id`, will cover a lot of use cases
+* `README.md` always included examples with environment variables that were named as illustrations only; these have changed from e.g. `AZURE_CLIENT_ID` to `ENTRA_CLIENT_ID` just for internal consistency, but while renaming your own related environment variables or constants (should you use any) may help with code base understanding and consistency, it's not essential. Those names are part of _your_ code base, not part of code in this gem.
+
+### Configuration
+
+Rename the strategy in your configuration block:
+
+```ruby
+config.omniauth(
+  :azure_activedirectory_v2,
+  # ...
+)
+```
+
+...becomes:
+
+```ruby
+config.omniauth(
+  :entra_id,
+  # ...
+)
+```
+
+### Callback routes
+
+Depending on how you handle callbacks from OmniAuth, you might need to update routes or controllers handling shared routes to account for the name change. The old callback URL of:
+
+```
+https://example.com/v1/auth/azure_activedirectory_v2/callback
+```
+
+...is now:
+
+```
+https://example.com/v1/auth/entra/callback
+```
+
+### URL generation
+
+Change things like this:
+
+```
+omniauth_authorize_url('resource_name_eg_user', 'azure_activedirectory_v2', scope: '...')
+```
+
+...to this:
+
+```
+omniauth_authorize_url('resource_name_eg_user', 'entra_id', scope: '...')
+```
+
+
+
+## Updates due to other breaking changes
+
+### Critical breaking change for all gem users
+
+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.
+
+You have two options, should the issue affect you (and it almost certainly will).
+
+* 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.
+  - If you can find a user with that ID, then all good - they've been migrated already or got connected to Entra *after* you started using the updated gem
+  - Otherwise, check `request.env['omniauth.auth'].extra.dig('raw_info', 'oid')` - this gives the value that the *old Azure ActiveDirectory V2 gem* used as UID
+  - Look up the user with this ID. If you find them, great; remember to migrate their record by updating their stored auth ID to the new `request.env['omniauth.auth'].uid` value.
+  - 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
+
+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
+
+* 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`.

bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "omniauth/azure/activedirectory/v2"
+require "omniauth/entra/id"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

lib/omniauth-entra-id.rb

@@ -0,0 +1 @@
+require File.join('omniauth', 'entra_id')

lib/omniauth/entra_id.rb

@@ -0,0 +1,2 @@
+require File.join('omniauth', 'entra_id', 'version')
+require File.join('omniauth', 'strategies', 'entra_id')

lib/omniauth/entra_id/version.rb

@@ -0,0 +1,8 @@
+module OmniAuth
+  module Entra
+    module Id
+      VERSION = "3.0.0"
+      DATE    = "2024-10-22"
+    end
+  end
+end