<titledata-rh="true">OAuth Public Frontend Configuration | Zrok</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://docs.zrok.io/docs/guides/self-hosting/oauth/configuring-oauth/"><metadata-rh="true"property="og:locale"content="en"><metadata-rh="true"name="docusaurus_locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docusaurus_version"content="current"><metadata-rh="true"name="docusaurus_tag"content="docs-default-current"><metadata-rh="true"name="docsearch:version"content="current"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-current"><metadata-rh="true"property="og:title"content="OAuth Public Frontend Configuration | Zrok"><metadata-rh="true"name="description"content="As of v0.4.7, zrok includes OAuth integration for both Google and GitHub for zrok access public public frontends."><metadata-rh="true"property="og:description"content="As of v0.4.7, zrok includes OAuth integration for both Google and GitHub for zrok access public public frontends."><linkdata-rh="true"rel="icon"href="/img/space-ziggy.png"><linkdata-rh="true"rel="canonical"href="https://docs.zrok.io/docs/guides/self-hosting/oauth/configuring-oauth/"><linkdata-rh="true"rel="alternate"href="https://docs.zrok.io/docs/guides/self-hosting/oauth/configuring-oauth/"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://docs.zrok.io/docs/guides/self-hosting/oauth/configuring-oauth/"hreflang="x-default"><linkdata-rh="true"rel="preconnect"href="https://CO73R59OLO-dsn.algolia.net"crossorigin="anonymous"><linkrel="preconnect"href="https://www.google-analytics.com">
<script>!function(){functiont(t){document.documentElement.setAttribute("data-theme",t)}vare=function(){try{returnnewURLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{returnlocalStorage.getItem("theme")}catch(t){}}();t(null!==e?e:"dark")}(),function(){try{constc=newURLSearchParams(window.location.search).entries();for(var[t,e]ofc)if(t.startsWith("docusaurus-data-")){vara=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><divid="__docusaurus"><divrole="region"aria-label="Skip to main content"><aclass="skipToContent_fXgn"href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><navaria-label="Main"class="navbar navbar--fixed-top"><divclass="navbar__inner"><divclass="navbar__items"><buttonaria-label="Toggle navigation bar"aria-expanded="false"class="navbar__toggle clean-btn"type="button"><svgwidth="30"height="30"viewBox="0 0 30 30"aria-hidden="true"><pathstroke="currentColor"stroke-linecap="round"stroke-miterlimit="10"stroke-width="2"d="M4 7h22M4 15h22M4 23h22"></path></svg></button><ahref="https://zrok.io"target="_self"rel="noopener noreferrer"class="navbar__brand"><divclass="navbar__logo"><imgsrc="/img/space-ziggy.png"alt="Ziggy Goes to Space"class="themedComponent_mlkZ themedComponent--light_NVdE"><imgsrc="/img/space-ziggy.png"alt="Ziggy Goes to Space"class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><bclass="navbar__title text--truncate">zrok</b></a></div><divclass="navbar__items navbar__items--right"><aaria-current="page"class="navbar__item navbar__link navbar__link--active"href="/docs/getting-started/">Docs</a><ahref="https://github.com/orgs/openziti/projects/16"target="_blank"rel="noopener noreferrer"class="navbar__item navbar__link">Roadmap<svgwidth="13.5"height="13.5"aria-hidden="true"viewBox="0 0 24 24"class="iconExternalLink_nPIU"><pathfill="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"></path></svg></a><ahref="https://github.com/openziti/zrok"target="_blank"rel="noopener noreferrer"class="navbar__item navbar__link">GitHub<svgwidth="13.5"height="13.5"aria-hidden="true"viewBox="0 0 24 24"class="iconExternalLink_nPIU"><pathfill="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"></path></svg></a><divclass="toggle_vylO colorModeToggle_DEke"><buttonclass="clean-btn toggleButton_gllP toggleButtonDisabled_aARS"type="button"disabled=""title="Switch between dark and light mode (currently dark mode)"aria-label="Switch between dark and light mode (currently dark mode)"aria-live="polite"><svgviewBox="0 0 24 24"width="24"height="24"class="lightToggleIcon_pyhR"><pathfill="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><svgviewBox="0 0 24 24"width="24"height="24"class="darkToggleIcon_wfgR"><pathfill="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
<p>As of <code>v0.4.7</code>, <code>zrok</code> includes OAuth integration for both Google and GitHub for <code>zrok access public</code> public frontends.</p>
<p>This integration allows you to create public shares and request that the public frontend authenticate your users against either the Google or GitHub OAuth endpoints (using the user's Google or GitHub accounts). Additionally, you can restrict the email address domain associated with the count to a list of domains that you provide when you create the share.</p>
<p>This is a first step towards a more comprehensive portfolio of user authentication strategies in future <code>zrok</code> releases.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="planning-for-the-oauth-frontend">Planning for the OAuth Frontend<ahref="#planning-for-the-oauth-frontend"class="hash-link"aria-label="Direct link to Planning for the OAuth Frontend"title="Direct link to Planning for the OAuth Frontend"></a></h2>
<p>The current implementation of the OAuth public frontend uses a HTTP listener to handle redirects from OAuth providers. You'll need to configure a DNS name and a port for this listener that is accessible by your end users. We'll refer to this listener as the "OAuth frontend" in this guide.</p>
<p>We'll use the public DNS address of the OAuth frontend when creating the Google and GitHub OAuth clients below. This address is typically configured into these clients as the "redirect URL" where these clients will send the authenticated users after authentication.</p>
<p>The <code>zrok</code> OAuth frontend will capture the successful authentication and forward the user back to their original destination.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="configuring-a-google-oauth-client-id">Configuring a Google OAuth Client ID<ahref="#configuring-a-google-oauth-client-id"class="hash-link"aria-label="Direct link to Configuring a Google OAuth Client ID"title="Direct link to Configuring a Google OAuth Client ID"></a></h2>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="oauth-content-screen">OAuth Content Screen<ahref="#oauth-content-screen"class="hash-link"aria-label="Direct link to OAuth Content Screen"title="Direct link to OAuth Content Screen"></a></h3>
<p>Before you can configure an OAuth Client ID in Google Cloud, you have to configure the "OAuth content screen".</p>
<p>In the Google Cloud console, navigate to: <code>APIs & Services > Credentials > OAuth content screen</code></p>
<p>Add a non-sensitive scope for <code>../auth/userinfo.email</code>. This is important as it allows the <code>zrok</code> OAuth frontend to receive the email address of the authenticated user.</p>
<p>Now your OAuth content screen is configured.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="create-the-oauth-20-client-id">Create the OAuth 2.0 Client ID<ahref="#create-the-oauth-20-client-id"class="hash-link"aria-label="Direct link to Create the OAuth 2.0 Client ID"title="Direct link to Create the OAuth 2.0 Client ID"></a></h3>
<p>Next we create the OAuth Client ID for your public frontend.</p>
<p>In the Google Cloud Console, navigate to: <code>APIs & Services > Credentials > + Create Credentials</code></p>
<p>The most important bit here is the "Authorized redirect URIs". You're going to want to put a URL here that matches the <code>zrok</code> OAuth frontend address that you configured at the start of this guide, but at the end of the URL you're going to append <code>/google/oauth</code> to the URL.</p>
<p>Save the client ID and the client secret. You'll configure these into your <code>frontend.yml</code>.</p>
<p>With this your Google OAuth client should be configured and ready.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="configuring-a-github-client-id">Configuring a GitHub Client ID<ahref="#configuring-a-github-client-id"class="hash-link"aria-label="Direct link to Configuring a GitHub Client ID"title="Direct link to Configuring a GitHub Client ID"></a></h2>
<p>Register a new OAuth application through the GitHub settings for the account that owns the application.</p>
<p>Navigate to:<code>Settings > Developer Settings > OAuth Apps > Register a new application</code></p>
<p>The "Authorized callback URL" should be configured to match the OAuth frontend address you configured at the start of this guide, with <code>/github/oauth</code> appended to the end.</p>
<p>Save the client ID and the client secret. You'll configure these into your <code>frontend.yml</code>.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="configuring-your-public-frontend">Configuring your Public Frontend<ahref="#configuring-your-public-frontend"class="hash-link"aria-label="Direct link to Configuring your Public Frontend"title="Direct link to Configuring your Public Frontend"></a></h2>
<p>The public frontend configuration includes a new <code>oauth</code> section:</p>
<p>The <code>bind_address</code> parameter determines where the OAuth frontend will bind. Should be in <code>ip:port</code> format.</p>
<p>The <code>redirect_url</code> parameter determines the base URL where OAuth frontend requests will be redirected.</p>
<p><code>cookie_domain</code> is the domain where authentication cookies should be stored.</p>
<p><code>hash_key</code> is a unique string for your installation that is used to secure the authentication payloads for your public frontend.</p>
<p><code>providers</code> is a list of configured providers for this public frontend. The current implementation supports <code>google</code> and <code>github</code> as options.</p>
<p>Both the <code>google</code> and <code>github</code> providers accept a <code>client_id</code> and <code>client_secret</code> parameter. These values are provided when you configure the OAuth clients at Google or GitHub.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="enabling-oauth-on-a-public-share">Enabling OAuth on a Public Share<ahref="#enabling-oauth-on-a-public-share"class="hash-link"aria-label="Direct link to Enabling OAuth on a Public Share"title="Direct link to Enabling OAuth on a Public Share"></a></h2>
<p>With your public frontend configured to support OAuth, you can test this by creating a public share. There are new command line options to support this:</p>
<divclass="language-text codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ zrok share public</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">Error: accepts 1 arg(s), received 0</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">Usage:</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> zrok share public <target> [flags]</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">Flags:</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> -b, --backend-mode string The backend mode {proxy, web, caddy, drive} (default "proxy")</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --basic-auth stringArray Basic authentication users (<username:password>,...)</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --frontends stringArray Selected frontends to use for the share (default [public])</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --headless Disable TUI and run headless</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> -h, --help help for public</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --insecure Enable insecure TLS certificate validation for <target></span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --oauth-check-interval duration Maximum lifetime for OAuth authentication; reauthenticate after expiry (default 3h0m0s)</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --oauth-email-domains stringArray Allow only these email domains to authenticate via OAuth</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --oauth-provider string Enable OAuth provider [google, github]</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">Global Flags:</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> -p, --panic Panic instead of showing pretty errors</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> -v, --verbose Enable verbose logging</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>The <code>--oauth-provider</code> flag enables OAuth for the share using the specified provider.</p>
<p>The <code>--oauth-email-domains</code> flag accepts a comma-separated list of authenticated email address domains that are allowed to access the share.</p>
<p>The <code>--oauth-check-interval</code> flag specifies how frequently the authentication must be checked.</p>
