This project's aim is to implement support for the OpenID Connect for Identity Assurance 1.0 (ODIC4IDA) protocol on Keycloak, using a custom Service Provider. The project is designed to enable Keycloak to receive, process, and respond to requests and responses from the OIDC4IDA protocol. This implementation fulfills all the specified requirements outlined in the protocol's specification: it incorporates advanced functionalities such as conducting JSON schema validations for verified claims' requests and objects; additionally, it allows the storage of verified claims within Keycloak's local database, or their retrieval from an external verification server.
Most of the magic happens thanks to authlete-java-common library (the documentation can be accessed here). It allows the processing of OIDC4IDA requests and it is recognized as one of the standards protocol implementations by the eKYC & Identity Assurance WG. All of the JSON objects manipulated in this code are validated using JSON schemas provided by the protocol development team. This is done with help of the jsonschemafriend library (the documentation page can be found here).
To utilize this extension and its functionalities, follow these steps:
-
Copy the file
/keycloak/extensions/keycloak-oidc4ida.jarinto the/providersdirectory of your Keycloak installation. -
Upon server initialization, a new protocol mapper should become available:
-
Configure the mapper according to your requirements. You can choose between consuming verified claims from Keycloak's local database or specifying the URL of an external source:
Once correctly set up, Keycloak will recognize the verified claims' requests that adhere to this JSON schema, and will retrieve users' verified claims from the specified source. User's verified claims should also adhere to their own JSON schema. If stored in Keycloak's local database, they should be part of a user's attribute, labeled as verified_claims.
A demonstrative environment has been set up and is available so the extension can be seen in action. The environment includes a Keycloak instance with a realm named OIDC4IDA. This realm has a client, ida-client, configured to use the OIDC4IDA protocol mapper. A single user has been configured, with one set of verified claims, specified in this file. The user's credentials are ida_user (username) and 123 (password).
To run the demo, execute the following commands in a terminal:
chmod +x dev.sh
./dev.sh runPostman can be used to actively send verified claims requests and receive responses. A collection file is also provided, with a set of request examples and a pre-configured environment for you to play around.
This project is designed to be customizable at your will. The entire source code is thoroughly documented and can be easily modified to suit your needs. To build the project after making changes, follow these steps:
Navigate to the /keycloak/extensions directory and execute the following command in a terminal:
mvn clean installThis command will build the project, and a new JAR file will be generated in the /keycloak/extensions directory.
Alternatively, you can use the demo environment for building and testing your changes. To do so, run the following command in a terminal:
./dev.sh run --mvn-compileThis command will compile the project within the demo environment and also create a new JAR file in the /keycloak/extensions directory.
In order to be able to store users' verified claims locally, Keycloak's database had to be modified. This is done automatically when the extension is loaded, and should cause no problems at all. The USER_ATTRIBUTE table has had its column VALUE length changed from 255 to MAX. This modification should be handled with care, and it is recommended to do a backup of your application's database before loading the extension.