This topic describes how to configure your team's authentication using GitHub Authentication.

Overview

Continuous integration servers often contain many secrets that let them access source code and deploy apps. It is important that those secrets remain well guarded. Concourse provides options for both authentication and authorization to give you control over who can access your server and how much they can see.

Any number of the following providers can be enabled at any one time. Users are given a choice when logging in as to which one they want to use.

!!! note "" Note: If you access your Concourse server over the public internet, then consider using TLS to secure your connection to the web node.

Configuring team authentication in Concourse is done in two parts:

  1. Configure the allowed authentication providers in the deployment manifest. See Configure Authentication Providers below.
  2. Add users and groups to Concourse teams using fly set-team. See Add Users and Groups to Teams below.

Configure Authentication Providers

--8<-- "docs/authenticating/snippets/configure-auth-providers.md"

GitHub Authentication

A Concourse server can authenticate against GitHub to take advantage of their permission model and other security improvements in their infrastructure. To do this, you need to:

  1. Create a GitHub app.
  2. Configure your deployment with the GitHub client details.

Create a GitHub App

You can create an OAuth app on GitHub. To do this, see Register a new OAuth app in GitHub.

The callback URL is the external URL of your Concourse server with /sky/issuer/callback appended. For example, Concourse's own CI server's callback URL is https://ci.concourse-ci.org/sky/issuer/callback.

!!! note "" Note: The app must be created under an org if you want to authorize users based on org/team membership. If the app is created under a personal account, only individual users can be authorized.

Configure the GitHub Client Details

GitHub provides a Client ID and a Client Secret for the new app. Supply this information in the github_auth, client_id, and client_secret fields. For more information about these fields, see github_auth in the BOSH documentation.

The Main Team

--8<-- "docs/authenticating/snippets/main-team.md"

Add Users and Groups to Teams

--8<-- "docs/authenticating/snippets/add-users-and-groups.md"

GitHub Users, Teams, and Orgs

Add GitHub users, teams, or orgs to a Concourse team.

  • Use --github-user=LOGIN to authorize an individual user.
  • Use --github-org=ORG-NAME to authorize an entire org's members.
  • Use --github-team=ORG-NAME:TEAM-NAME to authorize a team's members within an organization.

For example:

$ fly set-team -n my-team \
    --github-user my-github-login \
    --github-org my-org \
    --github-team my-org:my-team 1

!!! note "" Note: : is used as the separator when adding GitHub teams instead of /. If multiple teams are added, the flag must be repeated.
For example:
--github-team my-org:my-team 1
--github-team my-org:my-team 2

Team Configuration Details

--8<-- "docs/authenticating/snippets/team-config.md"

The output is similar to the following:

name     users          groups
main     github:User    github:Organization

Set User Roles and Permissions

--8<-- "docs/authenticating/snippets/set-user-roles-and-perms.md"

check-circle-line exclamation-circle-line close-line
Scroll to top icon