Skip to main content

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

In order to avoid being blocked out in case of an SSO malfunction, the force SSO feature does not apply to the Owner of the workspace. The Owner of the workspace will always be able to log in with email/password.

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.

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#

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