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.

Tips:

  • 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: https://ci.concourse.ci/auth/github/callback.

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:
    --github-auth-client-id=CLIENT_ID
    --github-auth-client-secret=CLIENT_SECRET
    

    If you are configuring GitHub Enterprise, set these additional flags as well:
    --github-auth-auth-url=https://github.example.com/login/oauth/authorize
    --github-auth-token-url=https://github.example.com/login/oauth/access_token
    --github-auth-api-url=https://github.example.com/api/v3/
    
  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:

    --github-auth-user=LOGIN

    To authorize an team’s members within an organization:

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

    To authorize an entire organization’s members:

    --github-auth-organization=ORG

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

Configuring UAA OAuth

If you’re using the User Access and Authentication (UAA) Cloud Foundry component, you can set up OAuth with your 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, https://ci.concourse.ci/auth/oauth/callback.

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

concourse:
  id: MY-CLIENT-ID
  secret: MY-CLIENT-SECRET
  scope: cloud_controller.read
  authorities: cloud_controller.admin
  authorized-grant-types: "authorization_code,client_credentials,refresh_token"
  access-token-validity: 3600
  refresh-token-validity: 3600
  autoapprove: true
  override: true
  redirect-uri: https://concourse.EXAMPLE.com/auth/uaa/callback

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 https://login.my-cf.com/oauth/authorize \
    --uaa-auth-token-url https://login.my-cf.com/oauth/token \
    --uaa-auth-cf-url https://api.my-cf.com \
    --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