Configure Kerberos for BI Connector

On this page

Active Directory Configuration

MongoDB Configuration
BI Connector Configuration
MongoDB Configuration
BI Connector Configuration

This version of the documentation is archived and no longer supported. View the current documentation instead.

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

Make sure you have a domain configured.
Create a user for MongoDB on the domain you created.
Create a user for MongoSQL on the domain you created.
Register an SPN for the MongoDB Service.
Register an SPN for the MongoSQL Service.
Enable delegation for your MongoSQL Service user.

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.

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

Install the BI Connector as a service.
Launch mongosqld as the MongoSQL Windows user you created in Active Directory.
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:

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:

Setting mongodb.net.auth.username to the schema user's UPN.
Setting mongodb.net.auth.password to no value.

Tip

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.

Important

Active Directory Configuration

Example

Note

Note

Linux Schema User Authenticating to ADC

MongoDB Configuration

BI Connector Configuration

Note

Example

Note

Linux Schema User Authenticating to ADC

Tip

See also:

MongoDB Configuration

Example

BI Connector Configuration

Note

Note

Tip

Testing BI Connector with Kerberos on localhost