Configuring OAuth Authentication
This topic describes how to configure your team's authentication using OAuth Authentication.
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: 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:
- Configure the allowed authentication providers in the deployment manifest. See Configure Authentication Providers below.
- Add users and groups to Concourse teams using
fly set-team. See Add Users and Groups to Teams below.
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
mainteam (either local users or users/groups from external authentication providers)
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 (
To add the OAuth provider, do the following:
- Create the OIDC client.
- 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
For example, Concourse's own CI server's callback URL is
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 in the BOSH documentation.
The Main Team
By default, Concourse comes with a single team called
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,
main is a special team.
Concourse requires you to specify at least one user/group to be a member of the
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 in the BOSH documentation.
An example of adding a local user to the main team can be found in the
file in the concourse-bosh-deployment 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.
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 the Concourse documentation.
Note: The exception to this is the
main team. Members of the
main team are configured as part of the initial deployment and cannot be changed after the deployment. For more information about the
main team, see the Concourse documentation.
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
You can configure which claim points to the group's information by specifying the
groups-key at startup.
--cf-user=USERNAMEto authorize an individual user.
--cf-org=ORG-NAMEto authorize an entire org's members.
--cf-space=ORG_NAME:SPACE-NAMEto authorize the members of a space within an org.
$ fly set-team -n my-team \ --oauth-user my-username \ --oauth-group my-group
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:
$ fly -t prod teams -d
The output is similar to the following:
name users groups main oauth:User oauth:Group
Set User Roles and Permissions
Concourse v5.2.0 now has five roles with varying levels of permission. These are described in the table below:
Admin is a special user attribute granted to owners of the main team.
Admins can administer teams using
For more information about the main team, see The Main Team.
Team owners can read, write, and manage authentication capabilities within the scope of their team.
They cannot rename or destroy the team.
Team members can perform read and write actions within their team.
They cannot change their team configuration.
Team pipeline operators can perform pipeline operations such as triggering builds and pinning resources.
They cannot update pipeline configurations.
Team viewers have read-only access to a team and its pipelines.
They cannot perform actions such as
For a full list of permissions granted to each user role, see the Concourse documentation.
In other words, anyone who could authenticate before the upgrade now authenticates as an owner of their team. This role is the closest equivalent to what they could do before.
More advanced roles configuration can be specified through the
-c flag expects a YAML file with a single field,
roles field points to a list of role authentication configs.
The attributes in each config vary by provider. For specifics of your chosen provider, see Add Users to Groups and Teams above.
For example, the following config sets three roles with different CF authentication configs for each role's provider:
roles: - name: owner cf: users: ["admin"] - name: member cf: orgs: ["my-team"] - name: viewer cf: spaces: ["org:my-other-team"] local: users: ["visitor"]