Configure SAML SSO

Single Sign-On (or SSO) allows you to manage your organization’s entire membership via a third-party provider.

GitGuardian supports the SAML2 standard for SSO which allows the Owner or any Manager, of the workspace to configure any SAML2-enabled Identity Provider (IdP) system (Google, Okta,...).

Set up SSO

To configure your SSO, navigate to Settings > Authentication.

Detailed set up procedures are available for the following IdP:

• Google
• Okta
• Auth0
• Microsoft Entra ID
• Duo
• Keycloak

For all other SAML2-enabled IdP, you can follow the generic procedure.

Just-In-Time (JIT) provisioning

GitGuardian supports Just-In-Time (JIT) provisioning. New members of your workspace are automatically registered with GitGuardian on their first login attempt with SAML2 SSO if they are authorized on the IdP side.

You don't need to invite users manually. You just need to authorize them on the IdP's side by being part of the "GitGuardian group". Users who are not part of the GitGuardian group on the IdP side will be rejected during their attempt to sign in via SSO.

info

GitGuardian does not support JIT deprovisioning yet but you can use the SCIM to automatically deprovision your users.

Default access level

Because GitGuardian uses Just-In-Time (JIT) provisioning, new members will be given a default access level upon their first login.

"Member" is the default setting. You can modify this default in your Authentication settings page.

If you selected "Member" as the default access level and your workspace is under the Business plan, you must also configure whether new Members will be part of the "All-incidents" team or not upon sign up. This option is available in Business plan.

Force SSO

Once you have successfully set up an SAML2 SSO integration, in your Authentication settings page, you have the option to force the SSO:

• If the option is turned ON, all the members of your workspace will have to go through your IdP in order to be able to access your GitGuardian workspace. Thus, only the users you have authorized on your IdP’s side will be able to sign into your GitGuardian workspace. If you want to activate the option, you will have the possibility to visualize the users that may encounter an issue.
• If the option is turned OFF, members of your workspace can still login via SSO, going through your IdP, but they can also sign up via email. As a result, users that are not whitelisted on the IdP side can still login to your GitGuardian workspace.

Once SSO is forced, all the members of the workspace, including the owner, will have to connect using SSO. If the owner has never connected with SSO, you will not be able to activate the option.

Make sure that your SSO connection works before enforcing SSO. In case of issues, you can contact the support team for assistance.

Email domain reservation

Essential Step: Reserve Your Email Domain

After configuring SSO, you must reserve your email domain to enable the full SSO experience. This critical step:

• Enables automatic SSO discovery - Users can log in from the main login page by entering their email; GitGuardian automatically redirects them to your SSO provider
• Prevents workspace fragmentation - Users cannot create separate workspaces with their company email, ensuring everyone joins the same workspace
• Simplifies user experience - Without domain reservation, users must bookmark and use the dedicated SSO login URL

To reserve your domain:

1. Navigate to Settings > Email Domain Management
2. Follow the instructions to reserve your organization's email domain

Learn more about email domain management.

Set up procedures

Google

1. First, go to the Google Admin Console, and create a new custom SAML app.
2. You will land on this page, where you can set your app name and general information for your SAML app that users will see when logging in.
   
3. Click on "Continue". Now, you need to configure the Identity Provider in your GitGuardian dashboard. Use these values provided by Google:
   • Entity Id field is filled with the Entity ID
   • Single Sign-On URL field is filled with the SSO URL
   • X509 Cert field is filled with the certificate from Google. Download it, use cat and copy/paste the plaintext value.
   • On the GitGuardian dashboard, ensure that the checkbox "I have specified that the response assertions with RSA_SHA256 as signature algorithm and SHA256 as digest algorithm" is unchecked.
4. Click on "Continue". You can now configure the Service Provider details provided by GitGuardian within Google:
   • ACS URL field is filled with the ACS URL value.
   • Entity ID field is filled with the SP Entity id value.
   • Signed Response must be checked
   • Name ID format must be set to EMAIL
   • Name ID must be set to Basic Information > Primary Email
