Skip to main content

Microsoft Entra ID SSO for Mealie

ThisPrerequisites: guide shows how to configure Mealie with Microsoft Entra ID using OpenID Connect (OIDC).

Important design note

If you use a client secret, register the application as a Web / confidential client. Do not document it as a Single Page Application when the backend is using a client secret.

Why use OIDC with Mealie

Benefits:

    centralized login optional self-service user creation optional group-based restrictions easier identity lifecycle management

    Prerequisites

      Mealie is deployed and reachable via HTTPS you can edit environment variables or Docker Compose permissionAbility to create an app registration with delegated rights and access to the Mealie Docker volume or startup method. Mealie should be installed correctly.

      Mealie makes recipe management and planning extremely easy. The Mealie software offers an OpenID interface, which means that Microsoft Entra ID can easily be used as an identity provider and permission manager.

      Create App Registration

      First, an app registration including client secret must be created in Microsoft Entra ID

      ID. All

      Stepsettings 1:can Createbe left at the appdefault registration

      values.
      • Platform:Type: Single-page Webapplication
      • Redirect URI:URIs:  use the callback URL expected by your Mealie version and reverse proxy designhttps://mealie.yourdomain.com/login

      Recordimage.png

      Add the Tenantcorresponding permissions for OpenID Connect as delegated permissions and grant admin consent for your tenant.

        Permissions: Delegated OpenId permissions (email, offline_access, openid, profile)

        image.png

        Create a client secret for the application and save the tenant ID, Clientapplication ID and Clientclient Secret.secret in your password manager. You can find instructions for this information here: Get app details and grant permissions to app registration

        Step

        Setup 2:Microsoft ConfigureEntra ID login provider

        With Mealie, the Microsoft Entra ID configurations can be set up using environment variables. Installation using Docker is mandatory for these instructions. The following environment variables enable the configuration of the OpenID integration. You can find more information on all of Mealie's environment variables here: Backend Configuration - Mealie

        The relevant environment variables for OpenID are as follows:

          OIDC_AUTH_ENABLED: Enables authentication via OpenID Connect if set to true.
           OIDC_SIGNUP_ENABLED: Enables new users to be created when signing in for the first time with OIDC if set to true.
           OIDC_CONFIGURATION_URL: This is the URL to the configuration of the provider. Using Microsoft Entra ID this probably: https://login.microsoftonline.com//v2.0/.well-known/openid-configuration OIDC_CLIENT_ID: This is the client id of your App Registration in Microsoft Entra ID. OIDC_CLIENT_SECRET: Here you have to provide the Client Secret from the App Registration. OIDC_PROVIDER_NAME: This is the display name for the button on the sign in screen.

          Side note: As this type of configuration involves environment variables, these contents can also be transferred via the volume as an .env file, specified with a simple startup command or specified in another declarative context (Kubernetes manifest, Terraform, etc.).

          Docker compose example

          This Docker Compose file shows a possible configuration for Mealie that authenticates using Microsoft Entra ID. In addition, a mail server is also specified for outgoing SMTP mail traffic.

          Customize this content with your specifications and save the content in a normal docker-compose.yaml file. As this is Docker Compose, the application can be started easily with the following command (in detach mode -> -d):

          docker compose up -d

          version: "3.7"
services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:latest
    container_name: <yourcontainername>
    ports:
        - "8600:<yourpublicport>"
    volumes:
      - <yourpersistentpath>:/app/data/
    environment:
      - ALLOW_SIGNUP=true
      - OIDC_AUTH_ENABLED=true
      - OIDC_SIGNUP_ENABLED=true
      - OIDC_CONFIGURATION_URL=https://login.microsoftonline.com/<tenant-idyourtenantid>/v2.0/.well-known/openid-configuration
      - OIDC_CLIENT_ID=<client-idyourclientid>
      - OIDC_CLIENT_SECRET=<client-secretyourclientsecret>
      - OIDC_PROVIDER_NAME=Microsoft Entra ID
      OIDC_USER_CLAIM=email- OIDC_NAME_CLAIM=namePUID=1000
      OIDC_GROUPS_CLAIM=groups- PGID=1000
      - TZ=<yourtimezone>
      - MAX_WORKERS=1
      - WEB_CONCURRENCY=1
      - BASE_URL=https://<yourmealiedomain>
      - SMTP_HOST=<yoursmtpmailhost>
      - SMTP_PORT=587
      - SMTP_FROM_EMAIL=<yoursmtpmail>
      - SMTP_USER=<yoursmtpmailuser>
      - SMTP_PASSWORD=<yoursmtpmailpassword>
      - SMTP_FROM_NAME=<yourmailname>
    restart: unless-stopped

          Optional:

            OIDC_USER_GROUP to allow only one specific group OIDC_ADMIN_GROUP to make selected users admins ALLOW_PASSWORD_LOGIN=false only after testing

            Best practices

              keep the app registration dedicated to Mealie use HTTPS only document the exact callback URL used use group-based filtering if access should be limited disable password login only after OIDC is fully tested

              Summary

              For Mealie, Microsoft Entra ID integration should be documented as a standard OIDC confidential client pattern when a client secret is used.

              Back to top