Document SAML 2.0 authentication

.vale/styles/config/vocabularies/DependencyTrack/accept.txt

@@ -75,6 +75,7 @@ PgBouncer
 Podman
 Postgres
 Protobuf
+SAML
 SBOMs?
 SPIs?
 SSDs
@@ -104,6 +105,7 @@ Webex
 [Bb]locklists?
 [Bb]ooleans?
 [Cc]amelCase
+[Cc]anonicalization
 [Cc]lassloaders?
 [Cc]lasspath
 [Cc]leartext

context/vocabulary.md

@@ -75,7 +75,7 @@ Use these terms consistently. Avoid synonyms not listed here.
 - **permission** — A granular access control attribute (e.g., VIEW_PORTFOLIO, VULNERABILITY_ANALYSIS, POLICY_MANAGEMENT).
 - **API key** — A long-lived authentication token. Either a *team API key*, scoped to a team, or owned by a service account and acting as it.
 - **managed user** — A user account managed within Dependency-Track.
-- **LDAP/OIDC user** — A user account managed by an external identity provider.
+- **LDAP/OIDC/SAML user** — A user account managed by an external identity provider.
 - **service account** — A non-human user for automation, authenticated only by its own API keys. Username starts with the reserved `svc:` prefix. Available in 5.2.0 and later.
 - **portfolio access control** — Restricts a team's visibility to a subset of projects.
 

docs/concepts/access-control.md

@@ -11,13 +11,14 @@ Dependency-Track uses a role-based access control model built around **permissio
 
 ## Users
 
-Four types of users exist:
+Five types of users exist:
 
 | Type            | Description                                                                                       |
 |:----------------|:--------------------------------------------------------------------------------------------------|
 | Managed User    | A local account created and managed within Dependency-Track.                                      |
 | LDAP User       | Authenticated via an external LDAP directory. See [Configuring LDAP](../guides/administration/configuring-ldap.md). |
 | OIDC User       | Authenticated via an OpenID Connect identity provider. See [Configuring OIDC](../guides/administration/configuring-oidc.md). |
