Add trento Single Sign-on integration docs

[arbulu89]

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.

[arbulu89]

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]

@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:

1. What's a task and what is a concept in your text?
2. 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. 🙂

[tomschr]

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

[tomschr]

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`.

[arbulu89]

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:

1. Have the attributes in the user profile (which the name they prefer)
2. Configure trento with those names

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

[tomschr]

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.

[arbulu89]

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

[arbulu89]

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

[arbulu89]

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]

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

[arbulu89]

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

[arbulu89]

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.

[arbulu89]

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

[tomschr]

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]

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

[abravosuse]

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]

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]

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]

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

[EMaksy]

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

Check it out @abravosuse

[abravosuse]

Just a few minor change requests.

[abravosuse]

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

[arbulu89]

@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 !