SAML

Concourse supports SAML 2.0 for enterprise single sign-on.

Configuration

auth:
  saml:
    enabled: true
    metadata_url: https://idp.example.com/app/xxx/sso/saml/metadata
    entity_id: https://your-concourse.example.com
    acs_url: https://your-concourse.example.com/api/v1/auth/saml/acs

Field	Description
enabled	Set to true to enable SAML.
metadata_url	URL to your IdP’s SAML metadata XML document.
entity_id	The SAML Service Provider (SP) entity ID. Use your Concourse public URL.
acs_url	The Assertion Consumer Service URL where the IdP posts SAML responses.

Authentication flow

1. The inboard app directs the user to GET /api/v1/auth/saml/login.
2. Concourse generates a SAML AuthnRequest and redirects the user to the IdP.
3. The user authenticates with the IdP.
4. The IdP posts a SAML response to POST /api/v1/auth/saml/acs.
5. Concourse validates the assertion, extracts user attributes, and issues a JWT.

SP metadata

Concourse exposes its SP metadata at:

GET /api/v1/auth/saml/metadata

Provide this URL to your IdP administrator during setup. It contains the entity ID, ACS URL, and signing certificate.

Provider setup

Okta

1. In the Okta Admin Console, create a new SAML 2.0 application.
2. Set the Single sign-on URL to https://your-concourse.example.com/api/v1/auth/saml/acs.
3. Set the Audience URI (SP Entity ID) to https://your-concourse.example.com.
4. Under attribute statements, map email and displayName.
5. Copy the metadata URL from the “Sign On” tab.

auth:
  saml:
    enabled: true
    metadata_url: https://your-org.okta.com/app/xxx/sso/saml/metadata
    entity_id: https://your-concourse.example.com
    acs_url: https://your-concourse.example.com/api/v1/auth/saml/acs

Azure AD (Entra ID)

1. In the Azure portal, go to Enterprise Applications and create a new application.
2. Under “Single sign-on”, choose SAML.
3. Set the Identifier (Entity ID) to https://your-concourse.example.com.
4. Set the Reply URL (ACS URL) to https://your-concourse.example.com/api/v1/auth/saml/acs.
5. Download the Federation Metadata XML URL.

auth:
  saml:
    enabled: true
    metadata_url: https://login.microsoftonline.com/{tenant-id}/federationmetadata/2007-06/federationmetadata.xml?appid={app-id}
    entity_id: https://your-concourse.example.com
    acs_url: https://your-concourse.example.com/api/v1/auth/saml/acs

OneLogin

1. Add a SAML Test Connector (IdP) or custom SAML app.
2. Set the ACS URL to https://your-concourse.example.com/api/v1/auth/saml/acs.
3. Set the Audience to https://your-concourse.example.com.
4. Copy the Issuer URL (metadata URL) from the SSO tab.

auth:
  saml:
    enabled: true
    metadata_url: https://your-org.onelogin.com/saml/metadata/xxx
    entity_id: https://your-concourse.example.com
    acs_url: https://your-concourse.example.com/api/v1/auth/saml/acs

PingFederate

1. Create a new SP Connection in PingFederate.
2. Import the SP metadata from https://your-concourse.example.com/api/v1/auth/saml/metadata.
3. Alternatively, manually set the ACS endpoint and entity ID.
4. Map the email and displayName attributes.

auth:
  saml:
    enabled: true
    metadata_url: https://ping.example.com/pf/federation_metadata.ping?PartnerSpId=xxx
    entity_id: https://your-concourse.example.com
    acs_url: https://your-concourse.example.com/api/v1/auth/saml/acs

Checking SAML status

curl http://localhost:8080/api/v1/auth/saml/status

Returns {"enabled": true} or {"enabled": false}.

Auto-provisioning

When a user signs in via SAML for the first time and no matching account exists, Concourse automatically creates a user with the member role. See Attribute Mapping for how user information is extracted from SAML assertions.