Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
1.0.0-RC1 #38
1.0.0-RC1 #38
Changes from all commits
89d4d07700bc7dc9e8c89d365501361608cc4e925563c0f4db7f7cdca5efb63d2186644026c0e7d23988341f37945f20f0e63854fbf3500b4ac9a2632a71da1e7510933729dbe9f81b32a29811e9936ca6f363c106c493b9de294053b2fc789f1bd8e65914608fbb92b2b63581f6c275aad00c2a2a41716f6a10091d94b0e30dec7a9214a1c3f18d8a375fe1e0d860cd8eac946136d39a92b4e93a9ccd679f5978311b90d3ecdc4e6a979c41044e28c13910bffdd491e334dd5e51c275a370683e159ea0f84b65f3b3f13d944bb0b31bece5c73e80fefbe465cf416caf4ee8d44c1178fc855208f2129f80fe189740147d409dfd9c4217069e7dda139e29e447b9a0e3533497a47b0f5eda1f032415d3dad27a96fb20b7ddfd62cf60b1399176bb8a08c218fb3f4f650ba5142807ea7fd3bb5bf06677769bf14e3ee8365c424b0810c208696a1bf839bcf2e9c651872d90de471553abab692a5314da3789f9f159fd71be9b58761276b8bdb51f953a800fe1b879e6727e49b967223217e4adfe974ed6b9281213490ed69bd43868d8711e13923da33e94ba7c3d1af9282e2e328be1ec88ce50defa2e16502480a5e563e7476c02a1da259d80604718e0d3b9d7530492c422bca1568c50d5cde8491b82bc410d676581e111d0b65731776a5400f6fb602a999756f7c02facab8ba4044dbea9b6703e96510a7cbea90ea5d2148c0573b12f2f8cf3aec808193d43cb875f54f609971801f40ab70da33b1385243046ed8713b45c24a7d9ef4cbfde0259ea126a312e3829db7870cad2498fa7a2cf555b8bf510a96a456e9b07ed376f87658dd84d0321914fcd9931d1fd5e10662e265c29be9d222b589ce7c1cb47dfa5d4881b1e480449f45945bfe2fe827cea850edafaa00f92a6650b3bb10e0f7293a01b43855c3ce2afbb49e36e5dd0a4f555d38402d3aeb1ae2aa969db1ab11dd43e0fc216d5822155ffc95c63bae90bca09c426b7fc6573b4d1c85b7f43939eccab4345b87d5b26bbfa4ef1bb185a0adcd409a605b2fec760d43198467e7d32a8ab100a46c4a0c8ff2fba4fd78add6f4f9f4fbdcb40dc1c3a8295f19980d0be4f02e53ab7be4aec60ed1706ec5822f738f5344b850024610ff4ed9234e4446311775b926080a7e2004749d64de5727c7323a5e961432f38f1ac879b8897bbaaf97b4e767546a22725f73514ab43d46bf313ed34952f68142a2de3a49aFile filter
Filter by extension
Conversations
Jump to
There are no files selected for viewing
eng-lollipop-consumer-java-sdk
This repository contains the code that composes the
eng-lollipop-consumer-java-sdk, containing the features to enable a LolliPoP validation inside a Consumer project using the JVM environment. It contains:Modules
The repository contains the following Gradle modules, to be used within other projects:
Samples
Use the SDK as dependency
The gradle modules contained in the repository (except the sources contained in the
sampledirectory) will be available on GitHub Packages. In order to include a dependency, use the Maven dependencyOr, in Gradle:
Where
MODULE_NAMEis one of the modules to be used for the SDK (Described in the paragraph above), andRELEASE_VERSIONis the version available on GitHub Packages (or the version installed locally).Local Installation
Prerequisites
In order to work with the
eng-lollipop-consumer-java-sdklocally the following are required to be installed:JDK 11Gradle 7.4+Maven Dependencies
In order to use maven it is required to have it installed locally, suggested to have it at least on version
3.8.5+.Github Packages Dependencies
This library uses some dependencies available through GitHub Packages. It is required to have the following information, in order to obtain them:
gpr.userproject property, or theGITHUB_ACTORenvironment variable, containing the GitHub handle to be used for package recoverygpr.keyproject property, or theGITHUB_TOKENenvironment variable, containing the GitHub token to be used for package recovery. The token must contain the permissions to retrieve GitHub Packages. See the Official GuidelinesBuild Locally
In order to build the library source locally it is suggested to run the
.\gradlew build --refresh-dependecies. Ensure that the properties regarding GitHub credentials have been defined beforehand.Metadata Verification
This repository uses the Gradle verification process on dependency checksums, using the file provided under
gradle\verification-metadata.xml. Whenever the dependency check does exit with a failure locally, it might be necessary to update the file. Gradle does provide the command.\gradlew --write-verification-metadata [algorithm] helpwhere the algorithm could be sha256, or whenever it is not available for a particular dependency sha1. An already known problem with the verification process and file update may not intercept all internal dependencies, obtaining a different result from the automated checks within the GitHub workflow. Whenever an update is required, and the provided cli command does not automatically update the file, it is required to introduce the checksum values manually. See the official Gradle Docs for troubleshooting of the metadata verification.Publish to Maven local repository
In order to publish the modules on the local maven repository the command to be used is
.\gradlew publishToMavenLocalNative Build
In order to compile the modules contained in this repository in a native form, the graalvm plugin is applied. In order to execute a native build it is required that an instance of the GraalVM JDK is installed and configured.
In order to compile natively execute this command:
.\gradlew nativeCompileThe result will be found under the module
build/nativedirectory.Note that currently a native version of the SDK is not automatically published on the GitHub Package.
Utilization
Configurations
The core module contains defined parameters to configure the provided services. Within each of the configuration classes provided in this module, that are not directly related to an implementation of a specific library or framework does not contain any functionality for property loading. The choice of the preferred method to apply the configuration properties is defined by the library user. The configuration classes are defined as follows:
LollipopConsumerRequestConfig
This configuration class contains the standard configuration properties for the SDK core functionalities:
AssertionStorageConfig
This configuration contains the standard properties regarding the storage interface for the SAML Assertion data:
IdpCertStorageConfig
This configuration contains the standard properties regarding the storage interface for the IdP certificates:
Other Configs
Inside the modules with the default implementations of the core interfaces regarding storage, rest clients and signature validation functionalities, are contained configuration classes specific for the provided implementations, the description of which are defined in the respective Readme files.
Implementations Usage
Each service inside the core SDK is defined by an interface and a related Factory to generate an instance of the service, using the related configurations. The repository contains default implementations for each one of the interfaces to be used. The following steps should be followed to ensure the usage of the SDK:
LollipopConsumerRequestConfig
The baseline for the SDK configuration is in this configuration class. As for any of the config files within the core SDK there is no reference to a particular method to be used for loading properties from an external source, leaving the possibility and responsibility to implement a proper loading method in the service utilizing the library (See for example the SpringLollipopConsumerRequestConfig extension, using annotations to load properties from the application context).
Whenever is required to define a new instance of the configuration class programmatically, it may be used a builder to setup the required parameters to be changed (not that otherwise the default values are applied):
Having defined the general configuration we can initialize the single instances of services (or related factories) to be used in the validation process.
HttpMessageVerifierFactory
An instance of the service to be used in order to verify the content digest and signatures related to the http request, through an implementation of the HttpMessageVerifier interface. The standard library does provide a factory interface to be used for the creation of a particular instance of the message verifier.
Whenever the factory helper class is not used and the generation of new instance of the service is required, we may use the following to generate an instance using the factory interface:
The repository provides a standard implementation of the service, and related factory. In order to initialize the factory the lollipopConsumerRequestConfig is required, as well as the value of the expected encoding. Note that the latter does not have a specific configuration file:
LollipopConsumerRequestValidationService
An instance of this service is used to apply formal validation a LollipopConsumerRequest instance. In order to use the provided implementation lollipopConsumerRequestConfig is required, as it is used to search for the headers using the name defined in the configuration class. We may define a new validation service as follows:
LollipopLoggerServiceFactory
An instance of the LollipopLoggerService is used to apply a form of logging in pre-defined portions of the SDK core services, in order to audit request validations, and if enabled the retrieval of Assertions and IdP Cert Data. The standard library does provide a factory interface to be used for the creation of a particular instance of the logger service.
Whenever the factory helper class is not used and the generation of new instance of the service is required, we may use the following to generate an instance using the factory interface:
The repository provides a standard implementation of the service, and related factory, using a standard logback implementation. In order to initialize the factory use the following snippet:
The SDK provides a default.xml logback include, as well as a default logback.xml file. The default may be used as a portion of other logback configuration, as an example see the spring implementation default logback-spring.xml.
AssertionStorageProvider
An instance of the service to be used in order to enable the possibility to retrieve or store already recovered SAML Assertions from a cache or storage, through an implementation of the AssertionStorage interface. The standard library does provide a factory interface to be used for the creation of a particular instance of the storage.
Whenever the factory helper class is not used and the generation of new instance of the service is required, we may use the following to generate an instance using the factory interface, using an instance of the StorageConfig class (described in the configuration paragraph):
The repository provides a standard implementation of the service, and related factory. that defines a simple in-memory cache storage for limited use, in order to initialize it, it is required to use the SimpleAssertionStorageProvider.
IdpCertStorageProvider
An instance of the service to be used in order to enable the possibility to retrieve or store already recovered IdP Certificates from a cache or storage, through an implementation of the IdpCertStorage interface. The standard library does provide a factory interface to be used for the creation of a particular instance of the storage.
Whenever the factory helper class is not used and the generation of new instance of the service is required, we may use the following to generate an instance using the factory interface, using an instance of the IdpCertStorageConfig class (described in the configuration paragraph):
The repository provides a standard implementation of the service, and related factory. that defines a simple in-memory cache storage for limited use, in order to initialize it, it is required to use the SimpleIdpCertStorageProvider.
Note that currently the storage is required only if applied directly to the default provider of IdP certificates data, as it is directly used in the Identity Services implementation. In case other implementations are used, this storage service may not be in use.
AssertionClientProvider
An instance of the service to be used in order to enable the possibility to retrieve SAML Assertions through an implementation of the AssertionClient interface. The standard library does provide a factory interface to be used for the creation of a particular instance of the client.
Whenever the factory helper class is not used and the generation of new instance of the service is required, we may use the following to generate an instance using the factory interface:
The repository provides a standard implementation of the service, and related factory, that defines a Rest Client using the available functionalities in the JDK 11 environment, available in the assertion-rest-client-native module.
See the related README.md for further information about the usage of this implementation.
IdpCertSimpleClientProvider
An instance of the service to be used in order to enable the possibility to retrieve IdPCert data through an implementation of the IdpCertClient interface. The standard library does provide a factory interface to be used for the creation of a particular instance of the client.
Whenever the factory helper class is not used and the generation of new instance of the service is required, we may use the following to generate an instance using the factory interface:
The repository provides a standard implementation of the service, and related factory, that defines a Rest Client using the available functionalities in the JDK 11 environment, available in the identity-service-rest-client-native module.
See the related README.md for further information about the usage of this implementation.
IdpCertProviderFactory
Once we have defined the necessary services to be used for the retrieval of the IdP certificates, we can use an implementation of the IdpCertProvider interface, in order to provide a transparent functionality inside the SDK library.
Whenever the factory helper class is not used and the generation of new instance of the service is required, we may use the following to generate an instance using the factory interface:
The repository provides a standard implementation of the service, and related factory. In order to initialize the factory an instance of the IdpCertClientProvider is required:
AssertionServiceFactory
Once we have defined the necessary services to be used for the retrieval of the SAML Assertion data, we can use an implementation of the AssertionService interface, in order to provide a transparent functionality inside the SDK library.
Whenever the factory helper class is not used and the generation of new instance of the service is required, we may use the following to generate an instance using the factory interface:
The repository provides a standard implementation of the service, and related factory. In order to initialize the factory an instance of the AssertionClientProvider, AssertionStorageProvider, and StorageConfig are required:
AssertionVerifierService
In order to execute a validation of the SAML Assertions starting form a LollipopConsumerRequest an interface of the AssertionVerifierService has to be used.
The standard implementation of this interface expects to have instances of the previously described interfaces, to be used for SAML Assertion retrieval and storage. Whenever we are using the factory helper it is not necessary to directly manage in any part the service startup, as it will be managed by the helper class itsefl if an implementation is missing.
In case it is necessary an instance of the standard implementation of the service can be applied with the following snippet, provided that the required services have been produced by the respective factory methods (or directly):
Factory Helper Startup
The LollipopFactoryHelper is a singleton class to be used by the LollipopCommandBuilder implementation, that provides (and creates if unavailable) the required services, through the provided implementations of the factory classes for the single components. It is not mandatory to be used in order to use the services, if the dependencies are injected using a dedicated library.
It requires an instance of a LollipopConsumerRequestConfig, HttpMessageVerifierFactory, AssertionStorageProvider, IdpCertProviderFactory, AssertionServiceFactory, LollipopLoggerServiceFactory. LollipopConsumerRequestValidationService
And related configs and sub-dependencies defined by the factory implementation.
Example
The following examples provides the complete setup method with default configurations created directly into the method. For a simple usage of the library the following can be used with minimal setup changes in configuration related to the expect origin method and url, and the rest client url to be used for Assertions retrieval. In a normal usage case each factory implementation and related configurations should be treated with an implementation for the related frameworks and libraries used for the application (As an example, defining Beans and configurations within a Spring context, such as in the provided spring-impl module, and within the spring sample):
Execute Validation Command
In order to execute a validation of an instance of LollipopConsumerRequest, after an instance of a LollipopConsumerFactoryHelper we could create an instance of the LollipopCommandBuilder interface as in the following snippet, directly into the execution method, or as the part of the application context (As an example, as a Spring Bean):
With an existing builder we could provide a new instance of a command to execute using the following:
A new LollipopConsumerCommand could be defined without the help of the FactoryHelper and the CommandBuilder, provided instances of an implementation of the required services are available, directly in the class requiring the new instance, or throughout the application context capable of enabling the usage of the @Inject annotations within the implemented command. In the case of a direct creation of a command to execute, use the following:
Defining LollipopRequestCommand instance
In order to define an instance of the LollipopRequestCommand, to be used in the validation process it is required to setup the following parameters:
The following snippet defines the conversion from an HttpServletRequest instance, to a new LollipopConsumerRequest
Using CommandResult instances
Whenever a validation command is executed, a CommandResult will be produced, abstracting the exceptions or validation errors produced by the services regarding the validation process for the http message, and the SAML assertion. The CommandResult has properties indicating:
The following snippet shows an example of how the CommandResult could be used to define the HttpServletRespons status and response body whenever the CommandResult is not ending in a successful state:
Utility classes
LollipopConsumerConverter
Class that implements Javax Servlet library with two utility methods:
convertToLollipopRequest:
interceptResult:
Examples of its usage can be found in the Spring Interceptor.
LollipopTypesafeConfig
Class that implements Lightbend's Config library, used to define configuration parameters.
The class' constructor retrieve from a Config object the parameters that can be used as configuration in the application, if the path to the parameter is not found (it hasn't been configured) a default value will be set.
Examples of its usage can be found in the Simple Typesafe sample, where the Config object is generated with the library's class ConfigFactory using as source for the configuration the sample's application.properties.
Testing
Testing of the repository functionalities is conducted by unit test, integration and e2e testing.
Collecting Test Coverage
This repository contains a module dedicated to collecting the test coverage of all the modules within the repository through the usage of a dedicated gradle plugin.
In order to obtain a centralized report of the repository test coverage, the following command can be used on the test-coverage module:
Afterwards, the report is found at
/test-coverage/build/reports/jacoco/testCodeCoverageReport.E2E
This repository contains a collection and docker-compose file to be used for the purpose of an integrated testing. See the related README.md for further information.
Generate new Rest Clients
The standard Rest Clients available in the repository are defined without a specific dependency, and relates to the standard services available (For example, the IdP Data Provider is referred to the existing Pagopa Identity Services).
In case a new implementation of the client (for example, using Feign), or one of the clients has a different specification from the one that has been used as a default, a tool may be used to generate the internal structure of the client using OpenApi generation tool or gradle plugin. For the latter the following steps may be used to produce the internals of the Rest Client implementation:
Introduce in your module the following plugin:
id("org.openapi.generator") version "6.5.0"Afterwards define the following task structure in your module:
Where the
dataLibraryconfig option defines the java version to be used, and thelibrarydefines witch implementation to be used. (For examplelibrary: "feign"will generate a Feign Rest Client).In order to execute the task run the following command:
.\gradlew openApiGenerateThe default openApi specs for the two services already implemented are found in the respective modules under the
openApifolder.See the OpenAPITools/openapi-generator repository for further information about the generation toolkit.
Having the Rest Client code generated, the output should be introduced inside the expected package within the module, and an instance of the core SDK interfaces should be implemented in order to handle the data retrieval through the generated client.
For example, in order to enable the usage of a new Rest Client regarding the IdP certificates retrieval an implementation of the IdpCertClient and IdpCertClientProvider should be defined. See for reference the IdpCertSimpleClient implementation.