<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="authentication">

  <title>Authentication</title>

  <section id="basic-auth">
    <info>
      <link type="guide" xref="index#authentication" />
    </info>
    <title>Basic Authentication</title>
    <p>
      The MongoDB C driver supports challenge response authentication (sometimes known as <code>MONGODB-CR</code> through the use of MongoDB connection URIs.
      Simply provide the username and password as you would with an <code>HTTP URL</code> as well as the database to authenticate against via <code>authSource</code>.
    </p>
    <screen><code>mongoc_client_t *client = mongoc_client_new ("mongodb://user:password@localhost/?authSource=mydb");</code></screen>
    <p>For more information on connection string URIs, see <link href="http://docs.mongodb.org/manual/reference/connection-string/">Connection String URI</link>.</p>
  </section>

  <section id="kerberos">
    <info>
      <link type="guide" xref="index#authentication" />
    </info>

    <title>GSSAPI (Kerberos) Authentication</title>

    <p><code>GSSAPI</code> (Kerberos) authentication is available in the Enterprise Edition of MongoDB, version 2.4 and newer. To authenticate using <code>GSSAPI</code> you must first install the MongoDB C driver with SASL support. Make sure you run <code>kinit</code> before using the following authentication methods:</p>

    <screen><output style="prompt">$ </output><input>kinit mongodbuser@EXAMPLE.COM</input>
<output>mongodbuser@EXAMPLE.COM's Password:</output>
<output style="prompt">$ </output><input>klist</input>
<output>Credentials cache: FILE:/tmp/krb5cc_1000
        Principal: mongodbuser@EXAMPLE.COM

  Issued                Expires               Principal
Feb  9 13:48:51 2013  Feb  9 23:48:51 2013  krbtgt/EXAMPLE.COM@EXAMPLE.COM</output></screen>

    <p>Now authenticate using the MongoDB URI. <code>GSSAPI</code> authenticates against the <code>$external</code> virtual database so you do not have to specify a database in the URI:</p>

    <screen><code><![CDATA[mongoc_client_t *client;

client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@example.com/?authMechanism=GSSAPI");
]]></code></screen>

    <note style="tip"><p>The kerberos principal must be url encoded.</p></note>

    <p>The default service name used by MongoDB and the MongoDB C driver is <code>mongodb</code>. You can specify a custom service name with the <code>gssapiServiceName</code> option:</p>

    <screen><code><![CDATA[mongoc_client_t *client;

client = mongoc_client_new ("mongodb://mongodbuser%40EXAMPLE.COM@example.com/?authMechanism=GSSAPI&gssapiServiceName=myservicename");
]]></code></screen>

    <note style="warning"><p>Kerberos support is only provided in environments supported by the <code>cyrus-sasl</code> kerberos implementation. This currently limits support to UNIX-like environments.</p></note>

    <note style="info"><p>If you see an error such as <code>Invalid net address</code>, you might be behind a NAT (Network Address Translation) firewall. In this case, you might need to create a ticket that uses <code>forwardable</code> and <code>addressless</code> Kerberos tickets. This can be done by passing <code>-f -A</code> to <code>kinit</code>.</p><screen><output style="prompt">$ </output><input>kinit -f -A mongodbuser@EXAMPLE.COM</input></screen></note>

  </section>

  <section id="plain">
    <info>
      <link type="guide" xref="index#authentication" />
    </info>

    <title>SASL Plain Authentication</title>

    <p>MongoDB Enterprise Edition versions 2.5.0 and newer support the <code>SASL PLAIN</code> authentication mechanism, initially intended for delegating authentication to an LDAP server. Using the <code>SASL PLAIN</code> mechanism is very similar to <code>MONGODB-CR</code>. These examples use the <code>$external</code> virtual database for <code>LDAP</code> support:</p>

    <note style="warning"><p><code>SASL PLAIN</code> is a clear-text authentication mechanism. We strongly recommend that you connect to MongoDB using SSL with certificate validation when using the <code>PLAIN</code> mechanism:</p></note>

    <screen><code><![CDATA[mongoc_client_t *client;

client = mongoc_client_new ("mongodb://user:password@example.com/?authMechanism=PLAIN&authSource=$external");]]></code></screen>

    <note style="tip"><p>You must build MongoDB C driver with SASL support to use <code>SASL PLAIN</code> authentication.</p></note>
  </section>

  <section id="x509">
    <info>
      <link type="guide" xref="index#authentication" />
    </info>

    <title>X.509 Certificate Authentication</title>

    <p>The MONGODB-X509 mechanism authenticates a username derived from the distinguished subject name of the X.509 certificate presented by the driver during SSL negotiation. This authentication method requires the use of SSL connections with certificate validation and is available in MongoDB 2.5.1 and newer:</p>

    <screen><code><![CDATA[mongoc_client_t *client;
mongoc_ssl_opt_t ssl_opts = { 0 };

ssl_opts.pem_file = "mycert.pem";
ssl_opts.pem_pwd = "mycertpassword";
ssl_opts.ca_file = "myca.pem";
ssl_opts.ca_dir = "trust_dir";
ssl_opts.weak_cert_validation = false;

client = mongoc_client_new ("mongodb://x509_derived_username@localhost/?authMechanism=MONGODB-X509");
mongoc_client_set_ssl_opts (client, &ssl_opts);
]]></code></screen>

    <p><code>MONGODB-X509</code> authenticates against the <code>$external</code> database, so specifying a database is not required.</p>

    <note style="warning"><p>You must build MongoDB C driver with SSL support for X.509 authentication support.</p></note>

  </section>

</page>
