Authentication and shared git repository

[donmartin76]

Hello dear oXygen users and administrators,

I am currently evaluating oXygen Web Author, and I am wildly struggling in understanding the model of authentication. To set the scenario: We want to edit a shared git repository using Web Author; each user should get their own user name/email in the commit messages.

What I have gathered so far is that in principle Web Author clones one single repository server side which is used by all users using the same Web Author server, but uses the individual user's name and email address to attribute the correct user to the commits. Is this correct?

My real struggle is to understand how authentication works: Ideally, I would want to log in to Web Author using an external identity provider, such as Microsoft Entra (or any other OIDC Identity Provider). Then I would expect to be able to map user claims to a user's name and email address for use in the commit messages.

But this does not seem to work like that. Instead, every user which opens the Web Author gets immediate access to the application, but needs to log in/authenticate using their git credentials (we are working with an Azure DevOps git repository, not GitHub/Enterprise nor GitLab). I would in principle be fine with that as well - but in this case, would each individual user get their own server-side git repository clone, or how does this work?

I can't really find any documentation which really makes sense to me - I figure I have some fundamental issue in understanding how this is working, and I would be super happy to be enlightened.

Best regards from Germany,
Martin

[donmartin76]

But this does not seem to work like that. Instead, every user which opens the Web Author gets immediate access to the application, but needs to log in/authenticate using their git credentials (we are working with an Azure DevOps git repository, not GitHub/Enterprise nor GitLab). I would in principle be fine with that as well - but in this case, would each individual user get their own server-side git repository clone, or how does this work?

What I found out so far, after tinkering around some more: Indeed it seems that, if you are asking for the same repository as different users, you all share the same cloned instance of that git repository inside the Web Author server's data storage. If you use different branches, Web Author seems to queue the requests and do a "git checkout" (branch switch) internally every time somebody needs a different branch from the one which was used the last time.

In consequence, for us, as our repository is several gigabytes large, this means that everybody needs to work on the same branch essentially; otherwise things get far too slow (10-20 seconds each request which needs to do the branch switch).

Did I understand this correctly? And this means it's actually the git credentials and the repository URL which decides on whether you have access to the data or not. I think we can work with that - but it's kind of not intuitive at first. Are there other ways of doing this, or is this the "canonical" way of handling things?

Happy for some feedback - still feeling kind of lost here

[cosminef]

Hello,

Thank you for reaching out.

In your case, if you are working with Azure DevOps git repository, it would be helpful to use the generic Git connector [1] [2] that is available by default in Web Author. Authentication to a Git repository through this connector can be done using a username and password.

Do you consider that the documentation we mentioned addresses your questions?

Best,
Cosmin

[1] https://www.oxygenxml.com/doc/versions/ ... fn_tjn_5jb
[2] https://www.oxygenxml.com/doc/versions/ ... ithub.html

[donmartin76]

Hello Cosmin,

Thank you for your answer.

The documentation kind of addresses the issues at hand - I think it was more an issue on my side understanding the underlying mechanisms, and that the actual authentication is solely based on the access to the git repository; this threw me off a little. But in the end, I think this works, and we just need to consider our branching strategy so that everybody would work on one single branch typically, otherwise it could be too slow.

For me, as somebody who would need to operate the Web Author solution and not being very familiar with the entire oXygen suite, a page with a little more guidance on how things typically look with respect to data storage and authentication could help - the architecture is very different from what I am used to for other types of applications. Completely offloading the authentication to the git access was a first for me.

Best regards,
Martin

[Bogdan Dumitru]

Hello Martin,

The bridge between Oxygen XML Web Author and File Storage Servers (e.g. GitHub, Drupal, Dropbox, etc.) is generally called a connector. This is basically a plugin whose purpose is to enable a connection to a file storage service.
Oxygen XML Web Author operates documents generically. It does not have built-in business logic for a specific File Storage Service. It has a few extension points, APIs, and interfaces that a connector must implement to make the actual connection to the file storage service. This generic approach is achieved by relying internally on java.net.URL objects.
When it needs to read a document, it opens an HTTP connection the document URL by using java.net.URL.openConnection(), and from the returned java.net.URLConnection, it reads the document from the java.io.InputStream returned by java.net.URLConnection.getInputStream() method call.

Based on the above we created a set of connectors and the Git connector is one of them. The Git connector contributes 6 connection types that materialize in max 6 tabs on the Dashboard, each with it's own configuration page in the Web Author Administration page/Plugins/Git Plugin/Configuration:

• GitHub - connects to Git repositories hosted on "github.com" via OAuth. This also supports connection to on-premise servers when checking the "Use GitHub Enterprise" checkbox.
• Bitbucket - connects to Git repositories hosted on "bitbucket.com" via OAuth
• Bitbucket Server - connects to Git repositories hosted on Bitbucket on-premise servers via OAuth
• GitLab - connects to Git repositories hosted on "gitlab.com" via OAuth
• GitLab - connects to Git repositories hosted on GitLab on-premise servers via OAuth
• Git - connects to any Git repository via username and password

The "Git" generic connector allow you to connect to any Git repository simply by specifying the repository URL. The application creates a clone for each user and updates the clone when a file is opened.
I'm not familiar with Azure DevOps git repository but you connect to it with an user and password you should be able to connect from Web Author to it using the same user and password.
The fact that each user will have its own clone make the app consume more disk space but don't think there should be a problem when switching branches.

If the generic Git doesn't help you, you can make you own connector from scratch by following the below guide but this implies an significant effort:
https://www.oxygenxml.com/doc/versions/ ... erver.html

A starting point about connectors would be the below topic:
https://www.oxygenxml.com/doc/versions/ ... orage.html

For a general starting point about Oxygen XML Web Author architecture/concepts see this:
https://www.oxygenxml.com/doc/versions/ ... cepts.html

[Bogdan Dumitru]

One last note: only the generic Git connection clones the entire repository to disk, whereas the others use dedicated REST APIs (for example, the GitHub integration uses the GitHub REST API to retrieve the content of specific files, this allowing us to avoid having to clone the whole repo).