Configure Kerberos for BI Connector
On this page
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.
This
KRB5_CLIENT_KTNAME
must include the key for both the schema user and the BI Connector service user.
MongoDB Configuration
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> Important
Setting Constraints
security.gssapi.hostname
should match the value insecurity.gssapi.serviceName
.If you configured Active Directory to use constrained delegation, add
security.gssapi.constrainedDelegation
: true
to themongosqld
config file or authentication fails.
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
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
andmongos
instances are running MongoDB Enterprise.Configure your
mongod
andmongos
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
andmongosql2
.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 theKRB5_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 insecurity.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.