Authentication

Instabase supports login with password, SAML and LDAP. API authentication methods include AD FS integration and OAuth2.

Password authentication

Instabase natively supports basic authentication for users with a username/email and password.

  • To add users to your Instabase deployment and configure their access control, see User Management.

Multi-factor authentication using SMS (in certain countries) and Time-based One-time Password (TOTP) can be optionally configured if a communication service is available to send text messages. For example, Twilio.

SAML authentication

Instabase supports Setup Security Assertion Markup Language (SAML) as an authentication backend to manage access to Instabase. SAML can be used for single sign-on (SSO) to automatically allow new users to create accounts on the Instabase platform upon initial login. The deployment can also be optionally configured to map external SAML Active Directory (AD) groups to Instabase organizations and groups.

Instabase uses SP-initiated SSO authentication.

Prerequisites

  • A SAML provider: Supported integrations include Ping Federate and Okta.

  • A unique service provider: The SAML Admin needs to register Instabase as a service provider. This service provider registration enables the Instabase authentication module to use the SSO provided by SAML. Two fields are required:

    • entity-id: A unique identifier. Recommendation: <your Instabase URL>
    • entity-label: A label associated with the provider. Recommendation: InstabaseSP

  • SAML attributes: SAML Admins are required to set up attributes to send to Instabase as part of the SSO response:

    • email: a unique email address that maps to the user’s corporate email address.
    • uid: a unique UID that maps to the user’s corporate username. This uid is the user’s Instabase username.
      Note

      The uid and email combination must be unique among all users.

Metadata

After the SAML prerequisite parameters are defined, the SAML Admin must provide Instabase the metadata file required for authenticating with SAML.

The metadata values can be provided in a metadata.xml file or in a metadata-server endpoint.

For reference, this is an example of a metadata.xml from Okta.

<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 Instabase for SAML user creation

After the prerequisites are set up, specify the parameters in Deployment Manager patches during installation.

The following configuration parameters are required:

  • AUTH_TYPE: Set the authentication type as saml

  • SAML_SP_ENTITY_ID: The entity-id that was configured in SAML (<your Instabase URL>)

  • SAML_SP_NAME: The label associated with the Instabase entity in SAML (InstabaseSP)

  • SAML_REQUIRED_ATTRIBUTES: The required email, uid attributes provided to Instabase by SAML.

  • SAML_HTTP_ACS_URL: The URL where SAML provider redirects after the user successfully authenticates. For example https://<your Instabase URL>/account/sso/saml2.

  • SAML_HTTPS_ACS_URL: The URL where SAML provider redirects after the user successfully authenticates. For example, http://<your Instabase URL>/account/sso/saml2.

  • AUTH_PROVIDER: How SAML metadata is provided.

    • local - provide a local file path to the metadata.xml file mounted to webapp in the Instabase’s deployment

    • remote - provide a URL to the metadata.xml file hosted by the SAML provider metadata server

These are optional environment variables that rarely ever need to be changed from the existing defaults. If you are setting these, there may be a misconfiguration in your SAML application from your Service Provider (SP).

  • SAML_ALLOW_UNSOLICITED: For SP instances, if set to true, the SP will consume unsolicited SAML responses for which it has not sent a respective SAML Authentication Request. Default value is True.

  • SAML_AUTHN_REQUESTS_SIGNED: For SP instances, this is a boolean flag to indicate if the Authentication Requests sent by this SP should be signed by default. Default value is False.

  • SAML_LOGOUT_REQUESTS_SIGNED: Indicates if this entity will sign the Logout Requests originated from it. Default value is True.

  • SAML_WANT_ASSERTIONS_SIGNED: Boolean flag that indicates that the assertions contained within the response that is sent to this SP must be signed. Default value is True.

  • SAML_WANT_RESPONSE_SIGNED: Boolean flag that indicates that the Authentication Response to this SP must be signed. Default value is False.

For example, the patches to enable SAML via Deployment-Manager:

In webapp:

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"

And in api-server:

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

Remote provider authentication

If AUTH_PROVIDER is remote, configure the Instabase servers to read the data from the provided URI.

  • Set the following env vars in the patch:

             - name: AUTH_PROVIDER
           value: "remote"
         - name: AUTH_PROVIDER_URI
           value: "<the metadata uri>"

Local provider authentication

If AUTH_PROVIDER is local, configure Instabase to read the data from a metadata.xml file. The metadata.xml file is stored as a Kubernetes secret.

To configure the Instabase installation to read the data from the secret:

  1. Create the secret with the following parameters:

    • name: saml-metadata

    • namespace: the namespace where Instabase is running

    • file: metadata.xml

    The command to create the secret for Kubernetes is:

    kubectl create secret generic saml-metadata --from-file=./metadata.xml --namespace namespace

  2. After the secrets are set up, set the values of these env vars in the patch to pick up the secrets file:

             - name: AUTH_PROVIDER
           value: "local"
         - name: AUTH_PROVIDER_URI
           value: "/etc/secrets/saml/metadata.xml"

Create SAML group mappings

Instabase supports mapping external groups in the SAML provider into Instabase groups. This allows users to be managed by the external IdP. Upon user login, the user’s groups are sent as part of the re-direct request back to Instabase, and the Instabase groups are synced accordingly. Just-in-time creation of new user accounts, adding and removal of users to and from groups will all be handled as part of this process.

For instructions on how to set up these mappings, see External Group Mappings under Site Settings.

This step can be done only after the platform has been fully deployed.

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

Note

This document describes the process of configuring Instabase to use AS FS servers as a means of authentication. This document will not help in setting up the AD FS server itself. Furthermore, this document is only useful to organizations that have specifically deployed AD FS into their environment, not for users who are using Azure AD.

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 may 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 integration 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:

Sample AD FS Configuration Sample AD FS Configuration

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"
}