DependencyTrack / DependencyTrack/dependency-track

missing info in docs

Open
#5,841 2 comments 0 reactions 0 assignees View on GitHub
defect in triage
Dominant language
Java
Stars
4.2k
Forks
811
Avg merge
8h 39m
Merged PRs (30d)
237

Description

### Current Behavior

there are some missing steps in the documents.

there is no mention of exact roles. this makes it difficult to define the roles on cloud providers in case of use of OIDC authentication. the roles include:

- VIEW_POLICY_VIOLATION
- VIEW_BADGES
- TAG_MANAGEMENT
- SYSTEM_CONFIGURATION
- PROJECT_CREATION_UPLOAD
- PORTFOLIO_MANAGEMENT
- POLICY_VIOLATION_ANALYSIS
- POLICY_MANAGEMENT
- BOM_UPLOAD
- ACCESS_MANAGEMENT

### Steps to Reproduce

1. Deploy Dependency-Track with OIDC authentication enabled.
2. Configure an external identity provider (IdP) (e.g., Microsoft Entra ID, Keycloak, Okta) for authentication.
3. Follow the official documentation to configure OIDC settings (issuer URL, client ID, client secret, scopes, redirect URI).
4. Attempt to configure authorization by mapping IdP roles/groups to Dependency-Track permissions.
5. Observe that the documentation does not specify the exact application roles required by Dependency-Track.
6. Attempt to create roles manually in the IdP using guessed names or partial information.
7. Assign these roles to a test user and perform login via OIDC.
8. After authentication, observe that permissions are missing, incomplete, or not applied as expected within the application.

### Expected Behavior

The official documentation for Dependency-Track should explicitly list all required application roles/authorities used for authorization when OIDC authentication is enabled.

Administrators should be able to:

Identify the exact role names expected by the application

Define these roles in the external identity provider (e.g., Microsoft Entra ID, Keycloak, Okta)

Map IdP roles or groups to Dependency-Track permissions without guesswork

Assign roles to users or groups prior to login

Achieve correct authorization immediately after successful OIDC authentication

The application should correctly interpret the provided roles/claims and grant permissions corresponding to:

- VIEW_POLICY_VIOLATION
- VIEW_BADGES
- TAG_MANAGEMENT
- SYSTEM_CONFIGURATION
- PROJECT_CREATION_UPLOAD
- PORTFOLIO_MANAGEMENT
- POLICY_VIOLATION_ANALYSIS
- POLICY_MANAGEMENT
- BOM_UPLOAD
- ACCESS_MANAGEMENT

to resolve the issue:
**The roles should be mentioned in the documents. Clear documentation would enable consistent configuration across cloud providers and prevent misconfiguration, missing permissions, and unnecessary troubleshooting.**

### Dependency-Track Version

4.7.x

### Dependency-Track Distribution

Container Image

### Database Server

PostgreSQL

### Database Server Version

_No response_

### Browser

Google Chrome

### Checklist

- [x] I have read and understand the [contributing guidelines](https://github.com/DependencyTrack/dependency-track/blob/master/CONTRIBUTING.md#filing-issues)
- [x] I have checked the [existing issues](https://github.com/DependencyTrack/dependency-track/issues) for whether this defect was already reported

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.