SAML integration and SSO

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

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 ShiftLeft Dashboard.

Notes

  • ShiftLeft 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 ShiftLeft access token and org ID values).

The SAML integration

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

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

Step 1: Create a SAML configuration in ShiftLeft

Create a SAML configuration for ShiftLeft via its API:

curl -XPOST -d '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:

ParametersDescription
nameThe name that will be used to refer to this configuration; ShiftLeft 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 ShiftLeft 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 ShiftLeft. If true, ShiftLeft 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/my_saml_config/metadata",
"sp_login_url": "https://app.shiftleft.io/login/saml/{orgId}}/my_saml_config",
"allow_implicit_invites": false,
"sign_authn_requests": true,
"allow_idp_initiated_logins": false
}
}

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

Follow the instructions provided by your identity provider (IdP) for setting up an integration that uses ShiftLeft 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 GET 'https://app.shiftleft.io/api/v2/organizations/{orgId}/saml/my_saml_config/metadata' \
--header 'Authorization: Bearer {accessToken}'

The SP metadata file ShiftLeft 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 ShiftLeft.

Step 3: Provide ShiftLeft 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 ShiftLeft API:

curl -XPUT -d 'https://app.shiftleft.io/api/v4/orgs/{orgId}/saml_configs/{name}' \
--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:

ParametersDescription
nameThe name of your SAML config
idp_metadata_urlThe URL to retrieve the IdP metadata
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 ShiftLeft 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: (Optional) 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 ShiftLeft and your identity provider (IdP).

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

    curl GET '"https://app.shiftleft.io/api/v4/orgs/{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 GET '"https://app.shiftleft.io/api/v4/orgs/{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 -d '"https://app.shiftleft.io/api/v4/orgs/{orgId}/configuration' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "sso_name": "ssoName",
    "default_saml_config": "samlConfig",
    "allowed_non_admin_auth_providers": [
    "providerName"
    ]
    }'
    ParametersDescription
    sso_nameThe desired SSO name
    default_saml_configThe URL to retrieve the IdP metadata
    allowed_non_admin_auth_providersThe types of login methods that can be used by the org's non-admin users

Logging in

Users should be able login 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