Single Sign-On (SSO)

Setup Homechart SSO
Categories:

For self-hosted users, Homechart can integrate with your existing authentication system to allow your household members to authenticate with it or even sign in automatically.

Homechart currently supports these methods:

OpenID Connect (OIDC)

Homechart should be able to integrate with any standards-compliant OpenID Connect (OIDC) issuer. OIDC uses OAuth to provided Homechart details about a user, which Homechart will “trust” to validate the user’s authentication.

Homechart exposes numerous configurations for OIDC. The exact details of a configuration for your provider varies, but a bare minimum configuration looks something like this:

{
  "oidc": {
    "google": {
      "clientID": "a-client-id",
      "clientSecret": "a-client-secret",
      "displayName": "Google",
      "oidcIssuerURL": "https://accounts.google.com"
    }
  }
}

Homechart will use app.baseURL/oidc as the redirect URL. If app.baseURL is set to https://example.com, the redirect URL would be https://example.com/oidc. You’ll need to use the right redirect URL when generating the client ID and client secret from your issuer.

Google

You can add Google as an OIDC issuer to Homechart using the same configuration as Homechart Cloud:

  1. Follow these instructions to generate a Client ID and Client Secret: https://support.google.com/cloud/answer/6158849. The authorized redirect URL will be your Homechart instance app.baseURL/oidc.
  2. Use this configuration with Homechart:
{
  "oidc": {
    "google": {
      "clientID": "<client ID you copied from Google>",
      "clientSecret": "<client secret you copied from Google>",
      "displayName": "Google",
      "oidcIssuerURL": "https://accounts.google.com"
    }
  }
}

Microsoft

You can add Microsoft as an OIDC issuer to Homechart using the same configuration as Homechart Cloud:

  1. Follow these instructions to generate a Client ID and Client Secret: https://learn.microsoft.com/en-us/power-pages/security/authentication/openid-settings#create-an-app-registration-in-azure. The authorized redirect URL will be your Homechart instance app.baseURL/oidc.
  2. Use this configuration with Homechart:
{
  "oidc": {
    "microsoft": {
      "clientID": "<client ID you copied from Microsoft>",
      "clientSecret": "<client secret you copied from Microsoft>",
      "displayName": "Microsoft",
      "oidcIssuerURL": "https://login.microsoftonline.com/consumers/v2.0"
    }
  }
}

HTTP Headers

Homechart can be configured to trust HTTP headers from a trusted authentication provider. These HTTP headers (typically Remote-Name or Remote-Email) will be passed to Homechart from the authentication provider/proxy and users will be automatically created and/or signed into Homechart.

The architecture for this depends on the proxy sitting in front of Homechart. The example below uses Traefik and Authelia, but other setups may be supported.

Things to understand:

  • The account will be created if the email address does not exist in Homechart already. You should pre-create your household members using the email address that the SSO will pass through, otherwise they will be created under a separate household.
  • If the account already exists in Homechart, Homechart will create a new session for the account associated with the email address that the SSO passes. Please ensure you have properly configured your SSO implementation to avoid malicious users from setting the proxy headers and gaining access to your instance.
  • At a minimum, you must have the appropriate configuration values set for proxyAddress and proxyHeaderEmail to enable SSO.

Examples

Traefik + Authelia + Homechart

In this example, Traefik sits in front of Homechart and proxies request to it. Authelia is installed and configured for authentication within Traefik. Traefik will check with Authelia to see if the traffic is allowed, and then pass the proxy headers to Homechart. Homechart is configured to look for these proxy headers (Remote-Name, Remote-Email) and source address of Traefik.

In this contrived example, Authelia is configured with a local database of users. On your network, you would configure Authelia to use your authentication source, such as LDAP/Active Directory.

Traefik Dynamic Config (traefik-dynamic.yaml)
http:
  middlewares:
    authelia:
      forwardauth:
        address: http://localhost:9091/api/verify?rd=https://auth.example.com:8443
        authResponseHeaders:
          - Remote-Name
          - Remote-Email
        trustForwardHeader: true
  routers:
    authelia:
      service: authelia
      rule: "Host(`auth.example.com`)"
      tls: true
    homechart:
      middlewares:
        - authelia
      service: homechart
      rule: "Host(`homechart.example.com`)"
      tls: true
  services:
    authelia:
      loadBalancer:
        servers:
          - url: http://localhost:9091
    homechart:
      loadBalancer:
        servers:
          - url: http://localhost:3000
Traefik Command Line
./traefik --entrypoints.https=true --entrypoints.https.address=:8443 --providers.file.filename=traefik-dynamic.yaml
Authelia Config (authelia.yaml)
server:
  host: 0.0.0.0
  port: 9091
log:
  level: debug
jwt_secret: C57E160E9CE711D214BF4CCF407DE6C64FCF19A7C20E7C6D7C2FF18826A7E1AA
default_redirection_url: https://auth.example.com:8443
authentication_backend:
  file:
    path: ./users.yaml
    password:
      algorithm: argon2id
      iterations: 1
      salt_length: 16
      parallelism: 8
      memory: 1024 # blocks this much of the RAM. Tune this.
access_control:
  default_policy: one_factor
session:
  name: authelia_session
  domain: example.com
storage:
  encryption_key: superdupersecretsecret
  local:
    path: ./db.sqlite3
notifier:
  filesystem:
    filename: ./notification.txt
Authelia User Config (users.yaml)
users:
  [email protected]:
    displayname: "Jane Doe"
    password: $argon2id$v=19$m=65536,t=1,p=8$Z2JJSk9qbVlXVk9VWUtQMw$2VqsXXhvTfiHxxvmDUj8GpzPCktmMxdLR2rojFxxknc
    email: [email protected]
    groups:
      - dev
  [email protected]:
    displayname: "John Doe"
    password: "$argon2id$v=19$m=65536,t=1,p=8$MlplVVhMbzNmcXJmaVVsaA$ydwPNQ5wW3Lu1XuPWhQW7dzlNGP3ynexmzlQmyVMaIY"
    email: [email protected]
    groups:
      - dev
Authelia Command Line
./authelia-linux-amd64 --config authelia.yaml
Homechart Command Line
homechart_app_proxyAddress=[::1] homechart_app_proxyHeaderEmail=Remote-Email homechart_app_proxyHeaderName=Remote-Name ./homechart_linux_amd64 -c config.json serve