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 role​

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

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

SSO default role

If you selected "Member" as the default role 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 SAML2 app.
  2. You will land on this page, where you can set your app name.
    google start
  3. Now, you need to configure the Identity Provider in GitGuardian dashboard. Use these values:
    • Entity Id field is filled with the Identity Provider Issuer
    • Single Sign-On URL field is filled with the SSO URL
    • X509 Cert field is filled with the certificate. Download it, use cat and copy/paste the plaintext value. google idp config
  4. Click "Next". You will land on this page, where you can set the general information for your SAML app that users will see when logging in. google basic info
  5. Click "Next". You can now configure basic settings:
    • ACS URL field is filled with the ACS URL value on GitGuardian dashboard.
    • Entity ID field is filled with the SP Entity ID value on GitGuardian dashboard.
    • Signed Response must be checked
    • Name ID must be set to Basic Information + Primary Email
    • Name ID format must be set to EMAILgoogle config sp
  6. Now, some mappings need to be done, they are quite straightforward:
    • first_name is mapped the user first name
    • last_name is mapped the user last name google mappings
  7. Finish your app configuration by clicking on "Finish". google config end

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"
  4. First, fill the Application Callback URL with the ACS URL provided in GitGuardian dashboard. auth0 setup acs
  5. Then, in the settings, you can configure mappings, name identifier and message signatures. Don't forget to save your changes.
    Here are the settings we use:
{
  "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 certificate

auth0 idp settings

Azure AD​

  1. First, go to the Azure portal and select "Azure Active Directory". Then go to "Enterprise Application" and click on "New application" > "Create your own application".
  2. In the new panel that appeared 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 "Create" button. azuread start
  3. After few seconds, you will be redirected to your newly created application. Click on "Single Sign On" and choose SAML sign-on method. azuread select sso
  4. Now, you need to configure the Service Provider in Azure. Click on Edit in the first 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". azuread setup sp
  5. Now, some mappings need to done. Select 'Edit' on the 'User Attributes & Claim' box. Click on 'Add new claim'. Leave 'Namespace' empty and use these values:
    • Name: first_name + Source attribute: user.givenname
    • Name: last_name + Source attribute: user.surname Don't forget to click on "Save". azuread mappings
  6. You also need to make sure that the User ID claim is set to Email. azuread 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: azuread signature
  8. Now, you need to configure the Identity Provider in GitGuardian dashboard. Use these values:
    • Entity Id field is filled with the Azure AD 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. azuread 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, using the following configurations:
      • Fill the Client ID field with the SP Entity ID from the GitGuardian dashboard.
      • Set the Client Protocol field to saml.
      • The Client SAML Endpoint should be filled with the ACS URL from the GitGuardian dashboard.

  5. Edit the client you just created by clicking on Edit, and apply these settings:

    • Set Include AuthnStatement, Sign Documents, and Sign Assertions fields to ON.
    • Signature Algorithm should be RSA_SHA256.
    • Set SAML Signature Key Name to NONE.
    • Client Signature Required should be set to OFF.
    • Set Force POST Binding and Front Channel Logout to ON.
    • Name ID Format should be email.
    • For Valid Redirect URIs and Master SAML Processing URL, use the ACS URL.
    • The Base URL should be the URL of your GitGuardian dashboard. For example: https://dashboard.gitguardian.com (SaaS) or https://gitguardian.mycorp.local (Self-Hosted).

    keycloak clients

  6. Under the "Client scopes" tab, edit the 'Dedicated scope and mappers for this client' and configure a mapper for the first name:

    • Choose User Property as the Mapper Type.
    • 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 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 ?