+| SAML User       | Authenticated via a SAML 2.0 identity provider. Available in 5.3.0 and later. See [Configuring SAML](../guides/administration/configuring-saml.md). |
 | Service Account | A non-human account for automation. Authenticates with its own API keys, or through workload identity federation. Available in 5.2.0 and later. See [Service accounts](#service-accounts). |
 
 All user types share the same permission model. The authentication mechanism determines
@@ -49,7 +50,7 @@ account also deletes its API keys and its workload identity bindings.
 
 Service account usernames always start with `svc:`, for example `svc:ci-pipeline`.
 No other user can have a username with that prefix. This prevents a service account
-from taking a username that an LDAP or OIDC user would receive on first login.
+from taking a username that an LDAP, OIDC, or SAML user would receive on first login.
 
 Managing service accounts requires the `ACCESS_MANAGEMENT` permission.
 

docs/guides/administration/.pages

@@ -16,6 +16,7 @@ nav:
   - configuring-observability.md
   - configuring-ldap.md
   - configuring-oidc.md
+  - configuring-saml.md
   - configuring-workload-identity-federation.md
   - managing-notification-templates.md
   - debugging-notifications.md

docs/guides/administration/configuring-ldap.md

@@ -174,4 +174,5 @@ environment variable equivalents, see the
 
 - [Permissions](../../reference/permissions.md): mapping LDAP groups to Dependency-Track teams
 - [Configuring OpenID Connect](configuring-oidc.md): alternative to LDAP using OpenID Connect
+- [Configuring SAML](configuring-saml.md): alternative to LDAP using SAML 2.0
 - [Configuring internal CA trust](configuring-internal-ca.md): trust internal TLS certificates for LDAPS

docs/guides/administration/configuring-oidc.md

@@ -223,4 +223,5 @@ For a full list of OIDC-related configuration properties, see the
 
 - [Permissions](../../reference/permissions.md): mapping IdP groups to Dependency-Track teams
 - [Configuring LDAP](configuring-ldap.md): alternative to OIDC using LDAP
+- [Configuring SAML](configuring-saml.md): alternative to OIDC using SAML 2.0
 - [Configuring Internal CA](configuring-internal-ca.md): trust internal TLS certificates for the IdP

docs/includes/abbreviations.md

@@ -22,6 +22,7 @@
 *[PAC]: Portfolio Access Control
 *[PURL]: Package URL, a standardized format for identifying software packages
 *[REST]: Representational State Transfer
+*[SAML]: Security Assertion Markup Language
 *[SARIF]: Static Analysis Results Interchange Format
 *[SBOM]: Software Bill of Materials
 *[SLO]: Service Level Objectives

docs/index.md

@@ -82,7 +82,8 @@ An API-first design makes it a natural fit for CI/CD pipelines.
 
 ### Control access
 
-- **Identity providers**: sign in through [OIDC](guides/administration/configuring-oidc.md)
+- **Identity providers**: sign in through [OIDC](guides/administration/configuring-oidc.md),
+  [SAML](guides/administration/configuring-saml.md),
   or [LDAP](guides/administration/configuring-ldap.md), with optional team synchronization.
 - **Teams and permissions**: grant fine-grained permissions to teams,
   and limit which projects each team can see with [portfolio access control](concepts/access-control.md).

docs/reference/configuration/properties.md

@@ -1081,6 +1081,17 @@ Defines the path to the data directory. This directory will hold logs,  keys, an
 <tr><th>ENV</th><td><code>DT_DATA_DIRECTORY</code></td></tr>
 </table>
 
+<span id="dtfrontend-url">**`dt.frontend-url`** [¶](#dtfrontend-url){ .headerlink }</span>
+
+Defines the publicly reachable URL of the frontend.  Used where the API server redirects browsers to the frontend,  for example after a SAML login, where users are sent to the frontend's `/login/saml` route.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>string</code></td></tr>
+<tr><th>Default</th><td><code>null</code></td></tr>
+<tr><th>Example</th><td><code>https://dtrack.example.com</code></td></tr>
+<tr><th>ENV</th><td><code>DT_FRONTEND_URL</code></td></tr>
+</table>
+
 <span id="dtinit-taskdatabase-migrationenabled">**`dt.init-task.database-migration.enabled`** [¶](#dtinit-taskdatabase-migrationenabled){ .headerlink }</span>
 
 Whether to enable the database migration init task.  Has no effect unless [`dt.init-tasks.enabled`](#dtinit-tasksenabled) is `true`.  
@@ -1605,6 +1616,148 @@ Defines the name of the claim that contains the username in the provider's useri
 
 
 
+## SAML
+
+<span id="dtsamldefault-teams">**`dt.saml.default-teams`** [¶](#dtsamldefault-teams){ .headerlink }</span>
+
+Defines one or more team names that newly provisioned SAML users are added to.  Has no effect when `[`dt.saml.user-provisioning`](#dtsamluser-provisioning)` is disabled, or `[`dt.saml.team-synchronization`](#dtsamlteam-synchronization)` is enabled.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>string</code></td></tr>
+<tr><th>Default</th><td><code>null</code></td></tr>
+<tr><th>Example</th><td><code>team1,team2</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_DEFAULT_TEAMS</code></td></tr>
+</table>
+
+<span id="dtsamlemail-attribute">**`dt.saml.email-attribute`** [¶](#dtsamlemail-attribute){ .headerlink }</span>
+
+Defines the name of the assertion attribute that contains the email address.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>string</code></td></tr>
+<tr><th>Default</th><td><code>null</code></td></tr>
+<tr><th>Example</th><td><code>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_EMAIL_ATTRIBUTE</code></td></tr>
+</table>
+
+<span id="dtsamlenabled">**`dt.saml.enabled`** [¶](#dtsamlenabled){ .headerlink }</span>
+
+Defines if SAML 2.0 will be used for user authentication.  If enabled, `dt.saml.*` properties should be set accordingly.  The frontend must be configured with `SAML_ENABLED=true` to show the SAML login button.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>boolean</code></td></tr>
+<tr><th>Default</th><td><code>false</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_ENABLED</code></td></tr>
+</table>
+
+<span id="dtsamlgroup-provisioning">**`dt.saml.group-provisioning`** [¶](#dtsamlgroup-provisioning){ .headerlink }</span>
+
+Specifies if a SAML group is created for every group of a user that does not exist yet.  Group names are taken verbatim from the groups attribute. Teams are not created,  and groups still need to be mapped to teams by an administrator.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>boolean</code></td></tr>
+<tr><th>Default</th><td><code>false</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_GROUP_PROVISIONING</code></td></tr>
+</table>
+
+<span id="dtsamlgroups-attribute">**`dt.saml.groups-attribute`** [¶](#dtsamlgroups-attribute){ .headerlink }</span>
+
+Defines the name of the assertion attribute that contains group memberships.  Each attribute value is treated as one group name. Required for team synchronization  and group provisioning.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>string</code></td></tr>
+<tr><th>Default</th><td><code>null</code></td></tr>
+<tr><th>Example</th><td><code>http://schemas.microsoft.com/ws/2008/06/identity/claims/groups</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_GROUPS_ATTRIBUTE</code></td></tr>
+</table>
+
+<span id="dtsamlidpmetadata-file">**`dt.saml.idp.metadata-file`** [¶](#dtsamlidpmetadata-file){ .headerlink }</span>
+
+Defines the path of a file containing the SAML metadata of the identity provider.  Exactly one of `[`dt.saml.idp.metadata-url`](#dtsamlidpmetadata-url)` and `[`dt.saml.idp.metadata-file`](#dtsamlidpmetadata-file)` must be set.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>string</code></td></tr>
+<tr><th>Default</th><td><code>null</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_IDP_METADATA_FILE</code></td></tr>
+</table>
+
+<span id="dtsamlidpmetadata-url">**`dt.saml.idp.metadata-url`** [¶](#dtsamlidpmetadata-url){ .headerlink }</span>
+
+Defines the HTTPS URL from which the SAML metadata of the identity provider is fetched.  The metadata is cached for one hour. Exactly one of `[`dt.saml.idp.metadata-url`](#dtsamlidpmetadata-url)`  and `[`dt.saml.idp.metadata-file`](#dtsamlidpmetadata-file)` must be set.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>string</code></td></tr>
+<tr><th>Default</th><td><code>null</code></td></tr>
+<tr><th>Example</th><td><code>https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app-id></code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_IDP_METADATA_URL</code></td></tr>
+</table>
+
+<span id="dtsamlspacs-url">**`dt.saml.sp.acs-url`** [¶](#dtsamlspacs-url){ .headerlink }</span>
+
+Defines the publicly reachable URL of the assertion consumer service (ACS).  This is the API server's `/api/v2/saml/acs` endpoint, as seen by users' browsers.  Must match the reply URL configured in the identity provider.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>string</code></td></tr>
+<tr><th>Default</th><td><code>null</code></td></tr>
+<tr><th>Example</th><td><code>https://dtrack-api.example.com/api/v2/saml/acs</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_SP_ACS_URL</code></td></tr>
+</table>
+
+<span id="dtsamlspentity-id">**`dt.saml.sp.entity-id`** [¶](#dtsamlspentity-id){ .headerlink }</span>
+
+Defines the entity ID of Dependency-Track as SAML service provider.  Must match the identifier configured for Dependency-Track in the identity provider.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>string</code></td></tr>
+<tr><th>Default</th><td><code>null</code></td></tr>
+<tr><th>Example</th><td><code>https://dtrack.example.com</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_SP_ENTITY_ID</code></td></tr>
+</table>
+
+<span id="dtsamlsubject-attribute">**`dt.saml.subject-attribute`** [¶](#dtsamlsubject-attribute){ .headerlink }</span>
+
+Defines the name of the assertion attribute that contains an immutable identifier of the user,  such as the object ID in Entra ID. Users are matched by this identifier, so a username that the  identity provider reassigns or renames never grants access to another person's account.  When not set, the `NameID` of the assertion's subject is used, which must then be persistent.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>string</code></td></tr>
+<tr><th>Default</th><td><code>null</code></td></tr>
+<tr><th>Example</th><td><code>http://schemas.microsoft.com/identity/claims/objectidentifier</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_SUBJECT_ATTRIBUTE</code></td></tr>
+</table>
+
+<span id="dtsamlteam-synchronization">**`dt.saml.team-synchronization`** [¶](#dtsamlteam-synchronization){ .headerlink }</span>
+
+Specifies if team memberships of SAML users are synchronized with their groups on every login.  Users are added to all teams mapped to one of their groups, and removed from all other teams.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>boolean</code></td></tr>
+<tr><th>Default</th><td><code>false</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_TEAM_SYNCHRONIZATION</code></td></tr>
+</table>
+
+<span id="dtsamluser-provisioning">**`dt.saml.user-provisioning`** [¶](#dtsamluser-provisioning){ .headerlink }</span>
+
+Specifies if SAML users are automatically created upon their first successful login.  When disabled, users must be created by an administrator before they can log in.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>boolean</code></td></tr>
+<tr><th>Default</th><td><code>false</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_USER_PROVISIONING</code></td></tr>
+</table>
+
+<span id="dtsamlusername-attribute">**`dt.saml.username-attribute`** [¶](#dtsamlusername-attribute){ .headerlink }</span>
+
+Defines the name of the assertion attribute that contains the username.  The username is shown in Dependency-Track, and follows renames at the identity provider.  When not set, the `NameID` of the assertion's subject is used.  
+
+<table>
+<tr><th>Type</th><td style="border-width: 0"><code>string</code></td></tr>
+<tr><th>Default</th><td><code>null</code></td></tr>
+<tr><th>Example</th><td><code>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name</code></td></tr>
+<tr><th>ENV</th><td><code>DT_SAML_USERNAME_ATTRIBUTE</code></td></tr>
+</table>
+
+
+
 ## Secrets
 
 <span id="dtsecret-managementdatabasedatasourcename">**`dt.secret-management.database.datasource.name`** [¶](#dtsecret-managementdatabasedatasourcename){ .headerlink }</span>