Authentication

Instabase supports a variety of user authentication methods including basic authentication, SAML-based single sign-on, and LDAP-based single sign-on. API authentication methods include AD FS integration and OAuth2.

Basic authentication

Instabase natively supports basic user authentication. Basic authentication is defined as registering and logging in with a username or email address and password.

When using basic authentication in your deployment, you can optionally enforce multi-factor authentication (MFA), using either SMS messages (texts) or an authenticator app as the secondary authentication method.

For details on adding and managing users, see the user management documentation. For details on configuring MFA, see the site settings documentation.

SAML authentication

Instabase supports security assertion markup language (SAML)-based authentication to manage access to your Instabase deployment. 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 deployment.

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

You can configure SAML authentication during installation or after installation. You can update your SAML connection at any time.

IdP configuration requirements

The SSO integration flow begins with registering Instabase as a service provider in your IdP. The app registration must include specific information and attributes (also called claims), outlined below. In addition, to complete your SAML configuration you must provide the IdP metadata XML, either as a file or as a link to where the XML is hosted.

App registration requirements

This table outlines suggested or required values to use when defining your app registration in your IdP. For reference, this table also provides 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 product UIs.

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.

You can also optionally use a groups attribute to map external groups in your IdP to Instabase groups. This mapping lets you leverage externally defined groups managed by the external IdP to manage account creation and group membership in Instabase. Upon user login, the user’s groups are sent as part of the redirect request back to Instabase, and the Instabase groups are synced accordingly. See the external group mappings documentation for additional information.

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

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

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.

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/abc123ABC123">
  <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIID... ...D4a8wA==</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://instabase.oktapreview.com/app/instabasedev123456_pysaml2example_1/abc123ABC123/sso/saml"/>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://instabase.oktapreview.com/app/instabasedev123456_pysaml2example_1/abc123ABC123/sso/saml"/>
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

Configure a SAML connection during installation

To configure a SAML connection during installation, you can either use the SAML configuration UI in the Instabase Installer or use the Installer SAML APIs.

For UI-based configuration, follow the instructions in the Instabase Installer guide.

For API-based configuration, follow the instructions in the Installer API documentation. Specifically, call the following APIs:

• Create SAML configuration: Creates the SAML configuration.

• (Optional) Upload IdP metadata XML: Uploads the IdP metadata XML file, if using local metadata access.

• Complete SAML configuration: Completes the SAML configuration connection.

  Note

  Only call the complete SAML configuration API after installation is complete.

Configure a SAML connection after installation

To configure a SAML connection after installation, use the Installer SAML APIs, following the instructions in the Installer API documentation. Specifically, call the following APIs:

• Create SAML configuration: Creates the SAML configuration.

• (Optional) Upload IdP metadata XML: Uploads the IdP metadata XML file, if using local metadata access.

• Complete SAML configuration: Completes the SAML configuration connection.

Update a SAML connection configuration

To update an existing SAML connection configuration, use the Installer SAML APIs, following the instructions in the Installer API documentation. Specifically, call the following APIs:

• Create SAML configuration: Creates the SAML configuration.

• (Optional) Upload IdP metadata XML: Uploads the IdP metadata XML file, if using local metadata access.

• Complete SAML configuration: Completes the SAML configuration connection.

Legacy SAML connection configuration

The preferred way to configure a SAML connection is to use the Installer SAML APIs or the Instabase Installer SAML configuration UI. The legacy method of applying Deployment Manager patches yourself is, however, still supported.

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"
           - name: SAML_OPTIONAL_ATTRIBUTES
             value: "groups,uid"
           - name: SAML_GROUPS_DELIMITER
             value: ""
           - name: SAML_SP_ENTITY_ID
             value: "http://instabase-dev.ib.com/account/sso/saml2"
           - name: SAML_SP_NAME
             value: "Instabase SP"
           - 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: api-server
         env:
           - name: AUTH_TYPE
             value: "saml"

LDAP authentication

Instabase supports Lightweight Directory Access Protocol (LDAP) as an authentication backend to manage access to Instabase. Use LDAP for single sign-on (SSO) to automatically allow new users to create accounts on the Instabase platform on initial login. Instabase does not support mapping of external LDAP groups into Instabase groups.

Configure environment variables

LDAP is configured on Instabase using environment variables on the webapp deployment.

1. Set the environment variables in the webapp.yml file in your deployment.

2. Restart the account-tservice service. The webapp service automatically restarts.

3. To acknowledge the change, log out and log back in to Instabase using your LDAP email and password.

LDAP environment variables

• AUTH_TYPE

  Set to LDAP.

  - name: AUTH_TYPE
    value: "ldap"
  

• LDAP_SERVER

  Default: 127.0.0.1. The URL or the IP address of the LDAP server.

  - name: LDAP_SERVER
    value: "<ldap_server_ip>"
  

• LDAP_PORT

  Default: 636. The port that provides LDAP connectivity to the LDAP_SERVER.

  - name: LDAP_SERVER
    value: "<ldap_server_port>"
  

• LDAP_PROTOCOL_VERSION

  Default: v3. The LDAP protocol version that is used for authentication.

  - name: LDAP_PROTOCOL_VERSION
    value: "v3"
  

• LDAP_TIMEOUT

  Default: 30. The number of seconds for the timeout for making LDAP queries.

  - name: LDAP_TIMEOUT
    value: "<ldap_query_timeout_secs>"
  

