SSO OpenID connect

[deepak chauhan]

Hi everyone,

I'm planning to implement OpenID Connect (OIDC) SSO on an AtoM instance using Azure AD. I've noticed there isn't much documentation regarding common pitfalls or configuration hurdles for this specific setup.

For those who have done this:

1. How complex was the setup of the arOidcPlugin? Are there any hidden dependencies beyond the standard OIDC requirements?

2. What Redirect URI did you use in your Azure App Registration? (e.g., is it the standard /login path or something specific to the plugin like /index.php/user/login?)

Any tips on mapping Azure claims to AtoM user groups would also be a huge help. Thanks!

[Johan Pieterse]

Hi

AtoM 2.10 is definitely doable, but there are a few gotchas worth flagging that the official docs don't always make obvious.

1. Setup complexity of arOidcPlugin

The arOidcPlugin requires editing multiple configuration files manually rather than just flipping a switch in the UI. (accesstomemory) The key steps are:

Create an empty file named activate-oidc-plugin in the root of your AtoM installation (accesstomemory) (permissions must match the other AtoM folders).

Change the login module to oidc in apps/qubit/config/settings.yml.

Change the user class to oidcUser in apps/qubit/config/factories.yml.

Configure the provider settings in plugins/arOidcPlugin/config/app.yml.

Hidden dependency: The OIDC plugin requires an external cache to function correctly — you need to change the storage class in factories.yml from QubitSessionStorage to QubitCacheSessionStorage. (accesstomemory) Miss this step and you'll get cryptic authentication failures. You'll need something like Memcached or Redis configured.

Also important: an administrator user must exist before activating the OIDC plugin if group membership mapping is deactivated (accesstomemory) — so create your admin account first with local auth, then switch over.

2. Redirect URI for Azure App Registration

The redirect_url in the arOidcPlugin's app.yml is the URL that Azure should redirect back to after authentication. For AtoM, this is typically:

https://your-atom-domain.com/index.php/oidc/login

This is the route the arOidcPlugin registers internally — it's not the standard /login or /user/login path. In your Azure App Registration under Authentication > Redirect URIs, enter this exact URL. Make sure the protocol matches (HTTPS in production). A mismatch here is the single most common cause of "invalid redirect" errors.

For the provider url setting in app.yml, with Azure/Entra the value will be:

https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0

And set client_id and client_secret from your Azure App Registration.

Azure-specific settings to note:

Set send_oidc_logout to false — Keycloak supports OIDC logout natively, but for other providers like Dex this should be set to false. (accesstomemory) Azure's logout behaviour differs from Keycloak, so test carefully. If you want SSO logout to work with Azure, you'll need to configure the front-channel logout URL separately in Entra.

Set server_cert to false if your Azure endpoints use publicly trusted certificates (which they do by default), or point it to the Microsoft root CA bundle.

For scopes, use at minimum: openid email profile. If you want to match users by email, the email scope is essential.

3. Mapping Azure claims to AtoM groups

This is where it gets interesting with Azure specifically. You enable this by setting set_groups_from_attributes to true, then configuring roles_source and roles_path to tell AtoM where to find role information in the OIDC tokens. (accesstomemory)

AtoM can look for roles in: access-token, id-token, verified-claims, or user-info. (accesstomemory)

For Azure/Entra, the approach is:

In your Azure App Registration, go to Token configuration > Add groups claim and select "Security groups" (or application groups if you want finer control).

Azure emits groups as object IDs by default, not friendly names. You can configure Azure to emit group display names or use App Roles instead.

If using App Roles (recommended — cleaner approach): Define roles in Azure (e.g. atom-admin, atom-editor, atom-contributor), then set roles_source: id-token and roles_path to the path where Azure puts the roles array (typically just roles).

If using Security Groups: Set roles_source: id-token and roles_path to groups. Be aware that the number of groups in the ID token cannot exceed 200 due to Azure's HTTP header size limits (Spacelift) — for large organisations this can be a real problem.

Then in user_groups, map each role value to the corresponding AtoM group_id:

user_groups:

  administrator:

    attribute_value: "atom-admin" # Must match the Azure App Role value

    group_id: 100 # AtoM administrator group

  editor:

    attribute_value: "atom-editor"

    group_id: 101

  contributor:

    attribute_value: "atom-contributor"  

    group_id: 102

The group_id values reference your AtoM database — check your aclGroup table for the correct IDs.

When group mapping is enabled, any manual group changes an admin makes in AtoM will be overwritten on the user's next OIDC login (accesstomemory) — so manage everything from Azure once you've turned this on.

User matching: Set user_matching_source to either oidc-email or oidc-username. A mismatch will result in a new user record being created. (accesstomemory) With Azure, oidc-email is usually the right choice, but make sure every Azure user has an email set — it's optional in Entra by default.

Quick tips:

Test with enable_refresh_token_use: false first to simplify debugging, then enable it once login works.

Once OIDC is activated, existing local password hashes are no longer used for authentication but become valid again if the plugin is deactivated. (accesstomemory)

Always clear the Symfony cache (php symfony cc) and restart php-fpm after any config changes.

Check AtoM's Symfony logs (log/qubit.log) for detailed OIDC error messages during troubleshooting.

Hope this helps 

Johan Pieterse
082 337-1406

--
You received this message because you are subscribed to the Google Groups "AtoM Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ica-atom-user...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/ica-atom-users/fec89691-6af5-442a-b307-5db20e0845c8n%40googlegroups.com.

[deepak chauhan]

thanks a lot for the detailed info. What about 2.9 version is it doable or better to get on 2.10 ?

[Johan Pieterse]

The OIDC plugin is fully available on v2.9.x — it was actually introduced in the 2.9.0 release. The configuration and setup is essentially the same as what I described in the earlier answer for 2.10. The 2.9 documentation covers it here: https://www.accesstomemory.org/en/docs/2.9/admin-manual/customization/authentication/#oidc-enabling

Key things specific to v2.9.x SSO:

In v2.9.1, a fix was included for not being able to access the User Menu when using CAS Authentication. (GitHub) There was also a fix for the logout route for SSO when IP is limited (GitHub) — this one is worth noting because if you're running IP restriction alongside SSO, the logout could fail on earlier 2.9.0.

Release 2.9.2 is a small release that fixes translation strings on the browse page (GitHub) — so no SSO-specific changes in 2.9.2 itself, but it does carry forward the 2.9.1 SSO fixes.

The big difference vs 2.10: AtoM 2.10.0 updated arOidcPlugin to use expires_in for access token handling (GitHub) . This is a meaningful improvement — the 2.9.x versions of the plugin handle token expiry slightly differently, which can cause issues with Azure AD where token lifetimes are tightly controlled. If you're on 2.9.2, you might encounter sessions dropping unexpectedly when access tokens expire.

Open issue worth flagging: There's an open issue (#1842) noting that activating the OIDC plugin currently removes the ability to login as a regular user to AtoM. The expected behaviour would be SSO offered in parallel with regular login. (github) This affects both 2.9.x and 2.10.x — it's still open. The issue also specifically calls out that having a working example of the OIDC plugin with Azure AD would go a long way towards its adoption. (github)

Johan Pieterse
082 337-1406

To view this discussion visit https://groups.google.com/d/msgid/ica-atom-users/a1236ac9-e899-4d42-9ee9-d63d8c79654dn%40googlegroups.com.

[deepak chauhan]

thanks a lot johan.