Skip to main content

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.

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


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


  • 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 -XPOST '{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:

nameThe name that will be used to refer to this configuration; Qwiet accepts alphanumeric characters, single dashes, and underscores
allow_implicit_invitesWhether 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_loginsWhether 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": "{orgId}/saml/your_saml_config/metadata",
"sp_login_url": "{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:

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

curl -XGET '{orgId}/saml/{your_saml_config}/metadata' \
--header 'Authorization: Bearer {accessToken}'

The SP metadata file Qwiet provides includes the entity ID and the ACS URL (the ACS URL will always be 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 -XPUT '{orgId}/saml_configs/{your_saml_config}' \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "testConfig",
"idp_metadata_url": "https://<yourIdpUrl>/.../metadata",
"default_org_role": "TEAM_DEFINED"

Payload parameters:

nameThe name of your SAML config
idp_metadata_urlThe URL to retrieve the IdP metadata
idp_metadataThe 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_roleThe 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 -XGET '{orgId}/saml_configs' \
    --header 'Authorization: Bearer {accessToken}'
  2. 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 -XGET '{orgId}/configuration' \
    --header 'Authorization: Bearer {accessToken}'
  3. Update your org's config to provide:

  • The desired SSO name

  • The SAML configuration that SSO name should be associated with

    curl -XPUT '{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": [
    sso_nameThe desired SSO name
    default_saml_configThe name of the SAML config to use as the default for this organization
    allowed_non_admin_auth_providersThe 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, clicking Login with SSO, and entering their credentials
  2. Visiting{sso_name} and providing their credentials