• LDAP_BASE_DN

  Default: none. A comma-separated sequence of relative Distinguished Names (DN) that define the path to the LDAP directory where the users for authentication are configured. For example, ‘ou=instabase,ou=apps,dc=example,dc=org'.

  - name: LDAP_BASE_DN
    value: "<ldap_base_dn>"
  

• LDAP_ENABLE_TLS

  • True - Enable TLS for connecting to LDAP server.
  • False - Default. Do not enable TLS connection.

  - name: LDAP_ENABLE_TLS
    value: "true"
  

• LDAP_IGNORE_TLS_CERT_VALIDATION

  • True - Ignore TLS client certificate validation.
  • False - Default. Respect TLS client certificate validation.

  - name: LDAP_IGNORE_TLS_CERT_VALIDATION
  value: "<use_tls_cert>"
  

• LDAP_CACERT_FILE

  Default: none. Path name of file that contains all trusted CA certificates that perform client side verification. Set to “/etc/secrets/ldap/cacerts” to use a pre-generated certificate.

  - name: LDAP_CACERT_FILE
    value: "<ldap_cacert>"
  

• LDAP_TRACE_LEVEL

  Default: 0. Sets the trace logging level provided by LDAP used to specify the amount of information being logged, used for debugging purposes. Accepted values are:

  • 0: No logging, default value.

  • 1: Only logging the method calls with arguments. Note that the arguments might include sensitive information.

  • 2: Logging the method calls with arguments and the complete results.

  • 9: In addition to method calls with arguments and complete results, includes logging the traceback of method calls.

  Warning

  Setting a non-zero value for this configuration can lead to logging of sensitive information such as passwords. This should be used only in development environments for debugging purposes. In addition, to enable a non-zero LDAP_TRACE_LEVEL, the LOG_LEVEL must also be set to DEBUG. If it is not, no LDAP trace level logs are emitted for security reasons.

  - name: LDAP_TRACE_LEVEL
    value: "<ldap_trace_level>"
  

• LDAP_USER_SEARCH_FILTER

  Default: none. The search filter that is used to look up an LDAP user in the LDAP base directory name (DN). Corresponds to the user name that the user enters for logging into Instabase.

  - name: LDAP_USER_SEARCH_FILTER
    value: "<ldap_user_search_filter>"
  

• LDAP_USER_ATTRIBUTE

  Default: none. LDAP attribute that determines the email address of the user for storing within Instabase. When a user logs in successfully, this value is updated in the Instabase database. For a search filter that leads to following search result, set to 'registeredAddress' like this example:

  [('cn=user123,dc=ldap,dc=example,dc=org',{'registeredAddress': ['user123@instabase.com']})]
  

  - name: LDAP_USER_ATTRIBUTE
    value: "<ldap_user_attribute_for_email>"
  

• LDAP_DELIMITER

  Default: "<>". Allow LDAP authentication to be performed against multiple nodes/directory in the LDAP tree. Set this param to define a delimiter input value for the following environment variables:

  • LDAP_BASE_DN: 'ou=users,o=ABC_Company<>ou=api,ou=apps,o=ABC_Company'

  • LDAP_USER_SEARCH_FILTER: '(&(objectclass=abcPerson)(cn={}))<>(&(objectclass=abcPerson)(cn={}))'

  • LDAP_USER_ATTRIBUTE: 'mail<>mail'

AD FS authentication

Instabase supports Active Directory Federation Services (AD FS) as an authentication backend to manage access to Instabase. AD FS can be used to authenticate inbound API calls to the Instabase platform for existing users—if the user does not already exist on Instabase, the API call will be denied.

Prerequisites

• Site admin privileges

• A standing and accessible AD FS server

• The access token returned by AD FS should contain the following information:

  • An audience claim

    • The value of this claim is used by Instabase to verify that a given access token is intended for Instabase.

    • The default field name of this claim is aud but your organization can use a different name. Instabase can be configured to use whichever claim field name your organization chooses to use.

  • A uid claim

    • The value of this claim is used by Instabase to identify which user initiated the API call. It must exactly match the username of the user initiating the API call. If your organization is using SAML (SSO), then this value must match the value of uid in the SAML response. See SAML authentication for more information.

    • The field name of this claim is determined by your organization. Instabase can be configured to use whichever claim name your organization chooses to use.

Configure Instabase for AD FS authentication

1. Go to Admin App > Site Settings > Configuration.

2. Scroll down to Active Directory Federation Services Configuration.

3. Under Authentication Server URI, provide the URI at which your AD FS server can be reached.

4. Under Audience Expected Value, provide the value of the audience claim Instabase can expect to find when inspecting AD FS access tokens.

   • For security reasons, this value should be specific to the Instabase environment.

   • Example value: https://instabase-dev.com or https://instabase-uat.com.

5. Optionally, under Audience Field Name, provide the name of the claim field name that will correspond to the audience value provided above. If this is left blank, the default value of aud will be used.

6. Under UID Field Name, provide the field name of the claim that will correspond to the UID, or username of the user making the API call.

Example

Let the following be a payload of an access token returned by an AD FS server found at https://sample-server.instabase.com:

{
  "aud": "https://instabase-sample.com",
  "primarysid": "A7654321",
  ...
}

The correct corresponding configuration will look like the following:

Calling an Instabase API with an AD FS access token

1. Retrieve an access token from the AD FS server

2. Add the access token as a Bearer Token to the Authorization field in the headers of the API call:

   {
       "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
   }
   

3. To tell Instabase to use the provided Bearer Token as an access token, add the following to the headers of the API call:

   {
       "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...",
       "ADFS-Authentication": "true"
   }