mirror of
https://github.com/openziti/zrok.git
synced 2024-12-26 08:38:50 +01:00
79 lines
38 KiB
HTML
79 lines
38 KiB
HTML
<!doctype html>
|
||
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-guides/self-hosting/oauth/configuring-oauth" data-has-hydrated="false">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="generator" content="Docusaurus v3.3.2">
|
||
<title data-rh="true">OAuth Public Frontend Configuration | Zrok</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://docs.zrok.io/docs/guides/self-hosting/oauth/configuring-oauth/"><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="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="OAuth Public Frontend Configuration | Zrok"><meta data-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."><meta data-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."><link data-rh="true" rel="icon" href="/img/space-ziggy.png"><link data-rh="true" rel="canonical" href="https://docs.zrok.io/docs/guides/self-hosting/oauth/configuring-oauth/"><link data-rh="true" rel="alternate" href="https://docs.zrok.io/docs/guides/self-hosting/oauth/configuring-oauth/" hreflang="en"><link data-rh="true" rel="alternate" href="https://docs.zrok.io/docs/guides/self-hosting/oauth/configuring-oauth/" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://CO73R59OLO-dsn.algolia.net" crossorigin="anonymous"><link rel="preconnect" href="https://www.googletagmanager.com">
|
||
<script>window.dataLayer=window.dataLayer||[]</script>
|
||
<script>!function(e,t,a,n,g){e[n]=e[n]||[],e[n].push({"gtm.start":(new Date).getTime(),event:"gtm.js"});var m=t.getElementsByTagName(a)[0],r=t.createElement(a);r.async=!0,r.src="https://www.googletagmanager.com/gtm.js?id=GTM-MDFLZPK8",m.parentNode.insertBefore(r,m)}(window,document,"script","dataLayer")</script>
|
||
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml" title="Zrok" href="/opensearch.xml"><link rel="stylesheet" href="/assets/css/styles.44f28847.css">
|
||
<script src="/assets/js/runtime~main.6fc8bd33.js" defer="defer"></script>
|
||
<script src="/assets/js/main.53605760.js" defer="defer"></script>
|
||
</head>
|
||
<body class="navigation-with-keyboard">
|
||
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-MDFLZPK8" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
|
||
|
||
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return localStorage.getItem("theme")}catch(t){}}();t(null!==e?e:"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 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="navbar navbar--fixed-top"><div class="navbar__inner"><div class="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 href="https://zrok.io" target="_self" rel="noopener noreferrer" class="navbar__brand"><div class="navbar__logo"><img src="/img/space-ziggy.png" alt="Ziggy Goes to Space" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/img/space-ziggy.png" alt="Ziggy Goes to Space" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><b class="navbar__title text--truncate">zrok</b></a></div><div class="navbar__items navbar__items--right"><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/getting-started/">Docs</a><a href="https://github.com/orgs/openziti/projects/16" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Roadmap<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><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"></path></svg></a><a href="https://github.com/openziti/zrok" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><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"></path></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="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"><svg viewBox="0 0 24 24" width="24" height="24" class="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" class="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></button></div><div class="navbarSearchContainer_Bca1"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="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-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/getting-started/">Getting Started</a></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="menu__link menu__link--sublist" href="/docs/concepts/">Concepts</a><button aria-label="Expand sidebar category 'Concepts'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></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="menu__link menu__link--sublist menu__link--active" href="/docs/category/guides/">Guides</a><button aria-label="Collapse sidebar category 'Guides'" aria-expanded="true" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" tabindex="0" href="/docs/guides/install/">Install</a><button aria-label="Expand sidebar category 'Install'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></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/guides/frontdoor/">frontdoor</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/guides/permission-modes/">Permission Modes</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" tabindex="0" href="/docs/guides/docker-share/">Docker Share</a><button aria-label="Expand sidebar category 'Docker Share'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--active" tabindex="0" href="/docs/category/self-hosting/">Self Hosting</a><button aria-label="Collapse sidebar category 'Self Hosting'" aria-expanded="true" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-3 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" tabindex="0" href="/docs/guides/self-hosting/linux/">Linux</a><button aria-label="Expand sidebar category 'Linux'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/guides/self-hosting/docker/">Docker</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-3 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" tabindex="0" href="/docs/category/metrics-and-limits/">Metrics and Limits</a><button aria-label="Expand sidebar category 'Metrics and Limits'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-3 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--active" tabindex="0" href="/docs/category/oauth/">OAuth</a><button aria-label="Collapse sidebar category 'OAuth'" aria-expanded="true" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-4 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/guides/self-hosting/oauth/configuring-oauth/">OAuth Public Frontend Configuration</a></li></ul></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/guides/self-hosting/instance-configuration/">Instance Config</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" tabindex="0" href="/docs/guides/drives/cli/">drives</a></div></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/guides/vpn/">VPN</a></li></ul></li></ul></nav></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" itemscope="" itemtype="https://schema.org/BreadcrumbList"><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 itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item"><a class="breadcrumbs__link" itemprop="item" href="/docs/category/guides/"><span itemprop="name">Guides</span></a><meta itemprop="position" content="1"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item"><a class="breadcrumbs__link" itemprop="item" href="/docs/category/self-hosting/"><span itemprop="name">Self Hosting</span></a><meta itemprop="position" content="2"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item"><a class="breadcrumbs__link" itemprop="item" href="/docs/category/oauth/"><span itemprop="name">OAuth</span></a><meta itemprop="position" content="3"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">OAuth Public Frontend Configuration</span><meta itemprop="position" content="4"></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"><h1>OAuth Public Frontend Configuration</h1>
|
||
<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>
|
||
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="planning-for-the-oauth-frontend">Planning for the OAuth Frontend<a href="#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>
|
||
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="configuring-a-google-oauth-client-id">Configuring a Google OAuth Client ID<a href="#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>
|
||
<h3 class="anchor anchorWithStickyNavbar_LWe7" id="oauth-content-screen">OAuth Content Screen<a href="#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><img decoding="async" loading="lazy" src="/assets/images/google_oauth_content_screen_2-b94a6456ce9b13e053b4c07d8f233e84.png" width="1469" height="1141" class="img_ev3q"></p>
|
||
<p>Here you can give your <code>zrok</code> public frontend an identity and branding to match your deployment.</p>
|
||
<p><img decoding="async" loading="lazy" src="/assets/images/google_oauth_content_screen_3-edf62ea2b291b58093289d31c2dae58d.png" width="1469" height="1141" class="img_ev3q"></p>
|
||
<p>Describe what domains are authorized to access your public frontend and establish contact information.</p>
|
||
<p><img decoding="async" loading="lazy" src="/assets/images/google_oauth_content_screen_4-4bc7e07b06c8a9a3c1e8f766f6f1c5a6.png" width="1469" height="1179" class="img_ev3q"></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><img decoding="async" loading="lazy" src="/assets/images/google_oauth_content_screen_5-7c375cf49d8e2e392ca12b584462ab59.png" width="1469" height="1179" class="img_ev3q"></p>
|
||
<p><img decoding="async" loading="lazy" src="/assets/images/google_oauth_content_screen_6-9b0fe216a782ef378313650e99ea52a1.png" width="1469" height="1179" class="img_ev3q"></p>
|
||
<p>Now your OAuth content screen is configured.</p>
|
||
<h3 class="anchor anchorWithStickyNavbar_LWe7" id="create-the-oauth-20-client-id">Create the OAuth 2.0 Client ID<a href="#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><img decoding="async" loading="lazy" src="/assets/images/google_create_credentials_1-e61ee7e8fa51bdc93feab84235a90673.png" width="1469" height="1179" class="img_ev3q"></p>
|
||
<p>Select <code>OAuth client ID</code> from the <code>+ Create Credentials</code> dropdown.</p>
|
||
<p><img decoding="async" loading="lazy" src="/assets/images/google_create_credentials_2-60cf4edb52f453d605907c17400e0800.png" width="1469" height="1179" class="img_ev3q"></p>
|
||
<p>Application type is <code>Web Application</code>.</p>
|
||
<p><img decoding="async" loading="lazy" src="/assets/images/google_create_credentials_3-1b3db3f9057d8626d64c5466dbb05ec7.png" width="1469" height="1179" class="img_ev3q"></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><img decoding="async" loading="lazy" src="/assets/images/google_create_credentials_4-f720031df1d09f997a18842745e9ea0d.png" width="1469" height="1179" class="img_ev3q"></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>
|
||
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="configuring-a-github-client-id">Configuring a GitHub Client ID<a href="#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><img decoding="async" loading="lazy" src="/assets/images/github_create_oauth_application_1-dbb289a694d0c99b50cb949654d818f8.png" width="1469" height="1179" class="img_ev3q"></p>
|
||
<p><img decoding="async" loading="lazy" src="/assets/images/github_create_oauth_application_2-bc9d4c3f25853d608870eb220d00e5ee.png" width="1469" height="1179" class="img_ev3q"></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><img decoding="async" loading="lazy" src="/assets/images/github_create_oauth_application_3-7973d63cd117eaba72fbaeb4ff119a39.png" width="1469" height="1179" class="img_ev3q"></p>
|
||
<p>Create a new client secret.</p>
|
||
<p><img decoding="async" loading="lazy" src="/assets/images/github_create_oauth_application_4-6fed398013c9e6c3a31e5721adac4a4c.png" width="1469" height="1179" class="img_ev3q"></p>
|
||
<p>Save the client ID and the client secret. You'll configure these into your <code>frontend.yml</code>.</p>
|
||
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="configuring-your-public-frontend">Configuring your Public Frontend<a href="#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>
|
||
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><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">oauth</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">bind_address</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> 0.0.0.0</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token number">8181</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_url</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">//oauth.zrok.io</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">cookie_domain</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> zrok.io</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">hash_key</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)">"the quick brown fox jumped over the lazy dog"</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">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 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"> google</span><br></span><span class="token-line" style="color:#F8F8F2"><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"> </span><span class="token string" style="color:rgb(255, 121, 198)">"<client id from google>"</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">client_secret</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)">"<client secret from google>"</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"> github</span><br></span><span class="token-line" style="color:#F8F8F2"><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"> </span><span class="token string" style="color:rgb(255, 121, 198)">"<client id from github>"</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">client_secret</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)">"<client secret from github>"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="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><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="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>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>
|
||
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="enabling-oauth-on-a-public-share">Enabling OAuth on a Public Share<a href="#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>
|
||
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><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">$ zrok share public --help</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Share a target resource publicly</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Usage:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> zrok share public <target> [flags]</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Flags:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> -b, --backend-mode string The backend mode {proxy, web, caddy, drive} (default "proxy")</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> --basic-auth stringArray Basic authentication users (<username:password>,...)</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> --frontends stringArray Selected frontends to use for the share (default [public])</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> --headless Disable TUI and run headless</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> -h, --help help for public</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> --insecure Enable insecure TLS certificate validation for <target></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> --oauth-check-interval duration Maximum lifetime for OAuth authentication; reauthenticate after expiry (default 3h0m0s)</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> --oauth-email-address-patterns stringArray Allow only these email domain globs to authenticate via OAuth</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> --oauth-provider string Enable OAuth provider [google, github]</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">Global Flags:</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> -p, --panic Panic instead of showing pretty errors</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> -v, --verbose Enable verbose logging</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="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><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="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-address-patterns</code> flag accepts a single glob pattern that matches an authenticated email address that is allowed to access the share. Use this flag multiple times to allow different patterns.</p>
|
||
<p>The <code>--oauth-check-interval</code> flag specifies how frequently the authentication must be checked.</p>
|
||
<p>An example public share:</p>
|
||
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><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">zrok share public --backend-mode web --oauth-provider github --oauth-email-address-patterns '*@zrok.io' ~/public</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="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><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col"><a href="https://github.com/openziti/zrok/blob/main/docs/../docs/guides/self-hosting/oauth/configuring-oauth.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"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/category/oauth/"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">OAuth</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/guides/self-hosting/instance-configuration/"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Instance Config</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="#planning-for-the-oauth-frontend" class="table-of-contents__link toc-highlight">Planning for the OAuth Frontend</a></li><li><a href="#configuring-a-google-oauth-client-id" class="table-of-contents__link toc-highlight">Configuring a Google OAuth Client ID</a><ul><li><a href="#oauth-content-screen" class="table-of-contents__link toc-highlight">OAuth Content Screen</a></li><li><a href="#create-the-oauth-20-client-id" class="table-of-contents__link toc-highlight">Create the OAuth 2.0 Client ID</a></li></ul></li><li><a href="#configuring-a-github-client-id" class="table-of-contents__link toc-highlight">Configuring a GitHub Client ID</a></li><li><a href="#configuring-your-public-frontend" class="table-of-contents__link toc-highlight">Configuring your Public Frontend</a></li><li><a href="#enabling-oauth-on-a-public-share" class="table-of-contents__link toc-highlight">Enabling OAuth on a Public Share</a></li></ul></div></div></div></div></main></div></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2024 NetFoundry Inc. Built with Docusaurus.</div></div></div></footer></div>
|
||
</body>
|
||
</html> |