Skip to content

Configuring OIDC Authentication

This topic describes how to configure your team's authentication using OIDC 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:

  1. Configure the allowed authentication providers in the deployment manifest. See Configure Authentication Providers below.
  2. 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 main team (either local users or users/groups from external authentication providers)

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

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 in the BOSH documentation.

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

Add Users and Groups to Teams

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:

$ fly set-team -n my-team \
    --oidc-user my-username \
    --oidc-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     oidc:User      oidc:Group