Identification Report Impl Java

Description

This project provides a simple Java support API to easily create and validate Identification Reports as described in https://github.com/Governikus/IdentificationReport.

---

Supported Versions

This implementation supports the version 2.0.0 of the Identification Report

Supported subjectRef-types

Version	Authentication Object Schema ID	SubjectRef-subtype
2.0.0	https://raw.githubusercontent.com/Governikus/IdReport-SubjectRefSchemas/2.0.0/fink/person-ref-minimal-fink.json	FinkPersonRefMinimal.class
2.0.0	https://raw.githubusercontent.com/Governikus/IdReport-SubjectRefSchemas/2.0.0/eid/person-ref-eid-card.json	EidCardPersonRef.class

Extendable

The supported subjectRef-types can be manually extended without changing the API. See below in the section How to use.

---

This project requires JDK 17 or higher

Please note that some Elliptic Curve algorithms will require at least JDK 11.

The library is available on maven central, just include it in your project like so:

<dependency>
    <groupId>de.governikus</groupId>
    <artifactId>identification-report-impl-java</artifactId>
    <version>2.0.0</version>
</dependency>

---

Note:

If the project does not compile within your IDE install the "lombok" plugin for your IDE and restart it.

---

Supported Features

• JSON Schema validation of the Identification Report
• Conversion of Identification Reports into and from JWT
  • JWS
  • Supported Key Types: RSA and EC
• easy conversion from and into strings

---

Basics

The identification report is a composition of two objects. The Identification Report itself and a subject that was identified. The identified subject is a free JSON-object and is placed in the subjectRef-attribute.

The subjectRef-attribute is identified by the attribute subjectRefType that contains the schema id of the referenced subject type.

{
    "reportId": "be4f9806-0b5f-45c3-a008-96fd2750f8cb",
    "serverIdentity": "https://test.governikus-eid.de/gov_autent/async",
    "reportTime": "2020-06-25T10:20:39Z",
    "identificationTime": "2020-06-25T10:19:54Z",
    "subjectRefType": "${some-uri-to-an-expected-schema-describing-the-subject-ref}",
    "subjectRef": {
        "restrictedId": "1",
        "givenName": "John",
        "familyName": "Doe",
        "dateOfBirth": "1-1-1986",
        "placeOfBirth": "Berlin",
        "birthName": "Dorian",
        "placeOfResidence": {
            "street": "GROẞENHAINER STR. 133/135",
            "city": "DRESDEN",
            "state": "Dresden",
            "country": "D",
            "zipCode": "01129"
        }
    },
    "idStatement": "successful identification sent by SAML-Assertion",
    "levelOfAssurance": "http://eidas.europa.eu/LoA/high"
}

---

SubjectRef Objects

This API provides an abstract object type with the name of SubjectRef. This object represents the Java POJOs that can be placed within an IdentificationReport-object.

public class IdentificationReport
{
  ...
  /**
   * The identified subject
   */
  private SubjectRef subjectRef;
  ...
}

---

Object serialization and deserialization

Serialization and deserialization is done by the jackson-databind API.

---

Pre-registered schemas

The schemas listed in the Supported Versions section are pre-registered and must not be added manually.

---

How to use:

Authentication Object Registering

This API allows automatic parsing of subtypes of the SubjectRef. In order to do so you should register the objects schema-id with its corresponding subtype.

final String mySchemaId = "some-schema-id-uri";
final Class<? extends SubjectRef> mySubType = EidCardAuthentication.class;
Schemas.addSchemaSubTypeReference(mySchemaId, mySubType);

Create and validate

IdentificationReport<EidCardPersonRef> identificationReport = 
                          IdentificationReport.<EidCardPersonRef>builder()
                                              .reportId(UUID.randomUUID().toString())
                                              .serverIdentity("https://some-idp-url.de")
                                              .reportTime(Instant.now())
                                              .identificationTime(Instant.now())
                                              .levelOfAssurance(LevelOfAssurance.EIDAS_LOW)
                                              .documentReferences(documentReferenceList)
                                              .build();
boolean isValid = identificationReport.validate();

Parse from String

final String json = "{the identification-report as json}";
final Class<?extends SubjectRef> subjectRefType = MySubjectRefType.class;
IdentificationReport identificationReport = IdentificationReport.fromJson(json, subjectRefType);

the type can be omitted if the subjectRefType parameter is present within the json document.

final String json = "{the identification-report as json with subjectRefType}";
IdentificationReport identificationReport = IdentificationReport.fromJson(json);

To JWS

public static String toJws(PrivateKey privateKey, IdentificationReport identificationReport)
{
  final String json = identificationReport.toString();
  JwtHandler jwtHandler = new JwtHandler(privateKey, null);
  return jwtHandler.createJws(json);
}

Parse from JWS

the JwtHandler resolves the algorithms automatically by analyzing the JWT-Header

public static <T extends SubjectRef> IdentificationReport<T> fromJws(X509Certificate certificate,
                                                                     String json,
                                                                     Class<T> subjectRefType)
{
  JwtHandler jwtHandler = new JwtHandler(null, certificate);
  JwtHandler.PlainJwtData plainJwtData = jwtHandler.handleJwt(json);
  return IdentificationReport.fromJson(plainJwtData.getBody().toString(), subjectRefType);
}