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><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2LWZ"id="1-deploy-keycloak"></a>1. Deploy Keycloak<aclass="hash-link"href="#1-deploy-keycloak"title="Direct link to heading">#</a></h3><p>First thing to do is to spin up a new instance of Keycloak. You will need <ahref="https://docs.docker.com/engine/install/"target="_blank"rel="noopener noreferrer">Docker installed</a>, and can then choose a tag, and pull the container from <ahref="https://quay.io/repository/keycloak/keycloak"target="_blank"rel="noopener noreferrer">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><divclass="codeBlockContainer_K1bP"><divclass="codeBlockContent_hGly bash"><pretabindex="0"class="prism-code language-bash codeBlock_23N8 thin-scrollbar"style="color:#393A34;background-color:#f6f8fa"><codeclass="codeBlockLines_39YC"><spanclass="token-line"style="color:#393A34"><spanclass="token plain">docker run -d </span><spanclass="token punctuation"style="color:#393A34">\</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> -p </span><spanclass="token number"style="color:#36acaa">8081</span><spanclass="token plain">:8080 </span><spanclass="token punctuation"style="color:#393A34">\</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> --name auth-server </span><spanclass="token punctuation"style="color:#393A34">\</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> -e </span><spanclass="token assign-left variable"style="color:#36acaa">KEYCLOAK_USER</span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain">admin </span><spanclass="token punctuation"style="color:#393A34">\</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> -e </span><spanclass="token assign-left variable"style="color:#36acaa">KEYCLOAK_PASSWORD</span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain">admin </span><spanclass="token punctuation"style="color:#393A34">\</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> quay.io/keycloak/keycloak:15.0.2</span></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_Ue-o clean-btn">Copy</button></div></div><p>If you need to pull from DockerHub, a non-official image is available <ahref="https://registry.hub.docker.com/r/jboss/keycloak"target="_blank"rel="noopener noreferrer">here</a>. Or if you would prefer not to use Docker, you can also directly install Keycloak from source, following <ahref="https://www.keycloak.org/docs/latest/getting_started/index.html"target="_blank"rel="noopener noreferrer">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><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2LWZ"id="2-setup-keycloak-users"></a>2. Setup Keycloak Users<aclass="hash-link"href="#2-setup-keycloak-users"title="Direct link to heading">#</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>Head over to the admin console</li><li>In the top-left corner there is a dropdown called 'Master', hover over it and then click 'Add Realm'</li><li>Give your realm a name, and h
For example:</p><divclass="codeBlockContainer_K1bP"><divclass="codeBlockContent_hGly yaml"><pretabindex="0"class="prism-code language-yaml codeBlock_23N8 thin-scrollbar"style="color:#393A34;background-color:#f6f8fa"><codeclass="codeBlockLines_39YC"><spanclass="token-line"style="color:#393A34"><spanclass="token key atrule"style="color:#00a4db">appConfig</span><spanclass="token punctuation"style="color:#393A34">:</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">...</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token key atrule"style="color:#00a4db">auth</span><spanclass="token punctuation"style="color:#393A34">:</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token key atrule"style="color:#00a4db">enableKeycloak</span><spanclass="token punctuation"style="color:#393A34">:</span><spanclass="token plain"></span><spanclass="token boolean important"style="color:#36acaa">true</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token key atrule"style="color:#00a4db">keycloak</span><spanclass="token punctuation"style="color:#393A34">:</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token key atrule"style="color:#00a4db">serverUrl</span><spanclass="token punctuation"style="color:#393A34">:</span><spanclass="token plain"></span><spanclass="token string"style="color:#e3116c">'http://localhost:8081'</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token key atrule"style="color:#00a4db">realm</span><spanclass="token punctuation"style="color:#393A34">:</span><spanclass="token plain"></span><spanclass="token string"style="color:#e3116c">'alicia-homelab'</span><spanclass="token plain"></span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token key atrule"style="color:#00a4db">clientId</span><spanclass="token punctuation"style="color:#393A34">:</span><spanclass="token plain"></span><spanclass="token string"style="color:#e3116c">'dashy'</span></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_Ue-o clean-btn">Copy</button></div></div><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 user permissions, time outs, password policies, access, 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><hr><h2><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2LWZ"id="alternative-authentication-methods"></a>Alternative Authentication Methods<aclass="hash-link"href="#alternative-authentication-methods"title="Direct link to heading">#</a></h2><p>If you are self-hosting Dashy, and require secure authentication to prevent unauthorized access, then you can either use Keycloak, or one of the following options:</p><ul><li><ahref="#authentication-server">Authentication Server</a> - Put Dashy behind a self-hosted auth server</li><li><ahref="#vpn">VPN</a> - Use a VPN to tunnel into the network where Dashy is running</li><li><ahref="#ip-based-access">IP-Based Access</a> - Disallow access from all IP addresses, except your own</li><li><ah
</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">$HTTP["host"] == "dashy.my-domain.net" {</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> server.document-root = "/home/lighttpd/dashy.my-domain.net/http"</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> server.errorlog = "/var/log/lighttpd/dashy.my-domain.net/error.log"</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> accesslog.filename = "/var/log/lighttpd/dashy.my-domain.net/access.log"</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> auth.require = (</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">"/docs/" => (</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">"method" =>"basic",</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">"realm" =>"Password protected area",</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">"require" =>"user=alicia"</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> )</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> )</span></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">}</span></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_Ue-o clean-btn">Copy</button></div></div><p>Restart your web server for changes to take effect.</p><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2LWZ"id="oauth-services"></a>OAuth Services<aclass="hash-link"href="#oauth-services"title="Direct link to heading">#</a></h3><p>There are also authentication services, such as <ahref="https://www.ory.sh/"target="_blank"rel="noopener noreferrer">Ory.sh</a>, <ahref="https://developer.okta.com/"target="_blank"rel="noopener noreferrer">Okta</a>, <ahref="https://auth0.com/"target="_blank"rel="noopener noreferrer">Auth0</a>, <ahref="https://firebase.google.com/docs/auth/"target="_blank"rel="noopener noreferrer">Firebase</a>. Implementing one of these solutions would involve some changes to the <ahref="https://github.com/Lissy93/dashy/blob/master/src/utils/Auth.js"target="_blank"rel="noopener noreferrer"><code>Auth.js</code></a> file, but should be fairly straight forward.</p><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2LWZ"id="static-site-hosting-providers"></a>Static Site Hosting Providers<aclass="hash-link"href="#static-site-hosting-providers"title="Direct link to heading">#</a></h3><p>If you are hosting Dashy on a cloud platform, you will probably find that it has built-in support for password protected access to web apps. For more info, see the relevant docs for your provider, for example: <ahref="https://docs.netlify.com/visitor-access/password-protection/"target="_blank"rel="noopener noreferrer">Netlify Password Protection</a>, <ahref="https://www.cloudflare.com/teams/access/"target="_blank"rel="noopener noreferrer">Cloudflare Access</a>, <ahref="https://aws.amazon.com/cognito/"target="_blank"rel="noopener noreferrer">AWS Cognito</a>, <ahref="https://docs.microsoft.com/en-us/azure/app-service/scenario-secure-app-authentication-app-service"target="_blank"rel="noopener noreferrer">Azure Authentication</a> and <ahref="https://vercel.com/docs/platform/projects#password-protection"target="_blank"rel="noopener noreferrer">Vercel Password Protection</a>.</p><p><strong><ahref="#">⬆️ Back to Top</a></strong></p></div><footerclass="row docusaurus-mt-lg"><divclass="col"><ahref="https://github.com/Lissy93/dashy/edit/gh-pages/docs/docs/authentication.md"target="_blank"rel="noreferrer noopener"><svgfill="currentColor"height="20"width="20"viewBox="0040
