mirror of
https://github.com/Lissy93/dashy.git
synced 2026-08-01 03:57:03 -04:00
112 lines
66 KiB
HTML
112 lines
66 KiB
HTML
<!doctype html>
|
||
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-authentication/header-auth" data-has-hydrated="false">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="generator" content="Docusaurus v3.10.1">
|
||
<title data-rh="true">Header Authentication | Dashy</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="keywords" content="dashy, dashboard, homelab, self-hosted, docker, homepage"><meta data-rh="true" property="og:type" content="website"><meta data-rh="true" property="og:url" content="https://dashy.to"><meta data-rh="true" property="og:image" content="https://dashy.to/img/dashy.png"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" name="twitter:title" content="Dashy - The Ultimate Homepage for your Homelab"><meta data-rh="true" name="twitter:description" content="Dashy is a self-hosted dashboard app for your homelab. Manage all your services, with status checks, widgets, themes and more."><meta data-rh="true" name="twitter:image" content="https://dashy.to/img/dashy.png"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Header Authentication | Dashy"><meta data-rh="true" name="description" content="Header authentication lets Dashy trust a reverse proxy in front of it to handle login. The proxy authenticates the user, then passes their username to Dashy in an HTTP header. Dashy reads that header and signs them in automatically, so there's no separate Dashy login page."><meta data-rh="true" property="og:description" content="Header authentication lets Dashy trust a reverse proxy in front of it to handle login. The proxy authenticates the user, then passes their username to Dashy in an HTTP header. Dashy reads that header and signs them in automatically, so there's no separate Dashy login page."><link data-rh="true" rel="icon" href="/img/favicon.ico"><link data-rh="true" rel="canonical" href="https://dashy.to/docs/authentication/header-auth"><link data-rh="true" rel="alternate" href="https://dashy.to/docs/authentication/header-auth" hreflang="en"><link data-rh="true" rel="alternate" href="https://dashy.to/docs/authentication/header-auth" hreflang="x-default"><script data-rh="true" type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Authentication","item":"https://dashy.to/docs/authentication"},{"@type":"ListItem","position":2,"name":"Header Authentication","item":"https://dashy.to/docs/authentication/header-auth"}]}</script><link rel="manifest" href="/manifest.json">
|
||
<meta name="theme-color" content="#54bff7">
|
||
<link rel="apple-touch-icon" href="/img/dashy.png">
|
||
|
||
|
||
<link rel="preconnect" href="https://pixelflare.cc">
|
||
<link rel="preconnect" href="https://cdn.as93.net">
|
||
<link rel="dns-prefetch" href="https://api.github.com">
|
||
<link rel="dns-prefetch" href="https://no-track.as93.net">
|
||
<script type="application/ld+json">{"@context":"https://schema.org","@type":"WebSite","name":"Dashy","url":"https://dashy.to","description":"The Ultimate Homepage for your Homelab","publisher":{"@type":"Person","name":"Alicia Sykes","url":"https://aliciasykes.com"}}</script>
|
||
<link rel="alternate" type="application/rss+xml" title="Dashy — Releases & Updates" href="/rss.xml">
|
||
<script src="https://no-track.as93.net/js/script.js" defer="defer" data-domain="dashy.to"></script><link rel="stylesheet" href="/assets/css/styles.0f46e5de.css">
|
||
<script src="/assets/js/runtime~main.766f6c4e.js" defer="defer"></script>
|
||
<script src="/assets/js/main.8ec23672.js" defer="defer"></script>
|
||
</head>
|
||
<body>
|
||
<svg style="display: none;"><defs>
|
||
<symbol id="theme-svg-external-link" viewBox="0 0 24 24"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol>
|
||
</defs></svg>
|
||
<script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||"dark"),document.documentElement.setAttribute("data-theme-choice",t||"dark")}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><div class="banner_woPo"><a class="link_ecgS" title="View the changelog, to see what's new!" href="/updates">Dashy <!-- -->V4.5.2<!-- --> is now live 🚀</a><a class="link2_y3x6" title="View the changelog, to see what's new!" href="/updates">See what's new…</a><button class="closeBtn_fC0A" title="Dismiss update, and don't show again" aria-label="Dismiss update, and don't show again">×</button></div><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="theme-layout-navbar navbar navbar--fixed-top navbarHideable_m1mJ"><div class="navbar__inner"><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/dashy.png" alt="Dashy Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/img/dashy.png" alt="Dashy Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><b class="navbar__title text--truncate">Dashy</b></a><a href="https://github.com/lissy93/dashy" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a><a href="https://demo.dashy.to" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Live Demo<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a><a class="navbar__item navbar__link" href="/docs/quick-start">Quick Start</a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs">Documentation</a><a class="navbar__item navbar__link" href="/api">API</a><a class="navbar__item navbar__link" href="/updates">Changelog</a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill="currentColor" d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"></path></svg></button></div><div class="navbarSearchContainer_Bca1"><div class="navbar__search searchBarContainer_NW3z" dir="ltr"><input placeholder="Search" aria-label="Search" class="navbar__search-input searchInput_YFbd" value=""><div class="loadingRing_RJI3 searchBarLoadingRing_YnHq"><div></div><div></div><div></div><div></div></div></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="theme-layout-main main-wrapper mainWrapper_z2l0"><div class="docsWrapper_hBAB"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docRoot_UBD9"><aside class="theme-doc-sidebar-container docSidebarContainer_YfHR"><div class="sidebarViewport_aRkj"><div class="sidebar_njMd sidebarWithHideableNavbar_wUlq"><a tabindex="-1" class="sidebarLogo_isFc" href="/"><img src="/img/dashy.png" alt="Dashy Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/img/dashy.png" alt="Dashy Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"><b>Dashy</b></a><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/docs/quick-start"><span title="Running Dashy" class="categoryLinkLabel_W154">Running Dashy</span></a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" role="button" aria-expanded="true" href="/docs/icons"><span title="Feature Docs" class="categoryLinkLabel_W154">Feature Docs</span></a></div><ul class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/icons"><span title="Icons" class="linkLabel_WmDU">Icons</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/widgets"><span title="Widgets" class="linkLabel_WmDU">Widgets</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/theming"><span title="Theming" class="linkLabel_WmDU">Theming</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/status-indicators"><span title="Status Indicators" class="linkLabel_WmDU">Status Indicators</span></a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--active" tabindex="0" href="/docs/authentication"><span title="Authentication" class="categoryLinkLabel_W154">Authentication</span></a><button aria-label="Collapse sidebar category 'Authentication'" aria-expanded="true" type="button" class="clean-btn menu__caret"></button></div><ul class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/authentication/authelia-oidc"><span title="Authelia OIDC" class="linkLabel_WmDU">Authelia OIDC</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/authentication/authentik"><span title="Authentik OIDC" class="linkLabel_WmDU">Authentik OIDC</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/authentication/built-in"><span title="Built-In Auth" class="linkLabel_WmDU">Built-In Auth</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/authentication/cloudflare-tunnel"><span title="Cloudflare Tunnel" class="linkLabel_WmDU">Cloudflare Tunnel</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/authentication/header-auth"><span title="Header Authentication" class="linkLabel_WmDU">Header Authentication</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/authentication/keycloak"><span title="Keycloak" class="linkLabel_WmDU">Keycloak</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/authentication/oidc"><span title="OIDC" class="linkLabel_WmDU">OIDC</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/authentication/other-auth-methods"><span title="Other Auth Methods" class="linkLabel_WmDU">Other Auth Methods</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/authentication/pocketid"><span title="Pocket ID OIDC" class="linkLabel_WmDU">Pocket ID OIDC</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/authentication/tailscale"><span title="Tailscale" class="linkLabel_WmDU">Tailscale</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/authentication/zitadel"><span title="Zitadel OIDC" class="linkLabel_WmDU">Zitadel OIDC</span></a></li></ul></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/searching"><span title="Search & Shortcuts" class="linkLabel_WmDU">Search & Shortcuts</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/alternate-views"><span title="Alternate Views & Opening Methods" class="linkLabel_WmDU">Alternate Views & Opening Methods</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/multi-language-support"><span title="Internationalization" class="linkLabel_WmDU">Internationalization</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/backup-restore"><span title="Cloud Backup and Restore" class="linkLabel_WmDU">Cloud Backup and Restore</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/pages-and-sections"><span title="Pages and Sections" class="linkLabel_WmDU">Pages and Sections</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/api"><span title="REST API" class="linkLabel_WmDU">REST API</span></a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/docs/showcase"><span title="Community" class="categoryLinkLabel_W154">Community</span></a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/docs/privacy"><span title="Misc" class="categoryLinkLabel_W154">Misc</span></a></div></li></ul></nav><button type="button" title="Collapse sidebar" aria-label="Collapse sidebar" class="button button--secondary button--outline collapseSidebarButton_PEFL"><svg width="20" height="20" aria-hidden="true" class="collapseSidebarButtonIcon_kv0_"><g fill="#7a7a7a"><path d="M9.992 10.023c0 .2-.062.399-.172.547l-4.996 7.492a.982.982 0 01-.828.454H1c-.55 0-1-.453-1-1 0-.2.059-.403.168-.551l4.629-6.942L.168 3.078A.939.939 0 010 2.528c0-.548.45-.997 1-.997h2.996c.352 0 .649.18.828.45L9.82 9.472c.11.148.172.347.172.55zm0 0"></path><path d="M19.98 10.023c0 .2-.058.399-.168.547l-4.996 7.492a.987.987 0 01-.828.454h-3c-.547 0-.996-.453-.996-1 0-.2.059-.403.168-.551l4.625-6.942-4.625-6.945a.939.939 0 01-.168-.55 1 1 0 01.996-.997h3c.348 0 .649.18.828.45l4.996 7.492c.11.148.168.347.168.55zm0 0"></path></g></svg></button></div><div class="sidebar-ad"><script async="" src="//cdn.carbonads.com/carbon.js?serve=CWYIC53L&placement=dashyto" id="_carbonads_js"></script></div></div></aside><main class="docMainContainer_TBSr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Feature Docs</span></li><li class="breadcrumbs__item"><a class="breadcrumbs__link" href="/docs/authentication"><span>Authentication</span></a></li><li class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link">Header Authentication</span></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Header Authentication</h1></header>
|
||
<p>Header authentication lets Dashy trust a reverse proxy in front of it to handle login. The proxy authenticates the user, then passes their username to Dashy in an HTTP header. Dashy reads that header and signs them in automatically, so there's no separate Dashy login page.</p>
|
||
<p>Use this when you already run something like <a href="https://www.authelia.com/" target="_blank" rel="noopener noreferrer" class="">Authelia</a>, <a href="https://goauthentik.io/" target="_blank" rel="noopener noreferrer" class="">Authentik</a>, Traefik's <code>forwardAuth</code>, Caddy's <code>forward_auth</code>, or nginx's <code>auth_request</code> in front of your services, and you want Dashy to pick up the same session.</p>
|
||
<h3 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="contents">Contents<a href="#contents" class="hash-link" aria-label="Direct link to Contents" title="Direct link to Contents" translate="no"></a></h3>
|
||
<ul>
|
||
<li class=""><a href="#configure-dashy" class="">Configure Dashy</a></li>
|
||
<li class=""><a href="#configure-your-proxy" class="">Configure your proxy</a></li>
|
||
<li class=""><a href="#logging-out" class="">Logging out</a></li>
|
||
<li class=""><a href="#example-oauth2-proxy-and-nginx" class="">Example: oauth2-proxy and nginx</a></li>
|
||
<li class=""><a href="#troubleshooting" class="">Troubleshooting</a></li>
|
||
<li class=""><a href="#security-notes" class="">Security notes</a></li>
|
||
<li class=""><a href="#how-it-works" class="">How it works</a></li>
|
||
</ul>
|
||
<h2 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="configure-dashy">Configure Dashy<a href="#configure-dashy" class="hash-link" aria-label="Direct link to Configure Dashy" title="Direct link to Configure Dashy" translate="no"></a></h2>
|
||
<p>In <code>/user-data/conf.yml</code>, set the <code>auth</code> block under <code>appConfig</code>:</p>
|
||
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#F8F8F2"><span class="token key atrule">appConfig</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">auth</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">enableHeaderAuth</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token boolean important">true</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">users</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> </span><span class="token key atrule">user</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> alice</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">hash</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> 0a7b1d4c2e</span><span class="token punctuation" style="color:rgb(248, 248, 242)">...</span><span class="token plain"> </span><span class="token comment" style="color:rgb(98, 114, 164)"># SHA-256 hash, see below</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">type</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> admin</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> </span><span class="token key atrule">user</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> bob</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">hash</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> 3f8e2b1a9d</span><span class="token punctuation" style="color:rgb(248, 248, 242)">...</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">type</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> normal</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">headerAuth</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">userHeader</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> Remote</span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain">User</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">proxyWhitelist</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> 172.18.0.2</span><br></div></code></pre></div></div>
|
||
<ul>
|
||
<li class=""><code>enableHeaderAuth</code> - turns the mode on</li>
|
||
<li class=""><code>userHeader</code> - the header holding the username. Defaults to <code>Remote-User</code>. Authelia sends <code>Remote-User</code>, Authentik sends <code>X-authentik-username</code>; use whatever yours forwards. The name is case-insensitive</li>
|
||
<li class=""><code>proxyWhitelist</code> - the IP(s) Dashy will accept the header from. Anything not on this list is rejected, which is what stops a client from setting the header itself. Required in practice: if it's empty, nothing gets through</li>
|
||
<li class=""><code>users</code> - the people allowed in. The forwarded username is matched (case-insensitive) against this list to find their <code>type</code> (<code>admin</code> or <code>normal</code>). They still need an entry here even though the proxy did the actual auth</li>
|
||
</ul>
|
||
<p>The <code>hash</code> is a SHA-256 of any string. Nobody types it, since the proxy already logged them in, but Dashy uses it to derive the session token it keeps in the browser, so each user needs one. Generate it the same way as for <a class="" href="/docs/built-in#generating-a-password-hash">built-in auth</a>.</p>
|
||
<h2 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="configure-your-proxy">Configure your proxy<a href="#configure-your-proxy" class="hash-link" aria-label="Direct link to Configure your proxy" title="Direct link to Configure your proxy" translate="no"></a></h2>
|
||
<p>Two things the proxy has to do:</p>
|
||
<ol>
|
||
<li class="">Forward the username header on every request to Dashy (e.g. <code>Remote-User: alice</code>). On most forward-auth setups this is a one-line setting</li>
|
||
<li class="">Connect to Dashy from an IP that's in <code>proxyWhitelist</code></li>
|
||
</ol>
|
||
<p>The whitelist is the security boundary, so Dashy must only be reachable through the proxy. If someone can hit Dashy directly and their IP happens to be whitelisted, they can forge the header. See <a href="#security-notes" class="">Security notes</a>.</p>
|
||
<h2 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="logging-out">Logging out<a href="#logging-out" class="hash-link" aria-label="Direct link to Logging out" title="Direct link to Logging out" translate="no"></a></h2>
|
||
<p>Dashy's logout button only clears Dashy's own session. Your session at the proxy stays alive, so the next page load signs you straight back in. To end both, point <code>logoutRedirectUrl</code> at your proxy's sign-out endpoint:</p>
|
||
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#F8F8F2"><span class="token key atrule">appConfig</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">auth</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">logoutRedirectUrl</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> https</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain">//dashy.example.com/oauth2/sign_out</span><br></div></code></pre></div></div>
|
||
<p>Logging out then sends the browser to that URL, where the proxy can destroy its session.</p>
|
||
<p>The specific endpoint depends on your proxy, but for oauth2-proxy it's usually <code>/oauth2/sign_out</code> with an <code>rd</code> query param to chain your identity provider's logout, e.g. <code>/oauth2/sign_out?rd=https://sso.example.com/logout</code> (the <code>rd</code> domain must be in oauth2-proxy's <code>whitelist_domains</code>).</p>
|
||
<hr>
|
||
<h2 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="example-oauth2-proxy-and-nginx">Example: oauth2-proxy and nginx<a href="#example-oauth2-proxy-and-nginx" class="hash-link" aria-label="Direct link to Example: oauth2-proxy and nginx" title="Direct link to Example: oauth2-proxy and nginx" translate="no"></a></h2>
|
||
<p>The following example was from <a href="https://github.com/vmario89" target="_blank" rel="noopener noreferrer" class="">@vmario89</a> (in <a href="https://github.com/lissy93/dashy/issues/2233#issuecomment-4924556178" target="_blank" rel="noopener noreferrer" class="">#2233</a>).</p>
|
||
<p><a href="https://oauth2-proxy.github.io/oauth2-proxy/" target="_blank" rel="noopener noreferrer" class="">oauth2-proxy</a> handles login against any OIDC or OAuth2 provider (Synology SSO here). nginx checks each request against its <code>/oauth2/auth</code> endpoint, then forwards the username to Dashy as <code>X-Remote-User</code>.</p>
|
||
<p>Dashy config, on top of <a href="#configure-dashy" class="">the setup above</a>. The whitelist is loopback because nginx proxies to Dashy on <code>127.0.0.1:4000</code>:</p>
|
||
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#F8F8F2"><span class="token key atrule">appConfig</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">auth</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">logoutRedirectUrl</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> https</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain">//dashy.example.com/oauth2/sign_out</span><span class="token punctuation" style="color:rgb(248, 248, 242)">?</span><span class="token plain">rd=https</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain">//sso.example.com/logout</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">headerAuth</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">userHeader</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> X</span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain">Remote</span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain">User</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">proxyWhitelist</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> 127.0.0.1</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'::1'</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">'::ffff:127.0.0.1'</span><br></div></code></pre></div></div>
|
||
<details class="details_lb9f alert alert--info details_b_Ee" data-collapsed="true"><summary>oauth2-proxy config</summary><div><div class="collapsibleContent_i85q">
|
||
<!-- -->
|
||
<div class="language-ini codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ini codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#F8F8F2"><span class="token key attr-name" style="color:rgb(241, 250, 140)">provider</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"</span><span class="token value attr-value inner-value">oidc</span><span class="token value attr-value">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">oidc_issuer_url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"</span><span class="token value attr-value inner-value">https://login.synology.nas/webman/sso</span><span class="token value attr-value">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">oidc_jwks_url</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"</span><span class="token value attr-value inner-value">https://login.synology.nas/webman/sso/openid-jwks.json</span><span class="token value attr-value">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">scope</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"</span><span class="token value attr-value inner-value">openid profile email</span><span class="token value attr-value">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">oidc_email_claim</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"</span><span class="token value attr-value inner-value">sub</span><span class="token value attr-value">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">client_id</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"</span><span class="token value attr-value inner-value"><client-id></span><span class="token value attr-value">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">client_secret</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"</span><span class="token value attr-value inner-value"><client-secret></span><span class="token value attr-value">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">cookie_secret</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"<secret>" # openssl rand -base64 32</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">cookie_name</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"</span><span class="token value attr-value inner-value">cookie_dashy</span><span class="token value attr-value">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">cookie_domains</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"</span><span class="token value attr-value inner-value">.example.com</span><span class="token value attr-value">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">cookie_secure</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">true</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">email_domains</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">[ "*" ]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">http_address</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">"</span><span class="token value attr-value inner-value">127.0.0.1:4180</span><span class="token value attr-value">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">upstreams</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">[ "static://200" ]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">set_xauthrequest</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">true</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">whitelist_domains</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token plain"> </span><span class="token value attr-value">[ "dashy.example.com", "login.synology.nas" ]</span><br></div></code></pre></div></div>
|
||
<p>And a systemd unit to run it:</p>
|
||
<div class="language-ini codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ini codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#F8F8F2"><span class="token section punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token section section-name selector" style="color:rgb(255, 121, 198)">Unit</span><span class="token section punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">Description</span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token value attr-value">OAuth2 Proxy (Dashy)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">After</span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token value attr-value">network.target</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token section punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token section section-name selector" style="color:rgb(255, 121, 198)">Service</span><span class="token section punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">User</span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token value attr-value">oauth2proxy</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">Group</span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token value attr-value">oauth2proxy</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">ExecStart</span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token value attr-value">/opt/oauth2-proxy/oauth2-proxy --config=/etc/oauth2-proxy/dashy.cfg --trusted-proxy-ip=127.0.0.1/32</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">Restart</span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token value attr-value">always</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">RestartSec</span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token value attr-value">10</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token section punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token section section-name selector" style="color:rgb(255, 121, 198)">Install</span><span class="token section punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key attr-name" style="color:rgb(241, 250, 140)">WantedBy</span><span class="token punctuation" style="color:rgb(248, 248, 242)">=</span><span class="token value attr-value">multi-user.target</span><br></div></code></pre></div></div>
|
||
</div></div></details>
|
||
<p>The load-bearing options:</p>
|
||
<ul>
|
||
<li class=""><code>set_xauthrequest = true</code> - returns the username on auth responses (<code>X-Auth-Request-User</code>) for nginx to pick up</li>
|
||
<li class=""><code>upstreams = [ "static://200" ]</code> - oauth2-proxy only answers auth checks here; nginx proxies to Dashy itself</li>
|
||
<li class=""><code>whitelist_domains</code> - must include the <code>rd=</code> logout domain, or the redirect is dropped</li>
|
||
<li class=""><code>--trusted-proxy-ip</code> - makes oauth2-proxy trust the <code>X-Forwarded-*</code> headers nginx sets</li>
|
||
</ul>
|
||
<details class="details_lb9f alert alert--info details_b_Ee" data-collapsed="true"><summary>nginx site config</summary><div><div class="collapsibleContent_i85q">
|
||
<!-- -->
|
||
<div class="language-nginx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-nginx codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#F8F8F2"><span class="token plain">map $auth_user $auth_user_local {</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> "" "";</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> ~^(?<lp>[^@]+)@.* $lp;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> default $auth_user;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">}</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">server {</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> server_name dashy.example.com;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> # TLS config here</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> location / {</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> auth_request /oauth2/auth;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> auth_request_set $auth_user $upstream_http_x_auth_request_user;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header X-Remote-User $auth_user_local;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header Host $host;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header X-Real-IP $remote_addr;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header X-Forwarded-Proto $scheme;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> error_page 401 = /oauth2/sign_in;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_pass http://127.0.0.1:4000;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> }</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> location /oauth2/ {</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_pass http://127.0.0.1:4180;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header Host $host;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header X-Real-IP $remote_addr;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header X-Scheme $scheme;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header X-Forwarded-Proto $scheme;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header X-Forwarded-Host $host;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header X-Auth-Request-Redirect $request_uri;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_set_header Content-Length "";</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_pass_request_body off;</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> }</span><br></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">}</span><br></div></code></pre></div></div>
|
||
</div></div></details>
|
||
<p><code>auth_request_set</code> reads the username from oauth2-proxy's response, and the <code>map</code> strips <code>@domain</code> from it, since oauth2-proxy forwards an email but Dashy matches the bare names in <code>auth.users</code>.</p>
|
||
<hr>
|
||
<h2 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="troubleshooting">Troubleshooting<a href="#troubleshooting" class="hash-link" aria-label="Direct link to Troubleshooting" title="Direct link to Troubleshooting" translate="no"></a></h2>
|
||
<h4 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="401-unauthorized---not-from-trusted-proxy">401 "Unauthorized - not from trusted proxy"<a href="#401-unauthorized---not-from-trusted-proxy" class="hash-link" aria-label="Direct link to 401 "Unauthorized - not from trusted proxy"" title="Direct link to 401 "Unauthorized - not from trusted proxy"" translate="no"></a></h4>
|
||
<p>The request reached Dashy from an IP that isn't in <code>proxyWhitelist</code>. The check is on the direct connection IP, so with Docker that's the proxy container's address on the shared network, not the host or the client's IP. Find it with <code>docker inspect <proxy-container></code> (or read the rejected IP from Dashy's logs) and add it.</p>
|
||
<h4 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="401-unauthorized---missing-user-header">401 "Unauthorized - missing user header"<a href="#401-unauthorized---missing-user-header" class="hash-link" aria-label="Direct link to 401 "Unauthorized - missing user header"" title="Direct link to 401 "Unauthorized - missing user header"" translate="no"></a></h4>
|
||
<p>The request came from a trusted IP but had no username header. Either the proxy isn't forwarding it, or <code>userHeader</code> doesn't match the header name the proxy actually sends. Check the exact header in your proxy config.</p>
|
||
<h4 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="user--from-upstream-proxy-was-not-found-in-confyml">"User '...' from upstream proxy was not found in conf.yml"<a href="#user--from-upstream-proxy-was-not-found-in-confyml" class="hash-link" aria-label="Direct link to "User '...' from upstream proxy was not found in conf.yml"" title="Direct link to "User '...' from upstream proxy was not found in conf.yml"" translate="no"></a></h4>
|
||
<p>The proxy sent a username with no matching entry in <code>auth.users</code>. Add a user whose <code>user</code> matches it (case doesn't matter).</p>
|
||
<h4 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="logged-in-but-cant-save-the-config">Logged in but can't save the config<a href="#logged-in-but-cant-save-the-config" class="hash-link" aria-label="Direct link to Logged in but can't save the config" title="Direct link to Logged in but can't save the config" translate="no"></a></h4>
|
||
<p>That user's <code>type</code> isn't <code>admin</code>. Saving is admin-only, so set <code>type: admin</code> on their entry.</p>
|
||
<h4 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="logging-out-just-logs-me-back-in">Logging out just logs me back in<a href="#logging-out-just-logs-me-back-in" class="hash-link" aria-label="Direct link to Logging out just logs me back in" title="Direct link to Logging out just logs me back in" translate="no"></a></h4>
|
||
<p>Expected with the default config. Logout clears Dashy's cookie, but you're still signed in at the proxy, so the next page load re-authenticates from the header. Set <code>logoutRedirectUrl</code> to your proxy's sign-out endpoint to end both sessions — see <a href="#logging-out" class="">Logging out</a>.</p>
|
||
<h2 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="security-notes">Security notes<a href="#security-notes" class="hash-link" aria-label="Direct link to Security notes" title="Direct link to Security notes" translate="no"></a></h2>
|
||
<ul>
|
||
<li class="">Header auth is only as strong as the proxy in front of it. Dashy trusts any whitelisted IP that sends the header, so the whole model depends on Dashy being unreachable except through the proxy. Lock that down at the network or firewall level</li>
|
||
<li class="">Keep <code>proxyWhitelist</code> tight: just the proxy's real connecting IP(s), nothing broader</li>
|
||
<li class="">The username and role come from <code>conf.yml</code>. A user the proxy authenticates but that you haven't listed is refused, so removing someone from <code>auth.users</code> blocks them even if the proxy still lets them through</li>
|
||
</ul>
|
||
<h2 class="anchor anchorTargetHideOnScrollNavbar_vjPI" id="how-it-works">How it works<a href="#how-it-works" class="hash-link" aria-label="Direct link to How it works" title="Direct link to How it works" translate="no"></a></h2>
|
||
<ol>
|
||
<li class="">The user hits Dashy through the proxy. The proxy authenticates them and adds the username header</li>
|
||
<li class="">On load, Dashy's frontend calls <code>/get-user</code>. The server checks the request IP against <code>proxyWhitelist</code>, and if it's trusted, reads the username from <code>userHeader</code> and returns it</li>
|
||
<li class="">The frontend looks that username up in <code>auth.users</code>, derives a session token from the user and hash, sets the auth cookie, and stores the username</li>
|
||
<li class="">From there it's normal Dashy auth: <code>isLoggedIn</code>, the admin check, and the per-page, section and item visibility rules all work as usual</li>
|
||
</ol>
|
||
<p>Server-side, the same proxy-whitelist middleware guards the config and API routes, so a request from an untrusted IP is rejected before it reaches anything. Writes (saving config) additionally require the matched user to be <code>type: admin</code>.</p>
|
||
<p>The relevant code is <code>src/utils/auth/HeaderAuth.js</code> on the frontend, and <code>services/app.js</code> with <code>services/endpoints/get-user.js</code> on the server.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col noPrint_WFHX"><a href="https://github.com/Lissy93/dashy/edit/master/docs/authentication/header-auth.md" target="_blank" rel="noopener noreferrer" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_JAkA"><span class="theme-last-updated">Last updated<!-- --> on <b><time datetime="2026-07-29T14:11:14.000Z" itemprop="dateModified">Jul 29, 2026</time></b> by <b>Liss-Bot</b></span></div></div></footer></article><nav class="docusaurus-mt-lg pagination-nav" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/authentication/cloudflare-tunnel"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Cloudflare Tunnel</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/authentication/keycloak"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Keycloak</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#contents" class="table-of-contents__link toc-highlight">Contents</a></li><li><a href="#configure-dashy" class="table-of-contents__link toc-highlight">Configure Dashy</a></li><li><a href="#configure-your-proxy" class="table-of-contents__link toc-highlight">Configure your proxy</a></li><li><a href="#logging-out" class="table-of-contents__link toc-highlight">Logging out</a></li><li><a href="#example-oauth2-proxy-and-nginx" class="table-of-contents__link toc-highlight">Example: oauth2-proxy and nginx</a></li><li><a href="#troubleshooting" class="table-of-contents__link toc-highlight">Troubleshooting</a></li><li><a href="#security-notes" class="table-of-contents__link toc-highlight">Security notes</a></li><li><a href="#how-it-works" class="table-of-contents__link toc-highlight">How it works</a></li></ul></div></div></div></div></main></div></div></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Intro</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://github.com/lissy93/dashy" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://demo.dashy.to" target="_blank" rel="noopener noreferrer" class="footer__link-item">Live Demo<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a class="footer__link-item" href="/docs/quick-start">Quick Start</a></li><li class="footer__item"><a class="footer__link-item" href="/docs">Documentation</a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Running Dashy</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/quick-start">Quick Start</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/deployment">Deployment</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/configuring">Configuring</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/management">App Management</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/troubleshooting">Troubleshooting</a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Feature Docs Pt 1</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/icons">Icons</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/widgets">Widgets</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/theming">Theming</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/status-indicators">Status Indicators</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/authentication">Authentication</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/searching">Search & Shortcuts</a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Feature Docs Pt 2</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/alternate-views">Alternate Views & Opening Methods</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/multi-language-support">Internationalization</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/backup-restore">Cloud Backup and Restore</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/pages-and-sections">Pages and Sections</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/api">REST API</a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/showcase">Dashy Showcase</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/contributing">Contributing</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/developing">Developing</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/development-guides">Development Guides</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/credits">Credits</a></li><li class="footer__item"><a href="https://github.com/Lissy93/dashy/blob/master/.github/CODE_OF_CONDUCT.md" target="_blank" rel="noopener noreferrer" class="footer__link-item">Code of Conduct<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Misc</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/privacy">Privacy</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/security">Security</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/license">License</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/release-workflow">Releases and Workflows</a></li><li class="footer__item"><a class="footer__link-item" href="/updates">Changelog</a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright"><a href="https://dashy.to">Dashy</a> - The Self-Hosted Dashboard for your Homelab<br>License under <a href="https://github.com/Lissy93/dashy/blob/master/LICENSE">MIT</a>. Copyright © 2026 <a href="https://aliciasykes.com">Alicia Sykes</a></div></div></div></footer></div>
|
||
</body>
|
||
</html> |