Concourse for PCF v3.x

Configuring Team Authentication

Continuous integration tools can grant considerable visibility into an organization’s source code and applications. To protect confidential or sensitive data, Concourse provides options for both authentication and authorization of different users.

User authentication controls who can log in to Concourse servers.

User authorization controls what data a user is allowed to see.

The authentication methods for Concourse teams are determined by flags passed to set-team. The exception to this is main team, which is the default team for any Concourse instance. Main team is configured as part of the initial deployment.

You can enable multiple authentication methods simultaneously. If you use multiple authentication methods, users are given the choice to log in using any of them.

Configuring Basic Authentication

HTTP Basic authentication is the simplest of the authentication mechanisms. It has good support in both browsers and command line tools. It provides a single set of credentials for all of a team’s users to share.

Important: Basic authentication is the least secure method of authentication, because shared credentials can be compromised or misused easily. Many highly secure organizations, such as financial institutions, do not allow the use of basic authorization.

  1. Open a terminal window.
  2. Enter the following commands:
    fly set-team -n YOUR-TEAM \
        --basic-auth-username TEAM-USERNAME \
        --basic-auth-password TEAM-PASSWORD

Configuring GitHub OAuth

A Concourse server can authenticate through GitHub to take advantage of their permission model. Using OAuth also saves Concourse users from having to make a unique login for their Concourse team, because they can use a credential set they already have.

An example GitHub OAuth configuration is below:

$ fly set-team -n NAME \
    --github-auth-client-id $CLIENT_ID \
    --github-auth-client-secret $CLIENT_SECRET \
    --github-auth-team NAME/TEAM-NAME

Configuring the Callback URL

Follow GitHub’s instructions to Create an OAuth application on GitHub.


  • Use a recognizable name, home page, and description to help your users recognize a trusted source when they log in.
  • Use the external URL of your Concourse server with /auth/github/callback appended, for the Authorization callback URL. For example: Configuring the Callback URL.

Configuring the Client

GitHub provides a Client ID and a Client Secret for your new application. Use these to set the following flags:

  1. Open a terminal window.
  2. Navigate to your Concourse deployment manifest.
  3. Set the following flags:

    If you are configuring GitHub Enterprise, set these additional flags as well:
  4. Note: The API URL must end in a forward slash (/).

Authorizing GitHub Users, Teams, and Organizations

You can now allow different organizations, teams, and individual users to access your server.

  1. Open a terminal window.
  2. Navigate to your Concourse deployment manifest.
  3. Set the following flags:

    To authorize an individual user:


    To authorize an team’s members within an organization:

    --github-auth-team=ORG/TEAM NAME

    To authorize an entire organization’s members:


You can use any of these flags multiple times to allow different levels of access.

Configuring UAA OAuth

If you are using the User Access and Authentication (UAA) Cloud Foundry component, you can set up OAuth with Concourse.

The --uaa-auth-* flags allow you to authorize members of a particular space in a Cloud Foundry deployment.

Configuring the UAA Client

Configure a client for Concourse with your UAA. The callback URL is the external URL of your Concourse server with /auth/oauth/callback appended. For example,

An example client is below. This client should be stored under uaa.clients:

uaac client add MY-CLIENT-ID \
  --name MY-CLIENT-ID \
  --scope \
  --authorized_grant_types "authorization_code,refresh_token" \
  --access_token_validity 3600 \
  --refresh_token_validity 3600 \
  --secret MY-CLIENT-SECRET \     
  client_id: MY-CLIENT-ID
  resource_ids: none
  authorized_grant_types: refresh_token authorization_code
  access_token_validity: 3600
  refresh_token_validity: 3600
  authorities: cloud_controller.admin
  name: MY-CLIENT-ID
  lastmodified: 1532640432000

Configuring the Team

An example authorization configuration for a team’s space in a PCF installation is below:

$ fly set-team -n my-cf-team \
    --uaa-auth-client-id $CLIENT_ID \
    --uaa-auth-client-secret $CLIENT_SECRET \
    --uaa-auth-auth-url \
    --uaa-auth-token-url \
    --uaa-auth-cf-url \
    --uaa-auth-cf-ca-cert ./path/to/cf-ca-cert.crt \
    --uaa-auth-cf-space GUID-OF-TEAM-SPACE
Create a pull request or raise an issue on the source for this page in GitHub