Better documentation for combining every aspect of the IDSA together

[AlWitton]

Which part of the repository is your change request related to?
Please provide the exact URL(s) of the page(s) [...]

Please describe which content you would expect here and tell us how to solve this request
Describe a little more in detail which information or resources you would expect here. And describe the change you would like to see (i.e. remove a chapter that is obsolete, replace a paragraph with the new version, correct a broken link, etc.). If your requested content should be brought here from another source, please share the link and details.
The generation process of auth tokens is very ambigiously described. Couldnt found a single entry point for a complete setup explanation as the project is extremely scattered. The documentation for each part is alright but putting everything together is poorly explained.

Can you already provide any alternative (or updated) content that can/should replace the existing content?
A clear and concise description of any alternative content you have considered.

A complete step by step guide accessed though the root wiki page, in which everything is described. If code or token generation is required, the code for creating dummy certificats that are working - including a brief explanation who needs them, where they are issued and where certifies them - is also included.

Additional notes
Add any other notes about the change request here.
Iis exhausting and little to none-productive jumping from tab to tab just because the required information are scattered throughout several projects and no one so far has taken any kind of effort putting them together in an easy to follow guide.

[anilturkmayali]

Hi @AlWitton thank you very much for providing this feedback! We are working to make the (huge amount of) content as user-friendly as possible, while trying to contain as much content as possible. This sometimes leads to ambiguity and I think your expertise and your experience as a user is definitely something we would like to hear about. We will have a major update on our main repo and would also be interested in creating a spot with practical information on explanations and steps to follow for a complete setup.

Would it be possible for you to explain your experience in more detail? To be more concrete,

1. What were the documents/repositories you checked to understand the generation process of auth tokens?
2. If you were going to name the steps you should follow (to find the information), how many steps would there be and how would you name each?

We would highly appreciate if you can provide this feedback to us so that we can understand your experience better and use your feedback to make the content more accessible and more user-friendly.

Thank you very much in advance,
Best regards,

[AlWitton]

Hi @anilturkmayali
regarding your questions:

1. I used the following repositories & documentation linked to them (such as the datamodel)

• https://github.com/International-Data-Spaces-Association/DataspaceConnector for basic connector functionality testing
• [dsd](https://github.com/International-Data-Spaces-Association/IDS-G/tree/main/Components/MetaDataBroker for using a MDB
• https://github.com/International-Data-Spaces-Association/IDS-testbed for testing it with DAPS since with the MDB i always got a failure in looking up my DAP token

2. Ste step by step guide should look like this:

• Overview
• Requirements
• Installation and Setup of Tools & Ressources
• Running locally (1 docker compose - testbed locally works fine)
• Abstraction to split up the components
  • several compose files (IDS,IDS,MDB,OMEJDN) so that all containers run in different docker networks to actually test a distributed system
    • instruction to set up compose files (env, volume, nginx for omejdn and broker-reverseproxy, ...)
    • instruction for CA, SLL, truststores and keystores
      • root CA (see Metadata Broker docs + something like this + if you work with SAN, include how to genereate custom SANs with a .ext file or include it in the CA python scripts as the testbed git only allows localhost and broker-reverseproxy as DNS names and does not allow anything else
      • relation of CA, SubCA and certs to the respective components (ids, broker, omejdn)
      • truststores, keystores and sslkeys generation for every ids explained with code snippets. This includes also the link of the key- and truststore to the DAPS-server and the broker as for me it is still 100% clear how they are connected with each other. I found some links by looking at the fingerprints of the keystores but I didnt investigate everything.
      • anything else i forgot in here:
        
        • SVG seems to be corrupted in my browser if zoomed in. here isa .png:
    • instructions to setup omejdn server or use public fraunhofer service such that ids connectors and broker can communicate with it and valid DAPS token are exchanged
      • import yml files that are liked to docker-compose and .env (omejdn.yml, webfinger.yml, nginx config,...)

Im not comming from certificates at all so this is still a huge endavour to get every configuration right and working - which is not very userfriendly at all. When working with the MDB i got invalid DAPS and in the testbed i received an SSL error for invalid hostname when trying to switch setup to communicate through my IP.

The testbed should be as close to production standards as possible. This includes besides https a distributed setup with communication not running completely local

The instructions should start from the beginning and not skipping crucial parts. If you follow them step by step (one entry point - not switching between 5 git documentation and some other sources to find CLI commands) you should start with nothing and end up with a distributed testbed. You should have deployed all services, be your own CA and have certificates as well as key- and truststores generated by yourself for all components required.

And just to be clear. I am not suggesting that mentioned pieces do not exist. They might not exist or not exist in the scope/detail that would be required to guide someone completely new to SSL and JWT through the process or they exist but are scattered throughout several projects in a way that its hard to follow.

[anilturkmayali]

Thank you very much for the detailed description @AlWitton we will review this and will come up with a lean and structured guidance based on the structure you have provided.

For your information,
@Sonia-IDSA @ssteinbuss