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

• I have read and understand the contributing guidelines
• I have checked the existing issues for whether this defect was already reported