mirror of
https://github.com/oauth2-proxy/oauth2-proxy.git
synced 2025-04-21 12:17:22 +02:00
56 lines
71 KiB
HTML
56 lines
71 KiB
HTML
<!doctype html>
|
|
<html class="docs-version-7.2.x" lang="en" dir="ltr">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<meta name="generator" content="Docusaurus v2.0.0-beta.15">
|
|
<title data-react-helmet="true">OAuth Provider Configuration | OAuth2 Proxy</title><meta data-react-helmet="true" name="twitter:card" content="summary_large_image"><meta data-react-helmet="true" property="og:url" content="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider"><meta data-react-helmet="true" name="docusaurus_locale" content="en"><meta data-react-helmet="true" name="docusaurus_version" content="7.2.x"><meta data-react-helmet="true" name="docusaurus_tag" content="docs-default-7.2.x"><meta data-react-helmet="true" property="og:title" content="OAuth Provider Configuration | OAuth2 Proxy"><meta data-react-helmet="true" name="description" content="You will need to register an OAuth application with a Provider (Google, GitHub or another provider), and configure it with Redirect URI(s) for the domain you intend to run oauth2-proxy on."><meta data-react-helmet="true" property="og:description" content="You will need to register an OAuth application with a Provider (Google, GitHub or another provider), and configure it with Redirect URI(s) for the domain you intend to run oauth2-proxy on."><link data-react-helmet="true" rel="icon" href="/oauth2-proxy/img/logos/OAuth2_Proxy_icon.svg"><link data-react-helmet="true" rel="canonical" href="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider"><link data-react-helmet="true" rel="alternate" href="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider" hreflang="en"><link data-react-helmet="true" rel="alternate" href="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider" hreflang="x-default"><link rel="stylesheet" href="/oauth2-proxy/assets/css/styles.19258e03.css">
|
|
<link rel="preload" href="/oauth2-proxy/assets/js/runtime~main.1b99ec01.js" as="script">
|
|
<link rel="preload" href="/oauth2-proxy/assets/js/main.7b57a222.js" as="script">
|
|
</head>
|
|
<body>
|
|
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script><div id="__docusaurus">
|
|
<div role="region"><a href="#" class="skipToContent_ZgBM">Skip to main content</a></div><nav class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Navigation bar toggle" class="navbar__toggle clean-btn" type="button" tabindex="0"><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="/oauth2-proxy/"><div class="navbar__logo"><img src="/oauth2-proxy/img/logos/OAuth2_Proxy_icon.svg" alt="OAuth2 Proxy" class="themedImage_W2Cr themedImage--light_TfLj"><img src="/oauth2-proxy/img/logos/OAuth2_Proxy_icon.svg" alt="OAuth2 Proxy" class="themedImage_W2Cr themedImage--dark_oUvU"></div><b class="navbar__title">OAuth2 Proxy</b></a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/oauth2-proxy/docs/">Docs</a></div><div class="navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a class="navbar__link" href="/oauth2-proxy/docs/">7.2.x</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/oauth2-proxy/docs/next/configuration/oauth_provider">Next</a></li><li><a aria-current="page" class="dropdown__link dropdown__link--active" href="/oauth2-proxy/docs/configuration/oauth_provider">7.2.x</a></li><li><a class="dropdown__link" href="/oauth2-proxy/docs/7.1.x/configuration/oauth_provider">7.1.x</a></li><li><a class="dropdown__link" href="/oauth2-proxy/docs/7.0.x/configuration/oauth_provider">7.0.x</a></li><li><a class="dropdown__link" href="/oauth2-proxy/docs/6.1.x/configuration/oauth_provider">6.1.x</a></li></ul></div><a href="https://github.com/oauth2-proxy/oauth2-proxy" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link"><span>GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_I5OW"><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></span></a><div class="toggle_Pssr toggle_TdHA toggleDisabled_jDku"><div class="toggleTrack_SSoT" role="button" tabindex="-1"><div class="toggleTrackCheck_XobZ"><span class="toggleIcon_eZtF">🌜</span></div><div class="toggleTrackX_YkSC"><span class="toggleIcon_eZtF">🌞</span></div><div class="toggleTrackThumb_uRm4"></div></div><input type="checkbox" class="toggleScreenReader_JnkT" aria-label="Switch between dark and light mode"></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div class="main-wrapper docs-wrapper docs-doc-page"><div class="docPage_P2Lg"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_RiI4" type="button"></button><aside class="theme-doc-sidebar-container docSidebarContainer_rKC_"><div class="sidebar_CW9Y"><nav class="menu thin-scrollbar menu_SkdO"><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="/oauth2-proxy/docs/">Installation</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/oauth2-proxy/docs/behaviour">Behaviour</a></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 hasHref_VCh3" aria-current="page" href="/oauth2-proxy/docs/configuration/overview">Configuration</a></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-2 menu__list-item"><a class="menu__link" tabindex="0" href="/oauth2-proxy/docs/configuration/overview">Overview</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="/oauth2-proxy/docs/configuration/oauth_provider">OAuth Provider Configuration</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="/oauth2-proxy/docs/configuration/session_storage">Session Storage</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="/oauth2-proxy/docs/configuration/tls">TLS Configuration</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="/oauth2-proxy/docs/configuration/alpha-config">Alpha Configuration</a></li></ul></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 hasHref_VCh3" href="/oauth2-proxy/docs/features/endpoints">Features</a></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-2 menu__list-item"><a class="menu__link" tabindex="0" href="/oauth2-proxy/docs/features/endpoints">Endpoints</a></li></ul></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 hasHref_VCh3" href="/oauth2-proxy/docs/community/security">Community</a></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-2 menu__list-item"><a class="menu__link" tabindex="0" href="/oauth2-proxy/docs/community/security">Security</a></li></ul></li></ul></nav></div></aside><main class="docMainContainer_TCnq"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_DM6M"><div class="docItemContainer_vinB"><article><span class="theme-doc-version-badge badge badge--secondary">Version: <!-- -->7.2.x</span><div class="tocCollapsible_jdIR theme-doc-toc-mobile tocMobile_TmEX"><button type="button" class="clean-btn tocCollapsibleButton_Fzxq">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>OAuth Provider Configuration</h1></header><p>You will need to register an OAuth application with a Provider (Google, GitHub or another provider), and configure it with Redirect URI(s) for the domain you intend to run <code>oauth2-proxy</code> on.</p><p>Valid providers are :</p><ul><li><a href="#google-auth-provider">Google</a> <em>default</em></li><li><a href="#azure-auth-provider">Azure</a></li><li><a href="#adfs-auth-provider">ADFS</a></li><li><a href="#facebook-auth-provider">Facebook</a></li><li><a href="#github-auth-provider">GitHub</a></li><li><a href="#keycloak-auth-provider">Keycloak</a></li><li><a href="#gitlab-auth-provider">GitLab</a></li><li><a href="#linkedin-auth-provider">LinkedIn</a></li><li><a href="#openid-connect-provider">OpenID Connect</a></li><li><a href="#logingov-provider">login.gov</a></li><li><a href="#nextcloud-provider">Nextcloud</a></li><li><a href="#digitalocean-auth-provider">DigitalOcean</a></li><li><a href="#bitbucket-auth-provider">Bitbucket</a></li><li><a href="#gitea-auth-provider">Gitea</a></li></ul><p>The provider can be selected using the <code>provider</code> configuration value.</p><p>Please note that not all providers support all claims. The <code>preferred_username</code> claim is currently only supported by the OpenID Connect provider.</p><h3 class="anchor anchorWithStickyNavbar_mojV" id="google-auth-provider">Google Auth Provider<a class="hash-link" href="#google-auth-provider" title="Direct link to heading"></a></h3><p>For Google, the registration steps are:</p><ol><li>Create a new project: <a href="https://console.developers.google.com/project" target="_blank" rel="noopener noreferrer">https://console.developers.google.com/project</a></li><li>Choose the new project from the top right project dropdown (only if another project is selected)</li><li>In the project Dashboard center pane, choose <strong>"API Manager"</strong></li><li>In the left Nav pane, choose <strong>"Credentials"</strong></li><li>In the center pane, choose <strong>"OAuth consent screen"</strong> tab. Fill in <strong>"Product name shown to users"</strong> and hit save.</li><li>In the center pane, choose <strong>"Credentials"</strong> tab.<ul><li>Open the <strong>"New credentials"</strong> drop down</li><li>Choose <strong>"OAuth client ID"</strong></li><li>Choose <strong>"Web application"</strong></li><li>Application name is freeform, choose something appropriate</li><li>Authorized JavaScript origins is your domain ex: <code>https://internal.yourcompany.com</code></li><li>Authorized redirect URIs is the location of oauth2/callback ex: <code>https://internal.yourcompany.com/oauth2/callback</code></li><li>Choose <strong>"Create"</strong></li></ul></li><li>Take note of the <strong>Client ID</strong> and <strong>Client Secret</strong></li></ol><p>It's recommended to refresh sessions on a short interval (1h) with <code>cookie-refresh</code> setting which validates that the account is still authorized.</p><h4 class="anchor anchorWithStickyNavbar_mojV" id="restrict-auth-to-specific-google-groups-on-your-domain-optional">Restrict auth to specific Google groups on your domain. (optional)<a class="hash-link" href="#restrict-auth-to-specific-google-groups-on-your-domain-optional" title="Direct link to heading"></a></h4><ol><li>Create a service account: <a href="https://developers.google.com/identity/protocols/OAuth2ServiceAccount" target="_blank" rel="noopener noreferrer">https://developers.google.com/identity/protocols/OAuth2ServiceAccount</a> and make sure to download the json file.</li><li>Make note of the Client ID for a future step.</li><li>Under "APIs & Auth", choose APIs.</li><li>Click on Admin SDK and then Enable API.</li><li>Follow the steps on <a href="https://developers.google.com/admin-sdk/directory/v1/guides/delegation#delegate_domain-wide_authority_to_your_service_account" target="_blank" rel="noopener noreferrer">https://developers.google.com/admin-sdk/directory/v1/guides/delegation#delegate_domain-wide_authority_to_your_service_account</a> and give the client id from step 2 the following oauth scopes:</li></ol><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">https://www.googleapis.com/auth/admin.directory.group.readonly</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">https://www.googleapis.com/auth/admin.directory.user.readonly</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><ol start="6"><li>Follow the steps on <a href="https://support.google.com/a/answer/60757" target="_blank" rel="noopener noreferrer">https://support.google.com/a/answer/60757</a> to enable Admin API access.</li><li>Create or choose an existing administrative email address on the Gmail domain to assign to the <code>google-admin-email</code> flag. This email will be impersonated by this client to make calls to the Admin SDK. See the note on the link from step 5 for the reason why.</li><li>Create or choose an existing email group and set that email to the <code>google-group</code> flag. You can pass multiple instances of this flag with different groups
|
|
and the user will be checked against all the provided groups.</li><li>Lock down the permissions on the json file downloaded from step 1 so only oauth2-proxy is able to read the file and set the path to the file in the <code>google-service-account-json</code> flag.</li><li>Restart oauth2-proxy.</li></ol><p>Note: The user is checked against the group members list on initial authentication and every time the token is refreshed ( about once an hour ).</p><h3 class="anchor anchorWithStickyNavbar_mojV" id="azure-auth-provider">Azure Auth Provider<a class="hash-link" href="#azure-auth-provider" title="Direct link to heading"></a></h3><ol><li>Add an application: go to <a href="https://portal.azure.com" target="_blank" rel="noopener noreferrer">https://portal.azure.com</a>, choose <strong>"Azure Active Directory"</strong> in the left menu, select <strong>"App registrations"</strong> and then click on <strong>"New app registration"</strong>.</li><li>Pick a name and choose <strong>"Webapp / API"</strong> as application type. Use <code>https://internal.yourcompany.com</code> as Sign-on URL. Click <strong>"Create"</strong>.</li><li>On the <strong>"Settings"</strong> / <strong>"Properties"</strong> page of the app, pick a logo and select <strong>"Multi-tenanted"</strong> if you want to allow users from multiple organizations to access your app. Note down the application ID. Click <strong>"Save"</strong>.</li><li>On the <strong>"Settings"</strong> / <strong>"Required Permissions"</strong> page of the app, click on <strong>"Windows Azure Active Directory"</strong> and then on <strong>"Access the directory as the signed in user"</strong>. Hit <strong>"Save"</strong> and then then on <strong>"Grant permissions"</strong> (you might need another admin to do this).</li><li>On the <strong>"Settings"</strong> / <strong>"Reply URLs"</strong> page of the app, add <code>https://internal.yourcompanycom/oauth2/callback</code> for each host that you want to protect by the oauth2 proxy. Click <strong>"Save"</strong>.</li><li>On the <strong>"Settings"</strong> / <strong>"Keys"</strong> page of the app, add a new key and note down the value after hitting <strong>"Save"</strong>.</li><li>Configure the proxy with</li></ol><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --provider=azure</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-id=<application ID from step 3></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-secret=<value from step 6></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --oidc-issuer-url=https://sts.windows.net/{tenant-id}/</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>Note: When using the Azure Auth provider with nginx and the cookie session store you may find the cookie is too large and doesn't get passed through correctly. Increasing the <code>proxy_buffer_size</code> in nginx or implementing the <a href="/oauth2-proxy/docs/configuration/session_storage#redis-storage">redis session storage</a> should resolve this.</p><h3 class="anchor anchorWithStickyNavbar_mojV" id="adfs-auth-provider">ADFS Auth Provider<a class="hash-link" href="#adfs-auth-provider" title="Direct link to heading"></a></h3><ol><li>Open the ADFS administration console on your Windows Server and add a new Application Group</li><li>Provide a name for the integration, select Server Application from the Standalone applications section and click Next</li><li>Follow the wizard to get the client-id, client-secret and configure the application credentials</li><li>Configure the proxy with</li></ol><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --provider=adfs</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-id=<application ID from step 3></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-secret=<value from step 3></span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>Note: When using the ADFS Auth provider with nginx and the cookie session store you may find the cookie is too large and doesn't get passed through correctly. Increasing the proxy_buffer_size in nginx or implementing the <a href="/oauth2-proxy/docs/configuration/session_storage#redis-storage">redis session storage</a> should resolve this.</p><h3 class="anchor anchorWithStickyNavbar_mojV" id="facebook-auth-provider">Facebook Auth Provider<a class="hash-link" href="#facebook-auth-provider" title="Direct link to heading"></a></h3><ol><li>Create a new FB App from <a href="https://developers.facebook.com/" target="_blank" rel="noopener noreferrer">https://developers.facebook.com/</a></li><li>Under FB Login, set your Valid OAuth redirect URIs to <code>https://internal.yourcompany.com/oauth2/callback</code></li></ol><h3 class="anchor anchorWithStickyNavbar_mojV" id="github-auth-provider">GitHub Auth Provider<a class="hash-link" href="#github-auth-provider" title="Direct link to heading"></a></h3><ol><li>Create a new project: <a href="https://github.com/settings/developers" target="_blank" rel="noopener noreferrer">https://github.com/settings/developers</a></li><li>Under <code>Authorization callback URL</code> enter the correct url ie <code>https://internal.yourcompany.com/oauth2/callback</code></li></ol><p>The GitHub auth provider supports two additional ways to restrict authentication to either organization and optional team level access, or to collaborators of a repository. Restricting by these options is normally accompanied with <code>--email-domain=*</code></p><p>NOTE: When <code>--github-user</code> is set, the specified users are allowed to login even if they do not belong to the specified org and team or collaborators.</p><p>To restrict by organization only, include the following flag:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">-github-org="": restrict logins to members of this organisation</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>To restrict within an organization to specific teams, include the following flag in addition to <code>-github-org</code>:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">-github-team="": restrict logins to members of any of these teams (slug), separated by a comma</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>If you would rather restrict access to collaborators of a repository, those users must either have push access to a public repository or any access to a private repository:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">-github-repo="": restrict logins to collaborators of this repository formatted as orgname/repo</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>If you'd like to allow access to users with <strong>read only</strong> access to a <strong>public</strong> repository you will need to provide a <a href="https://github.com/settings/tokens" target="_blank" rel="noopener noreferrer">token</a> for a user that has write access to the repository. The token must be created with at least the <code>public_repo</code> scope:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">-github-token="": the token to use when verifying repository collaborators</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>To allow a user to login with their username even if they do not belong to the specified org and team or collaborators, separated by a comma</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">-github-user="": allow logins by username, separated by a comma</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>If you are using GitHub enterprise, make sure you set the following to the appropriate url:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">-login-url="http(s)://<enterprise github host>/login/oauth/authorize"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-redeem-url="http(s)://<enterprise github host>/login/oauth/access_token"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-validate-url="http(s)://<enterprise github host>/api/v3"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><h3 class="anchor anchorWithStickyNavbar_mojV" id="keycloak-auth-provider">Keycloak Auth Provider<a class="hash-link" href="#keycloak-auth-provider" title="Direct link to heading"></a></h3><div class="admonition admonition-note alert alert--secondary"><div class="admonition-heading"><h5><span class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" width="14" height="16" 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</h5></div><div class="admonition-content"><p>This is the legacy provider for Keycloak, use <a href="#keycloak-oidc-auth-provider">Keycloak OIDC Auth Provider</a> if possible.</p></div></div><ol><li>Create new client in your Keycloak realm with <strong>Access Type</strong> 'confidental' and <strong>Valid Redirect URIs</strong> '<a href="https://internal.yourcompany.com/oauth2/callback'" target="_blank" rel="noopener noreferrer">https://internal.yourcompany.com/oauth2/callback'</a></li><li>Take note of the Secret in the credential tab of the client</li><li>Create a mapper with <strong>Mapper Type</strong> 'Group Membership' and <strong>Token Claim Name</strong> 'groups'.</li></ol><p>Make sure you set the following to the appropriate url:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --provider=keycloak</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-id=<client you have created></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-secret=<your client's secret></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --login-url="http(s)://<keycloak host>/auth/realms/<your realm>/protocol/openid-connect/auth"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --redeem-url="http(s)://<keycloak host>/auth/realms/<your realm>/protocol/openid-connect/token"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --profile-url="http(s)://<keycloak host>/auth/realms/<your realm>/protocol/openid-connect/userinfo"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --validate-url="http(s)://<keycloak host>/auth/realms/<your realm>/protocol/openid-connect/userinfo"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --keycloak-group=<first_allowed_user_group></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --keycloak-group=<second_allowed_user_group></span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>For group based authorization, the optional <code>--keycloak-group</code> (legacy) or <code>--allowed-group</code> (global standard)
|
|
flags can be used to specify which groups to limit access to.</p><p>If these are unset but a <code>groups</code> mapper is set up above in step (3), the provider will still
|
|
populate the <code>X-Forwarded-Groups</code> header to your upstream server with the <code>groups</code> data in the
|
|
Keycloak userinfo endpoint response.</p><p>The group management in keycloak is using a tree. If you create a group named admin in keycloak
|
|
you should define the 'keycloak-group' value to /admin.</p><h3 class="anchor anchorWithStickyNavbar_mojV" id="keycloak-oidc-auth-provider">Keycloak OIDC Auth Provider<a class="hash-link" href="#keycloak-oidc-auth-provider" title="Direct link to heading"></a></h3><ol><li>Create new client in your Keycloak realm with <strong>Access Type</strong> 'confidental', <strong>Client protocol</strong> 'openid-connect' and <strong>Valid Redirect URIs</strong> '<a href="https://internal.yourcompany.com/oauth2/callback'" target="_blank" rel="noopener noreferrer">https://internal.yourcompany.com/oauth2/callback'</a></li><li>Take note of the Secret in the credential tab of the client</li><li>Create a mapper with <strong>Mapper Type</strong> 'Group Membership' and <strong>Token Claim Name</strong> 'groups'.</li><li>Create a mapper with <strong>Mapper Type</strong> 'Audience' and <strong>Included Client Audience</strong> and <strong>Included Custom Audience</strong> set to your client name.</li></ol><p>Make sure you set the following to the appropriate url:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --provider=keycloak-oidc</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-id=<your client's id></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-secret=<your client's secret></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --redirect-url=https://myapp.com/oauth2/callback</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --oidc-issuer-url=https://<keycloak host>/auth/realms/<your realm></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --allowed-role=<realm role name> // Optional, required realm role</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --allowed-role=<client id>:<client role name> // Optional, required client role</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><h3 class="anchor anchorWithStickyNavbar_mojV" id="gitlab-auth-provider">GitLab Auth Provider<a class="hash-link" href="#gitlab-auth-provider" title="Direct link to heading"></a></h3><p>This auth provider has been tested against Gitlab version 12.X. Due to Gitlab API changes, it may not work for version prior to 12.X (see <a href="https://github.com/oauth2-proxy/oauth2-proxy/issues/994" target="_blank" rel="noopener noreferrer">994</a>).</p><p>Whether you are using GitLab.com or self-hosting GitLab, follow <a href="https://docs.gitlab.com/ce/integration/oauth_provider.html" target="_blank" rel="noopener noreferrer">these steps to add an application</a>. Make sure to enable at least the <code>openid</code>, <code>profile</code> and <code>email</code> scopes, and set the redirect url to your application url e.g. <a href="https://myapp.com/oauth2/callback" target="_blank" rel="noopener noreferrer">https://myapp.com/oauth2/callback</a>.</p><p>If you need projects filtering, add the extra <code>read_api</code> scope to your application.</p><p>The following config should be set to ensure that the oauth will work properly. To get a cookie secret follow <a href="/oauth2-proxy/docs/configuration/overview#generating-a-cookie-secret">these steps</a></p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --provider="gitlab"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --redirect-url="https://myapp.com/oauth2/callback" // Should be the same as the redirect url for the application in gitlab</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-id=GITLAB_CLIENT_ID</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-secret=GITLAB_CLIENT_SECRET</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --cookie-secret=COOKIE_SECRET</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>Restricting by group membership is possible with the following option:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">--gitlab-group="mygroup,myothergroup": restrict logins to members of any of these groups (slug), separated by a comma</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>If you are using self-hosted GitLab, make sure you set the following to the appropriate URL:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">--oidc-issuer-url="<your gitlab url>"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><h3 class="anchor anchorWithStickyNavbar_mojV" id="linkedin-auth-provider">LinkedIn Auth Provider<a class="hash-link" href="#linkedin-auth-provider" title="Direct link to heading"></a></h3><p>For LinkedIn, the registration steps are:</p><ol><li>Create a new project: <a href="https://www.linkedin.com/secure/developer" target="_blank" rel="noopener noreferrer">https://www.linkedin.com/secure/developer</a></li><li>In the OAuth User Agreement section:<ul><li>In default scope, select r_basicprofile and r_emailaddress.</li><li>In "OAuth 2.0 Redirect URLs", enter <code>https://internal.yourcompany.com/oauth2/callback</code></li></ul></li><li>Fill in the remaining required fields and Save.</li><li>Take note of the <strong>Consumer Key / API Key</strong> and <strong>Consumer Secret / Secret Key</strong></li></ol><h3 class="anchor anchorWithStickyNavbar_mojV" id="openid-connect-provider">OpenID Connect Provider<a class="hash-link" href="#openid-connect-provider" title="Direct link to heading"></a></h3><p>OpenID Connect is a spec for OAUTH 2.0 + identity that is implemented by many major providers and several open source projects.</p><p>This provider was originally built against CoreOS Dex and we will use it as an example.
|
|
The OpenID Connect Provider (OIDC) can also be used to connect to other Identity Providers such as Okta, an example can be found below.</p><h4 class="anchor anchorWithStickyNavbar_mojV" id="dex">Dex<a class="hash-link" href="#dex" title="Direct link to heading"></a></h4><p>To configure the OIDC provider for Dex, perform the following steps:</p><ol><li><p>Download Dex:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">go get github.com/dexidp/dex</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>See the <a href="https://dexidp.io/docs/getting-started/" target="_blank" rel="noopener noreferrer">getting started guide</a> for more details.</p></li><li><p>Setup oauth2-proxy with the correct provider and using the default ports and callbacks. Add a configuration block to the <code>staticClients</code> section of <code>examples/config-dev.yaml</code>:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">- id: oauth2-proxy</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">redirectURIs:</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">- 'http://127.0.0.1:4180/oauth2/callback'</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">name: 'oauth2-proxy'</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">secret: proxy</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div></li><li><p>Launch Dex: from <code>$GOPATH/github.com/dexidp/dex</code>, run:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">bin/dex serve examples/config-dev.yaml</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div></li><li><p>In a second terminal, run the oauth2-proxy with the following args:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">-provider oidc</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-provider-display-name "My OIDC Provider"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-client-id oauth2-proxy</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-client-secret proxy</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-redirect-url http://127.0.0.1:4180/oauth2/callback</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-oidc-issuer-url http://127.0.0.1:5556/dex</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-cookie-secure=false</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-cookie-secret=secret</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-email-domain kilgore.trout</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>To serve the current working directory as a web site under the <code>/static</code> endpoint, add:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">-upstream file://$PWD/#/static/</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div></li><li><p>Test the setup by visiting <a href="http://127.0.0.1:4180" target="_blank" rel="noopener noreferrer">http://127.0.0.1:4180</a> or <a href="http://127.0.0.1:4180/static" target="_blank" rel="noopener noreferrer">http://127.0.0.1:4180/static</a> .</p></li></ol><p>See also <a href="https://github.com/oauth2-proxy/oauth2-proxy/blob/master/contrib/local-environment" target="_blank" rel="noopener noreferrer">our local testing environment</a> for a self-contained example using Docker and etcd as storage for Dex.</p><h4 class="anchor anchorWithStickyNavbar_mojV" id="okta">Okta<a class="hash-link" href="#okta" title="Direct link to heading"></a></h4><p>To configure the OIDC provider for Okta, perform the following steps:</p><ol><li>Log in to Okta using an administrative account. It is suggested you try this in preview first, <code>example.oktapreview.com</code></li><li>(OPTIONAL) If you want to configure authorization scopes and claims to be passed on to multiple applications,
|
|
you may wish to configure an authorization server for each application. Otherwise, the provided <code>default</code> will work.</li></ol><ul><li>Navigate to <strong>Security</strong> then select <strong>API</strong></li><li>Click <strong>Add Authorization Server</strong>, if this option is not available you may require an additional license for a custom authorization server.</li><li>Fill out the <strong>Name</strong> with something to describe the application you are protecting. e.g. 'Example App'.</li><li>For <strong>Audience</strong>, pick the URL of the application you wish to protect: <a href="https://example.corp.com" target="_blank" rel="noopener noreferrer">https://example.corp.com</a></li><li>Fill out a <strong>Description</strong></li><li>Add any <strong>Access Policies</strong> you wish to configure to limit application access.</li><li>The default settings will work for other options.
|
|
<a href="https://developer.okta.com/docs/guides/customize-authz-server/overview/" target="_blank" rel="noopener noreferrer">See Okta documentation for more information on Authorization Servers</a></li></ul><ol start="3"><li>Navigate to <strong>Applications</strong> then select <strong>Add Application</strong>.</li></ol><ul><li>Select <strong>Web</strong> for the <strong>Platform</strong> setting.</li><li>Select <strong>OpenID Connect</strong> and click <strong>Create</strong></li><li>Pick an <strong>Application Name</strong> such as <code>Example App</code>.</li><li>Set the <strong>Login redirect URI</strong> to <code>https://example.corp.com</code>.</li><li>Under <strong>General</strong> set the <strong>Allowed grant types</strong> to <code>Authorization Code</code> and <code>Refresh Token</code>.</li><li>Leave the rest as default, taking note of the <code>Client ID</code> and <code>Client Secret</code>.</li><li>Under <strong>Assignments</strong> select the users or groups you wish to access your application.</li></ul><ol start="4"><li><p>Create a configuration file like the following:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">provider = "oidc"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">redirect_url = "https://example.corp.com/oauth2/callback"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">oidc_issuer_url = "https://corp.okta.com/oauth2/abCd1234"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">upstreams = [</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> "https://example.corp.com"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">]</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">email_domains = [</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> "corp.com"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">]</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">client_id = "XXXXX"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">client_secret = "YYYYY"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">pass_access_token = true</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">cookie_secret = "ZZZZZ"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">skip_provider_button = true</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div></li></ol><p>The <code>oidc_issuer_url</code> is based on URL from your <strong>Authorization Server</strong>'s <strong>Issuer</strong> field in step 2, or simply <a href="https://corp.okta.com" target="_blank" rel="noopener noreferrer">https://corp.okta.com</a> .
|
|
The <code>client_id</code> and <code>client_secret</code> are configured in the application settings.
|
|
Generate a unique <code>cookie_secret</code> to encrypt the cookie.</p><p>Then you can start the oauth2-proxy with <code>./oauth2-proxy --config /etc/example.cfg</code></p><h4 class="anchor anchorWithStickyNavbar_mojV" id="okta---localhost">Okta - localhost<a class="hash-link" href="#okta---localhost" title="Direct link to heading"></a></h4><ol><li>Signup for developer account: <a href="https://developer.okta.com/signup/" target="_blank" rel="noopener noreferrer">https://developer.okta.com/signup/</a></li><li>Create New <code>Web</code> Application: https://${your-okta-domain}/dev/console/apps/new</li><li>Example Application Settings for localhost:<ul><li><strong>Name:</strong> My Web App</li><li><strong>Base URIs:</strong> http://localhost:4180/</li><li><strong>Login redirect URIs:</strong> http://localhost:4180/oauth2/callback</li><li><strong>Logout redirect URIs:</strong> http://localhost:4180/</li><li><strong>Group assignments:</strong> <code>Everyone</code></li><li><strong>Grant type allowed:</strong> <code>Authorization Code</code> and <code>Refresh Token</code></li></ul></li><li>Make note of the <code>Client ID</code> and <code>Client secret</code>, they are needed in a future step</li><li>Make note of the <strong>default</strong> Authorization Server Issuer URI from: https://${your-okta-domain}/admin/oauth2/as</li><li>Example config file <code>/etc/localhost.cfg</code><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">provider = "oidc"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">redirect_url = "http://localhost:4180/oauth2/callback"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">oidc_issuer_url = "https://${your-okta-domain}/oauth2/default"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">upstreams = [</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> "http://0.0.0.0:8080"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">]</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">email_domains = [</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> "*"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">]</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">client_id = "XXX"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">client_secret = "YYY"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">pass_access_token = true</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">cookie_secret = "ZZZ"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">cookie_secure = false</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">skip_provider_button = true</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"># Note: use the following for testing within a container</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"># http_address = "0.0.0.0:4180"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div></li><li>Then you can start the oauth2-proxy with <code>./oauth2-proxy --config /etc/localhost.cfg</code></li></ol><h3 class="anchor anchorWithStickyNavbar_mojV" id="logingov-provider">login.gov Provider<a class="hash-link" href="#logingov-provider" title="Direct link to heading"></a></h3><p>login.gov is an OIDC provider for the US Government.
|
|
If you are a US Government agency, you can contact the login.gov team through the contact information
|
|
that you can find on <a href="https://login.gov/developers/" target="_blank" rel="noopener noreferrer">https://login.gov/developers/</a> and work with them to understand how to get login.gov
|
|
accounts for integration/test and production access.</p><p>A developer guide is available here: <a href="https://developers.login.gov/" target="_blank" rel="noopener noreferrer">https://developers.login.gov/</a>, though this proxy handles everything
|
|
but the data you need to create to register your application in the login.gov dashboard.</p><p>As a demo, we will assume that you are running your application that you want to secure locally on
|
|
http://localhost:3000/, that you will be starting your proxy up on http://localhost:4180/, and that
|
|
you have an agency integration account for testing.</p><p>First, register your application in the dashboard. The important bits are:</p><ul><li>Identity protocol: make this <code>Openid connect</code></li><li>Issuer: do what they say for OpenID Connect. We will refer to this string as <code>${LOGINGOV_ISSUER}</code>.</li><li>Public key: This is a self-signed certificate in .pem format generated from a 2048 bit RSA private key.
|
|
A quick way to do this is <code>openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3650 -nodes -subj '/C=US/ST=Washington/L=DC/O=GSA/OU=18F/CN=localhost'</code>,
|
|
The contents of the <code>key.pem</code> shall be referred to as <code>${OAUTH2_PROXY_JWT_KEY}</code>.</li><li>Return to App URL: Make this be <code>http://localhost:4180/</code></li><li>Redirect URIs: Make this be <code>http://localhost:4180/oauth2/callback</code>.</li><li>Attribute Bundle: Make sure that email is selected.</li></ul><p>Now start the proxy up with the following options:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain">./oauth2-proxy -provider login.gov \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -client-id=${LOGINGOV_ISSUER} \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -redirect-url=http://localhost:4180/oauth2/callback \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -oidc-issuer-url=https://idp.int.identitysandbox.gov/ \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -cookie-secure=false \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -email-domain=gsa.gov \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -upstream=http://localhost:3000/ \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -cookie-secret=somerandomstring12341234567890AB \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -cookie-domain=localhost \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -skip-provider-button=true \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -pubjwk-url=https://idp.int.identitysandbox.gov/api/openid_connect/certs \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -profile-url=https://idp.int.identitysandbox.gov/api/openid_connect/userinfo \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -jwt-key="${OAUTH2_PROXY_JWT_KEY}"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>You can also set all these options with environment variables, for use in cloud/docker environments.
|
|
One tricky thing that you may encounter is that some cloud environments will pass in environment
|
|
variables in a docker env-file, which does not allow multiline variables like a PEM file.
|
|
If you encounter this, then you can create a <code>jwt_signing_key.pem</code> file in the top level
|
|
directory of the repo which contains the key in PEM format and then do your docker build.
|
|
The docker build process will copy that file into your image which you can then access by
|
|
setting the <code>OAUTH2_PROXY_JWT_KEY_FILE=/etc/ssl/private/jwt_signing_key.pem</code>
|
|
environment variable, or by setting <code>--jwt-key-file=/etc/ssl/private/jwt_signing_key.pem</code> on the commandline.</p><p>Once it is running, you should be able to go to <code>http://localhost:4180/</code> in your browser,
|
|
get authenticated by the login.gov integration server, and then get proxied on to your
|
|
application running on <code>http://localhost:3000/</code>. In a real deployment, you would secure
|
|
your application with a firewall or something so that it was only accessible from the
|
|
proxy, and you would use real hostnames everywhere.</p><h4 class="anchor anchorWithStickyNavbar_mojV" id="skip-oidc-discovery">Skip OIDC discovery<a class="hash-link" href="#skip-oidc-discovery" title="Direct link to heading"></a></h4><p>Some providers do not support OIDC discovery via their issuer URL, so oauth2-proxy cannot simply grab the authorization, token and jwks URI endpoints from the provider's metadata.</p><p>In this case, you can set the <code>--skip-oidc-discovery</code> option, and supply those required endpoints manually:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -provider oidc</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -client-id oauth2-proxy</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -client-secret proxy</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -redirect-url http://127.0.0.1:4180/oauth2/callback</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -oidc-issuer-url http://127.0.0.1:5556</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -skip-oidc-discovery</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -login-url http://127.0.0.1:5556/authorize</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -redeem-url http://127.0.0.1:5556/token</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -oidc-jwks-url http://127.0.0.1:5556/keys</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -cookie-secure=false</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -email-domain example.com</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><h3 class="anchor anchorWithStickyNavbar_mojV" id="nextcloud-provider">Nextcloud Provider<a class="hash-link" href="#nextcloud-provider" title="Direct link to heading"></a></h3><p>The Nextcloud provider allows you to authenticate against users in your
|
|
Nextcloud instance.</p><p>When you are using the Nextcloud provider, you must specify the urls via
|
|
configuration, environment variable, or command line argument. Depending
|
|
on whether your Nextcloud instance is using pretty urls your urls may be of the
|
|
form <code>/index.php/apps/oauth2/*</code> or <code>/apps/oauth2/*</code>.</p><p>Refer to the <a href="https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/oauth2.html" target="_blank" rel="noopener noreferrer">OAuth2
|
|
documentation</a>
|
|
to setup the client id and client secret. Your "Redirection URI" will be
|
|
<code>https://internalapp.yourcompany.com/oauth2/callback</code>.</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -provider nextcloud</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -client-id <from nextcloud admin></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -client-secret <from nextcloud admin></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -login-url="<your nextcloud url>/index.php/apps/oauth2/authorize"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -redeem-url="<your nextcloud url>/index.php/apps/oauth2/api/v1/token"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -validate-url="<your nextcloud url>/ocs/v2.php/cloud/user?format=json"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>Note: in <em>all</em> cases the validate-url will <em>not</em> have the <code>index.php</code>.</p><h3 class="anchor anchorWithStickyNavbar_mojV" id="digitalocean-auth-provider">DigitalOcean Auth Provider<a class="hash-link" href="#digitalocean-auth-provider" title="Direct link to heading"></a></h3><ol><li><a href="https://cloud.digitalocean.com/account/api/applications" target="_blank" rel="noopener noreferrer">Create a new OAuth application</a><ul><li>You can fill in the name, homepage, and description however you wish.</li><li>In the "Application callback URL" field, enter: <code>https://oauth-proxy/oauth2/callback</code>, substituting <code>oauth2-proxy</code> with the actual hostname that oauth2-proxy is running on. The URL must match oauth2-proxy's configured redirect URL.</li></ul></li><li>Note the Client ID and Client Secret.</li></ol><p>To use the provider, pass the following options:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --provider=digitalocean</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-id=<Client ID></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-secret=<Client Secret></span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p> Alternatively, set the equivalent options in the config file. The redirect URL defaults to <code>https://<requested host header>/oauth2/callback</code>. If you need to change it, you can use the <code>--redirect-url</code> command-line option.</p><h3 class="anchor anchorWithStickyNavbar_mojV" id="bitbucket-auth-provider">Bitbucket Auth Provider<a class="hash-link" href="#bitbucket-auth-provider" title="Direct link to heading"></a></h3><ol><li><a href="https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html" target="_blank" rel="noopener noreferrer">Add a new OAuth consumer</a><ul><li>In "Callback URL" use <code>https://<oauth2-proxy>/oauth2/callback</code>, substituting <code><oauth2-proxy></code> with the actual hostname that oauth2-proxy is running on.</li><li>In Permissions section select:<ul><li>Account -> Email</li><li>Team membership -> Read</li><li>Repositories -> Read</li></ul></li></ul></li><li>Note the Client ID and Client Secret.</li></ol><p>To use the provider, pass the following options:</p><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --provider=bitbucket</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-id=<Client ID></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-secret=<Client Secret></span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>The default configuration allows everyone with Bitbucket account to authenticate. To restrict the access to the team members use additional configuration option: <code>--bitbucket-team=<Team name></code>. To restrict the access to only these users who has access to one selected repository use <code>--bitbucket-repository=<Repository name></code>.</p><h3 class="anchor anchorWithStickyNavbar_mojV" id="gitea-auth-provider">Gitea Auth Provider<a class="hash-link" href="#gitea-auth-provider" title="Direct link to heading"></a></h3><ol><li>Create a new application: <code>https://< your gitea host >/user/settings/applications</code></li><li>Under <code>Redirect URI</code> enter the correct URL i.e. <code>https://<proxied host>/oauth2/callback</code></li><li>Note the Client ID and Client Secret.</li><li>Pass the following options to the proxy:</li></ol><div class="codeBlockContainer_I0IT theme-code-block"><div class="codeBlockContent_wNvx"><pre tabindex="0" class="prism-code language-text codeBlock_jd64 thin-scrollbar" style="color:#bfc7d5;background-color:#292d3e"><code class="codeBlockLines_mRuA"><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --provider="github"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --redirect-url="https://<proxied host>/oauth2/callback"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --provider-display-name="Gitea"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-id="< client_id as generated by Gitea >"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --client-secret="< client_secret as generated by Gitea >"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --login-url="https://< your gitea host >/login/oauth/authorize"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --redeem-url="https://< your gitea host >/login/oauth/access_token"</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --validate-url="https://< your gitea host >/api/v1"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_wuS7 clean-btn">Copy</button></div></div><h2 class="anchor anchorWithStickyNavbar_mojV" id="email-authentication">Email Authentication<a class="hash-link" href="#email-authentication" title="Direct link to heading"></a></h2><p>To authorize by email domain use <code>--email-domain=yourcompany.com</code>. To authorize individual email addresses use <code>--authenticated-emails-file=/path/to/file</code> with one email per line. To authorize all email addresses use <code>--email-domain=*</code>.</p><h2 class="anchor anchorWithStickyNavbar_mojV" id="adding-a-new-provider">Adding a new Provider<a class="hash-link" href="#adding-a-new-provider" title="Direct link to heading"></a></h2><p>Follow the examples in the <a href="https://github.com/oauth2-proxy/oauth2-proxy/blob/master/providers/" target="_blank" rel="noopener noreferrer"><code>providers</code> package</a> to define a new
|
|
<code>Provider</code> instance. Add a new <code>case</code> to
|
|
<a href="https://github.com/oauth2-proxy/oauth2-proxy/blob/master/providers/providers.go" target="_blank" rel="noopener noreferrer"><code>providers.New()</code></a> to allow <code>oauth2-proxy</code> to use the
|
|
new <code>Provider</code>.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/oauth2-proxy/oauth2-proxy/edit/master/docs/versioned_docs/version-7.2.x/configuration/auth.md" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_dcUD" 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_foO9"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><div class="pagination-nav__item"><a class="pagination-nav__link" href="/oauth2-proxy/docs/configuration/overview"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Overview</div></a></div><div class="pagination-nav__item pagination-nav__item--next"><a class="pagination-nav__link" href="/oauth2-proxy/docs/configuration/session_storage"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Session Storage</div></a></div></nav></div></div><div class="col col--3"><div class="tableOfContents_cNA8 thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#google-auth-provider" class="table-of-contents__link toc-highlight">Google Auth Provider</a></li><li><a href="#azure-auth-provider" class="table-of-contents__link toc-highlight">Azure Auth Provider</a></li><li><a href="#adfs-auth-provider" class="table-of-contents__link toc-highlight">ADFS Auth Provider</a></li><li><a href="#facebook-auth-provider" class="table-of-contents__link toc-highlight">Facebook Auth Provider</a></li><li><a href="#github-auth-provider" class="table-of-contents__link toc-highlight">GitHub Auth Provider</a></li><li><a href="#keycloak-auth-provider" class="table-of-contents__link toc-highlight">Keycloak Auth Provider</a></li><li><a href="#keycloak-oidc-auth-provider" class="table-of-contents__link toc-highlight">Keycloak OIDC Auth Provider</a></li><li><a href="#gitlab-auth-provider" class="table-of-contents__link toc-highlight">GitLab Auth Provider</a></li><li><a href="#linkedin-auth-provider" class="table-of-contents__link toc-highlight">LinkedIn Auth Provider</a></li><li><a href="#openid-connect-provider" class="table-of-contents__link toc-highlight">OpenID Connect Provider</a></li><li><a href="#logingov-provider" class="table-of-contents__link toc-highlight">login.gov Provider</a></li><li><a href="#nextcloud-provider" class="table-of-contents__link toc-highlight">Nextcloud Provider</a></li><li><a href="#digitalocean-auth-provider" class="table-of-contents__link toc-highlight">DigitalOcean Auth Provider</a></li><li><a href="#bitbucket-auth-provider" class="table-of-contents__link toc-highlight">Bitbucket Auth Provider</a></li><li><a href="#gitea-auth-provider" class="table-of-contents__link toc-highlight">Gitea Auth Provider</a></li><li><a href="#email-authentication" class="table-of-contents__link toc-highlight">Email Authentication</a></li><li><a href="#adding-a-new-provider" class="table-of-contents__link toc-highlight">Adding a new Provider</a></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2022 OAuth2 Proxy.</div></div></div></footer></div>
|
|
<script src="/oauth2-proxy/assets/js/runtime~main.1b99ec01.js"></script>
|
|
<script src="/oauth2-proxy/assets/js/main.7b57a222.js"></script>
|
|
</body>
|
|
</html> |