Child pages
  • NameIdentifierMapping

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

...

During

...

the

...

execution

...

of

...

a

...

BrowserProfile,

...

when

...

the

...

user

...

authenticates

...

at

...

the

...

SSO

...

service,

...

the

...

IdentityProvider

...

typically

...

issues

...

the

...

user

...

a

...

special

...

type

...

of

...

NameIdentifier

...

called

...

a

...

ShibHandle

...

in

...

conjunction

...

with

...

the

...

authentication

...

assertion.

...

At

...

that

...

point,

...

the

...

!IdP

...

may

...

cache

...

the

...

identifier

...

so

...

it

...

can

...

subsequently

...

map

...

that

...

identifier

...

to

...

the

...

actual

...

principal

...

upon

...

request.

...

In

...

Shibboleth,

...

the

...

identifier

...

and

...

the

...

principal

...

are

...

represented

...

by

...

objects

...

of

...

type

...

SAMLNameIdentifier

...

and

...

LocalPrincipal

...

,

...

respectively:

...

}
Code Block
import org.opensaml.SAMLNameIdentifier;
import edu.internet2.middleware.shibboleth.common.LocalPrincipal;
{code}

 {{SAMLNameIdentifier}}  is an OpenSAML construct while  {{LocalPrincipal}}  implements  {{

SAMLNameIdentifier is an OpenSAML construct while LocalPrincipal implements java.security.Principal

...

.

...

As

...

users

...

enter

...

and

...

leave

...

the

...

system,

...

a

...

one-to-one

...

correspondence

...

between

...

SAMLNameIdentifier

...

and

...

LocalPrincipal

...

is

...

maintained

...

by

...

the

...

!IdP.

...

Interface NameIdentifierMapping

Shibboleth's

...

code

...

handling

...

of

...

this

...

mapping

...

is

...

based

...

on

...

the

...

NameIdentifierMapping

...

interface:

...

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

The

...

primary

...

methods

...

of

...

the

...

interface

...

are

...

getPrincipal

...

and

...

getNameIdentifier

...

,

...

which

...

represent

...

the

...

desired

...

mapping

...

between

...

LocalPrincipal

...

and

...

SAMLNameIdentifier

...

.

Class BaseNameIdentifierMapping

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

Code Block
package edu.internet2.middleware.shibboleth.common.provider;
public abstract class BaseNameIdentifierMapping implements NameIdentifierMapping;
{code}

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

h2. Class  {{PrincipalNameIdentifier}} 

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

{code}

BaseNameIdentifierMapping implements methods getId and getNameIdentifierFormat (which correspond to a pair of configuration options) but does not implement the methods getPrincipal and getNameIdentifier (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 principal of the same name.

Code Block
package edu.internet2.middleware.shibboleth.common.provider;
public class PrincipalNameIdentifier extends BaseNameIdentifierMapping;
{code}

The  {{PrincipalNameIdentifier}}  mapping is used whenever the principal name and the value of the  {{&lt;saml:NameIdentifier&gt;}}  element are identical.

h2. Class  {{X509SubjectNameNameIdentifierMapping}} 

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

{code}

The PrincipalNameIdentifier mapping is used whenever the principal name and the value of the <saml:NameIdentifier> element are identical.

Class X509SubjectNameNameIdentifierMapping

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

Code Block
package edu.internet2.middleware.shibboleth.common.provider;
public class X509SubjectNameNameIdentifierMapping extends BaseNameIdentifierMapping implements NameIdentifierMapping;
{code}

 {{X509SubjectNameNameIdentifierMapping}}  assumes the principal name is embedded in the DN.  In the  {{getPrincipal}}  method, the principal name is extracted from the DN by regular expression matching.

h2. Class  {{AQHNameIdentifierMapping}} 

Neither  {{PrincipalNameIdentifier}}  nor  {{X509SubjectNameNameIdentifierMapping}}  are very desirable in practice since they provide no privacy.  To ensure privacy, an opaque identifier called a ShibHandle 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}} :

{code}

X509SubjectNameNameIdentifierMapping assumes the principal name is embedded in the DN. In the getPrincipal method, the principal name is extracted from the DN by regular expression matching.

Class AQHNameIdentifierMapping

Neither PrincipalNameIdentifier nor X509SubjectNameNameIdentifierMapping are very desirable in practice since they provide no privacy. To ensure privacy, an opaque identifier called a ShibHandle 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 :

Code Block
package edu.internet2.middleware.shibboleth.common.provider;
public abstract class AQHNameIdentifierMapping extends BaseNameIdentifierMapping;
{code}

Two

...

important

...

classes

...

(

...

SharedMemoryShibHandle

...

and

...

CryptoShibHandle=

...

)

...

extend

...

=AQHNameIdentifierMapping

...

.

Class SharedMemoryShibHandle

The default implementation of NameIdentifierMapping is called SharedMemoryShibHandle :

Code Block
package edu.internet2.middleware.shibboleth.common.provider;
public class SharedMemoryShibHandle extends AQHNameIdentifierMapping implements NameIdentifierMapping;
{code}

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

h2. Class  {{CryptoShibHandle}} 

The most complicated implementation of  {{NameIdentifierMapping}}  is called  {{CryptoShibHandle}} :

{code}

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 :

Code Block
package edu.internet2.middleware.shibboleth.common.provider;
public class CryptoShibHandle extends AQHNameIdentifierMapping implements NameIdentifierMapping;
{code}

 {{CryptoShibHandle}}  concatenates an initialization vector, an HMAC, an expiration time, and a principal name, which is then encrypted, encoded and inserted into the  {{&lt;saml:NameIdentifier&gt;}}  element.  \(On the surface, an instance of  {{CryptoShibHandle}}  looks just like an ordinary ShibHandle.\)  Later the AA decodes and decrypts the value of the  {{&lt;saml:NameIdentifier&gt;}}  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 config options listed above.

h2. Class  {{NameMapper}} 

 {{NameMapper}}  incorporates all of the above \(except =X509SubjectNameNameIdentifierMapping=\) to produce a fully functional implementation:

{code}

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, an instance of CryptoShibHandle looks just like an ordinary ShibHandle.) Later the AA decodes and 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 config options listed above.

Class NameMapper

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

Code Block
package edu.internet2.middleware.shibboleth.common;
public class NameMapper;
{code}
							
 {{NameMapper}}  loads a default NameMapping element \(if no such element is defined in the !IdP config file idp.xml\).  The default mapping is  {{SharedMemoryShibHandle}}  with  {{handleTTL}}  set to 1800&nbsp;seconds.

 {{NameMapper}}  defines two new configuration options called  {{type}}  and  {{class}} .  Each NameMapping element in idp.xml must have exactly one of the  {{type}}  or  {{class}}  attributes.  A  {{type}}  attribute refers to one of the three aliases \(described below\).  A  {{class}}  attribute is the fully qualified class name of an implementation of  {{NameIdentifierMapping}} .

NameMapper loads a default NameMapping element (if no such element is defined in the !IdP config file idp.xml). The default mapping is SharedMemoryShibHandle with handleTTL set to 1800 seconds.

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