search

plantuml / plantuml

Generate diagrams from textual description
https://plantuml.com
Other
9.73k stars 881 forks source link

Authentication for SURL with BasicAuth and OAuth2 #796

Closed arittner closed 2 years ago

arittner commented 2 years ago

Implementation of authentication for SURL with BasicAuth and OAuth2 (client_credentials and password).

With the implementation, URLs to endpoints for imports, includes and internal functions such as loadJSON, can now be provided with an authentication method. BasicAuth and OAuth2 with the grant types "client_credentials" and "password" are currently supported.

The authentication is stored in the UserInfo part of the URL. For this purpose, there must be a configuration file with the same name that contains all the data for access in a JSON structure. This ensures that no confidential user data has to be stored in the DSL scripts.

Please note: Authentication for URLs are not a common use case for a public PlantUML server but very useful in intranets or PlantUML as a library in a modeling pipeline.

Example for a URL with authentication:

https://auth@www.example.com/api/rest/endpoint

PlantUML expects a local file with the name auth.credentials in a specific folder (configured by "plantuml.security.credentials.path").

As default, PlantUML allows only authentication over https (SSL/TLS). This can be changed by a config value "plantuml.security.allowNonSSLAuth", but in this case the credentials will be sent without any encryption. Please do this only in intranet environments.

Pull request contains a lot of tests. Documentation should be provided via Wiki (not in scope of this PR). Support for OpenID / JWT will be added in a future pull request.

Please feel free to contact me for any question.

arittner commented 2 years ago

Ok, one test is failing (only on github, not on my local env). I'll check.

arittner commented 2 years ago

Ok, lessons learned: Never mix canonical path with absolute path and compare it :-D

arnaudroques commented 2 years ago

Once again, many thanks for your contribution. We may slightly refactor it (formatting) to keep it consistent with the rest of the code. It's definitively well written with nice test coverage (which we really miss in the other part of the project). This will be released in the beginning of December, I'm sure users will find it very useful!

arittner commented 2 years ago

Hello @arnaudroques

I'm very happy that I was able to advance the PlantUML project a bit with this. I need the function for my CI/DI pipeline to create diagrams from existing data. Additionally, our internal Stash allows only BasicAuth access (and I host the models in a repository).

I'll try to find out what is not working yet in my formatter. Is it possibly the line breaks?

The question is where and how I should create the documentation. I would then create some examples and describe how to configure it.

Best regards, Aljoscha

arnaudroques commented 2 years ago

The question is where and how I should create the documentation. I would then create some examples and describe how to configure it.

We have set up a special wiki for that. It accepts markdown, dokuwiki and asciidoc syntax (with on-the-fly conversion), so you can use your preferred syntax. It's completely open, no login, no password. You can create your pages as you like (there is a validation process on our side)

So you can create:

http://alphadoc.plantuml.com/doc/markdown/en/url-authentication http://alphadoc.plantuml.com/doc/markdown/en/url-basicauth http://alphadoc.plantuml.com/doc/markdown/en/url-oauth2 http://alphadoc.plantuml.com/doc/markdown/en/anything-you-like

As example, you can be inspired by this page. Each page is divided in chapters.

Don't be afraid to do several tries, to edit stuff, to delete: there is nothing wrong you can do there. Tell us if you need some help to use this wiki.

The goal of this wiki is to translate the documentation in several languages but I suggest that you only write the English version right now.

arnaudroques commented 2 years ago

@arittner Is this method really used? It seems never used.

arittner commented 2 years ago

@arittner Is this method really used? It seems never used.

Reserved for future use :-D. I started with OAuth2 OpenID, but I postponed it. All the byte[] methods and request-callback handler should be moved to a HttpClient class. In my opinion, SURL is not a good place. But this refactoring is also postponed and will be included in my OpenId devs.

arnaudroques commented 2 years ago

@arittner We've done some cosmetic change in SURL. The most significant is the management of MalformedURLException here.

Please tell us if there is something you don't like. Thanks!

arittner commented 2 years ago

Hello @arnaudroques

Sorry for the late response. The mentioned code line was from the old create method. And I agree, hiding issues with returning null instead of using exceptions is a bad smell in code. However, for now, I just wanted to add the URL authentication implementation and avoid changing signatures of public methods.

I also looked at the other changes. I'll be honest, I'm not a big fan of removing the code block curly braces for one-liners :-). I've gotten into the practice of following the recommendations of Sonar, Findbugs, and many others that it's safer to basically put code blocks in curly braces. In the end, it's really not a big issue, I just didn't want to reformat the class completely with my PR, because otherwise, it's very hard for the person doing a review to see which change belongs to implementation and which to formatting.

best regards, Aljoscha

arittner commented 2 years ago

We have set up a special wiki for that. It accepts markdown, dokuwiki and asciidoc syntax (with on-the-fly conversion), so you can use your preferred syntax. It's completely open, no login, no password. You can create your pages as you like (there is a validation process on our side)

So you can create:

http://alphadoc.plantuml.com/doc/markdown/en/url-authentication http://alphadoc.plantuml.com/doc/markdown/en/url-basicauth http://alphadoc.plantuml.com/doc/markdown/en/url-oauth2 http://alphadoc.plantuml.com/doc/markdown/en/anything-you-like

Ok, @arnaudroques :-)

I created a documentation (hopefully everything is covered). What do you think? Some improvements?

arnaudroques commented 2 years ago

However, for now, I just wanted to add the URL authentication implementation and avoid changing signatures of public methods.

Sure, it's easier for me to change signature of public methods. PlantUML code is far from perfect, so do not hesitate to make suggestions. The PlantUML core code definitively needs some improvement.

I created a documentation (hopefully everything is covered). What do you think? Some improvements?

It's a very good start! It has just been published here. Right now, I find it very complete, so no idea for improvements.

I am waiting for the next official release (beginning of December) to make some public annoncement about it. My personal experience shows that when some real users are going to use your new feature, they will ask questions and at that time only the documentation will be improved. You may have to be patient: it may takes months before that happens... We will make some noise around this to speed up the process :-)

The-Lum commented 2 years ago

Hello all,

Right now, I find it very complete, so no idea for improvements.

💡 Here is one idea: I jut add some picture with the JSON representation of the API, and adding highlight for required field... [See on alphadoc/.../url-authentication]

If that helps more...

arittner commented 2 years ago

Hello @The-Lum!

I'll check this way to improve the documentation. Currently, I'm working on JWT based OAuth2 (OpenID). After that, I've a next loop to update the documentation. Thank you for your feedback.