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.

German ID card Login Handler

  • 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.