Microsoft SSO

By default, when you install the app, users log in using a combination of a username and password.

However, in practice, the Digital Collections use Microsoft’s Entra to authenticate users.

The PR has a lot of details and context.
Authentication is provided by two gems, omniauth-entra-id and omniauth-rails_csrf_protection.
A feature switch, ENV setting :log_in_using_microsoft_sso, determines whether the app uses Microsoft SSO to sign in or not. This is turned off by default, so if you want to use it in Dev, you will need to add some env variables (see “using SSO in dev”).
If Microsoft’s SSO service stops working or is not available, just turn off :log_in_using_microsoft_sso. Then you can log in using your email and password.
The Microsoft auth provider is configured with three more ENV settings:
- :microsoft_sso_client_id identifies the app to Microsoft SSO;
- :microsoft_sso_client_secret authenticates the app to Microsoft SSO;
- :microsoft_sso_tenant_id identifies the Microsoft SSO directory the app wants to check (namely the Institute one. This ID is the same for dev, staging and prod.)
Most of the configuration is done in two files:
- config/initializers/devise.rb
- config/routes.rb
Keys, values and secrets are stored in the usual spot, in 1Password.
There are three “app registrations” registered with Microsoft: one for dev (should work with any and all developers, assuming the app is at port 3000), one for staging, and one for production.
- These registrations are tied to hostnames, so if we add or change a hostname, they need to be edited.
- For a registration to function, it needs to have the following three Microsoft Graph permissions configured:
  - Microsoft Graph > openid
  - Microsoft Graph > profile
  - Microsoft Graph > User.Read
- The production secret is set to expire on 4/23/2025.
- To swap out the secret:
  - More than one secret can be active at once, so you should be able to do this with no downtime.
  - Go to http://portal.azure.com (this URL will likely change soon)
    - Find the app registrations
    - Find the Digital Collections (production) app registration
  - Click “New Client Secret”
  - Make a note of the value of the new secret
    - Note: we actually don’t need the Secret ID.
    - You can only see the value once, so be careful here.
  - Set the value of MICROSOFT_SSO_CLIENT_SECRETHeroku setting in production to the new value
  - Also update the corresponding entry in the password store (i.e. 1Password).
  - Delete any other files that might contain the value of the secret. It should exist only in the password store and in Heroku.

Using SSO in a development environment

SSO is turned off by default in development. If you want to try using SSO in development, you can temporarily add something like the following to your local_env.yml file:

log_in_using_microsoft_sso:  true
microsoft_sso_client_id:     [...]
microsoft_sso_client_secret: [...]
microsoft_sso_tenant_id:     [...]

Copy the last three keys directly from the dev SSO entry in the password store.

All developers can use the same keys.