authenticating.html.md.erb

---
title: Configuring Team Authentication
owner: Concourse
---

<strong><%= modified_date %></strong>

This topic describes how to configure your team's authentication using authentication providers and teams.

## <a id="overview"></a> 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.

<p class="note"><strong>Note:</strong>
If you access your Concourse server over the public internet, then consider using TLS to secure your connection to the web node.
</p>

Configuring team authentication in Concourse is done in two parts:

1. Configure the allowed authentication providers in the deployment manifest.
See [Configure Authentication Providers](#configuring) below.
2. Add users and groups to Concourse teams using `fly set-team`.
See [Add Users and Groups to Teams](#adding) below.

## <a id="configuring"></a> Configure Authentication Providers
Concourse can be configured to use local users, GitHub, generic LDAP, Cloud Foundry, OAuth,
and OIDC as authentication providers.
You must specify the allowed authentication providers before Concourse is deployed.

A Concourse operator needs to provide the following information in their Concourse deployment manifest:

* A list of allowed local users
* Configurations against third-party authentication providers (GitHub, generic LDAP, Cloud Foundry, OAuth, and OIDC)
* Users who should be members of the default `main` team (either local users or users/groups from external authentication providers)

### <a id="local-users"></a> Local Users
Local users must be declared in the `add_local_users` of the `atc` job in the deployment manifest.
Passwords can be supplied in plaintext or as a bcrypted string (minimum 10 rounds).

Example:
<pre class="code">
- user1:password1
- user2:$2y$10$W9542XKXzG5aedX09AlSg.nr0IwejlWosCWXzRKl1eOFzdpgOrGcG
</pre>

<p class="note"><strong>Note:</strong><code>user1</code> and <code>user2</code> mentioned above do not yet have access to any teams. They must be granted access on a team-by-team basis. For more information, see <a href="authenticating.html#adding">Add Users and Groups to Teams</a> below.</p>


### <a id="config-github"></a> 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](https://github.com/settings/applications/new) 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`.

<p class="note"><strong>Note: </strong>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.
</p>


#### 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](https://bosh.io/jobs/atc?source=github.com/concourse/concourse&version=4.0.0#p%3dgithub_auth) in the BOSH documentation.


### <a id="config-cf"></a> Cloud Foundry Authentication
Operators can use Cloud Foundry Authentication (CF Auth) to authenticate users against a Cloud Foundry deployment, using the User Account and Authentication (UAA) server.

To authenticate users, do the following:

1. Create a UAA Client.
2. Configure your deployment with the Cloud Foundry client details.


#### Create the Client
Create a client for Concourse in UAA.

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`.

The client should look something like this, under `uaa.clients`:

<pre class="code">
concourse:
  id: my-client-id
  secret: my-client-secret
  scope: openid,cloud_controller.read
  authorized-grant-types: "authorization_code,refresh_token"
  access-token-validity: 3600
  refresh-token-validity: 3600
  redirect-uri: https://concourse.example.com/sky/issuer/callback
</pre>


#### Configure the Client
You are given a Client ID and a Client Secret for your new app.
These are then passed in the `client_id` and `client-secret` fields on the `atc` job.
For more information about these fields, see [client_id](https://bosh.io/jobs/atc?source=github.com/concourse/concourse&version=4.0.0#p%3dcf_auth.client_id) in the BOSH documentation.

You also need to configure your base API URL for CF in the `api_url` field.
To do this, see [api_url](https://bosh.io/jobs/atc?source=github.com/concourse/concourse&version=4.0.0#p%3dcf_auth.api_url) in the BOSH documentation.


### <a id="config-oidc"></a> OIDC Authentication

If your authentication provider follows the OIDC specification, then use this provider.
Unlike the OAuth provider, you do not need to provide `auth-url`, `token-url`, and `userinfo-url`.
Instead, you can provide an `issuer-url`, and the system queries the `.well-known/openid-configuration` endpoint to discover the information it needs.

To add the OIDC authentication provider, do the following:

1. Create the OIDC client.
2. Configure the client.


#### Create the OIDC Client
First, you need to create a client with your OIDC provider.

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`.


#### Configure the Client
To configure the generic OIDC, fill in the `generic_oidc` fields in the `atc` job of the manifest.
For more information about these fields, see [generic_oidc](https://bosh.io/jobs/atc?source=github.com/concourse/concourse&version=4.0.0#p%3dgeneric_oidc) in the BOSH documentation.


### <a id="config-oauth"></a>  OAuth Authentication
If your authentication provider supports OAuth2 but does not follow the OIDC specification,
then use this provider.
This provider gives you more control over the OIDC provider by letting operators specify the full set of authorization endpoints (`auth-url`, `token-url`).

To add the OAuth provider, do the following:

1. Create the OIDC client.
2. Configure the client.


#### Create the OAuth Client
First, you need to create a client with your OAuth provider.

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`.


#### Configure the Client
To configure the OAuth provider, fill in the `generic_oauth` fields in the `atc` job of the manifest.
For more information about these fields, see [generic_oauth](https://bosh.io/jobs/atc?source=github.com/concourse/concourse&version=4.0.0#p%3dgeneric_oauth) in the BOSH documentation.


### <a id="config-main"></a> The Main Team
By default, Concourse comes with a single team called `main`.
The `main` team is an admin team.
This means it can create and update other teams.
Currently there is no way to promote a team to become an admin team,
so `main` is a special team.

Concourse requires you to specify at least one user/group to be a member of the `main`
team during deployment.
The list of allowed users, groups, and orgs are managed through the `main_team` property in the ATC job.
For more information about this property, see [main_team](https://bosh.io/jobs/atc?source=github.com/concourse/concourse&version=4.0.0#p%3dmain_team) in the BOSH documentation.

An example of adding a local user to the main team can be found in the `add-local-users.yml` file in the [concourse-bosh-deployment](https://github.com/concourse/concourse-bosh-deployment/blob/master/cluster/operations/add-local-users.yml) GitHub repository.

The values set in the authentication flags take effect whenever the ATC starts up.
This allows Concourse to be deployed against declared configurations.
It also makes sure that members of the `main` team do not get locked out of their Concourse.


## <a id="adding"></a>Add Users and Groups to Teams
After you deploy Concourse with the authentication providers configured,
you can specify allowed users and groups using the `fly set-team` command.
With this command, users and groups can be:

  * Added to new teams
  * Modified on existing teams

For more information about this command, see [fly set-team](https://concourse-ci.org/creating-and-updating-teams.html#fly-set-team).

<p class="note"><strong>Note: </strong>
The exception to this is the <code>main</code> team. Members of the <code>main</code> team are configured as part of the initial deployment and cannot be changed after the deployment. For more information about the <code>main</code> team, see <a href="https://concourse-ci.org/main-team.html">The <code>main</code> team</a>.
</p>


### <a id="add-basic-auth"></a> Local Users
You can grant local users access to a team using the `--local-user` flag:

<ol>
<li>Open a terminal window.</li>
<li>Enter the following command:<br/>
<pre class="code">
$  fly set-team -n YOUR-TEAM --local-user USERNAME
</pre>
</li>
</ol>


### <a id="add-github"></a> 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:
<pre class="code">
$ fly set-team -n my-team \
    --github-user my-github-login \
    --github-org my-org \
    --github-team my-org:my-team 1
</pre>

<p class="note"><strong>Note:</strong>
  <code>:</code> is used as the separator when adding GitHub teams instead of <code>/</code>. If multiple teams are added, the flag must be repeated.<br> For example:<br><code>-\-github-team my-org:my-team 1</code> <br><code>-\-github-team my-org:my-team 2</code>
</p>


### <a id="add-cf"></a> CF Auth Users, Spaces, and Orgs
Add users, spaces, and org members from a CF deployment to a Concourse team.

* Use `--cf-user=USERNAME` to authorize an individual user.
* Use `--cf-org=ORG-NAME` to authorize an entire org's members.
* Use `--cf-space=ORG-NAME:SPACE-NAME` to authorize the members of a space within an organization.

For example:

<pre class="code">
$ fly set-team -n my-team \
    --cf-user my-username \
    --cf-org my-org \
    --cf-space my-org:my-space
</pre>

<p class="note"><strong>Note:</strong>
  <code>:</code> is used as the separator when adding members from a CF space instead of <code>/</code>. If multiple spaces are added, the flag must be repeated.<br> For example:<br> -\-github-team my-org:my-space 1 <br> -\-github-team my-org:my-space 2
</p>


### <a id="add-oauth"></a> OAuth Users and Groups
Configure users and groups from a generic OAuth provider.

You can only configure groups if the authentication provider exposes this information in either the token itself
or in the contents of the `userinfo` endpoint.
You can configure which claim points to the group's information by specifying the `groups-key` at startup.

* Use `--cf-user=USERNAME` to authorize an individual user.
* Use `--cf-org=ORG-NAME` to authorize an entire org's members.
* Use `--cf-space=ORG_NAME:SPACE-NAME` to authorize the members of a space within an org.

For example:

<pre class="code">
$ fly set-team -n my-team \
    --oauth-user my-username \
    --oauth-group my-group
</pre>


### <a id="add-oidc"></a> OIDC Users and Groups
Team members can configure users and groups from a generic OIDC provider.
This is very similar to the OAuth connector.
The main difference is that OIDC providers must follow the OIDC specification,
while generic OAuth providers can be a little more flexible.

You can only configure groups if the authentication provider exposes this information in the contents of the userinfo endpoint.
You can configure which claim points to the groups information by specifying the `groups-key` at startup.

* Use `--oidc-user=USERNAME` to authorize an individual user.
* Use `--oidc-group=GROUP-NAME` to authorize anyone from the group.

For example:

<pre class="code">
$ fly set-team -n my-team \
    --oidc-user my-username \
    --oidc-group my-group
</pre>

### <a id="team-config"></a> Team Configuration Details
Team members can view the authentication settings of the teams they belong to by using the `fly teams -d` command.

For example, the command below:
<pre class="code">
$ fly -t prod teams -d
</pre>

The output is similar to the following:
<pre class="terminal">
<strong>name</strong>     <strong>users</strong>          <strong>groups</strong>
main     github:User    github:Organization
</pre>

## <a id="user-roles-and-permissions"></a> User Roles and Permissions

### <a id="setting-user-roles"></a> Setting User Roles
By default, the authorization config passed to `set-team` configures the [member role](#member). In addition, Existing 
team auth config will be transitioned to the team [owner role](#owner). In other words, anyone that can authenticate 
prior to the upgrade will now be authenticated as an owner of their team. This role is the closest equivalent to what 
they could do before.
  
More advanced [roles](#available-user-roles) configuration can be specified through the `--configuration` or `--c` flag. 
  
The `-c` flag expects a YAML file with a single field, `roles:`.
The `roles` field points to a list of role authorization configs. 

The attributes in each config will vary by provider. For specifics of your chosen provider, see 
[Add Users to Groups and Teams](#adding)
  
For example, the following config sets three roles with different Github auth configs for each role's provider:
<pre class="code">
roles:
- name: owner
  github:
    users: ["admin"]
- name: member
  github:
    teams: ["org:team"]
- name: viewer
  github:
    orgs: ["org"]
  local:
    users: ["visitor"]
</pre>

### <a id="available-user-roles"></a> Available User Roles

Concourse 5.2.0 comes with five roles: Concourse Admin, Team Owner, Team Member, Pipeline-Operator, and Team Viewer

#### <a id="concourse-admin"></a> Concourse Admin

Admin is a special user attribute granted to [owners](#owner) of the [main team](#config-main). 

Admins have the ability to administer teams using `fly set-team`, `fly destroy-team`, and `fly rename-team`
  
#### <a id="owner"></a> Owner

Team owners have read, write, and auth management capabilities within the scope of their team, but they cannot rename or 
destroy the team.   
  
#### <a id="member"></a> Member

Team members can perform read and write actions within their team, but they cannot change their team configuration.

#### <a id="pipeline-operator"></a> Pipeline Operator

Team pipeline operators can perform pipeline operations such as triggering builds and pinning resources, however they 
cannot update pipeline configurations. 

#### <a id="viewer"></a> Viewer

Team viewers have “read-only” access to a team and its pipelines. These users are preventing from performing actions such as 
`fly set-pipeline` or `fly intercept`. 

### <a id="permission-matrix"></a> Permission Matrix

For a full list of permissions granted to each user role, see the following 
<a href="https://concourse-ci.org/user-roles.html#permission-matrix">Permission Matrix</a>