5. Now, some mappings need to be done, they are quite straightforward:
   • first_name is mapped to the user first name
   • last_name is mapped to the user last name
6. Finish your app configuration by clicking on "Finish". You might need to modify the SAML app user access, which is OFF for everyone by default.
7. Important: Don't forget to reserve your email domain to enable automatic SSO discovery.

Okta

1. First, go to https://$YOUR_OKTA_DOMAIN-admin.okta.com/admin/apps/add-app, then click on "Create New App".
2. You will land on this page, where you can set the general information for your SAML app that users will see when logging in.
3. Click "Next". You can now configure basic settings:
   • Single sign on URL field is filled with the ACS URL value on GitGuardian dashboard.
   • Audience URI (SP Entity ID) field is filled with the SP Entity ID value on GitGuardian dashboard.
   • Default RelayState is left blank
   • Name ID format must be set to EmailAddress
4. Click on "Show Advanced Settings". Here make sure that both Response and Assertion Signature are signed, and that Signature and Digest Algorithm are respectively set to RSA-SHA256 and SHA256. Assertions are not encrypted.
5. Now, some straightforward mapping needs to done:
   • first_name is mapped the user first name
   • last_name is mapped the user last name
6. Finish your app configuration.
7. Finally, we need to configure the Identity Provider in GitGuardian dashboard. First, click on "View Setup Instructions", then use these values:
   • Entity Id field is filled with the Identity Provider Issuer
   • Single Sign-On URL field is filled with the Identity Provider Single Sign-On URL
   • X509 Cert field is filled with the X.509 Certificate
8. Important: Don't forget to reserve your email domain to enable automatic SSO discovery.

Auth0

1. First, go to your dashboard, select "Application", and click on "Create Application"
2. Choose "Regular Web Applications" as type and a name.
3. Go to your application addons. Click on "SAML2 Web App" and then on "Settings"
4. Fill the Application Callback URL with the ACS URL provided in GitGuardian dashboard.
5. Then, copy-paste these settings to configure mappings, name identifier and message signatures:

{
  "mappings": {
    "given_name": "first_name",
    "family_name": "last_name"
  },
  "signatureAlgorithm": "rsa-sha256",
  "digestAlgorithm": "sha256",
  "signResponse": true,
  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "nameIdentifierProbes": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  ],
  "includeAttributeNameFormat": "false"
}

6. Finally, we need to configure the Identity Provider in GitGuardian dashboard. First, click on "Usage", then use these values:
   • Entity id field is filled with the Issuer value
   • Single Sign-On URL field is filled with the Identity Provider Login URL value
   • X509 Cert field is filled with the plain text value of the Identity Provider Certificate
   • Ensure that the checkbox "I have specified that the response assertions with RSA_SHA256 as signature algorithm and SHA256 as digest algorithm" is unchecked.

7. Important: Don't forget to reserve your email domain to enable automatic SSO discovery.

Microsoft Entra ID

1. First, go to the Microsoft Entra admin center, click on "Add enterprise application" at the bottom of the page, then "Create your own application".
2. In the new panel that appears on the right, provide a name (e.g. "GitGuardian") and select "Integrate any other application you don't find in the gallery (Non-gallery)". Finally, click on the "Create" button.
3. After a few seconds, you will be redirected to your newly created application. Click on "Set up single sign on" and choose the SAML sign-on method.
4. Now, you need to configure the Service Provider in Microsoft Entra ID. Click on Edit in the "Basic SAML Configuration" box. Use these values:
   • Identifier (Entity Id) field is filled with the SP Entity ID value on GitGuardian dashboard.
   • Reply URL (Assertion Consumer Service URL) field is filled with the ACS URL value on GitGuardian dashboard.
     Don't forget to click on "Save".
5. Now, some mappings need to be done. Select 'Edit' on the 'Attributes & Claims' box. Click on 'Add new claim'. Leave 'Namespace' empty and use these values:
   • Name: first_name + Source attribute: user.givenname
     Don't forget to click on "Save".
   • Name: last_name + Source attribute: user.surname
     Don't forget to click on "Save".
