The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

MongoDB connector

MongoDB is an open source, high-performance, schema-free, document-oriented database written in the C++ programming language.

Installation and configuration

Download

Source

GIT

git clone git://github.com/UnitedID/shibboleth-idp-mongodb-connector.git

Tarballs

mongodb-connector-1.0.1-src.zip
mongodb-connector-1.0.1-src.tar.gz

Build from source

 $ mvn clean package

Binary

mongodb-connector-1.0.1-bin.zip
mongodb-connector-1.0.1-bin.tar.gz

Installation

Unpack mongodb-connector-1.0.1-bin.*.

cp mongodb-connector-1.0.1/lib/*.jar $IDP_INSTALL_DIR/lib

Configuration

Configure mongodb data connector

In $IDP_CONFIG_DIR/attribute-resolver.xml, add namespace and xsd schema to the root element:

xmlns:uid="http://dev.unitedid.org/NS/mongodb-connector
http://dev.unitedid.org/NS/mongodb-connector classpath:/schema/mongodb-connector.xsd
<resolver:AttributeResolver xmlns:resolver="urn:mace:shibboleth:2.0:resolver"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:pc="urn:mace:shibboleth:2.0:resolver:pc"
                   xmlns:ad="urn:mace:shibboleth:2.0:resolver:ad" xmlns:dc="urn:mace:shibboleth:2.0:resolver:dc"
                   xmlns:enc="urn:mace:shibboleth:2.0:attribute:encoder" xmlns:sec="urn:mace:shibboleth:2.0:security"
                   xmlns:uid="http://dev.unitedid.org/NS/mongodb-connector"
                   xsi:schemaLocation="urn:mace:shibboleth:2.0:resolver classpath:/schema/shibboleth-2.0-attribute-resolver.xsd
                                       urn:mace:shibboleth:2.0:resolver:pc classpath:/schema/shibboleth-2.0-attribute-resolver-pc.xsd
                                       urn:mace:shibboleth:2.0:resolver:ad classpath:/schema/shibboleth-2.0-attribute-resolver-ad.xsd
                                       urn:mace:shibboleth:2.0:resolver:dc classpath:/schema/shibboleth-2.0-attribute-resolver-dc.xsd
                                       urn:mace:shibboleth:2.0:attribute:encoder classpath:/schema/shibboleth-2.0-attribute-encoder.xsd
                                       urn:mace:shibboleth:2.0:security classpath:/schema/shibboleth-2.0-security.xsd
                                       http://dev.unitedid.org/NS/mongodb-connector classpath:/schema/mongodb-connector.xsd">

Also in $IDP_CONFIG_DIR/attribute-resolver.xml, add the mongodb connector

    <!-- ========================================== -->
    <!--      Data Connectors                       -->
    <!-- ========================================== -->

    <!-- Mongodb connector -->
    <resolver:DataConnector id="myMongo" xsi:type="uid:MongoDbDataConnector"
                            mongoDbName="your_database_name"
                            mongoCollection="your_collection_name">

      <!-- Database server to connect to, multiple entries allowed for use with master/slave or replica sets -->                      
      <uid:MongoHost host="server1.example.com" port="27017" />
      <!-- 
      <uid:MongoHost host="server2.example.com" port="27017" />
      <uid:MongoHost host="server3.example.com" port="27017" />
      -->

      <!-- The database query in JSON format -->
      <uid:QueryTemplate>
        <![CDATA[
            { 'username' : '$requestContext.principalName' }
        ]]>
      </uid:QueryTemplate>
      
      <!-- Example attribute mappings between a mongodb field to attributeID -->
      <!--
      <uid:AttributeMap mongoKey="username" attributeID="uid" />
      <uid:AttributeMap mongoKey="email" attributeID="mail" />
      -->
      <!-- Example how to map embedded HashMap fields to an attributeID -->
      <!--
      <uid:AttributeMap mongoKey="address">
        <uid:ValueMap mongoKey="address1" attributeID="homePostalAddress" />
        <uid:ValueMap mongoKey="zip" attributeID="postalCode" /> 
      </uid:AttributeMap>
      -->
    </resolver:DataConnector>

Next configure the <resolver:AttributeDefinition...> to depend on the new connector by
adding <resolver:Dependency ref="myMongo" />

    <resolver:AttributeDefinition xsi:type="ad:Scoped" id="eduPersonPrincipalName" scope="example.com" sourceAttributeID="uid">
        <resolver:Dependency ref="myMongo" />
        <resolver:AttributeEncoder xsi:type="enc:SAML1ScopedString" name="urn:mace:dir:attribute-def:eduPersonPrincipalName" />
        <resolver:AttributeEncoder xsi:type="enc:SAML2ScopedString" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" friendlyName="eduPersonPrincipalName" />
    </resolver:AttributeDefinition>

(Optional) Configure mongodb persistent ID connector mode

To use mongodb connector for both attribute release and computing persistent ID's two <resolver:DataConnector/>'s are required, one for each mode.

The mongodb persistent ID connector is compatible with computedID and storedID computed ID's.

In $IDP_CONFIG_DIR/attribute-resolver.xml, add the mongodb persistent ID connector

    <resolver:DataConnector id="myMongo2" xsi:type="uid:MongoDbDataConnector"
                            mongoDbName="your_database_name"
                            mongoCollection="shibpid">

      <!-- Resolver dependency needed to resolve 'uid' in sourceAttributeId -->
      <resolver:Dependency ref="myMongo" />

      <!-- Database server to connect to, multiple entries allowed for use with master/slave or replica sets -->                      
      <uid:MongoHost host="server1.example.com" port="27017" />
      <!-- 
      <uid:MongoHost host="server2.example.com" port="27017" />
      <uid:MongoHost host="server3.example.com" port="27017" />
      -->

      <!-- Salt needs to be at least 16 bytes long -->
      <uid:PersistentId generatedAttributeId="persistentID"
                        sourceAttributeId="uid"
                        salt="1234567890abcdefghijklmnopqrst" />
    </resolver:DataConnector>

Also in $IDP_CONFIG_DIR/attribute-resolver.xml, add an attribute definition for persistentID

    <resolver:AttributeDefinition xsi:type="ad:SAML2NameID" id="eduPersonTargetedID"
                                  nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" sourceAttributeID="persistentID">
        <resolver:Dependency ref="myMongo2" />
        <resolver:AttributeEncoder xsi:type="enc:SAML1XMLObject" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" />
        <resolver:AttributeEncoder xsi:type="enc:SAML2XMLObject" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" friendlyName="eduPersonTargetedID" />
    </resolver:AttributeDefinition>

Optional settings for the mongodb connector

cacheResults - Whether to use attribute cache. Accepted values are true or false. Defaults to false.

    <resolver:DataConnector id="myMongo" xsi:type="uid:MongoDbDataConnector"
                            mongoDbName="your_database_name"
                            mongoCollection="your_collection_name"
                            cacheResults="true">

mongoUser - Username used to authenticate against a specific database.

mongoPassword - Password used to authenticate against a specific database.

    <resolver:DataConnector id="myMongo" xsi:type="uid:MongoDbDataConnector"
                            mongoDbName="your_database_name"
                            mongoCollection="your_collection_name"
                            mongoUser="your_username"
                            mongoPassword="your_password">

Logging configuration

In $IDP_CONFIG_DIR/logging.xml, add logging configuration for the mongodb connector :

    <!-- Log mongodb connector related messages -->
    <logger name="org.unitedid.shibboleth" level="INFO" />

Deployment

Backup your IdP configuration before re-deploying the IdP web app

$IDP_INSTALL_DIR/install.sh

Limitations

Currently only support one level deep embedded documents.

Bugs and comments

Send bugs and comments to stefan@unitedid.org.