diff --git a/docs/assets/scss/common/_custom.scss b/docs/assets/scss/common/_custom.scss index efb1713c294..293e494fecb 100644 --- a/docs/assets/scss/common/_custom.scss +++ b/docs/assets/scss/common/_custom.scss @@ -98,6 +98,30 @@ h1, h2, h3, h4, h5, h6, visibility: hidden; // Hide sidebar until version is resolved } +@media (min-width: 992px) { + @supports ((position: -webkit-sticky) or (position: sticky)) { + .docs-sidebar { + display: flex !important; // Override Bootstrap d-lg-block { display: block !important } + flex-direction: column; + } + + .docs-version-toggle { + flex-shrink: 0; + } + + .version-menu-wrapper { + flex: 1; + min-height: 0; // Required: allows flex child to shrink below content size + overflow-y: auto; + } + + .docs-links { + max-height: none; // Parent flex container now handles height/scroll + overflow: visible; + } + } +} + .doks-sidebar .section-nav a { color: #333333; // Dojo Hue 04 transition: color 0.15s ease, background-color 0.15s ease; diff --git a/docs/content/admin/sso/OS__auth0.md b/docs/content/admin/sso/OS__auth0.md new file mode 100644 index 00000000000..dbaf8f0c60a --- /dev/null +++ b/docs/content/admin/sso/OS__auth0.md @@ -0,0 +1,36 @@ +--- +title: "Auth0" +description: "Configure Auth0 SSO in Open-Source DefectDojo" +weight: 4 +audience: opensource +--- + +Open-Source DefectDojo supports login via Auth0. DefectDojo Pro users should refer to the [Pro Auth0 guide](../PRO__auth0/). + +## Prerequisites + +Complete the following steps in your Auth0 dashboard before configuring DefectDojo: + +1. Create a new application: **Applications > Create Application > Single Page Web Application**. + +2. Configure the application: + - **Name:** `DefectDojo` + - **Allowed Callback URLs:** `https://your-instance.cloud.defectdojo.com/complete/auth0/` + +3. Note the following values — you will need them in DefectDojo: + - **Domain** + - **Client ID** + - **Client Secret** + +## Configuration + +Set the following as environment variables, or without the `DD_` prefix in your `local_settings.py` file (see [Configuration](/get_started/open_source/configuration/)): + +{{< highlight python >}} +DD_SOCIAL_AUTH_AUTH0_OAUTH2_ENABLED=True +DD_SOCIAL_AUTH_AUTH0_KEY=(str, 'YOUR_CLIENT_ID'), +DD_SOCIAL_AUTH_AUTH0_SECRET=(str, 'YOUR_CLIENT_SECRET'), +DD_SOCIAL_AUTH_AUTH0_DOMAIN=(str, 'YOUR_AUTH0_DOMAIN'), +{{< /highlight >}} + +Restart DefectDojo. A **Login with Auth0** button will appear on the login page. diff --git a/docs/content/admin/sso/OS__azure_ad.md b/docs/content/admin/sso/OS__azure_ad.md new file mode 100644 index 00000000000..baea2b204ae --- /dev/null +++ b/docs/content/admin/sso/OS__azure_ad.md @@ -0,0 +1,72 @@ +--- +title: "Azure Active Directory" +description: "Configure Azure AD SSO and group mapping in Open-Source DefectDojo" +weight: 6 +audience: opensource +--- + +Open-Source DefectDojo supports login via Azure Active Directory (Azure AD), including automatic User Group synchronization. DefectDojo Pro users should refer to the [Pro Azure AD guide](../PRO__azure_ad/). + +## Prerequisites + +Complete the following steps in the Azure portal before configuring DefectDojo: + +1. [Register a new app](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) in Azure Active Directory. + +2. Note the following values from the registered app: + - **Application (client) ID** + - **Directory (tenant) ID** + - Under **Certificates & Secrets**, create a new **Client Secret** and note its value + +3. Under **Authentication > Redirect URIs**, add a **Web** type URI: + `https://your-instance.cloud.defectdojo.com/complete/azuread-tenant-oauth2/` + +## Configuration + +Set the following as environment variables, or without the `DD_` prefix in your `local_settings.py` file (see [Configuration](/get_started/open_source/configuration/)): + +{{< highlight python >}} +DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY=(str, 'YOUR_APPLICATION_ID'), +DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET=(str, 'YOUR_CLIENT_SECRET'), +DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID=(str, 'YOUR_DIRECTORY_ID'), +DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_ENABLED=True +{{< /highlight >}} + +Restart DefectDojo. A **Login with Azure AD** button will appear on the login page. + +## Group Mapping + +To import User Group membership from Azure AD, set the following variable: + +{{< highlight python >}} +DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_GET_GROUPS=True +{{< /highlight >}} + +On login, DefectDojo will assign the user to all groups found in the Azure AD token. Any groups not found in DefectDojo will be created automatically. This allows product access to be governed via groups. + +### Configuring Azure AD to send groups + +The Azure AD token must be configured to include group IDs. Without this, no group information will be present in the token. + +To configure this: +1. Add a [Group Claim](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims) to the token. If unsure which group type to select, choose **All Groups**. +2. Do **not** enable **Emit groups as role claims**. +3. Update the application's API permissions to include `GroupMember.Read.All` or `Group.Read.All`. `GroupMember.Read.All` is recommended as it grants fewer permissions. + +### Filtering groups + +To limit which groups are imported, use a regex filter: + +{{< highlight python >}} +DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_GROUPS_FILTER='^team-.*' # or 'teamA|teamB|groupC' +{{< /highlight >}} + +### Automatic Group Cleanup + +To remove stale groups when users are removed from them in Azure AD: + +{{< highlight python >}} +DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_CLEANUP_GROUPS=True +{{< /highlight >}} + +When a user is removed from a group in Azure AD, they are also removed from the corresponding group in DefectDojo. Empty groups are left in place for record purposes. diff --git a/docs/content/admin/sso/OS__github_enterprise.md b/docs/content/admin/sso/OS__github_enterprise.md new file mode 100644 index 00000000000..8427b58decc --- /dev/null +++ b/docs/content/admin/sso/OS__github_enterprise.md @@ -0,0 +1,35 @@ +--- +title: "GitHub Enterprise" +description: "Configure GitHub Enterprise SSO in Open-Source DefectDojo" +weight: 8 +audience: opensource +--- + +Open-Source DefectDojo supports login via GitHub Enterprise. DefectDojo Pro users should refer to the [Pro GitHub Enterprise guide](../PRO__github_enterprise/). + +## Prerequisites + +Complete the following steps in GitHub Enterprise before configuring DefectDojo: + +1. [Create a new OAuth App](https://docs.github.com/en/enterprise-server/developers/apps/building-oauth-apps/creating-an-oauth-app) in your GitHub Enterprise Server. + +2. Choose a name for the application, e.g. `DefectDojo`. + +3. Set the **Redirect URI**: + `https://your-dojo-host:your-port/complete/github-enterprise/` + +4. Note the **Client ID** and **Client Secret** from the app. + +## Configuration + +Set the following as environment variables, or without the `DD_` prefix in your `local_settings.py` file (see [Configuration](/get_started/open_source/configuration/)): + +{{< highlight python >}} +DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_KEY=(str, 'YOUR_CLIENT_ID'), +DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_SECRET=(str, 'YOUR_CLIENT_SECRET'), +DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_URL=(str, 'https://github.yourcompany.com/'), +DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_API_URL=(str, 'https://github.yourcompany.com/api/v3/'), +DD_SOCIAL_AUTH_GITHUB_ENTERPRISE_OAUTH2_ENABLED=True, +{{< /highlight >}} + +Restart DefectDojo. A **Login with GitHub Enterprise** button will appear on the login page. diff --git a/docs/content/admin/sso/OS__gitlab.md b/docs/content/admin/sso/OS__gitlab.md new file mode 100644 index 00000000000..f8ae2bcaa90 --- /dev/null +++ b/docs/content/admin/sso/OS__gitlab.md @@ -0,0 +1,45 @@ +--- +title: "GitLab" +description: "Configure GitLab SSO in Open-Source DefectDojo" +weight: 10 +audience: opensource +--- + +Open-Source DefectDojo supports login via GitLab. DefectDojo Pro users should refer to the [Pro GitLab guide](../PRO__gitlab/). + +## Prerequisites + +Complete the following steps in GitLab before configuring DefectDojo: + +1. Navigate to your GitLab profile's Applications page: + - GitLab.com: `https://gitlab.com/profile/applications` + - Self-hosted: `https://your-gitlab-host/profile/applications` + +2. Create a new application: + - **Name:** `DefectDojo` + - **Redirect URI:** `https://your-dojo-host/complete/gitlab/` + +3. Note the **Application ID** and **Secret** from the application. + +## Configuration + +Set the following as environment variables, or without the `DD_` prefix in your `local_settings.py` file (see [Configuration](/get_started/open_source/configuration/)): + +{{< highlight python >}} +DD_SOCIAL_AUTH_GITLAB_KEY=(str, 'YOUR_APPLICATION_ID'), +DD_SOCIAL_AUTH_GITLAB_SECRET=(str, 'YOUR_SECRET'), +DD_SOCIAL_AUTH_GITLAB_API_URL=(str, 'https://gitlab.com'), +DD_SOCIAL_AUTH_GITLAB_OAUTH2_ENABLED=True +{{< /highlight >}} + +Restart DefectDojo. A **Login with GitLab** button will appear on the login page. + +### Auto-importing GitLab projects + +To automatically import your GitLab projects as DefectDojo Products, add the following variable: + +{{< highlight python >}} +DD_SOCIAL_AUTH_GITLAB_PROJECT_AUTO_IMPORT=True +{{< /highlight >}} + +**Note:** Enabling this on an existing instance with a GitLab integration will require users to re-grant the `read_repository` permission. diff --git a/docs/content/admin/sso/OS__google.md b/docs/content/admin/sso/OS__google.md new file mode 100644 index 00000000000..e7e1d505438 --- /dev/null +++ b/docs/content/admin/sso/OS__google.md @@ -0,0 +1,59 @@ +--- +title: "Google Auth" +description: "Configure Google OAuth in Open-Source DefectDojo" +weight: 12 +audience: opensource +--- + +Open-Source DefectDojo supports login via Google accounts. New users are created automatically on first login if they don't already exist. Existing DefectDojo users are matched to Google accounts by username (the portion before the `@` in their Google email). DefectDojo Pro users should refer to the [Pro Google guide](../PRO__google/). + +## Prerequisites + +Complete the following steps in the Google Cloud Console before configuring DefectDojo: + +1. Sign in to the [Google Developers Console](https://console.developers.google.com). + +2. Go to **Credentials > Create Credentials > OAuth Client ID**. + +3. Select **Web Application** and give it a descriptive name (e.g. `DefectDojo`). + +4. Under **Authorized Redirect URIs**, add: + `https://your-dojo-host/complete/google-oauth2/` + +5. Note the **Client ID** and **Client Secret Key**. + +## Configuration + +Set the following as environment variables, or without the `DD_` prefix in your `local_settings.py` file (see [Configuration](/get_started/open_source/configuration/)): + +{{< highlight python >}} +DD_SOCIAL_AUTH_GOOGLE_OAUTH2_ENABLED=True, +DD_SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=(str, 'YOUR_CLIENT_ID'), +DD_SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET=(str, 'YOUR_CLIENT_SECRET'), +{{< /highlight >}} + +You must also authorize which users can log in. You can whitelist by domain: + +{{< highlight python >}} +DD_SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_DOMAINS=['example.com', 'example.org'] +{{< /highlight >}} + +Or as an environment variable (comma-separated): + +{{< highlight python >}} +DD_SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_DOMAINS=example.com,example.org +{{< /highlight >}} + +Alternatively, whitelist specific email addresses: + +{{< highlight python >}} +DD_SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_EMAILS=['user@example.com'] +{{< /highlight >}} + +Or as an environment variable: + +{{< highlight python >}} +DD_SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_EMAILS=user@example.com,user2@example.com +{{< /highlight >}} + +Restart DefectDojo. A **Login With Google** button will appear on the login page. diff --git a/docs/content/admin/sso/OS__keycloak.md b/docs/content/admin/sso/OS__keycloak.md new file mode 100644 index 00000000000..e056f0da9fc --- /dev/null +++ b/docs/content/admin/sso/OS__keycloak.md @@ -0,0 +1,74 @@ +--- +title: "KeyCloak" +description: "Configure KeyCloak SSO in Open-Source DefectDojo" +weight: 14 +audience: opensource +--- + +Open-Source DefectDojo supports login via KeyCloak. DefectDojo Pro users should refer to the [Pro KeyCloak guide](../PRO__keycloak/). + +This guide assumes you already have a KeyCloak Realm configured. If not, see the [KeyCloak documentation](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/realms/create.html). + +## Prerequisites + +Complete the following steps in your KeyCloak realm before configuring DefectDojo: + +1. Add a new client with type `openid-connect`. Note the client ID. + +2. In the client settings: + - Set **Access Type** to `confidential` + - Under **Valid Redirect URIs**, add your DefectDojo URL, e.g. `https://your-dojo-host/*` + - Under **Web Origins**, add the same URL (or `+`) + - Under **Fine Grained OpenID Connect Configuration**: + - Set **User Info Signed Response Algorithm** to `RS256` + - Set **Request Object Signature Algorithm** to `RS256` + - Save the settings. + +3. Under **Scope**, set **Full Scope Allowed** to `off`. + +4. Under **Mappers**, add a custom mapper: + - **Name:** `aud` + - **Mapper Type:** `audience` + - **Included Audience:** select your client ID + - **Add ID to Token:** `off` + - **Add Access to Token:** `on` + +5. Under **Credentials**, copy the **Secret**. + +6. In **Realm Settings > Keys**, copy the **Public Key** (signing key). + +7. In **Realm Settings > General > Endpoints**, open the OpenID endpoint configuration and copy the **Authorization** and **Token** endpoint URLs. + +## Configuration + +Set the following as environment variables, or without the `DD_` prefix in your `local_settings.py` file (see [Configuration](/get_started/open_source/configuration/)): + +{{< highlight python >}} +DD_SESSION_COOKIE_SECURE=True, +DD_CSRF_COOKIE_SECURE=True, +DD_SECURE_SSL_REDIRECT=True, +DD_SOCIAL_AUTH_KEYCLOAK_OAUTH2_ENABLED=True, +DD_SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY=(str, 'YOUR_REALM_PUBLIC_KEY'), +DD_SOCIAL_AUTH_KEYCLOAK_KEY=(str, 'YOUR_CLIENT_ID'), +DD_SOCIAL_AUTH_KEYCLOAK_SECRET=(str, 'YOUR_CLIENT_SECRET'), +DD_SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL=(str, 'YOUR_AUTHORIZATION_ENDPOINT'), +DD_SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL=(str, 'YOUR_TOKEN_ENDPOINT') +{{< /highlight >}} + +For Helm deployments, add the following to the `extraConfig` section: + +```yaml +DD_SESSION_COOKIE_SECURE: 'True' +DD_CSRF_COOKIE_SECURE: 'True' +DD_SECURE_SSL_REDIRECT: 'True' +DD_SOCIAL_AUTH_KEYCLOAK_OAUTH2_ENABLED: 'True' +DD_SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY: '' +DD_SOCIAL_AUTH_KEYCLOAK_KEY: '' +DD_SOCIAL_AUTH_KEYCLOAK_SECRET: '' +DD_SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL: '' +DD_SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL: '' +``` + +Optionally, set `DD_SOCIAL_AUTH_KEYCLOAK_LOGIN_BUTTON_TEXT` to customize the login button text. + +Restart DefectDojo. A login button will appear on the login page with your configured text. diff --git a/docs/content/admin/sso/OS__oidc.md b/docs/content/admin/sso/OS__oidc.md new file mode 100644 index 00000000000..9c195889923 --- /dev/null +++ b/docs/content/admin/sso/OS__oidc.md @@ -0,0 +1,40 @@ +--- +title: "OIDC" +description: "Configure OpenID Connect (OIDC) SSO in Open-Source DefectDojo" +weight: 18 +audience: opensource +--- + +Open-Source DefectDojo supports login via a generic OpenID Connect (OIDC) provider. DefectDojo Pro users should refer to the [Pro OIDC guide](../PRO__oidc/). + +## Configuration + +Set the following required variables as environment variables, or without the `DD_` prefix in your `local_settings.py` file (see [Configuration](/get_started/open_source/configuration/)): + +{{< highlight python >}} +DD_SOCIAL_AUTH_OIDC_AUTH_ENABLED=True, +DD_SOCIAL_AUTH_OIDC_OIDC_ENDPOINT=(str, 'https://your-oidc-provider.com'), +DD_SOCIAL_AUTH_OIDC_KEY=(str, 'YOUR_CLIENT_ID'), +DD_SOCIAL_AUTH_OIDC_SECRET=(str, 'YOUR_CLIENT_SECRET') +{{< /highlight >}} + +The remaining OIDC configuration is auto-detected by fetching: +`/.well-known/openid-configuration` + +Restart DefectDojo. A **Log In With OIDC** button will appear on the login page. + +## Optional Variables + +{{< highlight python >}} +DD_SOCIAL_AUTH_OIDC_ID_KEY=(str, ''), # Key associated with OIDC user IDs +DD_SOCIAL_AUTH_OIDC_USERNAME_KEY=(str, ''), # Key associated with OIDC usernames +DD_SOCIAL_AUTH_CREATE_USER_MAPPING=(str, 'username'), # Can also be 'email' or 'fullname' +DD_SOCIAL_AUTH_OIDC_WHITELISTED_DOMAINS=(list, ['']), # Domains allowed for login +DD_SOCIAL_AUTH_OIDC_JWT_ALGORITHMS=(list, ['RS256', 'HS256']), +DD_SOCIAL_AUTH_OIDC_ID_TOKEN_ISSUER=(str, ''), +DD_SOCIAL_AUTH_OIDC_ACCESS_TOKEN_URL=(str, ''), +DD_SOCIAL_AUTH_OIDC_AUTHORIZATION_URL=(str, ''), +DD_SOCIAL_AUTH_OIDC_USERINFO_URL=(str, ''), +DD_SOCIAL_AUTH_OIDC_JWKS_URI=(str, ''), +DD_SOCIAL_AUTH_OIDC_LOGIN_BUTTON_TEXT=(str, 'Login with OIDC'), +{{< /highlight >}} diff --git a/docs/content/admin/sso/OS__okta.md b/docs/content/admin/sso/OS__okta.md new file mode 100644 index 00000000000..8348fdf2339 --- /dev/null +++ b/docs/content/admin/sso/OS__okta.md @@ -0,0 +1,46 @@ +--- +title: "Okta" +description: "Configure Okta SSO in Open-Source DefectDojo" +weight: 16 +audience: opensource +--- + +Open-Source DefectDojo supports login via Okta. DefectDojo Pro users should refer to the [Pro Okta guide](../PRO__okta/). + +## Prerequisites + +Complete the following steps in Okta before configuring DefectDojo: + +1. Sign in or create an account at [Okta](https://www.okta.com/developer/signup/). + +2. Go to **Applications** and click **Add Application**, then select **Web Applications**. + +3. Under **Login Redirect URLs**, add: + `https://your-dojo-host/complete/okta-oauth2/` + Also check the **Implicit** box. + +4. Click **Done**. + +5. From the **Dashboard**, note the **Org-URL**. + +6. Open the application and note the **Client ID** and **Client Secret**. + +## Configuration + +Set the following as environment variables, or without the `DD_` prefix in your `local_settings.py` file (see [Configuration](/get_started/open_source/configuration/)): + +{{< highlight python >}} +DD_SOCIAL_AUTH_OKTA_OAUTH2_ENABLED=True, +DD_SOCIAL_AUTH_OKTA_OAUTH2_KEY=(str, 'YOUR_CLIENT_ID'), +DD_SOCIAL_AUTH_OKTA_OAUTH2_SECRET=(str, 'YOUR_CLIENT_SECRET'), +DD_SOCIAL_AUTH_OKTA_OAUTH2_API_URL=(str, 'https://your-org-url/oauth2'), +{{< /highlight >}} + +Restart DefectDojo. A **Login With Okta** button will appear on the login page. + +### Redirect URI shows http instead of https + +If you see the error *The 'redirect_uri' parameter must be an absolute URI that is whitelisted in the client app settings* and the `redirect_uri` starts with `http://` instead of `https://`, add the following: + +- **Docker Compose:** `DD_SOCIAL_AUTH_REDIRECT_IS_HTTPS=True` +- **local_settings.py:** `SOCIAL_AUTH_REDIRECT_IS_HTTPS=True` diff --git a/docs/content/admin/sso/OS__remote_user.md b/docs/content/admin/sso/OS__remote_user.md new file mode 100644 index 00000000000..d2836e81643 --- /dev/null +++ b/docs/content/admin/sso/OS__remote_user.md @@ -0,0 +1,37 @@ +--- +title: "RemoteUser" +description: "Configure RemoteUser authentication in Open-Source DefectDojo" +weight: 19 +audience: opensource +--- + +RemoteUser authentication is suitable when DefectDojo is deployed behind an HTTP authentication proxy. The proxy handles authentication and passes user information to DefectDojo via HTTP headers. + +**Warning:** The proxy must be configured to strip any attacker-supplied headers matching the `DD_AUTH_REMOTEUSER_*` variable names before forwarding requests to DefectDojo, to prevent header spoofing. See the [Django documentation](https://docs.djangoproject.com/en/3.2/howto/auth-remote-user/#configuration) for details. + +## Configuration + +Set the following as environment variables, or without the `DD_` prefix in your `local_settings.py` file (see [Configuration](/get_started/open_source/configuration/)): + +| Variable | Required | Description | +|---|---|---| +| `DD_AUTH_REMOTEUSER_ENABLED` | Yes | Set to `True` to enable RemoteUser authentication | +| `DD_AUTH_REMOTEUSER_USERNAME_HEADER` | Yes | Header containing the username | +| `DD_AUTH_REMOTEUSER_TRUSTED_PROXY` | Yes | Comma-separated list of trusted proxy IPs or CIDR ranges | +| `DD_AUTH_REMOTEUSER_EMAIL_HEADER` | No | Header containing the user's email address | +| `DD_AUTH_REMOTEUSER_FIRSTNAME_HEADER` | No | Header containing the user's first name | +| `DD_AUTH_REMOTEUSER_LASTNAME_HEADER` | No | Header containing the user's last name | +| `DD_AUTH_REMOTEUSER_GROUPS_HEADER` | No | Header containing a comma-separated list of groups; the user will be assigned to these groups, and any missing groups will be created | +| `DD_AUTH_REMOTEUSER_GROUPS_CLEANUP` | No | When `True`, removes the user from any groups not present in the current request's group header | +| `DD_AUTH_REMOTEUSER_LOGIN_ONLY` | No | See [Django documentation](https://docs.djangoproject.com/en/3.2/howto/auth-remote-user/#using-remote-user-on-login-pages-only) | + +## User Permissions + +When a new user is created via RemoteUser (or any other SSO method), they are assigned only default permissions and cannot add, edit, or delete anything in DefectDojo. + +To grant permissions to new users automatically, configure the following in **System Settings**: + +- **Default group** — assign new users to a specific group on creation +- **Default group role** — set the role new users receive within that group + +For group-based access via the `DD_AUTH_REMOTEUSER_GROUPS_HEADER`, permissions are inherited from the groups the user belongs to. See [User Permissions](../../user_management/set_user_permissions/) and [User Groups](../../user_management/create_user_group/) for more information. diff --git a/docs/content/admin/sso/OS__saml.md b/docs/content/admin/sso/OS__saml.md new file mode 100644 index 00000000000..7ded9b13c26 --- /dev/null +++ b/docs/content/admin/sso/OS__saml.md @@ -0,0 +1,80 @@ +--- +title: "SAML Configuration" +description: "Configure SAML in Open-Source DefectDojo" +weight: 2 +audience: opensource +aliases: + - /en/working_with_findings/sla_configuration +--- + +Open-Source DefectDojo supports SAML authentication via environment variables. DefectDojo Pro users should refer to the [Pro SAML guide](../PRO__saml/). + +## Setup + +1. Navigate to your SAML Identity Provider and locate your metadata. + +2. Set the following as environment variables, or without the `DD_` prefix in your `local_settings.py` file (see [Configuration](/get_started/open_source/configuration/)): + + {{< highlight python >}} + DD_SAML2_ENABLED=(bool, True), + # Login button text shown on the DefectDojo login page + DD_SAML2_LOGIN_BUTTON_TEXT=(str, 'Login with SAML'), + # If the metadata is accessible from a URL: + DD_SAML2_METADATA_AUTO_CONF_URL=(str, 'https://your_IdP.com/metadata.xml'), + # Otherwise, download the metadata as an XML file and set the path: + DD_SAML2_METADATA_LOCAL_FILE_PATH=(str, '/path/to/your/metadata.xml'), + # Map SAML assertion attributes to DefectDojo user fields: + DD_SAML2_ATTRIBUTES_MAP=(dict, { + # Format: 'SAML attribute': 'django_user_field' + 'Email': 'email', + 'UserName': 'username', + 'Firstname': 'first_name', + 'Lastname': 'last_name' + }), + {{< /highlight >}} + + **Note:** In Kubernetes, `DD_SAML2_ATTRIBUTES_MAP` can be set in `extraConfig` as: + `DD_SAML2_ATTRIBUTES_MAP: 'Email'='email', 'Username'='username'...` + + **Note:** `DD_SITE_URL` may also need to be set depending on whether you use a metadata URL or a local file. + +3. Review the SAML section in `dojo/settings/settings.dist.py` to verify the configuration matches your requirements. See the [djangosaml2 plugin documentation](https://djangosaml2.readthedocs.io/contents/setup.html#configuration) for further options. + +4. Restart DefectDojo. A **Login with SAML** button will appear on the login page. + +**Note:** If your IdP uses a self-signed certificate, set the `REQUESTS_CA_BUNDLE` environment variable to the path of your private CA certificate. + +## Advanced Configuration + +The [djangosaml2](https://github.com/IdentityPython/djangosaml2) plugin supports many additional options. All DefectDojo defaults can be overridden in `local_settings.py`. For example, to customize the organization name: + +{{< highlight python >}} +if SAML2_ENABLED: + SAML_CONFIG['contact_person'] = [{ + 'given_name': 'Extra', + 'sur_name': 'Example', + 'company': 'DefectDojo', + 'email_address': 'dummy@defectdojo.com', + 'contact_type': 'technical' + }] + SAML_CONFIG['organization'] = { + 'name': [('DefectDojo', 'en')], + 'display_name': [('DefectDojo', 'en')], + }, +{{< /highlight >}} + +## Troubleshooting + +The SAML Tracer browser extension can help debug SAML issues: [Chrome](https://chromewebstore.google.com/detail/saml-tracer/mpdajninpobndbfcldcmbpnnbhibjmch?hl=en), [Firefox](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/). + +## Migrating from django-saml2-auth + +Prior to release 1.15.0, SAML was handled by [django-saml2-auth](https://github.com/fangli/django-saml2-auth). The following parameters changed with the switch to djangosaml2: + +| Old parameter | Status | +|---|---| +| `DD_SAML2_ASSERTION_URL` | No longer needed — auto-generated | +| `DD_SAML2_DEFAULT_NEXT_URL` | No longer needed — default forwarding is used | +| `DD_SAML2_NEW_USER_PROFILE` | No longer supported — default profile is used | +| `DD_SAML2_ATTRIBUTES_MAP` | Syntax has changed | +| `DD_SAML2_CREATE_USER` | Default changed to `False` to prevent security issues | diff --git a/docs/content/admin/sso/PRO__auth0.md b/docs/content/admin/sso/PRO__auth0.md new file mode 100644 index 00000000000..a755a31ee8c --- /dev/null +++ b/docs/content/admin/sso/PRO__auth0.md @@ -0,0 +1,33 @@ +--- +title: "Auth0" +description: "Configure Auth0 SSO in DefectDojo Pro" +weight: 3 +audience: pro +--- + +DefectDojo Pro supports login via Auth0. Open-Source users should refer to the [Open-Source Auth0 guide](../OS__auth0/). + +## Prerequisites + +Complete the following steps in your Auth0 dashboard before configuring DefectDojo: + +1. Create a new application: **Applications > Create Application > Single Page Web Application**. + +2. Configure the application: + - **Name:** `DefectDojo` + - **Allowed Callback URLs:** `https://your-instance.cloud.defectdojo.com/complete/auth0/` + +3. Note the following values — you will need them in DefectDojo: + - **Domain** + - **Client ID** + - **Client Secret** + +## Configuration + +In DefectDojo, go to **Enterprise Settings > OAuth Settings**, select **Auth0**, and fill in the form: + +- **Auth0 OAuth Key** — enter your **Client ID** +- **Auth0 OAuth Secret** — enter your **Client Secret** +- **Auth0 Domain** — enter your **Domain** + +Check **Enable Auth0 OAuth** to add a **Login With Auth0** button to the DefectDojo login page. diff --git a/docs/content/admin/sso/PRO__azure_ad.md b/docs/content/admin/sso/PRO__azure_ad.md new file mode 100644 index 00000000000..9682551e1aa --- /dev/null +++ b/docs/content/admin/sso/PRO__azure_ad.md @@ -0,0 +1,58 @@ +--- +title: "Azure Active Directory" +description: "Configure Azure AD SSO and group mapping in DefectDojo Pro" +weight: 5 +audience: pro +--- + +DefectDojo Pro supports login via Azure Active Directory (Azure AD), including automatic User Group synchronization. Open-Source users should refer to the [Open-Source Azure AD guide](../OS__azure_ad/). + +## Prerequisites + +Complete the following steps in the Azure portal before configuring DefectDojo: + +1. [Register a new app](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) in Azure Active Directory. + +2. Note the following values from the registered app: + - **Application (client) ID** + - **Directory (tenant) ID** + - Under **Certificates & Secrets**, create a new **Client Secret** and note its value + - **Application ID URI** + +3. Under **Authentication > Redirect URIs**, add a **Web** type URI: + `https://your-instance.cloud.defectdojo.com/complete/azuread-tenant-oauth2/` + +## Configuration + +In DefectDojo, go to **Enterprise Settings > OAuth Settings**, select **Azure AD**, and fill in the form: + +- **Azure AD OAuth Key** — enter your **Application (client) ID** +- **Azure AD OAuth Secret** — enter your **Client Secret** +- **Azure AD Resource** — defaults to `https://graph.microsoft.com/`. This is the URI DefectDojo uses to read additional information (such as group names) from the [Microsoft Graph Web API](https://docs.azure.cn/en-us/entra/identity-platform/security-best-practices-for-app-registration#application-id-uri). Only change this if your group names are stored on a different API resource. +- **Azure AD Tenant ID** — enter your **Directory (tenant) ID** +- **Azure AD Groups Filter** — optionally enter a regex string to restrict which User Groups are imported (see [Group Mapping](#group-mapping) below) + +Check **Enable Azure AD OAuth** and submit the form. A **Login With Azure AD** button will appear on the login page. + +## Group Mapping + +Group mapping allows DefectDojo to import [User Group](../../user_management/create_user_group/) membership from Azure AD. User Groups in DefectDojo govern product and product type access via [RBAC](../../user_management/set_user_permissions/). + +Check **Enable Azure AD OAuth Grouping** to activate this feature. On login, DefectDojo will match the user's Azure AD groups to existing DefectDojo groups. Any groups not found in DefectDojo will be created automatically. + +To import only a subset of groups, enter a regex in the **Azure AD Groups Filter** field. For example: +- `^team-.*` — matches any group starting with `team-` +- `teamA|teamB|groupC` — matches specific named groups + +### Configuring Azure AD to send groups + +The Azure AD token must be configured to include group IDs. Without this, no group information will be present in the token. + +To configure this: +1. Add a [Group Claim](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims) in the Azure AD token configuration. If unsure which group type to select, choose **All Groups**. +2. Do **not** enable **Emit groups as role claims**. +3. Update the application's API permissions to include `GroupMember.Read.All` or `Group.Read.All`. `GroupMember.Read.All` is recommended as it grants fewer permissions. + +### Group Cleaning + +If **Enable Azure AD OAuth Group Cleaning** is enabled, DefectDojo groups created via Azure AD sync will be automatically removed when they have no remaining members. When a user is removed from a group in Azure AD, they are also removed from the corresponding group in DefectDojo. diff --git a/docs/content/admin/sso/PRO__github_enterprise.md b/docs/content/admin/sso/PRO__github_enterprise.md new file mode 100644 index 00000000000..6318baf32e5 --- /dev/null +++ b/docs/content/admin/sso/PRO__github_enterprise.md @@ -0,0 +1,32 @@ +--- +title: "GitHub Enterprise" +description: "Configure GitHub Enterprise SSO in DefectDojo Pro" +weight: 7 +audience: pro +--- + +DefectDojo Pro supports login via GitHub Enterprise. Open-Source users should refer to the [Open-Source GitHub Enterprise guide](../OS__github_enterprise/). + +## Prerequisites + +Complete the following steps in GitHub Enterprise before configuring DefectDojo: + +1. [Create a new OAuth App](https://docs.github.com/en/enterprise-server/developers/apps/building-oauth-apps/creating-an-oauth-app) in your GitHub Enterprise Server. + +2. Choose a name for the application, e.g. `DefectDojo`. + +3. Set the **Redirect URI**: + `https://your-instance.cloud.defectdojo.com/complete/github-enterprise/` + +4. Note the **Client ID** and **Client Secret** from the app. + +## Configuration + +In DefectDojo, go to **Enterprise Settings > OAuth Settings**, select **GitHub Enterprise**, and fill in the form: + +- **GitHub Enterprise OAuth Key** — enter your **Client ID** +- **GitHub Enterprise OAuth Secret** — enter your **Client Secret** +- **GitHub Enterprise URL** — enter your organization's GitHub URL, e.g. `https://github.yourcompany.com/` +- **GitHub Enterprise API URL** — enter your organization's GitHub API URL, e.g. `https://github.yourcompany.com/api/v3/` + +Check **Enable GitHub Enterprise OAuth** and submit the form. A **Login With GitHub** button will appear on the login page. diff --git a/docs/content/admin/sso/PRO__gitlab.md b/docs/content/admin/sso/PRO__gitlab.md new file mode 100644 index 00000000000..cb854902a6f --- /dev/null +++ b/docs/content/admin/sso/PRO__gitlab.md @@ -0,0 +1,32 @@ +--- +title: "GitLab" +description: "Configure GitLab SSO in DefectDojo Pro" +weight: 9 +audience: pro +--- + +DefectDojo Pro supports login via GitLab. Open-Source users should refer to the [Open-Source GitLab guide](../OS__gitlab/). + +## Prerequisites + +Complete the following steps in GitLab before configuring DefectDojo: + +1. Navigate to your GitLab profile's Applications page: + - GitLab.com: `https://gitlab.com/profile/applications` + - Self-hosted: `https://your-gitlab-host/profile/applications` + +2. Create a new application: + - **Name:** `DefectDojo` + - **Redirect URI:** `https://your-dojo-instance.cloud.defectdojo.com/complete/gitlab/` + +3. Note the **Application ID** and **Secret** from the application. + +## Configuration + +In DefectDojo, go to **Enterprise Settings > OAuth Settings**, select **GitLab**, and fill in the form: + +- **GitLab OAuth Key** — enter your **Application ID** +- **GitLab OAuth Secret** — enter your **Secret** +- **GitLab API URL** — enter the base URL of your GitLab instance, e.g. `https://gitlab.com` + +Check **Enable GitLab OAuth** and submit the form. A **Login With GitLab** button will appear on the login page. diff --git a/docs/content/admin/sso/PRO__google.md b/docs/content/admin/sso/PRO__google.md new file mode 100644 index 00000000000..b03a63a7da7 --- /dev/null +++ b/docs/content/admin/sso/PRO__google.md @@ -0,0 +1,38 @@ +--- +title: "Google Auth" +description: "Configure Google OAuth in DefectDojo Pro" +weight: 11 +audience: pro +--- + +DefectDojo Pro supports login via Google accounts. New users are created automatically on first login if they don't already exist. Existing DefectDojo users are matched to Google accounts by username (the portion before the `@` in their Google email). Open-Source users should refer to the [Open-Source Google guide](../OS__google/). + +## Prerequisites + +Complete the following steps in the Google Cloud Console before configuring DefectDojo: + +1. Sign in to the [Google Developers Console](https://console.developers.google.com). + +2. Go to **Credentials > Create Credentials > OAuth Client ID**. + + ![image](images/google_1.png) + +3. Select **Web Application** and give it a descriptive name (e.g. `DefectDojo`). + +4. Under **Authorized Redirect URIs**, add: + `https://your-instance.cloud.defectdojo.com/complete/google-oauth2/` + +5. Note the **Client ID** and **Client Secret Key**. + +## Configuration + +In DefectDojo, go to **Enterprise Settings > OAuth Settings**, select **Google**, and fill in the form: + +- **Google OAuth Key** — enter your **Client ID** +- **Google OAuth Secret** — enter your **Client Secret Key** +- **Whitelisted Domains** — enter your organization's domain (e.g. `yourcompany.com`) to allow any user with that domain to log in +- **Whitelisted E-mail Addresses** — alternatively, enter specific email addresses to allow (e.g. `user1@yourcompany.com, user2@yourcompany.com`) + +You must set at least one whitelisted domain or email address, or no users will be able to log in via Google. + +Check **Enable Google OAuth** and submit the form. A **Login With Google** button will appear on the login page. diff --git a/docs/content/admin/sso/PRO__keycloak.md b/docs/content/admin/sso/PRO__keycloak.md new file mode 100644 index 00000000000..e90d6909bbb --- /dev/null +++ b/docs/content/admin/sso/PRO__keycloak.md @@ -0,0 +1,53 @@ +--- +title: "KeyCloak" +description: "Configure KeyCloak SSO in DefectDojo Pro" +weight: 13 +audience: pro +--- + +DefectDojo Pro supports login via KeyCloak. Open-Source users should refer to the [Open-Source KeyCloak guide](../OS__keycloak/). + +This guide assumes you already have a KeyCloak Realm configured. If not, see the [KeyCloak documentation](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/realms/create.html). + +## Prerequisites + +Complete the following steps in your KeyCloak realm before configuring DefectDojo: + +1. Add a new client with type `openid-connect`. Note the client ID. + +2. In the client settings: + - Set **Access Type** to `confidential` + - Under **Valid Redirect URIs**, add your DefectDojo URL, e.g. `https://yourorganization.cloud.defectdojo.com` or `https://your-dojo-host/*` + - Under **Web Origins**, add the same URL (or `+`) + - Under **Fine Grained OpenID Connect Configuration**: + - Set **User Info Signed Response Algorithm** to `RS256` + - Set **Request Object Signature Algorithm** to `RS256` + - Save the settings. + +3. Under **Scope**, set **Full Scope Allowed** to `off`. + +4. Under **Mappers**, add a custom mapper: + - **Name:** `aud` + - **Mapper Type:** `audience` + - **Included Audience:** select your client ID + - **Add ID to Token:** `off` + - **Add Access to Token:** `on` + +5. Under **Credentials**, copy the **Secret**. + +6. In **Realm Settings > Keys**, copy the **Public Key** (signing key). + +7. In **Realm Settings > General > Endpoints**, open the OpenID endpoint configuration and copy the **Authorization** and **Token** endpoint URLs. + +## Configuration + +In DefectDojo, go to **Enterprise Settings > OAuth Settings**, select **KeyCloak**, and fill in the form: + +- **KeyCloak OAuth Key** — enter your client name (from step 1) +- **KeyCloak OAuth Secret** — enter your client credentials secret (from step 5) +- **KeyCloak Public Key** — enter the Public Key from your realm settings (from step 6) +- **KeyCloak Resource** — enter the Authorization Endpoint URL (from step 7) +- **KeyCloak Group Limiter** — enter the Token Endpoint URL (from step 7) +- **KeyCloak OAuth Login Button Text** — choose the text for the DefectDojo login button + +Check **Enable KeyCloak OAuth** and submit the form. A login button will appear on the login page with the text you configured. diff --git a/docs/content/admin/sso/PRO__oidc.md b/docs/content/admin/sso/PRO__oidc.md new file mode 100644 index 00000000000..d68a0a4ad0e --- /dev/null +++ b/docs/content/admin/sso/PRO__oidc.md @@ -0,0 +1,23 @@ +--- +title: "OIDC" +description: "Configure OpenID Connect (OIDC) SSO in DefectDojo Pro" +weight: 17 +audience: pro +--- + +DefectDojo Pro supports login via a generic OpenID Connect (OIDC) provider. Open-Source users should refer to the [Open-Source OIDC guide](../OS__oidc/). + +## Configuration + +In DefectDojo, go to **Enterprise Settings > OIDC Settings**. + +![image](images/oidc_pro.png) + +Fill in the form: + +1. **Endpoint** — the base URL of your OIDC provider. Do not include `/.well-known/openid-configuration`. +2. **Client ID** — your OIDC client ID. +3. **Client Secret** — your OIDC client secret. +4. Check **Enable OIDC**. + +Submit the form. A **Log In With OIDC** button will appear on the DefectDojo login page. diff --git a/docs/content/admin/sso/PRO__okta.md b/docs/content/admin/sso/PRO__okta.md new file mode 100644 index 00000000000..4863dcb773b --- /dev/null +++ b/docs/content/admin/sso/PRO__okta.md @@ -0,0 +1,46 @@ +--- +title: "Okta" +description: "Configure Okta SSO in DefectDojo Pro" +weight: 15 +audience: pro +--- + +DefectDojo Pro supports login via Okta. Open-Source users should refer to the [Open-Source Okta guide](../OS__okta/). + +## Prerequisites + +Complete the following steps in Okta before configuring DefectDojo: + +1. Sign in or create an account at [Okta](https://www.okta.com/developer/signup/). + +2. Go to **Applications** and click **Add Application**. + + ![image](images/okta_1.png) + +3. Select **Web Applications**. + + ![image](images/okta_2.png) + +4. Under **Login Redirect URLs**, add your DefectDojo callback URL. Also check the **Implicit** box. + + ![image](images/okta_3.png) + +5. Click **Done**. + +6. From the **Dashboard**, note the **Org-URL**. + + ![image](images/okta_4.png) + +7. Open the newly created application and note the **Client ID** and **Client Secret**. + + ![image](images/okta_5.png) + +## Configuration + +In DefectDojo, go to **Enterprise Settings > OAuth Settings**, select **Okta**, and fill in the form: + +- **Okta OAuth Key** — enter your **Client ID** +- **Okta OAuth Secret** — enter your **Client Secret** +- **Okta Tenant ID** — enter your Org-URL in the format `https://your-org-url/oauth2` + +Check **Enable Okta OAuth** and submit the form. A **Login With Okta** button will appear on the login page. diff --git a/docs/content/admin/sso/PRO__saml.md b/docs/content/admin/sso/PRO__saml.md new file mode 100644 index 00000000000..7ca7b225e99 --- /dev/null +++ b/docs/content/admin/sso/PRO__saml.md @@ -0,0 +1,55 @@ +--- +title: "SAML Configuration" +description: "Configure SAML in DefectDojo Pro" +weight: 1 +audience: pro +--- + +DefectDojo Pro supports SAML authentication via the **Enterprise Settings** UI. Open-Source users should refer to the [Open-Source SAML guide](../OS__saml/). + +## Setup + +1. Open **Enterprise Settings > SAML Settings**. + + ![image](images/sso_betaui_1.png) + +2. Set an **Entity ID** — a label or URL that your SAML Identity Provider uses to identify DefectDojo. This field is required. + +3. Optionally set **Login Button Text** — the text shown on the button users click to begin SAML login. + +4. Optionally set a **Logout URL** to redirect users to after they log out of DefectDojo. + +5. Choose a **Name ID Format**: + - **Persistent** — users are consistently identified by SAML across sessions. + - **Transient** — users receive a different SAML ID on each login. + - **Entity** — all users share a single SAML NameID. + - **Encrypted** — each user's NameID is encrypted. + +6. **Required Attributes** — specify the attributes DefectDojo requires from the SAML response. + +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. + +8. **Remote SAML Metadata** — the URL where your SAML Identity Provider metadata is hosted. + +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. + + ![image](images/sso_saml_login.png). + +## SAML Group Mapping + +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. + +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. + +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. + +To activate group mapping, check the **Enable Group Mapping** checkbox at the bottom of the form. + +## Additional Options + +* **Create Unknown User** — automatically create a new DefectDojo user if they are not found in the SAML response. +* **Allow Unknown Attributes** — allow login for users who have attributes not listed in the Attribute Mapping. +* **Sign Assertions/Responses** — require all incoming SAML responses to be signed. +* **Sign Logout Requests** — sign all logout requests sent by DefectDojo. +* **Force Authentication** — require users to authenticate with the Identity Provider on every login, regardless of existing sessions. +* **Enable SAML Debugging** — log detailed SAML output for troubleshooting. diff --git a/docs/content/admin/sso/_index.md b/docs/content/admin/sso/_index.md new file mode 100644 index 00000000000..c48d92360ae --- /dev/null +++ b/docs/content/admin/sso/_index.md @@ -0,0 +1,58 @@ +--- +title: "Single Sign-On" +description: "Set Up User Permissions, SSO and Groups" +summary: "" +date: 2023-09-07T16:06:50+02:00 +lastmod: 2023-09-07T16:06:50+02:00 +draft: false +weight: 8 +collapsed: true +chapter: true +seo: + title: "" + description: "" + canonical: "" + robots: "" +exclude_search: true +aliases: + - /admin/user_management/configure_sso/ +--- + +Users can connect to DefectDojo with a Username and Password, but you can also allow users to authenticate via Single Sign-On (SSO). DefectDojo supports SAML and a range of OAuth providers: + +* **[Auth0](./PRO__auth0/)** +* **[Azure Active Directory](./PRO__azure_ad/)** +* **[GitHub Enterprise](./PRO__github_enterprise/)** +* **[GitLab](./PRO__gitlab/)** +* **[Google](./PRO__google/)** +* **[KeyCloak](./PRO__keycloak/)** +* **[Okta](./PRO__okta/)** +* **[OIDC (OpenID Connect)](./PRO__oidc/)** +* **[SAML](./PRO__saml/)** + +SSO configuration can only be performed by a **Superuser**. + +**DefectDojo Pro users:** Add the IP addresses of your SAML or SSO services to the Firewall whitelist before setting up SSO. See [Firewall Rules](/get_started/pro/cloud/using-cloud-manager/#changing-your-firewall-settings) for more information. + +## Disabling Username / Password Login + +Once SSO is configured, you may want to disable traditional username/password login. + +**DefectDojo Pro** users can uncheck **Allow Login via Username and Password** under **Enterprise Settings > Login Settings**. + +![image](images/pro_login_settings.png) + +**Open-Source** users can set the following environment variables in Docker: + +```yaml +DD_SOCIAL_LOGIN_AUTO_REDIRECT: "true" +DD_SOCIAL_AUTH_SHOW_LOGIN_FORM: "false" +``` + +### Login Fallback + +If your SSO integration stops working, you can always return to the standard login form by appending the following to your DefectDojo URL: + +`/login?force_login_form` + +We recommend keeping at least one admin account with a username and password configured as a fallback. diff --git a/docs/content/admin/user_management/configure_sso.md b/docs/content/admin/user_management/configure_sso.md index 864b852b11f..1e2f89f1e6a 100644 --- a/docs/content/admin/user_management/configure_sso.md +++ b/docs/content/admin/user_management/configure_sso.md @@ -619,6 +619,16 @@ The left side of the ‘=’ sign represents the attribute you want to map from * **Enable SAML Debugging** will log more detailed SAML output for debugging purposes. +#### SAML Group Mapping + +DefectDojo can use the SAML assertion to automatically assign users to [User Groups](../create_user_group/). Groups in DefectDojo can assign Permissions to all of their Group members, so using Group Mapping allows you to assign those permissions in bulk. This is the only way to set permissions via SAML. + +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. + +If no Group with a matching name exists, DefectDojo will automatically create one. Note that this Group will not have any permissions at the time of creation, but those can be configured later by a DefectDojo user with appropriate permissions. + +To activate group mapping, check the **Enable Group Mapping** checkbox at the bottom of the form. + ### Open-Source SAML 1. Navigate to your SAML IdP and find your metadata.