Skip to content
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

Better documentation for combining every aspect of the IDSA together #113

Open
AlWitton opened this issue Jul 15, 2022 · 3 comments
Open
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@AlWitton
Copy link

AlWitton commented Jul 15, 2022

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.

@AlWitton AlWitton changed the title Content Change Request Better documentation for combining every aspect of the IDSA together Jul 15, 2022
@anilturkmayali
Copy link
Member

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,

@anilturkmayali anilturkmayali added the documentation Improvements or additions to documentation label Jul 27, 2022
@AlWitton
Copy link
Author

AlWitton commented Jul 28, 2022

Hi @anilturkmayali
regarding your questions:

  1. I used the following repositories & documentation linked to them (such as the datamodel)
  1. 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:
          setup
          • SVG seems to be corrupted in my browser if zoomed in. here isa .png: setupids
      • 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
Copy link
Member

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

@anilturkmayali anilturkmayali self-assigned this Jul 28, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants