Docs Menu
Docs Home
/
BI Connector
/
Authentication

Configure Kerberos for BI Connector

New in version 2.5.

The MongoDB Connector for BI supports Kerberos authentication for connecting BI tools and for the BI Connector's admin user authenticating with MongoDB.

The following section guides you through configuring the BI Connector to use Kerberos authentication with two of the most common use cases:

  • Windows/Linux client machines authenticating to Active Directory

  • macOS client machine authenticating to Linux KDC

If you have another use case, please contact MongoDB Support for assistance.

Important

The domain part of any username must be written in all capital letters. This part of the username corresponds to a Kerberos realm or Active Directory domain. It is case sensitive.

Active Directory Configuration

Example

Assuming this configuration:

  • Your name is Grace Smith.

  • Your Windows domain is named EXAMPLE.COM.

  • You are running your BI tool on a Windows host named BI.EXAMPLE.COM.

In Active Directory, you create three users:

  • For MongoDB: mongodb@EXAMPLE.COM

  • For BI Connector: mongosql@EXAMPLE.COM

  • For you: grace.smith@EXAMPLE.COM

Create an SPN for each service:

setspn.exe -S mongodb/BI.EXAMPLE.COM mongodb
setspn.exe -S mongosql/BI.EXAMPLE.COM mongosql

Note

The names can be anything you choose as long as you use them consistently throughout this setup.

Open the Active Directory Administrative Center and double-click on your MongoDB service user (mongodb).

Set the mongosql user to delegate for the mongodb user from the BI.EXAMPLE.COM host.

Note

Linux Schema User Authenticating to ADC

If you are authenticating a user from a Linux host and the schema user is using a keytab file instead of a password, the following is required in addition to creating the user in MongoDB:

  • Creating a UPN for the schema user.

  • Setting the KRB5_CLIENT_KTNAME environment variable to this user's keytab.

    This KRB5_CLIENT_KTNAME must include the key for both the schema user and the BI Connector service user.

MongoDB Configuration

  • Install MongoDB Enterprise and start it as a service.

  • Set the following options in the configuration file:

    net:
      bindIp: <fullHostnameOfBIConnector>
    setParameter:
      authenticationMechanisms: "GSSAPI"

    For more information, see net.bindIp, setParameter, and authenticationMechanisms.

  • Run mongod as the MongoDB Windows user you created in Active Directory.

  • Create a user on your MongoDB database with the appropriate roles to sample data.

BI Connector Configuration

Example

  • Your name is Grace Smith.

  • Your Windows domain is named EXAMPLE.COM.

  • You are running your BI tool on a Windows host named BI.EXAMPLE.COM.

On BI.EXAMPLE.COM:

  • Install MongoDB and MongoDB Connector for BI as services.

  • Edit your mongod.cfg file to resemble:

    systemLog:
      destination: "file"
      path: "c:\\data\\log\\mongod.log"
      verbosity: 2
    storage:
      dbPath: "c:\\data\\db"
    net:
      bindIp: BI.EXAMPLE.COM
    setParameter:
      authenticationMechanisms: "GSSAPI"

  • Log on to the mongo shell and create your BI Connector user.

    db.getSiblingDB("$external").createUser(
      {
        user: "grace.smith@EXAMPLE.COM",
        roles: [ { role: "readAnyDatabase", db: "admin" } ]
      }
    )

  • Edit your mongosqld.cfg file to resemble:

    systemLog:
      path: "c:\\data\\log\\mongosqld.log"
      logAppend: true
      logRotate: "reopen"
      verbosity: 3
    runtime:
      memory:
        maxPerStage: 102400
    net:
      bindIp: BI.EXAMPLE.COM
      port: 3306
    security:
      enabled: true
      defaultSource: "$external"
      defaultMechanism: "GSSAPI"
      gssapi:
        hostname: "BI.EXAMPLE.COM"
        serviceName: "mongosql"
    mongodb:
      net:
        uri: "mongodb://BI.EXAMPLE.COM/"
        auth:
          username: "grace.smith@EXAMPLE.COM"
          password: "abc123!"
          source: "$external"
          mechanism: "GSSAPI"
    processManagement:
      service:
        displayName: "MongoDB BI Connector"

  • Open Services.

  • Set MongoDB to Log on as: This account: mongodb@EXAMPLE.COM

  • Set MongoDB Connector for BI to Log on as: This account: mongosql@EXAMPLE.COM

  • Start the MongoDB and MongoDB Connector for BI services.

Note

Linux Schema User Authenticating to ADC

If you are authenticating a user from a Linux host and your schema user is going to use a username and password, the following is required:

Tip

See also:

To learn how to configure Active Directory to manage your MongoDB instance, see Configure MongoDB with Kerberos Authentication and Active Directory Authorization.

MongoDB Configuration

  • Make sure your mongod and mongos instances are running MongoDB Enterprise.

  • Configure your mongod and mongos instances to use Kerberos (GSSAPI) authentication.

  • Verify you set the following options the MongoDB configuration file:

    net:
      bindIp: <fullHostnameOfBIConnector>
    setParameter:
      authenticationMechanisms: "GSSAPI"

  • Create a keytab file on the KDC that has the needed Kerberos service principals for mongosql and mongosql2.

    Example

    mongosql/<fullHostnameOfBIConnector>@<KERBEROS_REALM>

BI Connector Configuration

  • Copy the keytab file you created for your MongoDB deployment to the same host that serves the BI Connector.

  • If your keytab does not use the default name (krb5.keytab), you must set the KRB5_KTNAME environment variable.

    Note

    The Kerberos implementation on macOS, Heimdal, does not support the default_keytab_name configuration setting, like MIT Kerberos does. You must set the KRB5_KTNAME environment variable.

  • If your Kerberos configuration file does not use the default name (krb5.conf), you must set the KRB5_CONFIG environment variable. (Heimdal also supports this environment variable.)

  • Add the following BI Connector authentication settings to your mongosqld configuration file:

    security:
      enabled: true
      defaultMechanism: "GSSAPI"
      defaultSource: "$external"
      gssapi:
        hostname: <host running mongosqld>
        serviceName: <name of mongosqld service>

    Note

    security.gssapi.hostname should match the value in security.gssapi.serviceName.

    For more information, see:

  • Add the following settings that the BI Connector will use to authenticate with MongoDB:

    mongodb:
     net:
       uri: "mongodb://<hostname and port of mongodb database>/"
       auth:
         username: <database username>
         password: <database password>
         source: "$external"
         mechanism: "GSSAPI"

    For more information, see:

Tip

Testing BI Connector with Kerberos on localhost

If you are testing Kerberos with a mongosqld running on a localhost, you must set net.unixDomainSocket.enabled to true in the mongosqld configuration file.