The German ID card Login Handler supports the auhentication via the new German ID card (nPA) using the eID-Service provided by the Bundesdruckerei in Berlin, Germany.
In order to use this login handler, you will need to become a "Diensteanbieter" as described here: http://www.personalausweisportal.de/DE/Diensteanbieter_werden/diensteanbieter_node.html.
As a "Diensteanbieter" you will have the keys and a "Berchtigungszertifikat" for actually reading user attributes from the ID-Card.

You cannot use this Login Handler without being a "Diensteanbieter"!

Updating an existing IdP installation and configuration

Download the German ID card login handler

# Pre-compiled :
cd $IDP_INSTALL_DIR/lib
wget <<URL will be available shortly>>

Configuration

Web application

Gerenal settings

Enable the the German ID card login servlet in web.xml by adding the following snippet:

<!-- Servlet for doing German ID card authentication -->
<servlet>
    <servlet-name>NPAAuthHandler</servlet-name>
    <servlet-class>com.securedimensions.shibboleth.idp.authn.provider.NPAAuthServlet</servlet-class>
    
    <init-param>
        <param-name>nPASigningKeyPath</param-name>
        <param-value>path to the private key that should be used for signing the AuthnRequest</param-value>
    </init-param>
    
    <init-param>
        <param-name>nPASigningKeyPassword</param-name>
        <param-value>password for the private key above</param-value>
    </init-param>
    
    <init-param>
        <param-name>nPAEncryptionCrtPath</param-name>
        <param-value>path to the certificate (containing the public key) for encrypting the AuthnRequest nPA extension</param-value>
    </init-param>
    
    <init-param>
        <param-name>nPASignatureCrtPath</param-name>
        <param-value>path to the certificate (containing the public key) for verifying the digital signature on the received Assertion</param-value>
    </init-param>
    
    <init-param>
        <param-name>nPADecryptionKeyPath</param-name>
        <param-value>path to the private key used for decrypting the (encrypted) Assertion received</param-value>
    </init-param>
    
    <init-param>
        <param-name>nPADecryptionKeyPassword</param-name>
        <param-value>password for the private key above</param-value>
    </init-param>
    
    <init-param>
        <param-name>nPAIdentifier</param-name>
        <param-value>The identifier as a "Diensteanbieter"</param-value>
    </init-param>
    
    <init-param>
        <param-name>nPADestination</param-name>
        <param-value>The eID-Service URL endpoint provided by the Bundesdruckerei</param-value>
    </init-param>
    
    <init-param>
        <param-name>nPAACSUrl</param-name>
        <param-value>https://<your server name/>/idp/Authn/nPA</param-value>
    </init-param>

    <!-- nPA Attributes to be requested -->
  
</servlet>

<servlet-mapping>
    <servlet-name>NPAAuthHandler</servlet-name>
    <url-pattern>/Authn/nPA</url-pattern>
</servlet-mapping>

Attribute settings

You need to configure the Login Handler which Attributes are to be requested. This can
be achieved by including them as init-param elements. The param-name is the name of the
attribute to be requested, matching exactly (case-sensitive) the definition provided by the
Bundesdruckerei (available for "Diensteanbieter"). The param-value represents the required
attribute (true or false). The following example enable the Login Handler to request the
attributes "GivenNames" as optional and "FamilyNames" as required:

<init-param>
  <param-name>GivenNames</param-name>
  <param-value>false</param-value>
</init-param>

<init-param>
  <param-name>FamilyNames</param-name>
  <param-value>true</param-value>
</init-param>

Do not forget to update the idp.war file with the modified web.xml file as described below!

Handler configuration

In $IDP_CONFIG_DIR/handler.xml, add the xsd schema in the
<ProfileHandlerGroup> :

<ph:ProfileHandlerGroup
xmlns:ph="urn:mace:shibboleth:2.0:idp:profile-handler"
xmlns:npa="urn:com:securedimensions:npa:handler"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:mace:shibboleth:2.0:idp:profile-handler
classpath:/schema/shibboleth-2.0-idp-profile-handler.xsd
urn:com:securedimensions:npa:handler
classpath:/schema/shibboleth-2.0-idp-npa-handler.xsd">

Also in $IDP_CONFIG_DIR/handler.xml, add the German ID card Login Handler:

<!-- ... -->
<!-- Login Handlers -->

    <!-- nPA Login Handler -->
    <LoginHandler xsi:type="npa:NPAUser" nPAServletPath="/Authn/nPA">
        <AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</AuthenticationMethod>
    </LoginHandler>
<!-- ... -->

Resolver configuration

