Skip to main content
Sign Up

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:

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.

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.

SSO default access level

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.

SSO All-incidents team default membership setting

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.

SSO force sso

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.

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.
    google start
  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. google idp config
  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 Emailgoogle config sp
  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 google mappings
  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.

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. okta general
  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 EmailAddressokta basic settings
  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. okta advanced settings
  5. Now, some straightforward mapping needs to done:
    • first_name is mapped the user first name
    • last_name is mapped the user last name okta mappings
  6. Finish your app configuration. okta config end
  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 Certificateokta setup instructionsokta idp_settings

Auth0​

  1. First, go to your dashboard, select "Application", and click on "Create Application"
  2. Choose "Regular Web Applications" as type and a name. auth0 create app
  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. auth0 setup acs
  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"
}
  1. 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.

auth0 idp settings

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. entra-id start
  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. entra-id select sso
  4. Now, you need to configure the Service Provider in Azure. 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". entra-id setup sp
  5. Now, some mappings need to 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". entra-id mapping first_name
    • Name: last_name + Source attribute: user.surname
      Don't forget to click on "Save". entra-id mapping last_name
  6. You also need to make sure that the Unique User Identifier (Name ID) claim is set to user.mail. entra-id userid
  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: entra-id signature
  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. entra-id idp config
  9. Test your app configuration by clicking on "Test".

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)" duo create app
  3. Map the following from the Duo Generic Service Provider values into the GitGuardian dashboard:
Duo valuesGitGuardian configuration
Entity IDEntity ID
Single Sign-On URLSingle Sign On URL
Certificate contentsX509 Cert
  1. Map the following from the GitGuardian dashboard into the Duo Generic Service Provider configuration:
Duo Service Provider configurationGitGuardian values
Service Provider Entity IDSP Entity id
Assertion Consumer ServiceACS URL
  1. In the SAML Response section, add the following mapping in "Map attributes"
IdP AttributeSAML Response Attribute
First Namefirst_name
Last Namelast_name

duo attribute mapping

  1. Give the Service Provider configuration a recognizable name, such as "GitGuardian".
  2. Save.

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.

    keycloak realm endpoint

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

    keycloak realm 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.

    keycloak clients

  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.

    keycloak mappers

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

    keycloak client scopes

  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.

    keycloak client scopes Single Role Attribute

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

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.

SSO Service provider info

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. SSO IdP info
  3. The setup is complete. Your workspace will have a dedicated SSO login url for your collaborators to sign in using your IdP. SSO login url

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.

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.

SSO NameId unspecified and email_address attribute

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.

Something we didn’t cover?

See our Roadmap

Subscribe on GitHub

Submit a request

API status

How can I help you ?