Add trento Single Sign-on integration docs #177

arbulu89 · 2024-10-07T12:58:52Z

Not to be published until version 2.4 is released.

NOTE:
The xml file is created based in the migration file formatted as markdown. As definition_lists are not a standard component in markdown, but we already use them in the docs, i wanted to use them to list the available variables.
In order to enable the conversion of them, we need to indicate it to pandoc.
Use this command to generate the final xml:

pandoc --from=gfm+definition_lists+raw_attribute --to=docbook5 sso-integration.md --output ../xml/sso-integration.xml

PR creator: Description

Include Trento's new single sign-on (SSO) integration usage docs.
It explains how to setup different types depending on the user needs

PR creator: Are there any relevant issues/feature requests?

Not that I'm aware of.
@abravosuse maybe the next release jira ticket if we have one?

tomschr

@arbulu89 Thanks for the submission. 👍

I've reviewed it from a DocBook perspective. 😉 Here is a summary:

Some tags should be renamed. As Markdown is a "stupid" format, it cannot distinguish between a filename and an option. I marked it in some lines.
I haven't looked at the text itself yet. 😄 This is something for another round when all the structure is in place.
Be careful with <emphasise role="strong">. We use it rarely in our text. This could be fixed in the original Markdown source.

trento/xml/sso-integration.xml

arbulu89 · 2024-10-07T14:56:25Z

Hey @tomschr
I think I have applied all the corrections. As I still want to have the markdown as source of truth, I have done some "nasty" things there. It doesn't look that much as a valid markdown, but this is the price we need to pay to have a correctly generated xml file

abravosuse · 2024-10-07T17:18:39Z

@tomschr once both the structure and the content are review, could you please generate pdf file so that I can review the PR as well? Thanks!

tomschr

Thanks @arbulu89 for all your efforts! Much appreciated! I had the time to review it now. 🙂