6. You also need to make sure that the Unique User Identifier (Name ID) claim is set to user.mail.
7. Then, setup how responses and assertions are signed: Select 'Edit' on the 'SAML Certificates' box and choose 'Sign SAML response and assertion' as Signing Option and 'SHA-256' as Signing Algorithm:
8. Now, you need to configure the Identity Provider in GitGuardian dashboard. Use these values:
   • Entity Id field is filled with the Microsoft Entra Identifier
   • Single Sign-On URL field is filled with the Login URL
   • X509 Cert field is filled with the certificate. Download the Base64 certificate, use cat and copy/paste the plaintext value.
9. Test your app configuration by clicking on "Test".
10. Important: Don't forget to reserve your email domain to enable automatic SSO discovery.

Duo

1. Configure an Authentication Source for Single Sign-On in the Duo Dashboard. Ensure that FirstName and LastName are provided as attributes as described in the Duo documentation.
2. From the "Applications" tab, click on "Protect an Application", and choose to protect a "Generic Service Provider" with "2FA with SSO hosted by Duo (Single Sign-On)"
3. Map the following from the Duo Generic Service Provider values into the GitGuardian dashboard:
   

Duo values	GitGuardian configuration
Entity ID	Entity ID
Single Sign-On URL	Single Sign On URL
Certificate contents	X509 Cert

4. Map the following from the GitGuardian dashboard into the Duo Generic Service Provider configuration:

Duo Service Provider configuration	GitGuardian values
Service Provider Entity ID	SP Entity id
Assertion Consumer Service	ACS URL

5. In the SAML Response section, add the following mapping in "Map attributes"

IdP Attribute	SAML Response Attribute
First Name	first_name
Last Name	last_name

6. Give the Service Provider configuration a recognizable name, such as "GitGuardian".
7. Save.
8. Important: Don't forget to reserve your email domain to enable automatic SSO discovery.

Keycloak

1. Navigate to "Realm Settings" under the "General" tab in Keycloak, and copy the 'SAML 2.0 Identity Provider Metadata'. For example: https://$YOUR_KEYCLOAK_DOMAIN/realms/master/protocol/saml/descriptor.

   

2. Go to the "Keys" tab, and click on the 'Certificate' button next to the RS256 algorithm. Copy the displayed certificate.

   

3. To configure the Identity Provider in the GitGuardian dashboard, use the following values:

   • The Entity Id field should be filled with the Keycloak SAML 2.0 Identity Provider Metadata URL, excluding /protocol/saml/descriptor from the end. Example: https://$YOUR_KEYCLOAK_DOMAIN/realms/master.
   • The Single Sign-On URL field should include the Keycloak SAML 2.0 Identity Provider URL, excluding /descriptor from the end. Example: https://$YOUR_KEYCLOAK_DOMAIN/realms/master/protocol/saml.
   • In the X509 Cert field, paste the certificate copied in the previous step.

4. To configure the "Client" (Service Provider) in Keycloak:

   • Navigate to the Clients menu and click on 'Create client'. Use the following values:
     • Set the Client type field to SAML.
     • Fill the Client ID field with the SP Entity ID from the GitGuardian dashboard.
   • Click on 'Next', then:
     • Fill the Home URL field with the URL of your GitGuardian dashboard. For example: https://dashboard.gitguardian.com (SaaS) or https://gitguardian.mycorp.local (Self-Hosted).
     • Fill the Valid Redirect URIs and Master SAML Processing URL fields with the ACS URL.

5. Click on 'Save', then configure these settings on the newly created client:

   • In 'SAML capabilities', set the Name ID Format to email.
   • Set Force POST Binding and Include AuthnStatement to ON.
   • In 'Signature and Encryption', set Sign documents and Sign assertions fields to ON.
   • Signature algorithm should be RSA_SHA256.
   • Set SAML signature key name to NONE.
   • In 'Logout settings', set Front Channel Logout to ON.
   • Click on 'Save'.
   • In the 'Keys' tab, set Client signature required to OFF.

   

