diff --git a/docs/admin/git-providers.md b/docs/admin/external-auth.md similarity index 62% rename from docs/admin/git-providers.md rename to docs/admin/external-auth.md index 6d77498688a38..cd445eb913d19 100644 --- a/docs/admin/git-providers.md +++ b/docs/admin/external-auth.md @@ -1,9 +1,9 @@ -# Git Providers +# External Authentication -Coder integrates with git providers to automate away the need for developers to -authenticate with repositories within their workspace. +Coder integrates with Git and OpenID Connect to automate away the need for +developers to authenticate with external services within their workspace. -## How it works +## Git Providers When developers use `git` inside their workspace, they are prompted to authenticate. After that, Coder will store and refresh tokens for future @@ -16,26 +16,30 @@ Your browser does not support the video tag. ## Configuration -To add a git provider, you'll need to create an OAuth application. The following -providers are supported: +To add an external authentication provider, you'll need to create an OAuth +application. The following providers are supported: -- [GitHub](#github-app) +- [GitHub](#github) - [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html) - [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/) - [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops) Example callback URL: -`https://coder.example.com/gitauth/primary-github/callback`. Use an arbitrary ID -for your provider (e.g. `primary-github`). +`https://coder.example.com/external-auth/primary-github/callback`. Use an +arbitrary ID for your provider (e.g. `primary-github`). Set the following environment variables to [configure the Coder server](./configure.md): ```env -CODER_GITAUTH_0_ID="primary-github" -CODER_GITAUTH_0_TYPE=github|gitlab|azure-devops|bitbucket -CODER_GITAUTH_0_CLIENT_ID=xxxxxx -CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx +CODER_EXTERNAL_AUTH_0_ID="primary-github" +CODER_EXTERNAL_AUTH_0_TYPE=github|gitlab|azure-devops|bitbucket| +CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx +CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx + +# Optionally, configure a custom display name and icon +CODER_EXTERNAL_AUTH_0_DISPLAY_NAME="Google Calendar" +CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg" ``` ### GitHub @@ -69,9 +73,9 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx GitHub Enterprise requires the following authentication and token URLs: ```env -CODER_GITAUTH_0_VALIDATE_URL="https://github.example.com/login/oauth/access_token/info" -CODER_GITAUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize" -CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token" +CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://github.example.com/login/oauth/access_token/info" +CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize" +CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token" ``` ### Azure DevOps @@ -79,13 +83,13 @@ CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token" Azure DevOps requires the following environment variables: ```env -CODER_GITAUTH_0_ID="primary-azure-devops" -CODER_GITAUTH_0_TYPE=azure-devops -CODER_GITAUTH_0_CLIENT_ID=xxxxxx +CODER_EXTERNAL_AUTH_0_ID="primary-azure-devops" +CODER_EXTERNAL_AUTH_0_TYPE=azure-devops +CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx # Ensure this value is your "Client Secret", not "App Secret" -CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx -CODER_GITAUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/authorize" -CODER_GITAUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token" +CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx +CODER_EXTERNAL_AUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/authorize" +CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token" ``` ### Self-managed git providers @@ -94,9 +98,9 @@ Custom authentication and token URLs should be used for self-managed Git provider deployments. ```env -CODER_GITAUTH_0_AUTH_URL="https://github.example.com/oauth/authorize" -CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/oauth/token" -CODER_GITAUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info" +CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/oauth/authorize" +CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/oauth/token" +CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info" ``` ### Custom scopes @@ -104,10 +108,10 @@ CODER_GITAUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info" Optionally, you can request custom scopes: ```env -CODER_GITAUTH_0_SCOPES="repo:read repo:write write:gpg_key" +CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key" ``` -### Multiple git providers (enterprise) +### Multiple External Providers (enterprise) Multiple providers are an Enterprise feature. [Learn more](../enterprise.md). @@ -116,21 +120,21 @@ limit auth scope. Here's a sample config: ```env # Provider 1) github.com -CODER_GITAUTH_0_ID=primary-github -CODER_GITAUTH_0_TYPE=github -CODER_GITAUTH_0_CLIENT_ID=xxxxxx -CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx -CODER_GITAUTH_0_REGEX=github.com/orgname +CODER_EXTERNAL_AUTH_0_ID=primary-github +CODER_EXTERNAL_AUTH_0_TYPE=github +CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx +CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx +CODER_EXTERNAL_AUTH_0_REGEX=github.com/orgname # Provider 2) github.example.com -CODER_GITAUTH_1_ID=secondary-github -CODER_GITAUTH_1_TYPE=github -CODER_GITAUTH_1_CLIENT_ID=xxxxxx -CODER_GITAUTH_1_CLIENT_SECRET=xxxxxxx -CODER_GITAUTH_1_REGEX=github.example.com -CODER_GITAUTH_1_AUTH_URL="https://github.example.com/login/oauth/authorize" -CODER_GITAUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_token" -CODER_GITAUTH_1_VALIDATE_URL="https://github.example.com/login/oauth/access_token/info" +CODER_EXTERNAL_AUTH_1_ID=secondary-github +CODER_EXTERNAL_AUTH_1_TYPE=github +CODER_EXTERNAL_AUTH_1_CLIENT_ID=xxxxxx +CODER_EXTERNAL_AUTH_1_CLIENT_SECRET=xxxxxxx +CODER_EXTERNAL_AUTH_1_REGEX=github.example.com +CODER_EXTERNAL_AUTH_1_AUTH_URL="https://github.example.com/login/oauth/authorize" +CODER_EXTERNAL_AUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_token" +CODER_EXTERNAL_AUTH_1_VALIDATE_URL="https://github.example.com/login/oauth/access_token/info" ``` To support regex matching for paths (e.g. github.com/orgname), you'll need to diff --git a/docs/manifest.json b/docs/manifest.json index bfa75ad20d4ce..e6541f5634250 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -308,9 +308,9 @@ "icon_path": "./images/icons/toggle_on.svg" }, { - "title": "Git Providers", - "description": "Learn how connect Coder with external git providers", - "path": "./admin/git-providers.md", + "title": "External Auth", + "description": "Learn how connect Coder with external auth providers", + "path": "./admin/external-auth.md", "icon_path": "./images/icons/git.svg" }, {