Docs Menu
Docs Home
/
Languages
/
Ruby
/
Ruby MongoDB Driver
/
Security
/
Authentication

Kerberos (GSSAPI)

On this page

  • Overview
  • Code Placeholders
  • Using GSSAPI Authentication in Your Application
  • Using Kerberos Authentication with Ruby MRI
  • Using Kerberos Authentication with JRuby
  • Kerberos Authentication Example
  • API Documentation

Overview

The Generic Security Services API (GSSAPI) authentication mechanism allows you to use your principal name to authenticate to a Kerberos service. You can use this mechanism only when authenticating to MongoDB Enterprise Advanced.

Code Placeholders

The code examples on this page use the following placeholders:

  • <username>: LDAP username.

  • <hostname>: Network address of your MongoDB deployment.

  • <port>: Port number of your MongoDB deployment. If you omit this parameter, the driver uses the default port number (27017). Specifying a port number is optional when connecting to a MongoDB Atlas cluster.

  • <authentication_db>: MongoDB database that contains the user's LDAP credentials. If you omit this parameter, the driver uses the default database (admin).

To use the code examples on this page, replace these placeholders with your own values.

Using GSSAPI Authentication in Your Application

To configure MongoDB Server to use Kerberos, see the MongoDB Server Kerberos documentation.

To use the Kerberos authentication mechanism with the Ruby driver, you must install and load the mongo_kerberos library. To do so, add the following lines to your Gemfile:

gem 'mongo', '~> 2'
gem 'mongo_kerberos', '~> 2'

Then, add the following lines to your application code:

require 'mongo'
require 'mongo_kerberos'

Note

When using Kerberos authentication, you must specify the fully qualified domain name (FQDN) of the host.

The following sections describe how to use Kerberos authentication with Ruby MRI and JRuby.

Using Kerberos Authentication with Ruby MRI

If you're using Kerberos authentication with Ruby MRI, you must perform the following steps:

  • Establish a Kerberos session on the driver. The driver uses this session to prove the user's identity to the server.

  • You must ensure that the host system is configured for Kerberos authentication. To learn more about configuring the host system to use Kerberos, see the Kerberos documentation or your operating system documentation for details.

Use the kinit utility to establish a Kerberos session.

Using Kerberos Authentication with JRuby

If you're using Kerberos authentication with JRuby, you can externally establish the Kerberos session to the driver by using the process described above for MRI. You can also provide the path to a keytab file by storing the configuration in the java.security.auth.login.config system property. You must also configure the Java Runtime Environment to use Kerberos. To learn more, see the MongoDB Java Driver Kerberos documentation for more information.

Kerberos Authentication Example

Select the Connection String or Client Options tab to see the corresponding syntax for connecting to MongoDB with Kerberos authentication:

client = Mongo::Client.new("mongodb://<username>@<hostname>[:<port>]/<authentication_db>?authMechanism=GSSAPI")
client = Mongo::Client.new(['<hostname>[:<port>]'],
                           auth_mech: :gssapi,
                           user: '<username>')

Note

If you use a connection string to connect to MongoDB, ensure that you percent-encode any special characters that appear in the username.

API Documentation

To learn more about any of the methods or types discussed on this page, see the following API documentation:

Back

LDAP (PLAIN)

Next

Data Formats