Package: python-ishare
IntroductionWelcome to the python ishare package. This package implements helpers for the
authentication flow between iSHARE services. Specifically, the part of the process
where a json web token (per iSHARE specification) is transformed into an access token.
This access token can then be used to communicate with the rest of a Role's service
endpoints.This package could be relevant for connecting to/from the followingroles:Satellite or Data Space AuthoritiesAuthentication RegistriesIdentity ProvidersService or Data ProviderService or Data ConsumersFor more information on ISHARE;The ISHARE websiteThe developer documentationThe ISHARE FrameworkThe ISHARE Satellite repositoryUsagePrerequisitesFor a working connection with, for example, an iSHARE satellite you need a participant
registration.From the registration with an iSHARE Satellite.(encryption) The registered Certificate'sprivateRSA key. This must be kept SECRET!(x509 header) The registered Certificate'spublicx509 certificate chain.(client_id) The registered participant's EORI numberThe registered participant adherence status is "Active".For every participant Service you want to connect to:(audience) The target service's EORI number(decryption) Their public x509 (can be retrieved from an iSHARE Satellite)The domain of the service you're connecting toAll of these are required to encrypt and decrypt communication between different the
iSHARE services. For more detailed information refer to theprivate key jwtjson web
token flowhere.InstallationInstall this package usingpip;pipinstallpython-ishareor using poetry;poetryaddpython-ishareThe three-step methodologyCreate a json web token per iSHAREspecification).Use a client interface to communicate with a roleUse theISHARESatelliteClientinterface to verify a participantI. Creating the json web tokenThere is a convenience method (python_ishare.create_jwt) in the package to help create
the token.frompathlibimportPathfromcryptography.x509importload_pem_x509_certificates,Certificatefromcryptography.hazmat.primitives.serializationimportload_pem_private_keyfromcryptography.hazmat.primitives.asymmetric.rsaimportRSAPrivateKeyfrompython_ishareimportcreate_jwtYOUR_PARTICIPANT_EORI="XXX"THEIR_PARTICIPANT_EORI="YYY"# Load your RSA key to an RSAPrivateKeywithPath("path/to/my/key.pem")asfile:private_key:RSAPrivateKey=load_pem_private_key(file.read_bytes(),password=b"your_password_or_None")withPath("path/to/my/certs.pem")asfile:chain:list[Certificate]=load_pem_x509_certificates(file.read_bytes())# Create the actual tokenmy_token=create_jwt(payload={"iss":YOUR_PARTICIPANT_EORI,"sub":YOUR_PARTICIPANT_EORI,"aud":THEIR_PARTICIPANT_EORI,"jti":"your-unique-id"# optional},private_key=private_key,x5c_certificate_chain=chain)This method is strictly seperated out from the client interfacing (next step). This is
for two reasons;It makes you responsible for loading theCertificate's from the chain andRSAPrivateKeyas such that these important files can be stored anywhere.It makes it possible to sign the json web token externally using an AWS asymmetric key
for example. A great security solution.II. Connecting to an iSHARE SatelliteTo connect to an iSHARE satellite this package provides anISHARESatelliteClientinterface class.frompython_ishareimportISHARESatelliteClient# From step 1YOUR_PARTICIPANT_EORI="XXX"my_token=create_jwt(...)public_key=...client=ISHARESatelliteClient(target_domain="satellite.ishare.com",target_public_key=public_key,client_eori=YOUR_PARTICIPANT_EORI,json_web_token=my_token)# To retrieve the satellite's capabilitiescapabilities=client.get_capabilities()print(capabilities)# To retrieve the satellite's public capabilitiespublic_capabilities=client.get_capabilities(use_token=False)print(public_capabilities)The value of this interface class is that you never needed to worry about access tokens.
This is handled for you underwater. Tokens are re-used whenever a new request is made.III. Verifying an iSHARE participantVerifying a participant is a key responsibility for a number of roles. TheISHARESatelliteClienthas a method to do this for you.# From step 2YOUR_PARTICIPANT_EORI="XXX"client=IShareSatelliteClient(...)# Assuming you have some python web framework there will be a requestrequest=...# If you're a service provider, you can use this to verify other parties iSHARE tokensclient.verify_json_web_token(audience=YOUR_PARTICIPANT_EORI,client_id=request.param["client_id"],client_assertion=request.param["client_assertion"],client_assertion_type=request.param["client_assertion_type"],grant_type=request.param["grant_type"],scope=request.param["scope"],)[!IMPORTANT]Theverify_json_web_tokencurrently does not implement full Certificate validation!Developer SetupEverything needed to start developing on this package.Quick start||tl;drInstall the python package management tool;poetry.curl-sSLhttps://install.python-poetry.org|python3-Install the local python project.poetryinstallRun the test suite and linters usingtox.poetryruntoxRun development commands inside the virtualenv.poetryrun<my_command>SetupThis project runs on a centralpyproject.tomlconfiguration. Here you can find the
information for what python version to use and dependencies. Configuration for the
various linters, testing frameworks is also defined there.Poetry - Project installerPoetry is a smooth dependency manager for Python that is seemingly taking over the
market. TheDocumentationis
of excellent quality.Poetry installation:curl-sSLhttps://install.python-poetry.org|python3-For a specific version of poetry:curl-sSLhttps://install.python-poetry.org|python3---version<POETRY_VERSION>For users of pipx:pipxinstallpoetryProject InstallationRunningpoetry installwill install the source code and all it's dependencies
including development packages.Pythonic DependenciesBehind the scenes Poetry creates and manages the virtualenv with all the python
package dependencies necessary for the project. This means that to access packages and
scripts installed by Poetry you need to run commands in that environment.There are two different ways, pick your favorite;Wrap your command in apoetry runformat. For example;# poetry run <my_sub_command>poetryrunblackActivate the virtualenv in your shell, and all commands will run accordingly.# <my_sub_command>poetryshell# Spawns a shell with the venv activatedblack# (And all other commands after that)💡There are IDE's that understand Poetry and handle it for you so you don't have to
do anything else. For instance in PyCharm, you can configure your interpreter to use
Poetry.Linting libraries usedThe following packages are used to ensure code cody cleanliness and monitor some
known/preventable security issues.blackis used to auto-format code.isortis used to automatically sort imports.flake8is used enforce standard style guide
conventions not automatically handled by black.banditis used to detect some common
security issues.mypyis used to validate python typehints for correctness.safetyis used to check
dependencies for known security issues against a database.toxis used to run all of the above commands inside an isolated python
environment.