OAuth setup with Microsoft Entra ID

[woolfyx]

Configuration Example

This guide allow you to setup the Mealie application SSO with an Entra ID tenant.

Notice

I've described 2 ways of working to manage application rights: via groups or via application roles. You can select you preferred approach.

Because the group option is only used for rights management and not groups management inside mealie application, both approach works here without any issues or limitations.

Personally I prefer to use roles because it's more adapted for roles management.

Prerequisites

• A Microsoft Entra ID tenant (free or paid plan)
• If you choose the 'groups' approach: 2 groups created with proper user added

Microsoft Entra ID configuration

1. Register a new application via the Microsoft Enta Admin center. Use your prefered name, which accounts you want to support (I have tested only the 'Single tenant' option) and put the following redirect Web URI : https://<<mydomain.tld>>/login
   

2. In the 'Authentication' tab, add the following URI to the 'Web' platform:

   • https://<<mydomain.tld>>/login?direct=1
     
     And ensure 'Access tokens' are enabled in the 'Implicit grant and hybrid flows' section
     

3. In the 'Certificates & secrets' tab, create a new client secret with the name and the duration of your choice. Save the value for later use.

4. In the 'API Permissions' tab, add the following permissions: 'email', 'openid', 'profile' and click on 'Grant admin consent'.
   

5. In the 'Token configuration' tab, add an optional claim, select 'Access' token and the 'email' claim.
   

6. If you choose the 'groups' approach: add the groups claim with the 'security' group type. If you are on a paid plan, you can select the option 'Groups assigned to the application' to reduce the token size.
   

7. If you choose the 'roles' approach: in the 'App roles' tab, create 2 roles with the name you want for users and admins. Select 'Users/Groups' as allowed member types, define a value (this is the value we will used in our mealie configuration later) and add a nice comprehensive description. Don't forget to select the last option to enable the role.

8. In the 'Overview' tab, collect the remaining information needed for the mealie configuration part:

   • In the 'Essentials' section, select the 'Application (client) ID'
   • In the 'Endpoints' button find the 'OpenID Connect metadata document' URI

Mealie configuration

If you choose to use application roles :

OIDC_AUTH_ENABLED: true
OIDC_SIGNUP_ENABLED: true
OIDC_CONFIGURATION_URL: <<< Endpoints / OpenID Connect metadata document (step 8) >>>
OIDC_CLIENT_ID: <<< Application (client) ID (step 8) >>>
OIDC_CLIENT_SECRET: <<< Client secret value (step 3) >>>
OIDC_PROVIDER_NAME: Entra ID # This value can be customized if needed
OIDC_SCOPES_OVERRIDE: openid profile email
OIDC_GROUPS_CLAIM: roles
OIDC_USER_GROUP: <<< User role value (step 7)>>>
OIDC_ADMIN_GROUP: <<< Admin role value (step 7) >>>

If you choose to use groups:

OIDC_AUTH_ENABLED: true
OIDC_SIGNUP_ENABLED: true
OIDC_CONFIGURATION_URL: <<< Endpoints / OpenID Connect metadata document (step 8) >>>
OIDC_CLIENT_ID: <<< Application (client) ID (step 8) >>>
OIDC_CLIENT_SECRET: <<< Client secret value (step 3) >>>
OIDC_PROVIDER_NAME: Entra ID # This value can be customized if needed
OIDC_SCOPES_OVERRIDE: openid profile email
OIDC_GROUPS_CLAIM: groups
OIDC_USER_GROUP: <<< User group ID (not the name) >>>
OIDC_ADMIN_GROUP: <<< Admin group ID (not the name) >>>

Update your Docker Compose stack via docker compose up -d.

You should be able to see and use the 'Login with Entra ID' button