mirror/dashy
1
0
Fork 0
mirror of https://github.com/Lissy93/dashy.git synced 2026-04-24 20:27:02 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
gh-pages
dashy/docs/authentication/index.html
liss-bot b90385ad50 deploy: 80ea816def
2026-04-13 13:34:05 +00:00

348 lines
129 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!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" data-has-hydrated="false">
<head>
<meta charset="UTF-8">
<meta name="generator" content="Docusaurus v3.9.2">
<title data-rh="true">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="Authentication | Dashy"><meta data-rh="true" name="description" content="- Basic Auth"><meta data-rh="true" property="og:description" content="- Basic Auth"><link data-rh="true" rel="icon" href="/img/favicon.ico"><link data-rh="true" rel="canonical" href="https://dashy.to/docs/authentication"><link data-rh="true" rel="alternate" href="https://dashy.to/docs/authentication" hreflang="en"><link data-rh="true" rel="alternate" href="https://dashy.to/docs/authentication" 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"}]}</script><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="manifest" href="/manifest.json">
<meta name="theme-color" content="#54bff7">
<script src="https://no-track.as93.net/js/script.js" defer="defer" data-domain="dashy.to"></script><link rel="stylesheet" href="/assets/css/styles.391a2411.css">
<script src="/assets/js/runtime~main.33e41d76.js" defer="defer"></script>
<script src="/assets/js/main.45067b49.js" defer="defer"></script>
</head>
<body class="navigation-with-keyboard">
<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&#x27;s new!" href="/updates">Dashy <!-- -->V3.2.14<!-- --> is now live 🚀</a><a class="link2_y3x6" title="View the changelog, to see what&#x27;s new!" href="/updates">See what&#x27;s new…</a><button class="closeBtn_fC0A" title="Dismiss update, and don&#x27;t show again" aria-label="Dismiss update, and don&#x27;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"><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="/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"><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-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/authentication"><span title="Authentication" class="linkLabel_WmDU">Authentication</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/searching"><span title="Keyboard Shortcuts" class="linkLabel_WmDU">Keyboard 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 &amp; Opening Methods" class="linkLabel_WmDU">Alternate Views &amp; 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></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></div><div class="sidebar-ad"><script async="" src="//cdn.carbonads.com/carbon.js?serve=CWYIC53L&amp;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 breadcrumbs__item--active"><span class="breadcrumbs__link">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>Authentication</h1></header>
<ul>
<li class=""><a href="#built-in-auth" class="">Basic Auth</a>
<ul>
<li class=""><a href="#setting-up-authentication" class="">Setting Up Authentication</a></li>
<li class=""><a href="#hash-password" class="">Hash Password</a></li>
<li class=""><a href="#logging-in-and-out" class="">Logging In and Out</a></li>
<li class=""><a href="#enabling-guest-access" class="">Guest Access</a></li>
<li class=""><a href="#granular-access" class="">Granular Access</a></li>
<li class=""><a href="#permissions" class="">Permissions</a></li>
<li class=""><a href="#using-environment-variables-for-passwords" class="">Using Environment Variables for Passwords</a></li>
<li class=""><a href="#adding-http-auth-to-configuration" class="">Adding HTTP Auth to Configuration</a></li>
<li class=""><a href="#security" class="">Security</a></li>
</ul>
</li>
<li class=""><a href="#http-auth" class="">HTTP Auth</a>
<ul>
<li class=""><a href="#using-config-file-users-recommended" class="">Using Config-File Users</a></li>
<li class=""><a href="#using-static-credentials" class="">Using Static Credentials</a></li>
</ul>
</li>
<li class=""><a href="#keycloak" class="">Keycloak Auth</a></li>
<li class=""><a href="#header-authentication" class="">Header Authentication</a></li>
<li class=""><a href="#oidc" class="">OIDC Auth</a></li>
<li class=""><a href="#authentik" class="">authentik</a></li>
<li class=""><a href="#alternative-authentication-methods" class="">Alternative Authentication Methods</a>
<ul>
<li class=""><a href="#reverse-proxy-auth" class="">Reverse Proxy Auth</a></li>
<li class=""><a href="#zero-trust-tunnels" class="">Zero-Trust Tunnels</a></li>
<li class=""><a href="#vpn" class="">VPN</a></li>
<li class=""><a href="#ip-based-access" class="">IP-Based Access</a></li>
<li class=""><a href="#web-server-authentication" class="">Web Server Authentication</a></li>
<li class=""><a href="#sso--oauth-providers" class="">SSO / OAuth Providers</a></li>
<li class=""><a href="#cloud-hosting-providers" class="">Cloud Hosting Providers</a></li>
</ul>
</li>
</ul>
<div class="theme-admonition theme-admonition-important admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>important</div><div class="admonitionContent_BuS1"><p>Dashy&#x27;s built-in auth is not intended to protect a publicly hosted instance against unauthorized access. Instead you should use an auth provider compatible with your reverse proxy, or access Dashy via your VPN, or implement your own SSO logic.</p><p>If Dashy is only accessible within your home network and you just want a login page, then the built-in auth may be sufficient. To also protect server-side endpoints and config files, set <code>ENABLE_HTTP_AUTH=true</code> (see <a href="#adding-http-auth-to-configuration" class="">Adding HTTP Auth to Configuration</a>).</p></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="built-in-auth">Built-In Auth<a href="#built-in-auth" class="hash-link" aria-label="Direct link to Built-In Auth" title="Direct link to Built-In Auth" translate="no">​</a></h2>
<p>Dashy has a basic login page included, and frontend authentication. You can enable this by adding users to the <code>auth</code> section under <code>appConfig</code> in your <code>conf.yml</code>. If this section is not specified, then no authentication will be required to access the app, and the homepage will resolve to your dashboard. To also enable HTTP Authorization, set the <code>ENABLE_HTTP_AUTH</code> env var to <code>true</code>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="setting-up-authentication">Setting Up Authentication<a href="#setting-up-authentication" class="hash-link" aria-label="Direct link to Setting Up Authentication" title="Direct link to Setting Up Authentication" translate="no">​</a></h3>
<p>The <code>auth</code> property takes an array of users. Each user needs to include a username, hash and optional user type (<code>admin</code> or <code>normal</code>). The hash property is a <a href="https://en.wikipedia.org/wiki/SHA-2" target="_blank" rel="noopener noreferrer" class="">SHA-256 Hash</a> of your desired password.</p>
<p>For example:</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"><span 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></span><span 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></span><span 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></span><span 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"> alicia</span><br></span><span 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"> 4D1E58C90B3B94BCAD9848ECCACD6D2A8C9FBC5CA913304BBA5CDEAB36FEEFA3</span><br></span><span 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></span><span 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></span><span 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"> 5E884898DA28047151D0E56F8DC6292773603D0D6AABBDD62A11EF721D1542D8</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="hash-password">Hash Password<a href="#hash-password" class="hash-link" aria-label="Direct link to Hash Password" title="Direct link to Hash Password" translate="no">​</a></h3>
<p>Dashy uses <a href="https://en.wikipedia.org/wiki/Sha-256" target="_blank" rel="noopener noreferrer" class="">SHA-256 Hash</a>, a 64-character string, which you can generate by running <code>echo -n &quot;my-super-secure-password&quot; | sha256sum</code>, or using an online tool, such as <a href="https://passwordsgenerator.net/sha256-hash-generator/" target="_blank" rel="noopener noreferrer" class="">this one</a> or <a href="https://gchq.github.io/CyberChef/" target="_blank" rel="noopener noreferrer" class="">CyberChef</a> (which can be self-hosted/ ran locally).</p>
<p>A hash is a one-way cryptographic function, meaning that it is easy to generate a hash for a given password, but very hard to determine the original password for a given hash. This means, that so long as your password is long, strong and unique, it is safe to store its hash in the clear. Having said that, you should never reuse passwords, hashes can be cracked by iterating over known password lists, generating a hash of each.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="logging-in-and-out">Logging In and Out<a href="#logging-in-and-out" class="hash-link" aria-label="Direct link to Logging In and Out" title="Direct link to Logging In and Out" translate="no">​</a></h3>
<p>Once authentication is enabled, so long as there is no valid token in cookie storage, the application will redirect the user to the login page. When the user enters credentials in the login page, they will be checked, and if valid, then a token will be generated, and they can be redirected to the home page. If credentials are invalid, then an error message will be shown, and they will remain on the login page. Once in the application, to log out: the user can click the logout button (in the top-right), which will clear cookie storage, causing them to be redirected back to the login page.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="enabling-guest-access">Enabling Guest Access<a href="#enabling-guest-access" class="hash-link" aria-label="Direct link to Enabling Guest Access" title="Direct link to Enabling Guest Access" translate="no">​</a></h3>
<p>With authentication set up, by default no access is allowed to your dashboard without first logging in with valid credentials. Guest mode can be enabled to allow for read-only access to a secured dashboard by any user, without the need to log in. A guest user cannot write any changes to the config file, but can apply modifications locally (stored in their browser). You can enable guest access, by setting <code>appConfig.auth.enableGuestAccess: true</code>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="granular-access">Granular Access<a href="#granular-access" class="hash-link" aria-label="Direct link to Granular Access" title="Direct link to Granular Access" translate="no">​</a></h3>
<p>You can use the following properties to make certain pages, sections or items only visible to some users, or hide pages, sections and items from guests.</p>
<ul>
<li class=""><code>hideForUsers</code> - Page, Section or Item will be visible to all users, except for those specified in this list</li>
<li class=""><code>showForUsers</code> - Page, Section or Item will be hidden from all users, except for those specified in this list</li>
<li class=""><code>hideForGuests</code> - Page, Section or Item will be visible for logged in users, but not for guests</li>
</ul>
<p>For Example:</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"><span class="token-line" style="color:#F8F8F2"><span class="token key atrule">pages</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span 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">name</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> Home Lab</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> home</span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain">lab.yml</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">displayData</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">showForUsers</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain">admin</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span 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">name</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> Intranet</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">path</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> intranet.yml</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">displayData</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">hideForGuests</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></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">hideForUsers</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain">alicia</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> bob</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><br></span></code></pre></div></div>
<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"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> </span><span class="token key atrule">name</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> Code Analysis &amp; Monitoring</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">icon</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> fas fa</span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain">code</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">displayData</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">cols</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token number">2</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">hideForUsers</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain">alicia</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> bob</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">items</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">...</span><br></span></code></pre></div></div>
<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"><span class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain"> </span><span class="token key atrule">name</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> Deployment Pipelines</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">icon</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> fas fa</span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain">rocket</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">displayData</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">hideForGuests</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></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">items</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span 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">title</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> Hide Me</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">displayData</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">hideForUsers</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token plain">alicia</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"> bob</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="permissions">Permissions<a href="#permissions" class="hash-link" aria-label="Direct link to Permissions" title="Direct link to Permissions" translate="no">​</a></h3>
<p>Any user who is not an admin (with <code>type: admin</code>) will not be able to write changes to disk.</p>
<p>You can also prevent any user from writing changes to disk, using <code>preventWriteToDisk</code>. Or prevent any changes from being saved locally in browser storage, using <code>preventLocalSave</code>. Both properties can be found under <a class="" href="/docs/configuring#appconfig-optional"><code>appConfig</code></a>.</p>
<p>To disable all UI config features, including View Config, set <code>disableConfiguration</code>. Alternatively you can disable UI config features for all non admin users by setting <code>disableConfigurationForNonAdmin</code> to true.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="using-environment-variables-for-passwords">Using Environment Variables for Passwords<a href="#using-environment-variables-for-passwords" class="hash-link" aria-label="Direct link to Using Environment Variables for Passwords" title="Direct link to Using Environment Variables for Passwords" translate="no">​</a></h3>
<p>If you don&#x27;t want to hash your password, you can instead leave out the <code>hash</code> attribute, and replace it with <code>password</code> which should have the value of an environmental variable name you wish to use.</p>
<p>Note that env var must begin with <code>VUE_APP_</code>, and you must set this variable before building the app.</p>
<p>For example:</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"><span 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></span><span 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></span><span 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></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">password</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> VUE_APP_BOB</span><br></span></code></pre></div></div>
<p>Just be sure to set <code>VUE_APP_BOB=&#x27;my super secret password&#x27;</code> before build-time.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="adding-http-auth-to-configuration">Adding HTTP Auth to Configuration<a href="#adding-http-auth-to-configuration" class="hash-link" aria-label="Direct link to Adding HTTP Auth to Configuration" title="Direct link to Adding HTTP Auth to Configuration" translate="no">​</a></h3>
<p>Without this, the built-in auth is just a client-side login page — your config and API endpoints can still be accessed directly. Set <code>ENABLE_HTTP_AUTH=true</code> to protect them.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_BuS1"><p>HTTP Auth and guest access (<code>enableGuestAccess</code>) are incompatible. Guests have no credentials, so they can&#x27;t fetch the config file when HTTP auth is active.</p></div></div>
<p>This uses the same users you&#x27;ve already defined in <code>appConfig.auth.users</code> to authenticate all server-side requests (config files, status checks, system info, CORS proxy, etc.) via HTTP Basic Auth.</p>
<p><strong>How it works:</strong> When a user logs in through the Dashy UI, a session token is stored in a cookie. The frontend automatically includes this token in requests to local API endpoints. On the server side, the token is validated against your configured users. If someone tries to access an endpoint directly (e.g. with curl), the server will respond with a <code>401</code> and a Basic Auth challenge — they&#x27;ll need to provide a valid username and password.</p>
<p><strong>Setup:</strong></p>
<ol>
<li class="">Make sure you have users configured in your <code>conf.yml</code> (see <a href="#setting-up-authentication" class="">Setting Up Authentication</a> above)</li>
<li class="">Set the <code>ENABLE_HTTP_AUTH=true</code> environment variable (e.g. in your <code>docker-compose.yml</code> or <code>.env</code> file)</li>
<li class="">Restart the container - the auth mode is determined at startup, so env var changes need a restart</li>
</ol>
<p>Adding or removing users in <code>conf.yml</code> takes effect immediately without a restart, since the user list is read from disk on each request.</p>
<p>For full protection, you&#x27;ll want both the client-side login page (via <code>appConfig.auth.users</code>) and server-side auth (via <code>ENABLE_HTTP_AUTH=true</code>).</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="security">Security<a href="#security" class="hash-link" aria-label="Direct link to Security" title="Direct link to Security" translate="no">​</a></h3>
<p>With basic auth (and without HTTP auth), the login logic runs on the client-side. A technical user could inspect the code and view parts of your configuration, including password hashes. If the SHA-256 hash is of a common password, it may be possible to determine it using a lookup table, and then use that to generate a valid auth token. Therefore, you should always use a long, strong and unique password.</p>
<p>If your instance is exposed to the internet, the built-in auth alone is not sufficient - use a reverse proxy with its own authentication layer (see <a href="#alternative-authentication-methods" class="">Alternative Authentication Methods</a>), or access Dashy over a VPN. See the <a class="" href="/docs/management#network-exposure">Network Exposure</a> section in the management docs for more on this.</p>
<p>The built-in login page prevents casual unauthorized access on a private network. It&#x27;s not a security perimeter.</p>
<p><strong><strong><a href="#" class="">⬆️ Back to Top</a></strong></strong></p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="http-auth">HTTP Auth<a href="#http-auth" class="hash-link" aria-label="Direct link to HTTP Auth" title="Direct link to HTTP Auth" translate="no">​</a></h2>
<p>If you&#x27;d like to protect server-side endpoints with HTTP Basic Auth, there are two approaches. They protect the same endpoints but use different credential sources, so pick one - don&#x27;t combine them.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="using-config-file-users-recommended">Using config-file users (recommended)<a href="#using-config-file-users-recommended" class="hash-link" aria-label="Direct link to Using config-file users (recommended)" title="Direct link to Using config-file users (recommended)" translate="no">​</a></h3>
<p>This is the approach described in <a href="#adding-http-auth-to-configuration" class="">Adding HTTP Auth to Configuration</a> above. Set <code>ENABLE_HTTP_AUTH=true</code> and it uses the same <code>appConfig.auth.users</code> from your <code>conf.yml</code>. The frontend handles authentication automatically using the session token from the login page, so no extra setup is needed.</p>
<p>This is the recommended approach because it keeps credentials in one place and works together with the client-side login page. But the drawback is that your credentials will be stored in your config file.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="using-static-credentials">Using static credentials<a href="#using-static-credentials" class="hash-link" aria-label="Direct link to Using static credentials" title="Direct link to Using static credentials" translate="no">​</a></h3>
<p>If you don&#x27;t have users in your <code>conf.yml</code> (e.g. you handle user management externally, or just want a single shared password for server-side access), you can set the <code>BASIC_AUTH_USERNAME</code> and <code>BASIC_AUTH_PASSWORD</code> environmental variables instead.</p>
<p>With this approach, there is no Dashy login page. When the browser first requests the config file, the server responds with a <code>401</code> and the browser shows its native HTTP auth prompt. Once the user enters the correct credentials, the browser caches them for the session and all subsequent requests work.</p>
<p>To skip the browser prompt and have the frontend authenticate automatically, also set <code>VUE_APP_BASIC_AUTH_USERNAME</code> and <code>VUE_APP_BASIC_AUTH_PASSWORD</code> to the same values. These are baked in at build time, so a rebuild is required, and you should only do this on a trusted network.</p>
<div class="theme-admonition theme-admonition-warning admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>warning</div><div class="admonitionContent_BuS1"><p>Do not combine <code>BASIC_AUTH_USERNAME</code>/<code>BASIC_AUTH_PASSWORD</code> with conf.yml users. If both are present, the server will log a warning at startup. With <code>ENABLE_HTTP_AUTH</code> set, config-file users take priority and the static credentials are ignored. Without it, the static credentials protect the server but the Dashy login page will use conf.yml credentials, and the frontend will send the wrong credentials to server endpoints. Pick one approach or the other.</p></div></div>
<p><strong><strong><a href="#" class="">⬆️ Back to Top</a></strong></strong></p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="keycloak">Keycloak<a href="#keycloak" class="hash-link" aria-label="Direct link to Keycloak" title="Direct link to Keycloak" translate="no">​</a></h2>
<p>Dashy also supports using a <a href="https://www.keycloak.org/" target="_blank" rel="noopener noreferrer" class="">Keycloak</a> authentication server. The setup for this is a bit more involved, but it gives you greater security overall, useful for if your instance is exposed to the internet.</p>
<p><a href="https://www.keycloak.org/about.html" target="_blank" rel="noopener noreferrer" class="">Keycloak</a> is a Java-based <a href="https://github.com/keycloak/keycloak" target="_blank" rel="noopener noreferrer" class="">open source</a>, high-performance, secure authentication system, supported by <a href="https://www.redhat.com/en" target="_blank" rel="noopener noreferrer" class="">RedHat</a>. It is easy to setup (<a href="https://quay.io/repository/keycloak/keycloak" target="_blank" rel="noopener noreferrer" class="">with Docker</a>), and enables you to secure multiple self-hosted applications with single-sign-on using standard protocols (OpenID Connect, OAuth 2.0, SAML 2.0 and social login). It&#x27;s also very customizable, you can write or use custom <a href="https://wjw465150.gitbooks.io/keycloak-documentation/content/server_development/topics/themes.html" target="_blank" rel="noopener noreferrer" class="">themes</a>, <a href="https://www.keycloak.org/extensions.html" target="_blank" rel="noopener noreferrer" class="">plugins</a>, <a href="https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/authentication/password-policies.html" target="_blank" rel="noopener noreferrer" class="">password policies</a> and more.
The following guide will walk you through setting up Keycloak with Dashy. If you already have a Keycloak instance configured, then skip to Step 3.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-deploy-keycloak">1. Deploy Keycloak<a href="#1-deploy-keycloak" class="hash-link" aria-label="Direct link to 1. Deploy Keycloak" title="Direct link to 1. Deploy Keycloak" translate="no">​</a></h3>
<p>First thing to do is to spin up a new instance of Keycloak. You will need <a href="https://docs.docker.com/engine/install/" target="_blank" rel="noopener noreferrer" class="">Docker installed</a>, and can then choose a tag, and pull the container from <a href="https://quay.io/repository/keycloak/keycloak" target="_blank" rel="noopener noreferrer" class="">quay.io/keycloak/keycloak</a></p>
<p>Use the following run command, replacing the attributes (default credentials, port and name), or incorporate this into your docker-compose file.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">docker run -d \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> -p 8081:8080 \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> --name auth-server \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> -e KEYCLOAK_USER=admin \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> -e KEYCLOAK_PASSWORD=admin \</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> quay.io/keycloak/keycloak:15.0.2</span><br></span></code></pre></div></div>
<p>If you need to pull from DockerHub, a non-official image is available <a href="https://registry.hub.docker.com/r/jboss/keycloak" target="_blank" rel="noopener noreferrer" class="">here</a>. Or if you would prefer not to use Docker, you can also directly install Keycloak from source, following <a href="https://www.keycloak.org/docs/latest/getting_started/index.html" target="_blank" rel="noopener noreferrer" class="">this guide</a>.</p>
<p>You should now be able to access the Keycloak web interface, using the port specified above (e.g. <code>http://127.0.0.1:8081</code>), login with the default credentials, and when prompted create a new password.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-setup-keycloak-users">2. Setup Keycloak Users<a href="#2-setup-keycloak-users" class="hash-link" aria-label="Direct link to 2. Setup Keycloak Users" title="Direct link to 2. Setup Keycloak Users" translate="no">​</a></h3>
<p>Before we can use Keycloak, we must first set it up with some users. Keycloak uses Realms (similar to tenants) to create isolated groups of users. You must create a Realm before you will be able to add your first user.</p>
<ol>
<li class="">Head over to the admin console</li>
<li class="">In the top-left corner there is a dropdown called &#x27;Master&#x27;, hover over it and then click &#x27;Add Realm&#x27;</li>
<li class="">Give your realm a name, and hit &#x27;Create&#x27;</li>
</ol>
<p>You can now create your first user.</p>
<ol>
<li class="">In the left-hand menu, click &#x27;Users&#x27;, then &#x27;Add User&#x27;</li>
<li class="">Fill in the form, including username and hit &#x27;Save&#x27;</li>
<li class="">Under the &#x27;Credentials&#x27; tab, give the new user an initial password. They will be prompted to change this after first login</li>
</ol>
<p>The last thing we need to do in the Keycloak admin console is to create a new client</p>
<ol>
<li class="">Within your new realm, navigate to &#x27;Clients&#x27; on the left-hand side, then click &#x27;Create&#x27; in the top-right</li>
<li class="">Choose a &#x27;Client ID&#x27;, set &#x27;Client Protocol&#x27; to &#x27;openid-connect&#x27;, and for &#x27;Valid Redirect URIs&#x27; put a URL pattern to where you&#x27;re hosting Dashy (if you&#x27;re just testing locally, then * is fine), and do the same for the &#x27;Web Origins&#x27; field</li>
<li class="">Make note of your client-id, and click &#x27;Save&#x27;</li>
</ol>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-enable-keycloak-in-dashy-config-file">3. Enable Keycloak in Dashy Config File<a href="#3-enable-keycloak-in-dashy-config-file" class="hash-link" aria-label="Direct link to 3. Enable Keycloak in Dashy Config File" title="Direct link to 3. Enable Keycloak in Dashy Config File" translate="no">​</a></h3>
<p>Now that your Keycloak instance is up and running, all that&#x27;s left to do is to configure Dashy to use it. Under <code>appConfig</code>, set <code>auth.enableKeycloak: true</code>, then fill in the details in <code>auth.keycloak</code>, including: <code>serverUrl</code> - the URL where your Keycloak instance is hosted, <code>realm</code> - the name you gave your Realm, and <code>clientId</code> - the Client ID you chose.
For example:</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"><span 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></span><span 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><br></span><span 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></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">enableKeycloak</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></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">keycloak</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">serverUrl</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)">&#x27;http://localhost:8081&#x27;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">realm</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)">&#x27;alicia-homelab&#x27;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">clientId</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)">&#x27;dashy&#x27;</span><br></span></code></pre></div></div>
<p>Note that if you are using Keycloak V 17 or older, you will also need to set <code>legacySupport: true</code> (also under <code>appConfig.auth.keycloak</code>). This is because the API endpoint was updated in later versions.</p>
<p>If you use Keycloak with an external Identity Provier, you can set the <code>idpHint: &#x27;alias-of-kc-idp&#x27;</code> option to allow the IdP Hint to be passed to Keycloak. This will cause Keycloak to skip its login page and redirect the user directly to the specified IdP&#x27;s login page. Set to the value of the &#x27;Alias&#x27; field of the desired IdP as defined in Keycloak under &#x27;Identity Providers&#x27;.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-add-groups-and-roles-optional">4. Add groups and roles (Optional)<a href="#4-add-groups-and-roles-optional" class="hash-link" aria-label="Direct link to 4. Add groups and roles (Optional)" title="Direct link to 4. Add groups and roles (Optional)" translate="no">​</a></h3>
<p>Keycloak allows you to assign users roles and groups. You can use these values to configure who can access various sections or items in Dashy.
Keycloak server administration and configuration is a deep topic; please refer to the <a href="https://www.keycloak.org/docs/latest/server_admin/index.html#assigning-permissions-and-access-using-roles-and-groups" target="_blank" rel="noopener noreferrer" class="">server admin guide</a> to see details about creating and assigning roles and groups.
Once you have groups or roles assigned to users you can configure access under each section or item <code>displayData.showForKeycloakUser</code> and <code>displayData.hideForKeycloakUser</code>.
Both show and hide configurations accept a list of <code>groups</code> and <code>roles</code> that limit access. If a users data matches one or more items in these lists they will be allowed or excluded as defined.</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"><span class="token-line" style="color:#F8F8F2"><span class="token key atrule">sections</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span 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">name</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> DeveloperResources</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">displayData</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">showForKeycloakUsers</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">roles</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">&#x27;canViewDevResources&#x27;</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">hideForKeycloakUsers</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">groups</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">&#x27;ProductTeam&#x27;</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">items</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span 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">title</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> Not Visible for developers</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">displayData</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">hideForKeycloakUsers</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">groups</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">[</span><span class="token string" style="color:rgb(255, 121, 198)">&#x27;DevelopmentTeam&#x27;</span><span class="token punctuation" style="color:rgb(248, 248, 242)">]</span><br></span></code></pre></div></div>
<p>Depending on how you&#x27;re hosting Dashy and Keycloak, you may also need to set some HTTP headers, to prevent a CORS error. This would typically be the <code>Access-Control-Allow-Origin [URL-of Dashy]</code> on your Keycloak instance. See the <a class="" href="/docs/management#setting-headers">Setting Headers</a> guide in the management docs for more info.</p>
<p>Your app is now secured :) When you load Dashy, it will redirect to your Keycloak login page, and any user without valid credentials will be prevented from accessing your dashboard.</p>
<p>From within the Keycloak console, you can then configure things like time-outs, password policies, etc. You can also backup your full Keycloak config, and it is recommended to do this, along with your Dashy config. You can spin up both Dashy and Keycloak simultaneously and restore both applications configs using a <code>docker-compose.yml</code> file, and this is recommended.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="troubleshooting-keycloak">Troubleshooting Keycloak<a href="#troubleshooting-keycloak" class="hash-link" aria-label="Direct link to Troubleshooting Keycloak" title="Direct link to Troubleshooting Keycloak" translate="no">​</a></h3>
<p>If you encounter issues with your Keycloak setup, follow these steps to troubleshoot and resolve common problems.</p>
<ol>
<li class="">
<p>Client Authentication Issue
Problem: Redirect loop, if client authentication is enabled.
Solution: Switch off &quot;client authentication&quot; in &quot;TC clients&quot; -&gt; &quot;Advanced&quot; settings.</p>
</li>
<li class="">
<p>Double URL
Problem: If you get redirected to &quot;<a href="https://dashy.my.domain/#iss=https://keycloak.my.domain/realms/my-realm" target="_blank" rel="noopener noreferrer" class="">https://dashy.my.domain/#iss=https://keycloak.my.domain/realms/my-realm</a>&quot;
Solution: Make sure to turn on &quot;Exclude Issuer From Authentication Response&quot; in &quot;TC clients&quot; -&gt; &quot;Advanced&quot; -&gt; &quot;OpenID Connect Compatibility Modes&quot;</p>
</li>
<li class="">
<p>Problems with mutiple Dashy Pages
Problem: Refreshing or logging out of dashy results in an &quot;invalid_redirect_uri&quot; error.
Solution: In &quot;TC clients&quot; -&gt; &quot;Access settings&quot; -&gt; &quot;Root URL&quot; <a href="https://dashy.my.domain/" target="_blank" rel="noopener noreferrer" class="">https://dashy.my.domain/</a>, valid redirect URIs must be /*</p>
</li>
</ol>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="header-authentication">Header Authentication<a href="#header-authentication" class="hash-link" aria-label="Direct link to Header Authentication" title="Direct link to Header Authentication" translate="no">​</a></h2>
<p>Header authentication allows Dashy to trust an upstream reverse proxy to handle authentication. The proxy authenticates users and forwards their identity to Dashy via a configurable HTTP header (e.g. <code>REMOTE_USER</code>). This is the standard pattern used by <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&#x27;s <code>forwardAuth</code>, Caddy&#x27;s <code>forward_auth</code>, and Nginx&#x27;s <code>auth_request</code>.</p>
<p>This is useful when you already have a central authentication layer in front of your self-hosted services and want Dashy to automatically pick up the authenticated user without requiring a separate login.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="configuration">Configuration<a href="#configuration" class="hash-link" aria-label="Direct link to Configuration" title="Direct link to Configuration" translate="no">​</a></h3>
<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"><span 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></span><span 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></span><span 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></span><span 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></span><span 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></span><span 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 of password</span><span class="token plain"></span><br></span><span 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></span><span 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></span><span 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></span><span 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></span><span 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></span><span 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></span><span 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></span><span 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></span><span 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></span></code></pre></div></div>
<ul>
<li class=""><strong><code>userHeader</code></strong> - The HTTP header name containing the authenticated username. Defaults to <code>Remote-User</code> if not specified. Common values: <code>Remote-User</code> (Authelia), <code>X-authentik-username</code> (Authentik), or whatever your proxy forwards. Header matching is case-insensitive.</li>
<li class=""><strong><code>proxyWhitelist</code></strong> - Required. An array of IP addresses that Dashy will accept the header from. Only requests originating from these IPs will be trusted. This prevents clients from spoofing the header directly.</li>
<li class=""><strong><code>users</code></strong> - Required. The header username is matched against this list to determine the user&#x27;s role (<code>admin</code> or <code>normal</code>) and to generate the session token. Users must be defined here even though authentication is handled externally.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" 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></h3>
<ol>
<li class="">User visits Dashy, which is behind a reverse proxy (e.g. Authelia)</li>
<li class="">The proxy authenticates the user and forwards the request with a header like <code>Remote-User: alice</code></li>
<li class="">Dashy&#x27;s server checks that the request comes from a whitelisted proxy IP, then returns the username via the <code>/get-user</code> endpoint</li>
<li class="">The client matches the username against the configured users, generates a session token, and sets the auth cookie</li>
<li class="">From this point, standard Dashy auth applies - <code>isLoggedIn()</code>, admin checks, and granular access controls all work as normal</li>
</ol>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="notes">Notes<a href="#notes" class="hash-link" aria-label="Direct link to Notes" title="Direct link to Notes" translate="no">​</a></h3>
<ul>
<li class="">The <code>proxyWhitelist</code> checks <code>req.socket.remoteAddress</code>, which is the direct connection source. If your proxy connects through Docker networking, use the container&#x27;s internal IP (e.g. <code>172.18.0.2</code>), not the external IP</li>
<li class="">Logout clears Dashy&#x27;s session cookie, but the user remains authenticated at the proxy level. Revisiting the page will re-authenticate automatically</li>
<li class="">When header auth is enabled, server-side API endpoints are also protected by the proxy whitelist. Requests not from a whitelisted IP will be rejected. Admin enforcement applies - only users with <code>type: admin</code> can access write endpoints (config save, rebuild)</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="oidc">OIDC<a href="#oidc" class="hash-link" aria-label="Direct link to OIDC" title="Direct link to OIDC" translate="no">​</a></h2>
<p>Dashy also supports using a general <a href="https://openid.net/connect/" target="_blank" rel="noopener noreferrer" class="">OIDC compatible</a> authentication server. In order to use it, the authentication section needs to be configured:</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"><span 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></span><span 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></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">enableOidc</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></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">oidc</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">clientId</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)">&#x27;registered-client-id&#x27;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">endpoint</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)">&#x27;https://your-oidc-provider.example.com&#x27;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">scope</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)">&#x27;openid profile email&#x27;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">adminGroup</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> admin</span><br></span></code></pre></div></div>
<p>Because Dashy is a SPA, a <a href="https://datatracker.ietf.org/doc/html/rfc6749#section-2.1" target="_blank" rel="noopener noreferrer" class="">public client</a> registration with PKCE is needed.</p>
<p>Note, that if your <code>clientId</code> is numeric, you must place it in quotes. Otherwise it will be interpreted as a number and truncated to 64 chars!</p>
<p>An example for Authelia is shared below, but other OIDC systems can be used:</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"><span class="token-line" style="color:#F8F8F2"><span class="token key atrule">identity_providers</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">oidc</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">clients</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span 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">client_id</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> dashy</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">client_name</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> dashy</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">public</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></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">authorization_policy</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)">&#x27;one_factor&#x27;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">require_pkce</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></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">pkce_challenge_method</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)">&#x27;S256&#x27;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">redirect_uris</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span 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"> https</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain">//dashy.local </span><span class="token comment" style="color:rgb(98, 114, 164)"># should point to your dashy endpoint</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">grant_types</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span 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"> authorization_code</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">scopes</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span><br></span><span 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)">&#x27;openid&#x27;</span><span class="token plain"></span><br></span><span 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)">&#x27;profile&#x27;</span><span class="token plain"></span><br></span><span 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)">&#x27;roles&#x27;</span><span class="token plain"></span><br></span><span 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)">&#x27;email&#x27;</span><span class="token plain"></span><br></span><span 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)">&#x27;groups&#x27;</span><br></span></code></pre></div></div>
<p>Groups and roles will be populated and available for controlling display similar to <a href="#keycloak" class="">Keycloak</a> above.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="authentik">authentik<a href="#authentik" class="hash-link" aria-label="Direct link to authentik" title="Direct link to authentik" translate="no">​</a></h2>
<p>This documentation is specific to <code>authentik</code>, however it may be useful in getting other idP&#x27;s working with <code>Dashy</code>.</p>
<p>This guide will only walk through the following:</p>
<ul>
<li class="">Creating and configuring an OIDC provider</li>
<li class="">Creating and configuring an application</li>
<li class="">Assigning groups</li>
<li class="">Configuring <code>Dashy</code> to use the OIDC client</li>
<li class="">Show quick examples of how to hide/show <code>pages</code>, <code>items</code>, and <code>sections</code> using OIDC groups</li>
</ul>
<p>This guide assumes the following:</p>
<ul>
<li class="">You have a working instance of <code>authentik</code> terminated with SSL</li>
<li class="">You have a working instance of <code>Dashy</code> terminated with SSL</li>
<li class="">Users and groups are provisioned</li>
<li class="">You are familiar with how <code>authentik</code> works in case you need to do further troubleshooting that is outside the scope of this guide.</li>
</ul>
<div class="theme-admonition theme-admonition-tip admonition_xJq3 alert alert--success"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_BuS1"><p>It it recommended that you create groups specific for <code>Dashy</code>. Groups will allow you to display content based on group membership as well as limiting user access to <code>Dashy</code>. If you do not need this functionality, then you can forgo creating specific groups.</p></div></div>
<div class="theme-admonition theme-admonition-tip admonition_xJq3 alert alert--success"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_BuS1"><p>You can use the application wizard to create the provider and application at one time. This is the recommended route, but only the manual process will be outlined in this guide.</p></div></div>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/72e45162-6c86-4d6f-a1ae-724ac503c00c" alt="image" class="img_ev3q"></p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-create-an-oidc-provider">1. Create an OIDC provider<a href="#1-create-an-oidc-provider" class="hash-link" aria-label="Direct link to 1. Create an OIDC provider" title="Direct link to 1. Create an OIDC provider" translate="no">​</a></h4>
<p>Login to the admin console for <code>authentik</code>. Go to <code>Applications</code> &gt; <code>Providers</code>. Click <code>Create</code>.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/c1f7f45d-469c-4bf1-a825-34658341a83e" alt="image" class="img_ev3q"></p>
<p>A dialog box will pop-up, select the <code>OAuth2/OpenID Provider</code>. Click <code>Next</code>.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/ea84fe57-b813-404d-8dad-5e221b440bdb" alt="image" class="img_ev3q"></p>
<p>On the next page of the wizard, set the <code>Name</code>, <code>Authentication flow</code>, and <code>Authorization flow</code>. See example below. Using the <code>default-provider-authorization-implicit-consent</code> authorization flow on internal services and <code>default-provider-authorization-explicit-consent</code> on external services is a common practice. However, it is fully up to you on how you would like to configure this option. <code>Implicit</code> will login directly without user consent, <code>explicit</code> will ask if the user approves the service being logged into with their user credentials.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/e600aeaf-08d1-49aa-b304-11e90e5c89cd" alt="image" class="img_ev3q"></p>
<p>Scroll down and configure the <code>Protocol settings</code>. Set the <code>Client type</code> to <code>Public</code>. Add the <code>Redirect URIs/Origins (RegEx)</code>. If the site is hosted at <code>dashy.lan.domain.com</code>, then you would enter as the example below.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_BuS1"><p>If you have an internal and external domain for <code>Dashy</code>, enter both URI&#x27;s. Enter each URI on a new line.</p></div></div>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/4a289d7e-d7b4-4ff6-af5d-3e5202fae84e" alt="image" class="img_ev3q"></p>
<p>Scroll down to set the <code>Signing Key</code>. It is recommended to use the built in <code>authentik Self-signed Certificate</code> here unless you have special needs for your own custom cert.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/386c0750-9d2b-4482-8938-8b301b489b38" alt="image" class="img_ev3q"></p>
<p>Expand <code>Advanced protocol settings</code> then verify the <code>Scopes</code> are set to what is highlighted in <code>white</code> below. Set the <code>Subject mode</code> to <code>Based on the Users&#x27;s Email</code>.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/ae5e87b8-1ad6-41dd-b6e1-9665623f842a" alt="image" class="img_ev3q"></p>
<p>Lastly, toggle <code>Include claims in id_token</code> to on. Click <code>Finish</code> to complete creating the provider.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/25353b3c-3f54-47cf-bd47-b5023f86d7cf" alt="image" class="img_ev3q"></p>
<p>Grab the generated <code>Client ID</code> and <code>OpenID Configuration Issuer</code> URL by clicking the newly created provider as this will use this later when <code>Dashy</code> is configured to use the OIDC auth mechanism. In this tutorial, what was generated is used below. Obviously adjust the <code>Client ID</code> that was generated and use your domain here for the <code>issuer</code>.</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">Client ID: pzN9DCMLqHTTatgtYFg50cl0jn1NmCyBC3wreX15</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">OpenID Configuration Issuer: https://auth.domain.com/application/o/dashy/</span><br></span></code></pre></div></div>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-create-an-application">2. Create an application<a href="#2-create-an-application" class="hash-link" aria-label="Direct link to 2. Create an application" title="Direct link to 2. Create an application" translate="no">​</a></h4>
<p>Make sure you are still in the <code>authentik</code> admin console then go to <code>Applications</code> &gt; <code>Applications</code>. Click <code>Create</code>.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/fd225936-15a1-409f-83c8-e24a43047df0" alt="image" class="img_ev3q"></p>
<p>Next, it is required to give a user facing <code>Name</code>, <code>Slug</code> and assign the newly created provider. Use the example below if you have been following the guide. If you have used your own naming, then adjust accordingly. Click <code>Create</code> once you are done.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/e6574d7d-6b22-4e7d-b388-45341b98746b" alt="image" class="img_ev3q"></p>
<div class="theme-admonition theme-admonition-tip admonition_xJq3 alert alert--success"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_BuS1"><p>Open the application in a new tab from the <code>authentik</code> user portal and upload a custom icon. You can also enter a user facing <code>Description</code> that the user would see.</p></div></div>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/20561387-549f-49de-98e6-30330dcdc734" alt="image" class="img_ev3q"></p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-optional-limiting-access-via-authentik-with-groups">3. <em>(Optional)</em> Limiting access via <code>authentik</code> with groups<a href="#3-optional-limiting-access-via-authentik-with-groups" class="hash-link" aria-label="Direct link to 3-optional-limiting-access-via-authentik-with-groups" title="Direct link to 3-optional-limiting-access-via-authentik-with-groups" translate="no">​</a></h4>
<p>If you would like to deny <code>Dashy</code> access from specific users who are not within <code>authentik</code> based groups, you bind them to the application you just created now. <code>authentik</code> will deny access to those who are not members of this group or groups. If you want to allow everyone access from your <code>authentik</code> instance, skip this step.</p>
<p>Make sure you are still in the <code>authentik</code> admin console then go to <code>Applications</code> &gt; <code>Applications</code>. Click the newly created <code>Dashy</code> application.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/613fafe7-881f-4664-a903-945854ac65e2" alt="image" class="img_ev3q"></p>
<p>Click the <code>Policy/Group/User Bindings</code> tab at the top, then click <code>Bind existing policy</code>. This assumes you have already created the groups you want to use for <code>Dashy</code> and populated users in those groups.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/10fca15b-e77d-4624-ae03-0ece3910904c" alt="image" class="img_ev3q"></p>
<p>Click <code>Group</code> for the binding type. Under <code>Group</code> select the appropriate group you would like to bind. Make sure <code>Enabled</code> is toggeled on. Click <code>Create</code>.</p>
<p><img decoding="async" loading="lazy" src="https://github.com/user-attachments/assets/ebf680ab-696f-4c08-ae89-d73fe92b398f" alt="image" class="img_ev3q"></p>
<p><code>Dashy</code> will now be scoped only to users within the assigned groups you have bound the application to. Keep adding groups if you would like to adjust the dashboard visibilty based on group membership.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-configure-dashy-to-use-oidc-client">4. Configure <code>Dashy</code> to use OIDC client<a href="#4-configure-dashy-to-use-oidc-client" class="hash-link" aria-label="Direct link to 4-configure-dashy-to-use-oidc-client" title="Direct link to 4-configure-dashy-to-use-oidc-client" translate="no">​</a></h4>
<div class="theme-admonition theme-admonition-important admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>important</div><div class="admonitionContent_BuS1"><p>It is highly recommended to edit your <code>conf.yml</code> directly for this step.</p></div></div>
<div class="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>caution</div><div class="admonitionContent_BuS1"><p>Do not make the same mistake many have made here by including the fully qualified address for the <code>OpenID Configuration URL</code>. <code>Dashy</code> will append the <code>.well-known</code> configuration automatically. If the <code>.well-known</code> URI is included the app will get redirect loops and <code>400</code> errors.</p></div></div>
<p>Enter the <code>Client ID</code> in the <code>clientId</code> field and <code>OpenID Configuration Issuer</code> in the <code>endpoint</code> field.</p>
<p>Below is how to configure the <code>auth</code> section in the yaml syntax. Once this is enabled, when an attempt to access <code>Dashy</code> is made it will now redirect you to the <code>authentik</code> login page moving forward.</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">appConfig:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> theme: glass</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> layout: auto</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> iconSize: medium</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> auth:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> enableOidc: true</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> oidc:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> clientId: pzN9DCMLqHTTatgtYFg50cl0jn1NmCyBC3wreX15</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> endpoint: https://auth.domain.com/application/o/dashy/</span><br></span></code></pre></div></div>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-optional-example-snippets-for-dashboard-visibility">5. <em>(OPTIONAL)</em> Example snippets for dashboard visibility<a href="#5-optional-example-snippets-for-dashboard-visibility" class="hash-link" aria-label="Direct link to 5-optional-example-snippets-for-dashboard-visibility" title="Direct link to 5-optional-example-snippets-for-dashboard-visibility" translate="no">​</a></h4>
<p>Using the <code>hideForKeycloakUsers</code> configuration option is needed to use the <code>authentik</code> groups that were created previously.</p>
<p>Adjusting <code>pages</code> visibility:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">pages:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> - name: App Management</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> path: appmgmt.yml</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> displayData:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> hideForKeycloakUsers:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> groups:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> - Dashy Users</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> - name: Network Management</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> path: network.yml</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> displayData:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> hideForKeycloakUsers:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> groups:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> - Dashy Users</span><br></span></code></pre></div></div>
<p>Adjusting <code>items</code> visibility:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain"> items:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> - title: Authentik Admin</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> icon: authentik.svg</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> url: https://auth.domain.com/if/admin/</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> target: newtab</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> id: 0_1472_authentikadmin</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> displayData:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> hideForKeycloakUsers:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> groups:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> - Dashy Users</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> - title: Authentik User</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> icon: authentik-light.png</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> url: https://auth.domain.com/if/user/</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> target: newtab</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> id: 1_1472_authentikuser</span><br></span></code></pre></div></div>
<p>Adjusting <code>sections</code> visibility:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">sections:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> - name: Authentication</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> displayData:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> sortBy: default</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> rows: 2</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> cols: 1</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> collapsed: false</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> hideForGuests: false</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> hideForKeycloakUsers:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> groups: </span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> - Dashy Users</span><br></span></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="alternative-authentication-methods">Alternative Authentication Methods<a href="#alternative-authentication-methods" class="hash-link" aria-label="Direct link to Alternative Authentication Methods" title="Direct link to Alternative Authentication Methods" translate="no">​</a></h2>
<p>These are alternatives to Dashy&#x27;s built-in auth, Keycloak, and OIDC. Most of them sit in front of Dashy at the network or reverse proxy level, which is generally the better approach for anything internet-facing.</p>
<ul>
<li class=""><a href="#reverse-proxy-auth" class="">Reverse Proxy Auth</a> - Authelia, Authentik, or similar sitting in front of Dashy</li>
<li class=""><a href="#zero-trust-tunnels" class="">Zero-Trust Tunnels</a> - Cloudflare Tunnel, Tailscale Funnel</li>
<li class=""><a href="#vpn" class="">VPN</a> - Keep Dashy off the internet entirely</li>
<li class=""><a href="#ip-based-access" class="">IP-Based Access</a> - Restrict by source IP in your web server</li>
<li class=""><a href="#web-server-authentication" class="">Web Server Authentication</a> - HTTP basic auth at the proxy level</li>
<li class=""><a href="#sso--oauth-providers" class="">SSO / OAuth Providers</a> - Cloud-hosted identity providers</li>
<li class=""><a href="#cloud-hosting-providers" class="">Cloud Hosting Providers</a> - Built-in auth on hosting platforms</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="reverse-proxy-auth">Reverse proxy auth<a href="#reverse-proxy-auth" class="hash-link" aria-label="Direct link to Reverse proxy auth" title="Direct link to Reverse proxy auth" translate="no">​</a></h3>
<p>The most common setup for self-hosters running multiple services. You put an auth server in front of your reverse proxy, and it handles login, 2FA, and sessions for everything behind it. You configure it once, and all your apps get protected.</p>
<p>Dashy has <a href="#header-authentication" class="">Header Authentication</a> support, so when your proxy authenticates a user and forwards their identity via a header, Dashy picks up the username and maps it to a configured user automatically. No separate Dashy login needed.</p>
<p><strong>Authelia</strong> is lightweight and Docker-friendly. It supports 2FA, per-path access rules, and multiple user backends. To get started quickly:</p>
<ol>
<li class=""><code>git clone https://github.com/authelia/authelia.git</code></li>
<li class=""><code>cd authelia/examples/compose/lite</code></li>
<li class="">Edit <code>users_database.yml</code>, <code>configuration.yml</code>, and <code>docker-compose.yml</code> for your domain and users</li>
<li class=""><code>docker compose up -d</code></li>
</ol>
<p>See the <a href="https://www.authelia.com/docs/" target="_blank" rel="noopener noreferrer" class="">Authelia docs</a> for the full setup guide.</p>
<p><strong>Authentik</strong> is heavier but gives you a proper admin UI, built-in OIDC/SAML support, and user self-service (password resets, enrollment flows, etc). Good if you want a single identity provider across many apps. See the <a href="https://docs.goauthentik.io/docs/installation/docker-compose" target="_blank" rel="noopener noreferrer" class="">authentik Docker Compose install</a> to get started, and the <a href="#authentik" class="">authentik section</a> above for Dashy-specific OIDC config.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="zero-trust-tunnels">Zero-trust tunnels<a href="#zero-trust-tunnels" class="hash-link" aria-label="Direct link to Zero-trust tunnels" title="Direct link to Zero-trust tunnels" translate="no">​</a></h3>
<p>These let you expose Dashy to the internet without opening inbound ports or configuring port forwarding. Auth is handled by the tunnel provider before traffic ever reaches your server.</p>
<p><strong>Cloudflare Tunnel</strong> connects Dashy to Cloudflare&#x27;s edge network via an outbound-only <code>cloudflared</code> daemon (runs nicely as a Docker sidecar). Cloudflare handles DNS, TLS, and DDoS protection. Pair it with Cloudflare Access to require identity provider login before anyone reaches Dashy. The free tier covers most home setups. See the <a href="https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/" target="_blank" rel="noopener noreferrer" class="">Cloudflare Tunnel docs</a>.</p>
<p><strong>Tailscale Funnel</strong> exposes Dashy through your Tailscale mesh to the public internet, with automatic TLS. Simpler to set up than Cloudflare but you get less control over access policies. See the <a href="https://tailscale.com/kb/1223/funnel" target="_blank" rel="noopener noreferrer" class="">Funnel docs</a>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="vpn">VPN<a href="#vpn" class="hash-link" aria-label="Direct link to VPN" title="Direct link to VPN" translate="no">​</a></h3>
<p>A VPN keeps Dashy off the public internet entirely. You connect to your home network remotely and access Dashy like you&#x27;re on the LAN. No auth to configure, no attack surface to worry about. The downside: you need the VPN running to see anything, and some networks (corporate WiFi, hotels) block VPN traffic.</p>
<p><a href="https://www.wireguard.com/" target="_blank" rel="noopener noreferrer" class="">WireGuard</a> is fast and minimal. Most self-hosters run it through a UI like <a href="https://github.com/wg-easy/wg-easy" target="_blank" rel="noopener noreferrer" class="">wg-easy</a>, which gives you a web interface for managing peers and generating QR codes for mobile.</p>
<p><a href="https://tailscale.com/" target="_blank" rel="noopener noreferrer" class="">Tailscale</a> wraps WireGuard and takes care of NAT traversal, key exchange, and device management. No port forwarding needed, works across networks with zero config. There&#x27;s a generous free tier. <a href="https://github.com/juanfont/headscale" target="_blank" rel="noopener noreferrer" class="">Headscale</a> is a self-hosted coordination server if you want to keep everything on your own infrastructure.</p>
<p><a href="https://openvpn.net/" target="_blank" rel="noopener noreferrer" class="">OpenVPN</a> still works fine if you already have it running, but for a new setup WireGuard or Tailscale are easier to get going.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="ip-based-access">IP-based access<a href="#ip-based-access" class="hash-link" aria-label="Direct link to IP-based access" title="Direct link to IP-based access" translate="no">​</a></h3>
<p>If you have a static IP or are already on a VPN, you can restrict access to Dashy by source IP at the web server level. This works well as an extra layer on top of other auth methods.</p>
<p>NGINX:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">location / {</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_pass http://dashy:8080;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> allow 192.168.1.0/24;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> allow 203.0.113.50;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> deny all;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">}</span><br></span></code></pre></div></div>
<p>Caddy (<a href="https://caddyserver.com/docs/caddyfile/matchers" target="_blank" rel="noopener noreferrer" class="">request matchers docs</a>):</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">dashy.example.com {</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> @blocked not remote_ip 192.168.1.0/24 203.0.113.50</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> respond @blocked &quot;Access denied&quot; 403</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> reverse_proxy dashy:8080</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">}</span><br></span></code></pre></div></div>
<p>Apache (2.4+):</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">&lt;Location /&gt;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> Require ip 192.168.1.0/24</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> Require ip 203.0.113.50</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">&lt;/Location&gt;</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="web-server-authentication">Web server authentication<a href="#web-server-authentication" class="hash-link" aria-label="Direct link to Web server authentication" title="Direct link to Web server authentication" translate="no">​</a></h3>
<p>Your reverse proxy can handle HTTP basic auth directly, no extra services needed. This gives you a browser login prompt in front of Dashy. Make sure you&#x27;re using HTTPS, as basic auth sends credentials base64-encoded (not encrypted) with every request.</p>
<p>NGINX (<a href="https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html" target="_blank" rel="noopener noreferrer" class="">auth module docs</a>):</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">location / {</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> auth_basic &quot;Dashy&quot;;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> auth_basic_user_file /etc/nginx/conf.d/.htpasswd;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> proxy_pass http://dashy:8080;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">}</span><br></span></code></pre></div></div>
<p>Generate the password file with <code>htpasswd -c /etc/nginx/conf.d/.htpasswd alicia</code>.</p>
<p>Caddy (<a href="https://caddyserver.com/docs/caddyfile/directives/basicauth" target="_blank" rel="noopener noreferrer" class="">basicauth directive</a>):</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">dashy.example.com {</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> basicauth {</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> alicia $2a$14$... # generate with: caddy hash-password</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> reverse_proxy dashy:8080</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">}</span><br></span></code></pre></div></div>
<p>Apache:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">AuthType Basic</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">AuthName &quot;Dashy&quot;</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">AuthUserFile /path/to/.htpasswd</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Require valid-user</span><br></span></code></pre></div></div>
<p>Generate the password file with <code>htpasswd -c /path/to/.htpasswd alicia</code>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="sso--oauth-providers">SSO / OAuth providers<a href="#sso--oauth-providers" class="hash-link" aria-label="Direct link to SSO / OAuth providers" title="Direct link to SSO / OAuth providers" translate="no">​</a></h3>
<p>Cloud identity providers like <a href="https://auth0.com/" target="_blank" rel="noopener noreferrer" class="">Auth0</a>, <a href="https://developer.okta.com/" target="_blank" rel="noopener noreferrer" class="">Okta</a>, <a href="https://www.ory.sh/" target="_blank" rel="noopener noreferrer" class="">Ory</a>, and <a href="https://cloud.google.com/identity" target="_blank" rel="noopener noreferrer" class="">Google Cloud Identity</a> can work with Dashy through its <a href="#oidc" class="">OIDC support</a>. If your provider speaks OIDC (most do), just configure it as described in the OIDC section and you&#x27;re set.</p>
<p>For providers that only support OAuth2 or SAML without an OIDC layer, you&#x27;ll need something in between to translate. Authentik, Keycloak, and Authelia can all bridge from SAML/OAuth2 to OIDC.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="cloud-hosting-providers">Cloud hosting providers<a href="#cloud-hosting-providers" class="hash-link" aria-label="Direct link to Cloud hosting providers" title="Direct link to Cloud hosting providers" translate="no">​</a></h3>
<p>If you&#x27;re running Dashy on a cloud platform, most have their own auth options you can enable without touching Dashy&#x27;s config. See your provider&#x27;s docs: <a href="https://www.cloudflare.com/teams/access/" target="_blank" rel="noopener noreferrer" class="">Cloudflare Access</a>, <a href="https://docs.netlify.com/visitor-access/password-protection/" target="_blank" rel="noopener noreferrer" class="">Netlify Password Protection</a>, <a href="https://aws.amazon.com/cognito/" target="_blank" rel="noopener noreferrer" class="">AWS Cognito</a>, <a href="https://learn.microsoft.com/en-us/azure/app-service/overview-authentication-authorization" target="_blank" rel="noopener noreferrer" class="">Azure App Service Authentication</a>, and <a href="https://vercel.com/docs/security/password-protection" target="_blank" rel="noopener noreferrer" class="">Vercel Password Protection</a>.</p>
<p><strong><strong><a href="#" class="">⬆️ Back to Top</a></strong></strong></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/docs/authentication.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-04-13T13:32:23.000Z" itemprop="dateModified">Apr 13, 2026</time></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/status-indicators"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Status Indicators</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/searching"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Keyboard Shortcuts</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="#built-in-auth" class="table-of-contents__link toc-highlight">Built-In Auth</a><ul><li><a href="#setting-up-authentication" class="table-of-contents__link toc-highlight">Setting Up Authentication</a></li><li><a href="#hash-password" class="table-of-contents__link toc-highlight">Hash Password</a></li><li><a href="#logging-in-and-out" class="table-of-contents__link toc-highlight">Logging In and Out</a></li><li><a href="#enabling-guest-access" class="table-of-contents__link toc-highlight">Enabling Guest Access</a></li><li><a href="#granular-access" class="table-of-contents__link toc-highlight">Granular Access</a></li><li><a href="#permissions" class="table-of-contents__link toc-highlight">Permissions</a></li><li><a href="#using-environment-variables-for-passwords" class="table-of-contents__link toc-highlight">Using Environment Variables for Passwords</a></li><li><a href="#adding-http-auth-to-configuration" class="table-of-contents__link toc-highlight">Adding HTTP Auth to Configuration</a></li><li><a href="#security" class="table-of-contents__link toc-highlight">Security</a></li></ul></li><li><a href="#http-auth" class="table-of-contents__link toc-highlight">HTTP Auth</a><ul><li><a href="#using-config-file-users-recommended" class="table-of-contents__link toc-highlight">Using config-file users (recommended)</a></li><li><a href="#using-static-credentials" class="table-of-contents__link toc-highlight">Using static credentials</a></li></ul></li><li><a href="#keycloak" class="table-of-contents__link toc-highlight">Keycloak</a><ul><li><a href="#1-deploy-keycloak" class="table-of-contents__link toc-highlight">1. Deploy Keycloak</a></li><li><a href="#2-setup-keycloak-users" class="table-of-contents__link toc-highlight">2. Setup Keycloak Users</a></li><li><a href="#3-enable-keycloak-in-dashy-config-file" class="table-of-contents__link toc-highlight">3. Enable Keycloak in Dashy Config File</a></li><li><a href="#4-add-groups-and-roles-optional" class="table-of-contents__link toc-highlight">4. Add groups and roles (Optional)</a></li><li><a href="#troubleshooting-keycloak" class="table-of-contents__link toc-highlight">Troubleshooting Keycloak</a></li></ul></li><li><a href="#header-authentication" class="table-of-contents__link toc-highlight">Header Authentication</a><ul><li><a href="#configuration" class="table-of-contents__link toc-highlight">Configuration</a></li><li><a href="#how-it-works" class="table-of-contents__link toc-highlight">How it Works</a></li><li><a href="#notes" class="table-of-contents__link toc-highlight">Notes</a></li></ul></li><li><a href="#oidc" class="table-of-contents__link toc-highlight">OIDC</a></li><li><a href="#authentik" class="table-of-contents__link toc-highlight">authentik</a></li><li><a href="#alternative-authentication-methods" class="table-of-contents__link toc-highlight">Alternative Authentication Methods</a><ul><li><a href="#reverse-proxy-auth" class="table-of-contents__link toc-highlight">Reverse proxy auth</a></li><li><a href="#zero-trust-tunnels" class="table-of-contents__link toc-highlight">Zero-trust tunnels</a></li><li><a href="#vpn" class="table-of-contents__link toc-highlight">VPN</a></li><li><a href="#ip-based-access" class="table-of-contents__link toc-highlight">IP-based access</a></li><li><a href="#web-server-authentication" class="table-of-contents__link toc-highlight">Web server authentication</a></li><li><a href="#sso--oauth-providers" class="table-of-contents__link toc-highlight">SSO / OAuth providers</a></li><li><a href="#cloud-hosting-providers" class="table-of-contents__link toc-highlight">Cloud hosting providers</a></li></ul></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">Setup Guide</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/deployment">Deploying</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">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/authentication">Authentication</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/alternate-views">Alternate Views</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/backup-restore">Backup &amp; Restore</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/icons">Icons</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/multi-language-support">Language Switching</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/searching">Searching &amp; Shortcuts</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/theming">Theming</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/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/contributing">Contributing</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/showcase">Showcase</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/credits">Credits</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 &amp; Security</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/license">License</a></li><li class="footer__item"><a href="https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md" target="_blank" rel="noopener noreferrer" class="footer__link-item">Legal<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://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><li class="footer__item"><a href="https://github.com/Lissy93/dashy/blob/master/.github/CHANGELOG.md" target="_blank" rel="noopener noreferrer" class="footer__link-item">Changelog<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><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>
Reference in New Issue View Git Blame Copy Permalink