clarify creating moderated sessions for leaf nodes

[capnspacehook]

If a role specifies that created sessions must be moderated with require_session_join and a user containing that role attempts to connect to a leaf node, it should not require moderation, unless the mapped leaf roles also require moderation. This should be documented.

[zmb3]

Web UI, tsh, or both?

[capnspacehook]

Both

[capnspacehook]

This is actually expected behavior and should be documented. Unless the mapped roles of the leaf cluster require session moderation, created sessions for leaf nodes will succeed.

[zmb3]

This is not just for moderated sessions and is just how RBAC role mapping works across trusted clusters.

The docs cover this here: https://goteleport.com/docs/architecture/trustedclusters/#role-mapping

I'll leave it up to @ptgott or @alexfornuto to determine whether or not we need to expand this.

[alexfornuto]

I think the flowchart linked explains role mapping pretty well for what it is, but that in general that image is not the best way to document this feature. All the content in that image can't be parsed by our search engine, and won't come up in results... and in general it's difficult to read.

I think we could improve this bit of documentation by:

• Replacing the chart with a smaller one with less copy in it, then detailing the flow underneath with text.
• While we're in there we can use the OP as an example of how role mapping behaves in that given scenario.

Thoughts @ptgott & @lsgunn-teleport ?

[lsgunn-teleport]

I've started working a complete rewrite of this section (in part, I had to learn about trusted root and leaf clusters to address gravitational/docs#379 and https://github.com/gravitational/teleport-private/issues/130#top).
Right now I'm lumping it all in one page, but it might make sense to split it into a few shorter pages in a future iteration.