Skip to content

Commit 017fc02

Browse files
paulOsinskipaulOsinski
committed
update SAML documentation
1 parent 808726e commit 017fc02

1 file changed

Lines changed: 85 additions & 10 deletions

File tree

‎docs/content/admin/sso/PRO__saml.md‎

Lines changed: 85 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,19 @@ audience: pro
77

88
DefectDojo Pro supports SAML authentication via the **Enterprise Settings** UI. Open-Source users should refer to the [Open-Source SAML guide](/admin/sso/os__saml/).
99

10+
## ACS URL (Assertion Consumer Service)
11+
12+
Your Identity Provider needs to know where to POST the SAML response after a user authenticates. DefectDojo's ACS URL is:
13+
14+
```
15+
https://<your-instance>.cloud.defectdojo.com/saml2/acs/
16+
```
17+
18+
A few things to know about this endpoint:
19+
20+
- **The endpoint accepts `POST` requests only.** Opening the ACS URL directly in a browser issues a GET and will return an **HTTP 405 Method Not Allowed**. This is expected behavior — it does not mean SAML is broken or misconfigured. The endpoint is designed to be invoked by your IdP as part of the SAML redirect flow, not by a browser typing the URL.
21+
- **The ACS URL is available on your DefectDojo Cloud instance at all times** — you do not need to enable SAML in DefectDojo first before pointing your IdP at it. You can configure the IdP side and the DefectDojo side in either order.
22+
1023
## Setup
1124

1225
1. Open **Enterprise Settings > SAML Settings**.
@@ -27,19 +40,41 @@ DefectDojo Pro supports SAML authentication via the **Enterprise Settings** UI.
2740

2841
6. **Required Attributes** — specify the attributes DefectDojo requires from the SAML response.
2942

