postalserver/postal · error · Postal::Error

OIDC cannot be used unless enabled in the configuration

Error message

OIDC cannot be used unless enabled in the configuration

What it means

Raised by SessionsController#create_from_oidc, the OmniAuth callback handler for Postal's login. Before touching the identity payload it asserts Postal::Config.oidc.enabled?; when the oidc section is absent or disabled in postal.yml the callback must be inert, so any request to it fails fast with Postal::Error instead of silently mis-authenticating.

Source

Thrown at app/controllers/sessions_controller.rb:72

      flash.now[:alert] = "You must enter a new password"
      return
    end

    @user.password = params[:password]
    @user.password_confirmation = params[:password_confirmation]
    return unless @user.save

    login(@user)
    redirect_to_with_return_to root_path, notice: "Your new password has been set and you've been logged in."
  end

  def ip
    render plain: "ip: #{request.ip} remote ip: #{request.remote_ip}"
  end

  def create_from_oidc
    unless Postal::Config.oidc.enabled?
      raise Postal::Error, "OIDC cannot be used unless enabled in the configuration"
    end

    auth = request.env["omniauth.auth"]
    user = User.find_from_oidc(auth.extra.raw_info, logger: Postal.logger)
    if user.nil?
      redirect_to login_path, alert: "No user was found matching your identity. Please contact your administrator."
      return
    end

    login(user)
    flash[:remember_login] = true
    redirect_to_with_return_to root_path
  end

  def oauth_failure
    redirect_to login_path, alert: "An issue occurred while logging you in with OpenID. Please try again later or contact your administrator."
  end

View on GitHub (pinned to d038eaa8c7)

Solutions

1. Enable OIDC in postal.yml under the correct environment: oidc.enabled plus host, client_id, client_secret, issuer/authorization_endpoint/token_endpoint/userinfo_endpoint, then restart Postal
2. Verify the config is actually loaded (e.g. Postal::Config.oidc.enabled? in a rails console on the same env)
3. Check the block is nested under the right Rails.env key and that ENV interpolation for the oidc values resolves
4. If OIDC is not meant to be used, remove/avoid the /auth/postc-style SSO entry points rather than leaving the callback reachable

Example fix

# before (postal.yml)
production:
  # no oidc section -> callback raises

# after
production:
  oidc:
    enabled: true
    host: postal.example.com
    client_id: <%= ENV["POSTAL_OIDC_CLIENT_ID"] %>
    client_secret: <%= ENV["POSTAL_OIDC_CLIENT_SECRET"] %>
    issuer: https://idp.example.com
    scope: openid email profile
    authorization_endpoint: https://idp.example.com/authorize
    token_endpoint: https://idp.example.com/token
    userinfo_endpoint: https://idp.example.com/me

# before linking/redirecting users to SSO
redirect_to login_path, alert: "Single sign-on is not enabled." unless Postal::Config.oidc.enabled?

def oidc_usable?
  Postal::Config.oidc.respond_to?(:enabled?) && Postal::Config.oidc.enabled?
end

begin
  post "/auth/postal/callback"
rescue Postal::Error => e
  # configuration problem, not a user mistake: report loudly
  render plain: "SSO is not configured on this server", status: :service_unavailable
end

When it happens

Trigger: The OmniAuth callback request (GET /auth/postal/callback after the IdP redirects back) reaches the controller while postal.yml has no oidc block or enabled is false - e.g. clicking a stale SSO link on a server where OIDC was never turned on, or the callback URL is hit directly by a scanner.

Common situations: Enabling omniauth routes but forgetting the matching postal.yml oidc section (host, client_id, client_secret, issuer, scope, etc.); the oidc block placed under the wrong Rails environment key so it never loads; typos in the config key; testing the callback locally against production-style config; environment variable substitution producing an empty oidc section.

Related errors

• User has OIDC enabled, password resets are not supported
• Invalid email address
• No host was given for the request
• Could not resolve '#{@host}' to any IP address
• Destination '#{@host}' (#{address}) is not permitted

AI-assisted analysis of postalserver/postal@d038eaa8c7 (2026-08-21). Data as JSON: /api/errors/1d36b7eacdf11b54. Report an issue: GitHub.