6. Still in the same client, under the 'Client scopes' tab, edit the 'Dedicated scope and mappers for this client' and configure a new mapper for the first name:

   • Choose User Property as the Mapper Type.
   • The Name field should be firstName.
   • The Property field should be firstName.
   • Set the SAML Attribute Name to first_name and the SAML Attribute NameFormat to Basic.

7. For the last name, create a second mapper:

   • Again, select User Property for the Mapper Type.
   • The Name field should be lastName.
   • The Property field should be lastName.
   • Set the SAML Attribute Name to last_name and the SAML Attribute NameFormat to Basic.

   

8. In the "Client Scopes" tab, note the 'Assigned Default Client Scopes'. For example, role_list.

   

9. Edit the client scope(s) listed in the previous step by navigating to the "Client Scopes" menu. Go to the "Mappers" tab, edit the Role list mapper, and ensure the Single Role Attribute field is set to ON.

   

10. Finalize your setup by testing the SSO authentication using the Login URL provided in the GitGuardian dashboard SAML configuration page.

11. Important: Don't forget to reserve your email domain to enable automatic SSO discovery.

Generic procedure for SAML2-enabled IdP

1. Register GitGuardian on your Identity provider.

In order to integrate GitGuardian with your Identity Provider, you must first register GitGuardian (Service Provider) as an application on the IdP’s side. Follow these steps carefully:

1. Navigate to Settings > Authentication
2. Click on "Configure"

3. On your IdP:
   1. Fill in the SAML endpoint provided by GitGuardian (ACS url, SP Entity id)
   2. Fill in Email or EmailAddress as the primary identifier (Name ID format).
      Refer to our FAQ if this Name ID format is not available in your IdP.
   3. Set RSA_SHA256 for the signature algorithm, and SHA256 for the digest algorithm for your response.
      Some Identity Providers (IdPs) may require you to sign either the response message or the response assertions. GitGuardian provides the ability to specify this IdP behavior.
      Note that at least one of these, either the response message or the response assertions, must be signed.
   4. Configure first_name and last_name mapped attributes.

2. Register your IdP on GitGuardian’s side

Once GitGuardian is registered as an application on your IdP’s side, you need to provide your IdP metadata fields on GitGuardian (Service Provider side) in order to complete the integration:

1. While still on the Authentication config page of your workspace settings, complete the form with:
   • Entity Id [required]
   • Single Sign On Url [required]
   • Single Log Out Url [optional]
   • X509 certificate [required]
2. Submit the form to fully register the SAML integration.
3. The setup is complete. Your workspace will have a dedicated SSO login url for your collaborators to sign in using your IdP.

You can register this SSO login url on the IdP side to enable the SSO flow with one click directly in the IdP interface. However this IdP-Initiated flow carries a security risk and is therefore NOT recommended. Make sure you understand the risks before enabling IdP-initiated SSO.

Next Step

Don't forget to complete the Email domain reservation step above to enable automatic SSO discovery and prevent workspace fragmentation.

FAQ

How to verify that my SSO connection is working?

If you have not reserved an email domain, please remember your SSO login URL.

1. Make sure to know your login credentials, i.e., your email and password.
2. Log out of the application.
3. Go to the SSO login URL, and log in by selecting the SSO option.
   For additional security purpose, GitGuardian will ask you to submit your email and password to confirm your identity.

My Identity Provider (IdP) does not support "emailAddress" as the Name ID format. What do I do?

If your IdP does not support emailAddress as the Name ID format, please contact us. We will allow you to use unspecified as the Name ID format.

caution

When using unspecified as the Name ID format, you must ensure that you send the email addresses of your IdP users as an email_address attribute. This is mandatory, as email is the unique identifier that GitGuardian uses for its users.

I want to configure MFA for GitGuardian. What do I do?

Combining SSO with MFA is more secure than using a simple SSO connection.

Leverage the MFA feature provided by all the SSO providers we support. We strongly advise that you enable the Force SSO setting to ensure that through SSO authentication, MFA is applied to all users authenticating to GitGuardian.