omniauth-entra-id 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 12d51e6e7781fc58e98afb3631c673ffe033f6b606ddb549df20e8baaae1c5af
+  data.tar.gz: 8b507bae0a8bbf2e72601e3e3be9c9d0513977528988ee04f9f70b5a8ce1672d
+SHA512:
+  metadata.gz: 3595a1f659a7429216de6f00a39949b4a70655e4505bf6d126e9ea158569b977f0a7af8ebddb3df7791f89e85ad1ca35b53d926fc8bc6727d5477a06b20fc18a
+  data.tar.gz: c090da890e3c2c2edd5a4f36e922f5eadae2caf498c5cd9ba398eaba6c62c2ef055ff4cf4da487dc353cf79438abd8004c2c6cb09e9fe8024184c51b2e77642d

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Change Log
+
+## v3.0.0 (2024-10-22)
+
+* To upgrade from the Azure ActiveDirectory V2 gem, please see [`UPGRADING.md`](UPGRADING.md)
+* Branched from `omniauth-azure-activedirectory-v2` 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)

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at dev@ripaglobal.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+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
+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,229 @@
+# OmniAuth::Entra::Id
+
+[![Gem Version](https://badge.fury.io/rb/omniauth-entra-id.svg)](https://rubygems.org/gems/omniauth-entra-id)
+[![Build Status](https://github.com/RIPAGlobal/omniauth-entra-id/actions/workflows/master.yml/badge.svg)](https://github.com/RIPAGlobal/omniauth-entra-id/actions)
+[![License](https://img.shields.io/github/license/RIPAGlobal/omniauth-entra-id.svg)](LICENSE.txt)
+
+OAuth 2 authentication with [Entra ID API](https://learn.microsoft.com/en-us/entra/identity-platform/v2-overview). Rationale:
+
+* https://github.com/marknadig/omniauth-azure-oauth2 is no longer maintained.
+* https://github.com/marknadig/omniauth-azure-oauth2/pull/29 contains important additions.
+
+This gem combines the two and makes some changes to support the Entra API. The old ActiveDirectory V1 API used OpenID Connect. If you need this, a gem from Microsoft [is available here](https://github.com/AzureAD/omniauth-azure-activedirectory), but seems to be abandoned.
+
+**If upgrading from older versions of this gem under its old name of "Azure ActiveDirectory V2", please follow the instructions in [`UPGRADING.md`](UPGRADING.md).**
+
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'omniauth-entra-id'
+```
+
+And then execute:
+
+```shell
+$ bundle install
+```
+
+Or install it yourself as:
+
+```shell
+$ gem install omniauth-entra-id
+```
+
+
+
+## Usage
+
+Please start by reading https://github.com/marknadig/omniauth-azure-oauth2 for basic configuration and background information. Note that with this gem, you must use strategy name `entra_id` rather than `azure_oauth2`. Additional configuration information is given below.
+
+### Entra ID server configuration
+
+In most cases, you only want to receive 'verified' email addresses in your application. For older app registrations in the Entra portal, this may need to be [enabled explicitly](https://learn.microsoft.com/en-us/graph/applications-authenticationbehaviors?tabs=http#prevent-the-issuance-of-email-claims-with-unverified-domain-owners). It's [enabled by default](https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization#how-do-i-protect-my-application-immediately) for new multi-tenant app registrations made after June 2023.
+
+### Implementation
+#### With `OmniAuth::Builder`
+
+You can do something like this for a static / fixed configuration:
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider(
+    :entra_id,
+    {
+      client_id:     ENV['ENTRA_CLIENT_ID'],
+      client_secret: ENV['ENTRA_CLIENT_SECRET']
+    }
+  )
+end
+```
+
+...or, if using a custom provider class (called `YouTenantProvider` in this example, described in more detail later):
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider(
+    :entra_id,
+    YouTenantProvider
+  )
+end
+```
+
+#### With Devise
+
+In your `config/initializers/devise.rb` file you can do something like this for a static / fixed configuration:
+
+```ruby
+config.omniauth(
+  :entra_id,
+  {
+    client_id:     ENV['ENTRA_CLIENT_ID'],
+    client_secret: ENV['ENTRA_CLIENT_SECRET']
+  }
+)
+```
+
+...or, if using a custom provider class (called `YouTenantProvider` in this example, described in more detail later):
+
+```ruby
+config.omniauth(
+  :entra_id,
+  YouTenantProvider
+)
+```
+
+### Configuration options
+
+All of the items listed below are optional, unless noted otherwise. They can be provided either in a static configuration Hash as shown in examples above, or via *read accessor instance methods* in a provider class (more on this later).
+
+To have your application authenticate with Entra via a client secret, specify `client_secret`. If you instead want to use certificate-based authentication via client assertion, give the `certificate_path` and `tenant_id` instead. You should provide only `client_secret` or `certificate_path`, not both.
+
+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'`. |
+
+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.
+
+#### Explaining `custom_policy` and `tenant_name`
+
+When using Azure ActiveDirectory B2C - which seems to be distinct from Entra ID and not renamed as of October 2024 - tenants can define custom policies. With normal OAuth use cases, when the underlying `oauth2` gem creates the request for getting a token via POST, it places all `params` (which would include anything you've provided in the normal configuration to name your custom policy) in the `body` of the request. This would not work. Microsoft's documentation indicates that when [requesting a token](https://learn.microsoft.com/en-us/azure/active-directory-b2c/access-tokens#request-a-token), they want the name of custom policies to be given in the URL rather than in the body of the request. They ignore a custom policy specified in the body.
+
+Solve this for B2C use cases by giving your tenant name and custom policy name in the relevant configuration options. This causes a base URL to be constructed as follows:
+
+```
+<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy-name>/oauth2/v2.0/...
+```
+
+#### Explaining `authorize_params`
+
+The `authorize_params` hash-like object contains key-value pairs which are added to existing standard OAuth data in the initial `POST` request made by this gem from your web site, to the Microsoft Entra login page, at the start of OAuth flow. You can find these listed some way down the table just below an OAuth URL example at:
+
+* https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow#request-an-authorization-code
+
+...looking for in particular items from `prompt` onwards. For example, Microsoft say that a prompt option of `select_account` will always lead to the account selection UI to be shown at login, whether or not the user is currently signed into a Microsoft Entra ID account in that browser session. You would active it using options that look something like this in your OmniAuth Builder or Devise setup code:
+
+```ruby
+{
+  client_id:        ENV['ENTRA_CLIENT_ID'],
+  client_secret:    ENV['ENTRA_CLIENT_SECRET']
+  authorize_params: {
+    prompt: 'select_account'
+  }
+}
+```
+
+
+
+#### Dynamic options via a custom provider class
+
+Documentation mentioned earlier at https://github.com/marknadig/omniauth-azure-oauth2#usage gives an example of setting tenant ID dynamically via a custom provider class. We can also use that class in other ways. For example, let's rewrite it thus:
+
+```ruby
+class YouTenantProvider
+  def initialize(strategy)
+    @strategy = strategy
+  end
+
+  def client_id
+    ENV['ENTRA_CLIENT_ID']
+  end
+
+  def client_secret
+    ENV['ENTRA_CLIENT_SECRET']
+  end
+
+  def authorize_params
+    ap = {}
+
+    if @strategy.request && @strategy.request.params['login_hint']
+      ap['login_hint'] = @strategy.request.params['login_hint']
+    end
+
+    # (...and/or set other options such as 'prompt' here...)
+
+    return ap
+  end
+end
+```
+
+In this example, we're providing custom `authorize_params`. You can just return a standard Ruby Hash here, using lower case String or Symbol keys. The `strategy` value given to the initializer is an instance of [`OmniAuth::Strategies::EntraId`](https://github.com/RIPAGlobal/omniauth-entra-id/blob/master/lib/omniauth/strategies/entra_id.rb) which is a subclass of [`OmniAuth::Strategies::OAuth2`](https://www.rubydoc.info/gems/omniauth-oauth2/1.8.0/OmniAuth/Strategies/OAuth2), but that's not all that helpful! What's more useful is to know that **the Rails `request` object is available via `@strategy.request` and, likewise, the session store via `@strategy.session`**. This gives you a lot of flexibility for responding to an inbound request or user session, varying the parameters used for the Entra OAuth flow.
+
+In method `#authorize_params` above, the request object is used to look for a `login_hint` query string entry, set in whichever view(s) is/are presented by your application for use when your users need to be redirected to the OmniAuth controller in order to kick off OAuth with Entra. The value is copied into the `authorize_params` Hash. Earlier, it was mentioned that there was a special case of `prompt` being pulled from the request URL query data, but that this could also be done via a custom provider - here, you can see how; just check `@strategy.request.params['prompt']` and copy that into `authorize_params` if preset.
+
+> **NB:** Naming things is hard! The predecessor gem used the name `YouTenantProvider` since it was focused on custom tenant provision, but if using this in a more generic way, perhaps consider a more generic name such as, say, `CustomOmniAuthEntraProvider`.
+
+#### Special case scope override
+
+If required and more convenient, you can specify a custom `scope` value via generation of an authorisation URL including that required `scope`, rather than by using a custom provider class with `def scope...end` method. Include the `scope` value in your call to generate the URL thus:
+
+```ruby
+omniauth_authorize_url('resource_name_eg_user', 'entra_id', scope: '...')
+```
+
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/RIPAGlobal/omniauth-entra-id. This project is intended to be a safe, welcoming space for collaboration so contributors must adhere to the [code of conduct](https://github.com/RIPAGlobal/omniauth-entra-id/blob/master/CODE_OF_CONDUCT.md).
+
+### Getting running
+
+* Fork the repository
+* Check out your fork
+* `cd` into the repository
+* `bin/setup`
+* `bundle exec rspec` to make sure all the tests run
+
+### Making changes
+
+* Make your change
+* Add tests and check that `bundle exec rspec` still runs successfully
+* For new features (rather than bug fixes), update `README.md` with details
+
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+
+
+## Code of Conduct
+
+Everyone interacting in this project's codebases, issue trackers, chat rooms and mailing lists must follow the [code of conduct](https://github.com/RIPAGlobal/omniauth-entra-id/blob/master/CODE_OF_CONDUCT.md).

data/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`.

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/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

data/lib/omniauth/entra_id.rb

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

data/lib/omniauth/strategies/entra_id.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'omniauth-oauth2'
+
+module OmniAuth
+  module Strategies
+    class EntraId < OmniAuth::Strategies::OAuth2
+      BASE_URL = 'https://login.microsoftonline.com'
+
+      option :name,            'entra_id'
+      option :tenant_provider, nil
+      option :jwt_leeway,      60
+
+      DEFAULT_SCOPE    = 'openid profile email'
+      COMMON_TENANT_ID = 'common'
+
+      # The tenant_provider must return client_id, client_secret and,
+      # optionally, tenant_id and base_url.
+      #
+      args [:tenant_provider]
+
+      def client
+        provider = if options.tenant_provider
+          options.tenant_provider.new(self)
+        else
+          options
+        end
+
+        options.client_id = provider.client_id
+
+        if provider.respond_to?(:client_secret) && provider.client_secret
+          options.client_secret = provider.client_secret
+        elsif provider.respond_to?(:certificate_path) && provider.respond_to?(:tenant_id) && provider.certificate_path && provider.tenant_id
+          options.token_params = {
+            tenant:                provider.tenant_id,
+            client_id:             provider.client_id,
+            client_assertion:      client_assertion(provider.tenant_id, provider.client_id, provider.certificate_path),
+            client_assertion_type: client_assertion_type
+          }
+        else
+          raise ArgumentError, "You must provide either client_secret or certificate_path and tenant_id"
+        end
+
+        options.tenant_id = if provider.respond_to?(:tenant_id)
+          provider.tenant_id
+        else
+          COMMON_TENANT_ID
+        end
+
+        options.base_url = if provider.respond_to?(:base_url )
+          provider.base_url
+        else
+          BASE_URL
+        end
+
+        options.tenant_name                  = provider.tenant_name      if provider.respond_to?(:tenant_name)
+        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.authorize_params.prompt      = request.params['prompt']  if defined?(request) && request.params['prompt']
+
+        options.authorize_params.scope = if defined?(request) && request.params['scope']
+          request.params['scope']
+        elsif provider.respond_to?(:scope) && provider.scope
+          provider.scope
+        else
+          DEFAULT_SCOPE
+        end
+
+        oauth2 = if provider.respond_to?(:adfs?) && provider.adfs?
+          'oauth2'
+        else
+          'oauth2/v2.0'
+        end
+
+        tenanted_endpoint_base_url = if options.custom_policy && options.tenant_name
+          "https://#{options.tenant_name}.b2clogin.com/#{options.tenant_name}.onmicrosoft.com/#{options.custom_policy}"
+        else
+          "#{options.base_url}/#{options.tenant_id}"
+        end
+
+        options.client_options.authorize_url = "#{tenanted_endpoint_base_url}/#{oauth2}/authorize"
+        options.client_options.token_url     = "#{tenanted_endpoint_base_url}/#{oauth2}/token"
+
+        super
+      end
+
+      uid do
+        #
+        # 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.
+        #
+        raw_info['tid'] + raw_info['oid']
+      end
+
+      info do
+        {
+          name:       raw_info['name'],
+          email:      raw_info['email'],
+          nickname:   raw_info['unique_name'],
+          first_name: raw_info['given_name'],
+          last_name:  raw_info['family_name']
+        }
+      end
+
+      extra do
+        { raw_info: raw_info }
+      end
+
+      def callback_url
+        full_host + callback_path
+      end
+
+      # https://learn.microsoft.com/en-us/entra/identity-platform/id-tokens
+      #
+      # Some account types from Microsoft seem to only have a decodable ID token,
+      # with JWT unable to decode the access token. Information is limited in those
+      # cases. Other account types provide an expanded set of data inside the auth
+      # token, which does decode as a JWT.
+      #
+      # Merge the two, allowing the expanded auth token data to overwrite the ID
+      # token data if keys collide, and use this as raw info.
+      #
+      def raw_info
+        if @raw_info.nil?
+          id_token_data = begin
+            ::JWT.decode(access_token.params['id_token'], nil, false).first
+          rescue StandardError
+            {}
+          end
+
+          # 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.
+          #
+          issuer = if options.tenant_id.nil? || options.tenant_id == COMMON_TENANT_ID
+            nil
+          else
+            "#{options.base_url || BASE_URL}/#{options.tenant_id}/v2.0"
+          end
+
+          # 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]
+          )
+
+          auth_token_data = begin
+            ::JWT.decode(access_token.token, nil, false).first
+          rescue StandardError
+            {}
+          end
+
+          id_token_data.merge!(auth_token_data)
+          @raw_info = id_token_data
+        end
+
+        @raw_info
+      end
+
+      # https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow#request-an-access-token-with-a-certificate-credential
+      #
+      # The below methods support the flow for using certificate-based client
+      # assertion authentication.
+      #
+      def client_assertion_type
+        'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
+      end
+
+      def client_assertion_claims(tenant_id, client_id)
+        {
+          'aud' => "https://login.microsoftonline.com/#{tenant_id}/oauth2/v2.0/token",
+          'exp' => Time.now.to_i + 300,
+          'iss' => client_id,
+          'jti' => SecureRandom.uuid,
+          'nbf' => Time.now.to_i,
+          'sub' => client_id,
+          'iat' => Time.now.to_i
+        }
+      end
+
+      def client_assertion(tenant_id, client_id, certificate_path)
+        certificate_file         = OpenSSL::PKCS12.new(File.read(certificate_path))
+        certificate_thumbprint ||= Digest::SHA1.digest(certificate_file.certificate.to_der)
+        private_key              = OpenSSL::PKey::RSA.new(certificate_file.key)
+
+        claims = client_assertion_claims(tenant_id, client_id)
+        x5c    = Base64.strict_encode64(certificate_file.certificate.to_der)
+        x5t    = Base64.strict_encode64(certificate_thumbprint)
+
+        JWT.encode(claims, private_key, 'RS256', { 'x5c': [x5c], 'x5t': x5t })
+      end
+    end
+  end
+end

data/lib/omniauth-entra-id.rb

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

data/omniauth-entra-id.gemspec

@@ -0,0 +1,53 @@
+# -*- encoding: utf-8 -*-
+# frozen_string_literal: true
+
+$:.push File.expand_path( '../lib', __FILE__ )
+require 'omniauth/entra_id/version'
+
+# https://guides.rubygems.org/specification-reference/
+#
+Gem::Specification.new do |s|
+  s.name                  = 'omniauth-entra-id'
+  s.version               = OmniAuth::Entra::Id::VERSION
+  s.date                  = OmniAuth::Entra::Id::DATE
+  s.summary               = 'OAuth 2 authentication with the Entra ID API.'
+  s.authors               = [ 'RIPA Global'        ]
+  s.email                 = [ 'dev@ripaglobal.com' ]
+  s.licenses              = [ 'MIT'               ]
+  s.homepage              = 'https://github.com/RIPAGlobal/omniauth-entra-id'
+
+  s.required_ruby_version = Gem::Requirement.new('>= 3.0.0')
+  s.require_paths         = ['lib']
+  s.bindir                = 'exe'
+  s.files                 = %w{
+    README.md
+    CHANGELOG.md
+    CODE_OF_CONDUCT.md
+    UPGRADING.md
+    LICENSE.txt
+
+    Gemfile
+    bin/console
+    bin/setup
+
+    lib/omniauth-entra-id.rb
+    lib/omniauth/entra_id.rb
+    lib/omniauth/entra_id/version.rb
+    lib/omniauth/strategies/entra_id.rb
+
+    omniauth-entra-id.gemspec
+  }
+
+  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'
+  }
+
+  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')
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: omniauth-entra-id
+version: !ruby/object:Gem::Version
+  version: 3.0.0
+platform: ruby
+authors:
+- RIPA Global
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omniauth-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description:
+email:
+- dev@ripaglobal.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- UPGRADING.md
+- bin/console
+- bin/setup
+- lib/omniauth-entra-id.rb
+- lib/omniauth/entra_id.rb
+- lib/omniauth/entra_id/version.rb
+- lib/omniauth/strategies/entra_id.rb
+- omniauth-entra-id.gemspec
+homepage: https://github.com/RIPAGlobal/omniauth-entra-id
+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:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.21
+signing_key:
+specification_version: 4
+summary: OAuth 2 authentication with the Entra ID API.
+test_files: []