SAML integration and SSO

This article walks you through configuring a SAML 2.0 integration so that users can leverage single sign-on into Qwiet.

note

SAML integration is a premium feature; please contact your customer success or sales representative if you'd like to enable this feature.

Requirements

• You must be an org owner or a super admin.
• You must have the following information: SHIFTLEFT_ACCESS_TOKEN and SHIFTLEFT_ORG_ID. These values are available in the Qwiet Dashboard.

Notes

• Qwiet acts as the service provider (SP); you must bring your own identity provider (IdP).

• Configuring a SAML integration is a process that can only be done via API; we recommend some familiarity with working with APIs before proceeding.

  We offer a Postman Collection that includes the endpoints necessary for the integration; the relevant section of the Collection is called SAML. You may also need to work with the endpoints that allow you to manage your organization.

  We suggest creating an environment to store frequently used variables (including your Qwiet access token and org ID values).

The SAML integration

To create a SAML integration, you'll need to:

1. Create a SAML configuration for Qwiet preZero
2. Configure the identity provider (IdP) to use Qwiet as the service provider (SP)
3. Provide Qwiet with the metadata provided to you by your IdP
4. Test your configuration

Step 1: Create a SAML configuration in Qwiet

Create a SAML configuration for Qwiet via its API:

curl --location 'https://app.shiftleft.io/api/v4/orgs/{orgId}/saml_configs' \
--header 'Authorization: Bearer {AccessToken}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "testConfig",
    "allow_implicit_invites": true,
    "allow_idp_initiated_logins": true
}'

Payload parameters:

Parameters	Description
name	The name that will be used to refer to this configuration; Qwiet accepts alphanumeric characters, single dashes, and underscores
allow_implicit_invites	Whether any successfully identified SAML user can join; if true, they can join, otherwise new users can only join via invitation issued by Qwiet at the request of an admin
allow_idp_initiated_logins	Whether the IdP should be allowed to initiate the login process by submitting a SAMLRequest to Qwiet. If true, Qwiet includes idp_default_relay_state in the response. Default: false

Your response will look something like the following (be sure to make a note of the following response parameters since you'll need them at a later step: idp_default_relay_state, sp_metadata_url, and sp_login_url):

{
  "ok": true,
  "response": {
    "name": "testConfig",
    "idp_default_relay_state": "eyJ...In0=",
    "sp_metadata_url": "https://app.shiftleft.io/api/v2/organizations/{orgId}/saml/your_saml_config/metadata",
    "sp_login_url": "https://app.shiftleft.io/login/saml/{orgId}}/your_saml_config",
    "allow_implicit_invites": false,
    "sign_authn_requests": true,
    "allow_idp_initiated_logins": false
  }
}

Step 2: Configure the identity provider (IdP) to use Qwiet as the service provider

Follow the instructions provided by your identity provider (IdP) for setting up an integration that uses Qwiet as the service provider (SP). The following is a list of commonly used IdPs and their setup instructions:

• Okta
• Azure Active Directory
• OneLogin

Retrieve the service provider (SP) SAML metadata using the following API call:

curl --location 'https://app.shiftleft.io/api/v4/orgs/{orgId}/saml_configs' \
--header 'Authorization: Bearer {accessToken}'

The SP metadata file Qwiet provides includes the entity ID and the ACS URL (the ACS URL will always be https://app.shiftleft.io/api/v2/public/auth/saml/acs) values; make a note of these values, since the IdP will prompt you to provide these values during the setup process. The IdP may also ask you to upload this file.

At the end of the IdP configuration process, you'll be provided the Identity Provider metadata; get the URL used to retrieve this information since you'll need to provide it to Qwiet.

Step 3: Provide Qwiet with the metadata provided to you by your IdP

Update the SAML configuration you created in step 1 by making the following call to the Qwiet API:

curl --location --request PUT 'https://app.shiftleft.io/api/v4/orgs/{orgId}/saml_configs/{your_saml_config}' \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "idp_metadata_url": "https://<yourIdpUrl>/.../metadata",
    "idp_metadata": "<Optionally, insert the full XML metadata. Choose the idp_metadata_url or this XML input, not both>"
}'

Payload parameters:

Parameters	Description
name	The name of your SAML config
idp_metadata_url	The URL to retrieve the IdP metadata
idp_metadata	The raw XML metadata that can be provided instead of the URL indicated by idp_metadata_url; use either idp_metadata_url or idp_metadata, not both. Ensure that you've escaped all quotation marks with \ and remove all newline \n characters in your XML
default_org_role	The default role that new users in the org are given when joining via SAML. If not specified, this defaults to TEAM_DEFINED. Use the List roles endpoint to get information about the accepted roles.

If you're using Okta as your IdP, assign users to your Qwiet app. Otherwise, they will not be able to log in via SSO.

Step 4: Test the SAML configuration

Once you've completed the three steps above, you can test your configuration by logging in using one of the following methods:

• The IdP landing page;
• The service provider login URL (sp_login_url) that you saved in the first step of this tutorial

Step 5: Service provider-initiated single sign-on

The following steps show you how to implement service-provider-initiated single sign-on once you have a valid SAML configuration.

You must be an admin of Qwiet and your identity provider (IdP).

1. Get a copy of your current Qwiet SAML configuration:

curl --location 'https://app.shiftleft.io/api/v4/orgs/{orgId}/saml_configs' \
--header 'Authorization: Bearer {accessToken}'

1. Get a copy of your org's current configuration. In the following steps, you'll update your org config, but first, you should save a copy of the initial config just in case you overwrite a value and need to roll back:

curl --location 'https://app.shiftleft.io/api/v4/orgs/{orgId}/configuration' \
--header 'Authorization: Bearer {accessToken}'

1. Update your org's config to provide:

• The desired SSO name
• The SAML configuration that SSO name should be associated with

curl --location --request PUT 'https://app.shiftleft.io/api/v4/orgs/{orgId}/configuration' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
    "sso_name": "ssoName",
    "default_saml_config": "your_saml_config",
    "allowed_non_admin_auth_providers": [
        "{providerName}",
        "{providerName}",
        "{providerName}"
    ]
}'

Parameters	Description
sso_name	The desired SSO name
default_saml_config	The name of the SAML config to use as the default for this organization
allowed_non_admin_auth_providers	The types of login methods that can be used by the org's non-admin users. Accepted values: google, github, username-password, sl-saml2, gitlab, bitbucket, microsoft

Logging in

Users should be able to log in by:

1. Visiting app.shiftleft.io/login, clicking Login with SSO, and entering their credentials
2. Visiting app.shiftleft.io/sso/{sso_name} and providing their credentials