Shibboleth Developers

[Tom Scavo <>]

Many thanks to Scott for helping us work through this problem.  There
are two possible solutions on the table: define a custom format or
implement a "MappingManager" that essentially allows multiple
NameMapping elements per format.  We're still considering our options
(it's always good to have options :).

Attached is a summary of existing Shibboleth NameIdentifier mappings
and a corresponding class diagram.  Perhaps others might find this
documentation useful.

Tom
(for the GridShib Team)

On Thu, 17 Mar 2005 20:48:48 -0600, Von Welch 
<>
 wrote:
> 
> My take on this is that there are two conceptual classes of X509
> NameMappers:
> 
>  -Those that map DNs which can be algorithmically mapped to the the
> local Principal name. These DNs were most probably issued by the IdP
> itself.
> 
>  -Those that map DNs which cannot be algorithmically mapped to the
> local Principal name. These were most probably issued by a CA not
> associated with the IdP. In this case you need some sort of
> administratively configured mapping.
> 
> The Grid will fall into the second category for the forseeable
> future. We will develop a mapp that acts as described for that
> category.
> 
> As pointed out we will run into problems if we run into a IdP that
> needs to do both types of mappings, as despite the fact the names are
> the same format, they really are different types of names. In this
> case, we'll dig in then and write a wrapper as Scott suggests.
> 
> Von
> 
> Tom Scavo writes (19:49 March 16, 2005):
>  > Okay, now I'm following you.  In fact, Von suggested a similar "super
>  > mapping" concept earlier today.
Shibboleth NameIdentifier Mappings

During the execution of a browser SSO profile, when the user authenticates at 
the SSO service, the IdP typically issues the user an opaque handle along 
with the authn assertion.  At that point, the IdP caches the identifier so it 
can subsequently map that identifier to the actual principal upon request.

In Shibboleth, the principal and identifer are represented by objects of type 
AuthNPrincipal and SAMLNameIdentifier, respectively:

import org.opensaml.SAMLNameIdentifier;
import edu.internet2.middleware.shibboleth.common.AuthNPrincipal;

As users enter and leave the system, a one-to-one correspondence between 
AuthNPrincipal and SAMLNameIdentifier is maintained by the IdP.  
AuthNPrincipal is an OpenSAML construct while AuthNPrincipal implements 
java.security.Principal.

Interface NameIdentifierMapping

Shibboleth's code handling of this mapping is based on the 
NameIdentifierMapping interface:

package edu.internet2.middleware.shibboleth.common;
public interface NameIdentifierMapping {
  public String getId();
  public URI getNameIdentifierFormat();
  public AuthNPrincipal getPrincipal(SAMLNameIdentifier nameId, 
ServiceProvider sp, IdentityProvider idp);
  public SAMLNameIdentifier getNameIdentifierName(AuthNPrincipal principal, 
ServiceProvider sp, IdentityProvider idp);
  public void destroy();
}

The primary methods of the interface are getPrincipal and 
getNameIdentifierName, which represent the desired mapping between 
AuthNPrincipal and SAMLNameIdentifier.

Class BaseNameIdentifierMapping

The abstract class BaseNameIdentifierMapping is the superclass of all 
implementations of the NameIdentifierMapping interface:

package edu.internet2.middleware.shibboleth.common;
public abstract class BaseNameIdentifierMapping implements 
NameIdentifierMapping;

BaseNameIdentifierMapping implements methods getId and 
getNameIdentifierFormat (which correspond to a pair of configuration options) 
but does not implement the methods getPrincipal and getNameIdentifierName 
(which are left to subclasses).

Class PrincipalNameIdentifier

The simplest implementation of NameIdentifierMapping is 
PrincipalNameIdentifier, which maps the value of the <saml:NameIdentifier> 
element directly to a local Shib principal of the same name.

package edu.internet2.middleware.shibboleth.hs.provider;
public class PrincipalNameIdentifier extends BaseNameIdentifierMapping;

The PrincipalNameIdentifier mapping is used whenever the principal name and 
the value of the <saml:NameIdentifier> element are identical.  This approach 
provides no anonymity, however, and may raise privacy issues in some 
scenarios.

Class X509SubjectNameNameIdentifierMapping

Another implementation of NameIdentifierMapping called 
X509SubjectNameNameIdentifierMapping was developed for e-authentication 
conformance testing:

package edu.internet2.middleware.shibboleth.hs.provider;
public class X509SubjectNameNameIdentifierMapping extends 
BaseNameIdentifierMapping implements NameIdentifierMapping;

X509SubjectNameNameIdentifierMapping assumes the principal name is embedded 
in the DN.  The principal name is extracted from the DN by regular expression 
matching.

Class AQHNameIdentifierMapping

Neither PrincipalNameIdentifier nor X509SubjectNameNameIdentifierMapping are 
very useful in practice since they provide no privacy.  To ensure privacy, an 
opaque identifier called a handle is used.  Shibboleth handles are transient, 
that is, they have a relatively short lifetime.  The lifetime of a Shibboleth 
handle is governed by a configuration option called handleTTL (handle 
time-to-live), which is a member of the abstract class 
AQHNameIdentifierMapping:

package edu.internet2.middleware.shibboleth.hs.provider;
public abstract class AQHNameIdentifierMapping extends 
BaseNameIdentifierMapping;

Two important classes (SharedMemoryShibHandle and CryptoShibHandle) extend 
AQHNameIdentifierMapping.

Class SharedMemoryShibHandle

The default implementation of NameIdentifierMapping is called 
SharedMemoryShibHandle:

package edu.internet2.middleware.shibboleth.hs.provider;
public class SharedMemoryShibHandle extends AQHNameIdentifierMapping 
implements NameIdentifierMapping;

SharedMemoryShibHandle, the Shibboleth workhorse implementation of 
NameIdentifierMapping, defines a memory cache that is maintained as handles 
are generated or expired.

Class CryptoShibHandle

The most complicated implementation of NameIdentifierMapping is called 
CryptoShibHandle:

package edu.internet2.middleware.shibboleth.hs.provider;
public class CryptoShibHandle extends AQHNameIdentifierMapping implements 
NameIdentifierMapping;

CryptoShibHandle concatenates an initialization vector, an HMAC, an 
expiration time, and a principal name, which is then encrypted, encoded and 
inserted into the <saml:NameIdentifier> element.  (On the surface, the 
encrypted value looks just like an ordinary Shibboleth handle.)  Later the AA 
decrypts the value of the <saml:NameIdentifier> element to recover the 
principal name.  No caching is required in this case.

CryptoShibHandle presupposes a number of configuration options:

  + KeyStorePath (required)
  + KeyStorePassword (required)
  + KeyStoreKeyAlias (required)
  + KeyStoreKeyPassword (required)
  + KeyStoreType (optional)
  + Cipher (optional)
  + MAC (optional)

Reasonable defaults are provided for the optional configuration options 
listed above.

Class NameMapper

Class NameMapper incorporates all of the above (except 
X509SubjectNameNameIdentifierMapping) to produce a fully functional 
implementation:

package edu.internet2.middleware.shibboleth.common;
public class NameMapper;

The NameMapper class pre-registers three mappings:

  Alias                     Class
  -------------------------------------------------
  CryptoHandleGenerator     CryptoShibHandle
  SharedMemoryShibHandle    SharedMemoryShibHandle
  Principal                 PrincipalNameIdentifier
  -------------------------------------------------

An alias is used as the value of the type attribute in a NameMapping element 
(see below).

NameMapper also loads a default NameMapping element (if no such element is 
defined in origin.xml).  The default mapping is SharedMemoryShibHandle with 
handleTTL set to 1800 seconds.

NameMapping defines two new configuration options called type and class.  
Each NameMapping element in origin.xml must have exactly one of the type or 
class attributes.  A type attribute refers to one of the three aliases above. 
 A class attribute is the fully qualified class name of an implementation of 
NameIdentifierMapping.

Element NameMapping

A NameMapping element in origin.xml calls out the mappings recognized by any 
given deployment.  Only one NameMapping element per format is allowed.  Some 
examples are listed below:

<!-- SharedMemoryShibHandle configuration (default) -->
<NameMapping
  xmlns="urn:mace:shibboleth:namemapper:1.0"
  id="..."
  format="urn:mace:shibboleth:1.0:nameIdentifier"
  type="SharedMemoryShibHandle"
  handleTTL="1800"/>

<!-- CryptoShibHandle configuration -->
<NameMapping
  xmlns="urn:mace:shibboleth:namemapper:1.0"
  id="..."
  format="urn:mace:shibboleth:1.0:nameIdentifier"
  type="CryptoHandleGenerator"
  handleTTL="1800"/>

<!-- PrincipalNameIdentifier configuration (test) -->
<NameMapping
  xmlns="urn:mace:shibboleth:namemapper:1.0"
  id="..."
  format="urn-x:test:NameIdFormat1"
  type="Principal"/>

<!-- X509SubjectNameNameIdentifierMapping configuration (e-auth) -->
<NameMapping
  xmlns="urn:mace:shibboleth:namemapper:1.0"
  id="..."
  format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName"
  
class="edu.internet2.middleware.shibboleth.hs.provider.X509SubjectNameNameIdentifierMapping"/>

<!-- custom configuration (e.g.) -->
<NameMapping
  xmlns="urn:mace:shibboleth:namemapper:1.0"
  id="..."
  format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName"
  class="edu.uiuc.ncsa.shibboleth.plugin.MappingManager">
  <NameMapping
    id="..."
    format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName"
    
class="edu.internet2.middleware.shibboleth.hs.provider.X509SubjectNameNameIdentifierMapping"/>
  <NameMapping
    id="..."
    format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName"
    
class="edu.uiuc.ncsa.shibboleth.plugin.X509SubjectNameNameIdentifierMapping"/>
</NameMapping>

In this case, the MappingManager invokes each of the nested mappings (in 
order) until the mapping succeedes.

For example, suppose an attribute query is sent to the AA with the following 
NameIdentifier element:

<saml:NameIdentifier
  Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName">
  <!-- insert X.509 Subject DN here -->
</saml:NameIdentifier>

The AA consults origin.xml and finds a NameMapping element such as the last 
one above.  Since the value of the Format attribute of the NameIdentifier 
element matches the value of the format attribute of the containing 
NameMapping element, the AA invokes the MappingManager as given by the class 
attribute.  The MappingManager then applies each of the nested mappings in 
turn.

GridShib
March 2005

Attachment: shib-NameIdMapping.doc
Description: MS-Word document