30-
7. **Attribute Mapping** — map SAML attributes to DefectDojo user fields. For example: `email=email`. The left side is the attribute name from the SAML response; the right side is the DefectDojo user field.
43+
7. **Attribute Mapping** — map SAML attributes to DefectDojo user fields. Each mapping is written as `saml_attribute=dojo_field`, and multiple mappings are separated by commas. The left side is the attribute name from the SAML response; the right side is the DefectDojo user field.
44+
45+
Multiple attributes (typical case):
46+
47+
```
48+
Email=email, UserName=username, Firstname=first_name, Lastname=last_name
49+
```
50+
51+
- Whitespace around the comma is ignored.
52+
- The right-hand side must be a field on the DefectDojo `User` model — most commonly `email`, `username`, `first_name`, `last_name`.
53+
- The left-hand side must match the attribute name your IdP actually emits. Some IdPs (e.g. Entra ID / Azure AD) send fully qualified claim URIs like `http://schemas.microsoft.com/identity/claims/emailaddress` instead of friendly names. If you are unsure what your IdP is sending, enable **Enable SAML Debugging** (see [Troubleshooting](#troubleshooting)) and inspect the assertion in the logs.
54+
- At minimum, you should map the attribute that corresponds to `username`, since DefectDojo looks up users by username when matching SAML logins to existing accounts.
3155

3256
8. **Remote SAML Metadata** — the URL where your SAML Identity Provider metadata is hosted.
3357

3458
9. Check **Enable SAML** at the bottom of the form to activate SAML login. A **Login With SAML** button will appear on the DefectDojo login page.
3559

3660
![image](images/sso_saml_login.png).
3761

62+
## Additional Options
63+
64+
* **Create Unknown User** — automatically create a new DefectDojo user if they are not found in the SAML response.
65+
* **Allow Unknown Attributes** — allow login for users who have attributes not listed in the Attribute Mapping.
66+
* **Sign Assertions/Responses** — require all incoming SAML responses to be signed.
67+
* **Sign Logout Requests** — sign all logout requests sent by DefectDojo.
68+
* **Force Authentication** — require users to authenticate with the Identity Provider on every login, regardless of existing sessions.
69+
* **Enable SAML Debugging** — log detailed SAML output for troubleshooting. See [Troubleshooting → SAML Debugging output](#saml-debugging-output) for where the log output appears.
70+
3871
## SAML Group Mapping
3972

4073
DefectDojo can use the SAML assertion to automatically assign users to [User Groups](../../user_management/create_user_group/). Groups in DefectDojo assign permissions to all of their members, so Group Mapping allows you to manage permissions in bulk. This is the only way to set permissions via SAML.
4174

42-
The **Group Name Attribute** field specifies which attribute in the SAML assertion contains the user's group memberships. When a user logs in, DefectDojo reads this attribute and assigns the user to any matching groups. To limit which groups from the assertion are considered, use the **Group Limiter Regex Expression** field.
75+
**Group mapping is optional.** Although the **Group Name Attribute** and **Group Limiter Regex Expression** fields appear with a required-field asterisk (`*`) in the UI, the SAML form will submit without them, and SAML login will work without group mapping. You do not need to pre-build groups or roles in your IdP (e.g. Azure AD application roles) before enabling SAML — you only need to configure these fields when you actually want DefectDojo to read group membership from the assertion. If you do not configure group mapping, newly created SSO users will have no permissions by default; see [Default access for SSO-provisioned users](#default-access-for-sso-provisioned-users) below.
76+
77+
The **Group Name Attribute** field specifies which attribute in the SAML assertion contains the user's group memberships. When a user logs in, DefectDojo reads this attribute and assigns the user to any matching groups. To limit which groups from the assertion are considered, use the **Group Limiter Regex Expression** field — this is a regular expression applied to the group names from the assertion, used to filter which ones DefectDojo should act on.
4378

4479
The value must match the attribute name your Identity Provider emits in the assertion exactly, including any namespace prefix. A short, friendly name like `groups` will only work if your IdP is configured to emit that literal attribute name — many IdPs use a fully qualified claim URI instead.
4580

@@ -52,12 +87,30 @@ The value must match the attribute name your Identity Provider emits in the asse
5287
| **Keycloak** | `groups` (or whatever you set as the "SAML Attribute Name" on the Group List mapper) |
5388
| **PingFederate / generic** | Whatever value you configured on the IdP side — check your IdP's assertion before assuming `groups` |
5489

55-
If group mapping appears to do nothing — users log in successfully but no groups are created or assigned — the most common cause is a mismatch between this field and the attribute name your IdP is actually sending. Enable **Enable SAML Debugging** (see [Additional Options](#additional-options)) to see the raw attributes coming back from the IdP.
90+
If group mapping appears to do nothing — users log in successfully but no groups are created or assigned — see [Troubleshooting → SAML group mapping does nothing](#saml-group-mapping-does-nothing--users-log-in-but-no-groups-are-assigned) below.
5691

5792
If no group with a matching name exists, DefectDojo will automatically create one. Note that a newly created group will not have any permissions configured — those can be set later by a Superuser.
5893

5994
To activate group mapping, check the **Enable Group Mapping** checkbox at the bottom of the form.
6095

96+
## Default access for SSO-provisioned users
97+
98+
When a new user is created via SAML (or any social-auth provider) and is not added to any group via SAML Group Mapping, they will land on a DefectDojo instance with **no permissions**. They will see zero Product Types, zero Products, and zero Engagements when they log in — the dashboard will appear empty.
99+
100+
To give every newly provisioned SSO user a sensible baseline, configure a **Default group** + **Default group role** on the System Settings page:
101+
102+
1. Open **⚙️ Configuration → System Settings** (Superuser only).
103+
2. Set **Default group** to the [User Group](../../user_management/create_user_group/) that newly created users should join.
104+
3. Set **Default group role** to the role they should hold in that group (e.g. **Reader**).
105+
4. Optionally set **Default group email pattern** to a regex (e.g. `.*@yourcompany\.com$`) so the default group is only applied to users whose email matches.
106+
5. Save.
107+
108+
Both **Default group** and **Default group role** must be set — if either is empty, the default group is not applied.
109+
110+
This setting applies to **every newly created user**, including users created via SAML, OAuth, and other social-auth providers, because it runs on Django's user-creation signal rather than inside a specific authentication backend.
111+
112+
> **Existing users are not affected.** The default group is only applied when a user is first created. Existing DefectDojo users will keep their current group memberships even if you change this setting later.
113+
61114
## Cloud vs On-Premise Differences
62115

63116
DefectDojo Cloud does not have the same level of SAML customization as DefectDojo On-Prem. The only variables that can be set are through the UI. Here are some of the key differences:
@@ -72,11 +125,33 @@ DefectDojo Cloud does not have the same level of SAML customization as DefectDoj
72125

73126
If you need to match users on an attribute other than NameID (such as `uid` or `email`), configure your Identity Provider to send the desired value as the NameID rather than adjusting DefectDojo settings.
74127

75-
## Additional Options
128+
## Troubleshooting
76129

77-
* **Create Unknown User** — automatically create a new DefectDojo user if they are not found in the SAML response.
78-
* **Allow Unknown Attributes** — allow login for users who have attributes not listed in the Attribute Mapping.
79-
* **Sign Assertions/Responses** — require all incoming SAML responses to be signed.
80-
* **Sign Logout Requests** — sign all logout requests sent by DefectDojo.
81-
* **Force Authentication** — require users to authenticate with the Identity Provider on every login, regardless of existing sessions.
82-
* **Enable SAML Debugging** — log detailed SAML output for troubleshooting.
130+
### SAML Debugging output
131+
132+
When **Enable SAML Debugging** (in [Additional Options](#additional-options)) is checked, DefectDojo writes detailed SAML processing output — including the raw attributes received from the IdP — to the application logs at the `DEBUG` level under the `saml2` logger.
133+
134+
| Where you're running | Where to read the debug output |
135+
|---|---|
136+
| **DefectDojo Cloud** | The SAML debug log is not exposed in the UI. Contact DefectDojo Support to request the logs for a specific time window. |
137+
| **On-Premise (single container)** | `docker logs dojo` (or your Helm/K8s log aggregation) |
138+
| **On-Premise (Helm/K8s)** | `kubectl logs deployment/defectdojo-django -c uwsgi` (or your cluster's log aggregator) |
139+
140+
Turn this option **off** after you've finished troubleshooting — SAML debug logs are verbose and may contain sensitive attribute values from your IdP.
141+
142+
### Users get a "User not found" or "Permission denied" error after a successful IdP login
143+
144+
If the SAML assertion parses successfully (no XML or signature errors) but DefectDojo refuses the login, the most common cause is a **username mismatch** between the IdP and DefectDojo.
145+
146+
DefectDojo looks up the user **by username** when matching a SAML login to an existing account. If the value your IdP sends as the `username` attribute does not match an existing DefectDojo user's username, the lookup fails — even though the rest of the assertion is valid.
147+
148+
Two remedies, pick whichever fits your environment:
149+
150+
- **Drop `username` from the Attribute Mapping** and let DefectDojo fall back to using the SAML `NameID` as the username instead. This is appropriate if your DefectDojo usernames already match the NameID format your IdP emits.
151+
- **Align the usernames.** Make sure the usernames in DefectDojo are exactly what your IdP sends in the `username` claim. For most organizations the easiest convention is to make DefectDojo usernames equal to the user's email address, and have the IdP send the email as the `username` claim.
152+
153+
If you're not sure what the IdP is actually sending, enable **Enable SAML Debugging** (above) and inspect the parsed attributes in the logs.
154+
155+
### SAML group mapping does nothing — users log in but no groups are assigned
156+
157+
The most common cause is a mismatch between the **Group Name Attribute** field and the attribute name your IdP is actually sending. See the [Group Name Attribute by Identity Provider](#group-name-attribute-by-identity-provider) table above, and enable **Enable SAML Debugging** to see the raw attributes coming back from the IdP.

0 commit comments

Comments
 (0)