In $IDP_CONFIG_DIR/attribute-resolver.xml, add the xsd schema in the
<AttributeResolver> :

    <AttributeResolver xmlns="urn:mace:shibboleth:2.0:resolver" 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:npar="urn:com:securedimensions:npa:resolver"
        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
        urn:com:securedimensions:npa:resolver classpath:/schema/shibboleth-2.0-idp-npa-resolver.xsd">

Also in $IDP_CONFIG_DIR/attribute-resolver.xml, add the nPA Attributes:

        <!-- nPA Attributes -->
        <resolver:AttributeDefinition id="DocumentType" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="DocumentType">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:DocumentType" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:DocumentType" friendlyName="DocumentType" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="IssuingState" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="IssuingState">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:IssuingState" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:IssuingState" friendlyName="IssuingState" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="GivenNames" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="GivenNames">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:GivenNames" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:GivenNames" friendlyName="GivenNames" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="FamilyNames" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="FamilyNames">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:FamilyNames" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:FamilyNames" friendlyName="FamilyNames" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="ArtisticName" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="ArtisticName">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:ArtisticName" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:ArtisticName" friendlyName="ArtisticName" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="AcademicTitle" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="AcademicTitle">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:AcademicTitle" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:AcademicTitle" friendlyName="AcademicTitle" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="DateOfBirth" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="DateOfBirth">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:DateOfBirth" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:DateOfBirth" friendlyName="DateOfBirth" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="PlaceOfResidence" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="PlaceOfResidence">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:PlaceOfResidence" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:PlaceOfResidence" friendlyName="PlaceOfResidence" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="RestrictedId" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="RestrictedId">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:RestrictedId" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:RestrictedId" friendlyName="RestrictedId" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="RestrictedId2" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="RestrictedId2">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:RestrictedId2" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:RestrictedId2" friendlyName="RestrictedId2" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="CommunityIdVerfication" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="CommunityIdVerfication">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:CommunityIdVerfication" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:CommunityIdVerfication" friendlyName="CommunityIdVerfication" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="AgeVerification" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="AgeVerification">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:AgeVerification" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:AgeVerification" friendlyName="AgeVerification" />
        </resolver:AttributeDefinition>
        
        <resolver:AttributeDefinition id="DocumentValidity" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="DocumentValidity">
            <resolver:Dependency ref="AttributesDataConnector" xmlns="urn:mace:shibboleth:2.0:resolver:ad"/>
            <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:DocumentValidity" />
            <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:de:bdr:npa:attribute:DocumentValidity" friendlyName="DocumentValidity" />
        </resolver:AttributeDefinition>

Data Connector configuration

In $IDP_CONFIG_DIR/attribute-resolver.xml, add the configuration for the German ID card data connector:

        <!-- nPA Data Connector -->
        <resolver:DataConnector id="AttributesDataConnector" xsi:type="AttributeLookup" xmlns="urn:com:securedimensions:npa:resolver"/>

Attribute Filtering

In $IDP_CONFIG_DIR/attribute-filter.xml, enable all those German ID card attributes that shall be released. For example, release the FamilyNames attributes to anyone:

        <!--  Release of nPA Attributes to anyone -->
        <AttributeFilterPolicy id="NPAAtributesToAnyone">
            <PolicyRequirementRule xsi:type="basic:ANY" />
            
            <AttributeRule attributeID="FamilyNames">
                <PermitValueRule xsi:type="basic:ANY"/>
            </AttributeRule>
            
        </AttributeFilterPolicy>

Deployment

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

 
# change to the war directory
cd $IDP_INSTALL_DIR/war

#create directory WEB-INF/lib
mkdir -p WEB-INF/lib

# copy npa-login-handler.jar into the lib directory
cp $IDP_INSTALL_DIR/lib/npa-login-handler.jar $IDP_INSTALL_DIR/war/WEB-INF/lib

# unzip the web.xml file
unzip -l idp.war WEB-INF/web.xml

# apply changes to the web.xml file as described above

#update the idp.war file to contain the configured nPA Login Handler
zip -u idp.war WEB-INF/web.xml WEB-INF/lib/npa-login-handler.jar

The IdP should re-start automatically after you executed the zip command above!

Limitations in the current version

Querying Capabilities

The German ID card interface supports the construction of queries:

CommunityIdVerfication
AgeVerification
DocumentValidity

Those are not supported in the current version of the Login Handler.

PlaceOfResidence

The nPA Attribute "PlaceOfResidence" is structured. This structure is currently flattened into a String.

Clock Skew

The clock skew is hardcoded to 5 seconds.

Session Lifetime

The session lifetime is hardcoded to 30 minutes. This means that establishing new sessions with
additional service providers with Single-Sign-On is limited to 30 minutes.
session no longer inactive

Bugs & comments

No bugs are known at this point.

Please send bug reports & comments to am@secure-dimensions.com.