Skip to content

Authentication#

Concourse uses a username and password combination to authenticate every user. For every request, Concourse requires the user’s identity to be successfully verified.

When connecting to Concourse via a driver, the REST API, or the shell, you must initially provide a username and password. Those credentials are transparently exchanged for an access token that is automatically used on subsequent requests to verify your identity.

Access Tokens#

Concourse issues access tokens in exchange for a valid username and password combination during a login request. The access tokens themselves contain no identifiable information about the users they represent, but are associated with a user within a secure enclave of Concourse Server.

Access tokens are temporary and non-persistent. They automatically expire after a period of inactivity or when Concourse Server shuts down, whichever is sooner.

Client drivers automatically renew tokens by keeping credentials client-side and transparently re-authenticating when a token expires or the server restarts. This renewal is invisible to the application.

User Roles#

Concourse supports role-based access control with two primary roles:

  • ADMIN: Full access to all operations, including user management and server administration.
  • USER: Access to data operations within the environments they have been granted permission to.

Initial Administrator#

When Concourse Server starts for the first time, it creates an administrator account using the credentials specified in the configuration:

1
2
3
4
5
# concourse.yaml
init:
  root:
    username: admin
    password: admin

Or using the flat configuration format:

1
2
init_root_username: admin
init_root_password: admin

Change Default Credentials

The default credentials (admin/admin) should be changed immediately after installation. These credentials are only used during initial setup.

Docker#

When running Concourse in Docker, you can set the initial root password via an environment variable:

1
2
docker run -e CONCOURSE_INIT_ROOT_PASSWORD=secure-pw \
    cinchapi/concourse

Environment-Scoped Access#

Permissions in Concourse are scoped to environments. A user can be granted different levels of access in different environments. This enables multi-tenant deployments where users only have access to their designated environments.

Managing Users#

Creating Users#

Administrators can create new users through the management interface. New users must be assigned a username, password, and role.

Granting Permissions#

The grant operation gives a user access to a specific environment:

1
2
// Java (admin connection)
concourse.grant("username", "environment");

Revoking Permissions#

The revoke operation removes a user’s access to a specific environment:

1
2
// Java (admin connection)
concourse.revoke("username", "environment");

Password Requirements#

Concourse enforces the following password requirements:

  • Minimum length of 8 characters
  • Must contain at least one non-whitespace character

Usernames must not contain whitespace characters.

Security Best Practices#

  1. Change default credentials immediately after installation.
  2. Use environment-scoped access to limit users to only the environments they need.
  3. Secure the credentials file (access_credentials_file) by placing it in a directory with restrictive operating system permissions.
  4. Use separate accounts for each user or application rather than sharing credentials.
  5. Use strong passwords that meet or exceed the minimum requirements.