Before you start working on the comments itself (maybe they aren't that important), we should maybe discuss about the overall structure. Sometimes I was a bit confused.

The Trento documentation is structured in a way that it distinguishes between two "doc types":

Tasks that the user has to execute to achieve a specific goal.
Concepts that explains background information.

It would be helpful if your text could be adapted to this "doc framework"/convention. At the moment, I see a mixture of both. Don't worry, I'm here to help you! 🙂

If you look through the Trento documentation, you can see lots of tasks ("Installing Trento Server" instead of "Trento Server Installation").

When Alberto and I described a task, we use a procedure. A procedure is a step-by-step instruction what the user has to do.

So my more holistic suggestion would be:

What's a task and what is a concept in your text?
If it's a task, what steps do you need? Can we rewrite the text into some steps?

So your text is about single sign-on. Just from my gut feeling, we could discuss if this structure would be appropriate:

4.5 Integrate Single Sign-On
  4.5.1 Background information
        Tell here about available protocols, user roles, and
        authentication. Maybe also requirements?
        Don't add tasks.
  4.5.2 Using/Integrating OpenID Connect
  4.5.3 Using/Integrating OAuth 2
  4.5.4 Using/Integrating Security Assertion Markup Language

To make it a bit more visible, this is how it could look like if you write a procedure for section 4.5.2

# Using/Integrating OpenID Connect
By default, OIDC is disabled. To enable OIDC in Trento, proceed
as follows:

1. Open the file /etc/trento/trento-web
2. Provide the following environment variables
   # add here a short description
3. Use the optional variables ... to do ...
   # Maybe this step can be skipped. Or in what situation do you need
   # the optional variables?
4. Restart the application with:
   # add here the command

Hope that makes it clearer what I intend. 🙂

trento/migration/sso-integration.md

* Try to use procedures (step-by-step instructions) * Add comments in // * Still needs some additions from my suggestions at GitHub

tomschr

@arbulu89 Thanks for the efforts. Here is my suggestion. 😉

trento/migration/sso-integration.md

tomschr · 2024-10-09T16:57:06Z

trento/migration/sso-integration.md

+#### SAML user profile
+
+Users provided by the SAML installation must have some few mandatory attributes to login in Trento. All of them are mandatory, even though their name is configurable.
+The user profile must include attributes for: username, email, first name and last name.
+This attributes must be mapped for all users wanting to connect to Trento.
+
+By default, Trento expects the `username`, `email`, `firstName` and `lastName` attribute names. All these 4 attribute names are configurable using the next environment variables, following the same order: `SAML_USERNAME_ATTR_NAME`, `SAML_EMAIL_ATTR_NAME`, `SAML_FIRSTNAME_ATTR_NAME` and `SAML_LASTNAME_ATTR_NAME`.
+So for example, if the IDP user profile username is defined as `attr:username`, `SAML_USERNAME_ATTR_NAME=attr:username` should be used.


I'm not sure what the user has to do here. Could we turn that into a task?

Maybe something like this? Although I think this is probably not enough, isn't it?

Suggested change

#### SAML user profile

Users provided by the SAML installation must have some few mandatory attributes to login in Trento. All of them are mandatory, even though their name is configurable.

The user profile must include attributes for: username, email, first name and last name.

This attributes must be mapped for all users wanting to connect to Trento.

By default, Trento expects the `username`, `email`, `firstName` and `lastName` attribute names. All these 4 attribute names are configurable using the next environment variables, following the same order: `SAML_USERNAME_ATTR_NAME`, `SAML_EMAIL_ATTR_NAME`, `SAML_FIRSTNAME_ATTR_NAME` and `SAML_LASTNAME_ATTR_NAME`.

So for example, if the IDP user profile username is defined as `attr:username`, `SAML_USERNAME_ATTR_NAME=attr:username` should be used.

#### SAML user profile

Users provided by the SAML installation must have some few mandatory attributes to login in Trento. All of them are mandatory, even though their name is configurable.

1. For each user profile, include the attributes username, email, first name, and last name. These attributes must be mapped for all users wanting to connect to Trento. By default, Trento expects the `username`, `email`, `firstName` and `lastName` attribute names.

1. Ensure that the SAML environment variables adhere to the same spelling and order.

Use the names `SAML_USERNAME_ATTR_NAME`, `SAML_EMAIL_ATTR_NAME`, `SAML_FIRSTNAME_ATTR_NAME` and `SAML_LASTNAME_ATTR_NAME`.

For example, if the IDP user profile username is defined as `attr:username`, use `SAML_USERNAME_ATTR_NAME=attr:username`.

Ok, this is how SAML works.
When you have a SAML IDP, you have a user profile (one) that is used to model all the users created in the IDP.
This user profile, has some fields, the typical ones are email, name, etc

Each IDP installation will have different naming for the fields though. Some might have email, others userEmail, others attr:email, etc

So what the users needs to do is:

Have the attributes in the user profile (which the name they prefer)

Configure trento with those names

Now, that I have listed you this, I will transform the content to something similar

trento/migration/sso-integration.md

tomschr · 2024-10-09T17:03:54Z

trento/migration/sso-integration.md

+curl http://localhost:4000/api/public_keys
+```
+
+Copy the content of the certificate from there, and provide it to the IDP. This way, the IDP will sign and verify the messages sent by both ends.


What do you mean by "provide it to the IDP"? And "both ends" means Trento and IDP, right?

Suggested change

Copy the content of the certificate from there, and provide it to the IDP. This way, the IDP will sign and verify the messages sent by both ends.

Copy the content of the certificate from there and provide it to the IDP. This way, the IDP will sign and verify the messages sent by both ends.

No, Trento already have it (it was created by Trento), so you need to copy the content and provide to the IDP, and we cannot say how you do that, because this depends on the IDP. But all IDPs will have the option to use it

by both ends means that the IDP will sign the messages it sends and verify the messages it receives from trento

I will rephrase to Copy the content of the certificate from there and provide it to the IDP. This way, the IDP will sign its messages and verify the messages received from Trento.

tomschr · 2024-10-09T17:08:41Z

trento/migration/sso-integration.md

+### Restart Trento
+
+Once the certificate is provided to the IDP, the IDP recreates its own <filename>metadata.xml</filename> file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new <filename>metadata.xml</filename> content.
+
+If the <option>SAML_METDATA_CONTENT</option> option is being used, the content of this variable must be updated with the new metadata. In the other hand, if <option>SAML_METADATA_URL</option> is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized


Ok, what exactly has the user to do?

So you provide/upload etc. the certificate to the IDP, the IDP creates a metadata file which is then used by Trento, right?

But why does a user want to use this variable SAML_METADATA_CONTENT? To provide the data manually? Is is still a bit foggy to me.

Suggested change

### Restart Trento

Once the certificate is provided to the IDP, the IDP recreates its own <filename>metadata.xml</filename> file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new <filename>metadata.xml</filename> content.

If the <option>SAML_METDATA_CONTENT</option> option is being used, the content of this variable must be updated with the new metadata. In the other hand, if <option>SAML_METADATA_URL</option> is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized

### Restarting Trento

Once the certificate is provided to the IDP, the IDP recreates its own <filename>metadata.xml</filename> file. This file defines which certificate is used to sign the messages by both sides. At this point, Trento Web must be restarted to use the new <filename>metadata.xml</filename> content.

If the <option>SAML_METDATA_CONTENT</option> option is being used, the content of this variable must be updated with the new metadata. In the other hand, if <option>SAML_METADATA_URL</option> is used, the new metadata is automatically fetched. If neither of these steps are completed, communication will fail because the message signatures will not be recognized

Yes, once you get the certificate from trento, you provide it to the IDP (each IDP will have its own way).
Now, the IDP will update its own IDP with the given certificate.
Some IDP has a endpoint that you can access using a url that returns you the content of the metadata.
Others don't, and it just gives you some other way (plain text) for example.

If you are in the 1st option (IDP has metadata endpoint), the easiest way is to use it (as if for some reason, you change something in the IDP, Trento will fetch the update automatically).

In the second case (IDP doesn't have an endpoint), you will need to copy the content of the metadata.xml (it is given as one lines string) in the SAML_METADATA_CONTENT variable.

In any case, whoever is using SAML will know (should know all of this) much better than we do. As they are IDP operators and experts on this field

trento/migration/sso-integration.md

arbulu89 · 2024-10-10T07:21:44Z

Hey @tomschr ,
I have some more improvements in the SAML chapter.
So far, I see 2 main points we might want to discuss.

The Configuring SAML user profile and Restarting Trento chapters. I have improved both. Let's see if you like them more

tomschr

Thanks @arbulu89. Some smaller things.

trento/migration/sso-integration.md

arbulu89 · 2024-10-10T13:50:07Z

@tomschr All the suggestions applied.
A pity that I cannot commit here, as I need to create the final xml 🙈

tomschr · 2024-10-10T13:57:09Z

A pity that I cannot commit here, as I need to create the final xml

~~Argh, that's really pity, but maybe I can do that or Eugen (if he still has the permissions).~~ You have write permission. 🙂

Thank you!

EMaksy · 2024-10-10T15:07:42Z

Hey @abravosuse check out the build docs :D
SLES-SAP-trento_en.pdf

abravosuse · 2024-10-11T13:38:20Z

I plan to use the document to test the integration of my rolling environment with our internal IDP provider. But my rolling environment runs on K3s and the documentation seems to be specific to rpm and container deployment. Is the SSO integration not possible when Trento runs on a Kubernetes cluster?

arbulu89 · 2024-10-14T07:05:30Z

I plan to use the document to test the integration of my rolling environment with our internal IDP provider. But my rolling environment runs on K3s and the documentation seems to be specific to rpm and container deployment. Is the SSO integration not possible when Trento runs on a Kubernetes cluster?

Yes, it is usable. The thing is, we don't have any real documentation about almost any variable used in the k3s deployment before hand, so I guess we didn't add them when Eugen started first to document the SSO integrations.

Do you want me to add them? At the end, it is just a bunch more of variables to be used with --set.
Anyway, we don't have them in our internal documentation neither

abravosuse · 2024-10-14T07:31:42Z

I plan to use the document to test the integration of my rolling environment with our internal IDP provider. But my rolling environment runs on K3s and the documentation seems to be specific to rpm and container deployment. Is the SSO integration not possible when Trento runs on a Kubernetes cluster?

Yes, it is usable. The thing is, we don't have any real documentation about almost any variable used in the k3s deployment before hand, so I guess we didn't add them when Eugen started first to document the SSO integrations.

Do you want me to add them? At the end, it is just a bunch more of variables to be used with --set. Anyway, we don't have them in our internal documentation neither.

Yes, please. It'd be helpful to have at least the list of helm variables to be used to enable SSO integration with the different protocols.

arbulu89 · 2024-10-14T07:36:42Z

@abravosuse Kubernetes deployment steps added in last commit.
@EMaksy Could you create the pdf again so it has the latest changes?

EMaksy · 2024-10-14T07:46:13Z

Here the latest changes: SLES-SAP-trento_en.pdf

Check it out @abravosuse

abravosuse

Just a few minor change requests.

trento/xml/sso-integration.xml

trento/migration/sso-integration.md

abravosuse · 2024-10-31T12:34:01Z

@arbulu89 I just left a couple of comments for your review.

arbulu89 · 2024-11-04T08:36:51Z

@abravosuse Thank you for this final review. All suggested changes done!
Just as a side note, you don't need to review both .md and .xml files. Just reviewing the last is enough for me, as anything wrong there, must be first changed in t he md file which will forward all the changes to the final result

abravosuse

Thank you @arbulu89 !

arbulu89 added the prj:Trento Related to Trento documentation label Oct 7, 2024

arbulu89 requested review from tomschr and abravosuse October 7, 2024 12:58

Add trento sso integration docs

fde88f3

arbulu89 force-pushed the trento-sso-integration branch from d927791 to fde88f3 Compare October 7, 2024 13:04

tomschr requested changes Oct 7, 2024

View reviewed changes

Apply xml improvements

2382fc0

arbulu89 requested a review from tomschr October 7, 2024 14:55

tomschr requested changes Oct 8, 2024

View reviewed changes

tomschr and others added 2 commits October 9, 2024 10:29

First draft of restructure into tasks + concepts

ae8e05b

* Try to use procedures (step-by-step instructions) * Add comments in // * Still needs some additions from my suggestions at GitHub

Apply some suggestions and improve SAML content

e6ec22d

tomschr requested changes Oct 9, 2024

View reviewed changes

Improve SAML usage chapter content

10b11f8

arbulu89 requested a review from tomschr October 10, 2024 07:22

Change order in SAML installation steps

d1f2c7a

tomschr requested changes Oct 10, 2024

View reviewed changes

Apply more improvements and fix typos

1c03908

arbulu89 requested a review from tomschr October 10, 2024 13:49

EMaksy force-pushed the trento-sso-integration branch from 4bd52c9 to 1c03908 Compare October 10, 2024 15:10

arbulu89 force-pushed the trento-sso-integration branch from e468c61 to 8a18571 Compare October 14, 2024 07:40

Add kubernetes installation chapters

ec95aae

arbulu89 force-pushed the trento-sso-integration branch from 8a18571 to ec95aae Compare October 14, 2024 07:42

arbulu89 and others added 11 commits October 14, 2024 12:04

Ident helm commands with new lines

cc12bdf

Update sso-integration.md

06e9c28

Update sso-integration.xml

affd706

Update sso-integration.md

53a82cc

Update sso-integration.xml

4b407a3

Fix and improve certs usage in SAML configuration chapter

67e86c0

Fix typo in oauth2 helm deployment command

a45076d

Fix encrypting typo

cb01887

Add note to explain saml must be enabled to get certs

a7a8c88

Explain how to restart docker deployments

85d7f6d

Change SAML_SP_DIR default location

f58cec8

abravosuse requested changes Oct 24, 2024

View reviewed changes

Add more corrections and format optional vars usage

1363b6f

arbulu89 marked this pull request as ready for review November 4, 2024 08:35

arbulu89 requested a review from abravosuse November 4, 2024 08:35

abravosuse approved these changes Nov 4, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add trento Single Sign-on integration docs #177

Add trento Single Sign-on integration docs #177

arbulu89 commented Oct 7, 2024 •

edited

Loading

tomschr left a comment

arbulu89 commented Oct 7, 2024

abravosuse commented Oct 7, 2024

tomschr left a comment •

edited

Loading

tomschr left a comment

tomschr Oct 9, 2024

arbulu89 Oct 10, 2024

tomschr Oct 9, 2024

arbulu89 Oct 10, 2024

arbulu89 Oct 10, 2024

arbulu89 Oct 10, 2024

tomschr Oct 9, 2024

arbulu89 Oct 10, 2024 •

edited

Loading

arbulu89 commented Oct 10, 2024

tomschr left a comment

arbulu89 commented Oct 10, 2024

tomschr commented Oct 10, 2024 •

edited

Loading

EMaksy commented Oct 10, 2024 •

edited

Loading

abravosuse commented Oct 11, 2024

arbulu89 commented Oct 14, 2024

abravosuse commented Oct 14, 2024

arbulu89 commented Oct 14, 2024

EMaksy commented Oct 14, 2024

abravosuse left a comment

abravosuse commented Oct 31, 2024

arbulu89 commented Nov 4, 2024

abravosuse left a comment

	Copy the content of the certificate from there, and provide it to the IDP. This way, the IDP will sign and verify the messages sent by both ends.
	Copy the content of the certificate from there and provide it to the IDP. This way, the IDP will sign and verify the messages sent by both ends.

Add trento Single Sign-on integration docs #177

Are you sure you want to change the base?

Add trento Single Sign-on integration docs #177

Conversation

arbulu89 commented Oct 7, 2024 • edited Loading

PR creator: Description

PR creator: Are there any relevant issues/feature requests?

tomschr left a comment

Choose a reason for hiding this comment

arbulu89 commented Oct 7, 2024

abravosuse commented Oct 7, 2024

tomschr left a comment • edited Loading

Choose a reason for hiding this comment

tomschr left a comment

Choose a reason for hiding this comment

tomschr Oct 9, 2024

Choose a reason for hiding this comment

arbulu89 Oct 10, 2024

Choose a reason for hiding this comment

tomschr Oct 9, 2024

Choose a reason for hiding this comment

arbulu89 Oct 10, 2024

Choose a reason for hiding this comment

arbulu89 Oct 10, 2024

Choose a reason for hiding this comment

arbulu89 Oct 10, 2024

Choose a reason for hiding this comment

tomschr Oct 9, 2024

Choose a reason for hiding this comment

arbulu89 Oct 10, 2024 • edited Loading

Choose a reason for hiding this comment

arbulu89 commented Oct 10, 2024

tomschr left a comment

Choose a reason for hiding this comment

arbulu89 commented Oct 10, 2024

tomschr commented Oct 10, 2024 • edited Loading

EMaksy commented Oct 10, 2024 • edited Loading

abravosuse commented Oct 11, 2024

arbulu89 commented Oct 14, 2024

abravosuse commented Oct 14, 2024

arbulu89 commented Oct 14, 2024

EMaksy commented Oct 14, 2024

abravosuse left a comment

Choose a reason for hiding this comment

abravosuse commented Oct 31, 2024

arbulu89 commented Nov 4, 2024

abravosuse left a comment

Choose a reason for hiding this comment

arbulu89 commented Oct 7, 2024 •

edited

Loading

tomschr left a comment •

edited

Loading

arbulu89 Oct 10, 2024 •

edited

Loading

tomschr commented Oct 10, 2024 •

edited

Loading

EMaksy commented Oct 10, 2024 •

edited

Loading