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 SSOTo 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) provisioningGitGuardian 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 roleBecause 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.
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.
#
Force SSOOnce 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.
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- First, go to the Google Admin Console, and create a new SAML2 app.
- You will land on this page, where you can set your app name.
- Now, you need to configure the Identity Provider in GitGuardian dashboard. Use these values:
Entity Id
field is filled with theIdentity Provider Issuer
Single Sign-On URL
field is filled with theSSO URL
X509 Cert
field is filled with the certificate. Download it, usecat
and copy/paste the plaintext value.
- 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.
- Click "Next". You can now configure basic settings:
ACS URL
field is filled with theACS URL
value on GitGuardian dashboard.Entity ID
field is filled with theSP Entity ID
value on GitGuardian dashboard.Signed Response
must be checkedName ID
must be set toBasic Information
+Primary Email
Name ID format
must be set toEMAIL
- Now, some mappings need to be done, they are quite straightforward:
first_name
is mapped the user first namelast_name
is mapped the user last name
- Finish your app configuration by clicking on "Finish".
#
Okta- First, go to https://$YOUR_OKTA_DOMAIN-admin.okta.com/admin/apps/add-app, then click on "Create New App".
- You will land on this page, where you can set the general information for your SAML app that users will see when
logging in.
- Click "Next". You can now configure basic settings:
Single sign on URL
field is filled with theACS URL
value on GitGuardian dashboard.Audience URI (SP Entity ID)
field is filled with theSP Entity ID
value on GitGuardian dashboard.Default RelayState
is left blankName ID format
must be set toEmailAddress
- Click on "Show Advanced Settings". Here make sure that both
Response
andAssertion Signature
are signed, and thatSignature
andDigest Algorithm
are respectively set toRSA-SHA256
andSHA256
. Assertions are not encrypted. - Now, some straightforward mapping needs to done:
first_name
is mapped the user first namelast_name
is mapped the user last name
- Finish your app configuration.
- 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 theIdentity Provider Issuer
Single Sign-On URL
field is filled with theIdentity Provider Single Sign-On URL
X509 Cert
field is filled with theX.509 Certificate
#
Auth0- First, go to your dashboard, select "Application", and click on "Create Application"
- Choose "Regular Web Applications" as type and a name.
- Go to your application addons. Click on "SAML2 Web App"
- First, fill the Application Callback URL with the ACS URL provided in GitGuardian dashboard.
- 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"}
- 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 theIssuer
valueSingle Sign-On URL
field is filled with theIdentity Provider Login URL
valueX509 Cert
field is filled with the plain text value of the certificate
#
Azure AD- 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".
- 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.
- After few seconds, you will be redirected to your newly created application. Click on "Single Sign On" and choose SAML sign-on method.
- 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 theSP Entity ID
value on GitGuardian dashboard.Reply URL (Assertion Consumer Service URL)
field is filled with theACS URL
value on GitGuardian dashboard.
Don't forget to click on "Save".
- 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".
- You also need to make sure that the User ID claim is set to Email.
- 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:
- Now, you need to configure the Identity Provider in GitGuardian dashboard. Use these values:
Entity Id
field is filled with theAzure AD Identifier
Single Sign-On URL
field is filled with theLogin URL
X509 Cert
field is filled with the certificate. Download the Base64 certificate, usecat
and copy/paste the plaintext value.
- Test your app configuration by clicking on "Test".
#
Duo- Configure an Authentication Source for Single Sign-On in the Duo Dashboard. Ensure that
FirstName
andLastName
are provided as attributes as described in the Duo documentation. - 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)"
- 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 |
- 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 |
- 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 |
- Give the Service Provider configuration a recognizable name, such as "GitGuardian".
- 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:
- Navigate to Settings > Authentication
- Click on "Configure"
- On your IdP:
- Fill in the SAML endpoint provided by GitGuardian (ACS url, SP Entity id)
- 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. - 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. - Configure
first_name
andlast_name
mapped attributes.
#
2. Register your IdP on GitGuardian’s sideOnce 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:
- 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]
- Submit the form to fully register the SAML integration.
- 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.
#
FAQMy 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.