This topic describes how to configure your team's authentication using Cloud Foundry 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:
fly set-team
. See Add Users and Groups to Teams below.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:
main
team (either local users or users/groups from external authentication providers)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:
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
:
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
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 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 in the BOSH documentation.
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 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 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.
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:
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.
Add users, spaces, and org members from a CF deployment to a Concourse team.
--cf-user=USERNAME
to authorize an individual user.--cf-org=ORG-NAME
to authorize an entire org's members.--cf-space=ORG-NAME:SPACE-NAME
to authorize the members of a space within an organization.For example:
$ fly set-team -n my-team \
--cf-user my-username \
--cf-org my-org \
--cf-space my-org:my-space
Note :
is used as the separator when adding members from a CF space instead of /
. If multiple spaces are added, the flag must be repeated.
For example:
-\-github-team my-org:my-space 1
-\-github-team my-org:my-space 2
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 cf:User cf:Organization
Concourse v5.2.0 now has five roles with varying levels of permission. These are described in the table below:
Role | Description |
---|---|
Admin | Admin is a special user attribute granted to owners of the main team. Admins can administer teams using fly set-team , fly destroy-team , and fly rename-team .For more information about the main team, see The Main Team. |
Team Owner | Team owners can read, write, and manage authentication capabilities within the scope of their team. They cannot rename or destroy the team. |
Team Member | Team members can perform read and write actions within their team. They cannot change their team configuration. |
Pipeline Operator | Team pipeline operators can perform pipeline operations such as triggering builds and pinning resources. They cannot update pipeline configurations. |
Viewer | Team viewers have read-only access to a team and its pipelines. They cannot perform actions such as fly set-pipeline or fly intercept . |
For a full list of permissions granted to each user role, see the Concourse documentation.
By default, the authentication config passed to set-team
configures the member role. In addition, the existing team authentication config transitions to the team owner role.
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 --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 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"]