Configure SAML-based SSO for SaaS environments

Instabase supports security assertion markup language (SAML)-based authentication to manage access to your Instabase environment. Using SAML-based single sign-on (SSO) lets you leverage your existing SSO identity provider (IdP) to automatically create new user accounts on the Instabase platform upon initial login. You can also optionally map existing groups configured in your IdP to groups in your Instabase environment.

Instabase uses service provider (SP)-initiated SSO authentication and supports IdPs that use SAML 2.0. Supported IdPs include:

• Microsoft Entra ID

• Active Directory Federation Services (AD FS)

• Auth0

• Okta

• PingFederate

Customer requirements

Enabling SAML on an Instabase SaaS environment involves working closely with your Instabase support team. While your Instabase support team performs configuration steps on the Instabase side, it’s your responsibility to review this documentation and ensure the following customer requirements are met:

1. At least one user in the environment is configured as a site admin.

2. You’ve created an app registration in your IdP according to the IdP configuration requirements. As part of this requirement, ensure that:

   • You can provide Instabase with the SP entity ID, SP name, and ACS URL values used in your app registration.

   • All user accounts in the environment have credentials that match the uid and email attributes defined in the app registration.

3. You’ve connected with Instabase support to discuss and apply the required SAML patches.

4. (Optional) You’ve configured external group mappings.

IdP configuration requirements

The SSO integration flow begins with you registering Instabase as a service provider in your IdP. The app registration must include specific information and attributes (also called claims), outlined below. After completing the app registration, you can provide the IdP metadata XML to Instabase as either an XML file or an endpoint directing to the XML metadata. Your Instabase representative then completes the SSO setup on the Instabase side.

App registration requirements

This table outlines the required values from your app registration that you must provide to your Instabase representative. The table outlines the suggested value for each field, and the name of the corresponding field in select IdPs. The accuracy of the Corresponding IdP field column is not guaranteed as Instabase doesn’t closely monitor changes to external products’ UI.

Attribute requirements

Your app registration must include the following attributes (also called claims), with the attribute’s name exactly matching the name written in the table below. For example, the attribute email cannot be substituted with a similar attribute, such as emailAddress.

IdP metadata XML requirements

Instabase supports two methods of referencing the IdP metadata XML:

• Local: Referencing a static metadata.xml file that is stored as a Kubernetes secret in the environment.

• Remote: Referencing a metadata-server endpoint where the XML file is hosted on the SAML provider metadata server.

After configuring your app registration and required claims, connect with your Instabase representative to provide your IdP metadata XML file or metadata-server endpoint. This table outlines where you can find the local or remote access value in select IdPs. The accuracy of this table is not guaranteed, as Instabase doesn’t closely monitor changes to external products’ UI.

Reference: Service provider configuration details

In SaaS environments, the service provider (Instabase backend) configuration is performed by Instabase. For reference and possible configuration troubleshooting, this section provides sample configurations and related backend information.

Service provider configuration parameters

The following configuration parameters are set when configuring SSO in the Instabase backend:

In addition to the parameters that must be manually defined according to the IdP-provided values, the following parameters are also set. These parameters are typically used with their default value. Refer to the default values to understand if an SP default value is conflicting with an IdP-defined value.

Sample service provider configurations

The following are sample configurations for how a SAML-based SSO configuration is defined in the Instabase backend. The configurations are in the form of patches that are applied using the Instabase Deployment Manager.

Two patches are applied: one that targets deployment-webapp and defines the SAML configuration parameters, and one that targets deployment-api-server to set the AUTH_TYPE as saml. Click to expand the sample patches.

apiVersion: apps/v1
kind: Deployment
spec:
 template:
   spec:
     containers:
       - name: webapp
         env:
           - name: AUTH_PROVIDER
             value: "remote"
           - name: AUTH_PROVIDER_URI
             value: "https://saml.ib.com/app/sso/saml/metadata"
           - name: AUTH_TYPE
             value: "saml"
           - name: SAML_REQUIRED_ATTRIBUTES
             value: "email,uid"
           - name: SAML_OPTIONAL_ATTRIBUTES
             value: "groups"
           - name: SAML_GROUPS_DELIMITER
             value: ""
           - name: SAML_SP_ENTITY_ID
             value: "http://instabase-dev.ib.com/"
           - name: SAML_SP_NAME
             value: "InstabaseSP"
           - name: SAML_HTTP_ACS_URL
             value: "https://instabase-dev.ib.com/account/sso/saml2"
           - name: SAML_HTTPS_ACS_URL
             value: "http://instabase-dev.ib.com/account/sso/saml2"
           - name: SAML_ALLOW_UNSOLICITED
             value: "True"
           - name: SAML_AUTHN_REQUESTS_SIGNED
             value: "False"
           - name: SAML_LOGOUT_REQUESTS_SIGNED
             value: "True"
           - name: SAML_WANT_ASSERTIONS_SIGNED
             value: "True"
           - name: SAML_WANT_RESPONSE_SIGNED
             value: "False"

apiVersion: apps/v1
kind: Deployment
spec:
 template:
   spec:
     containers:
       - name: webapp
         env:
           - name: AUTH_PROVIDER
             value: "local"
           - name: AUTH_PROVIDER_URI
             value: ""
           - name: AUTH_TYPE
             value: "saml"
           - name: SAML_REQUIRED_ATTRIBUTES
             value: "email,uid"
           - name: SAML_OPTIONAL_ATTRIBUTES
             value: "groups"
           - name: SAML_GROUPS_DELIMITER
             value: ""
           - name: SAML_SP_ENTITY_ID
             value: "http://instabase-dev.ib.com/"
           - name: SAML_SP_NAME
             value: "InstabaseSP"
           - name: SAML_HTTP_ACS_URL
             value: "https://instabase-dev.ib.com/account/sso/saml2"
           - name: SAML_HTTPS_ACS_URL
             value: "http://instabase-dev.ib.com/account/sso/saml2"
           - name: SAML_ALLOW_UNSOLICITED
             value: "True"
           - name: SAML_AUTHN_REQUESTS_SIGNED
             value: "False"
           - name: SAML_LOGOUT_REQUESTS_SIGNED
             value: "True"
           - name: SAML_WANT_ASSERTIONS_SIGNED
             value: "True"
           - name: SAML_WANT_RESPONSE_SIGNED
             value: "False"
         volumeMounts:
           - name: saml-metadata
             mountPath: /etc/secrets/saml
             readOnly: true
     volumes:
       - name: saml-metadata
         secret:
           secretName: saml-metadata

apiVersion: apps/v1
kind: Deployment
spec:
 template:
   spec:
     containers:
       - name: api-server
         env:
           - name: AUTH_TYPE
             value: "saml"