tctl sso: update general SSO docs and GitHub guide.#14227
Conversation
|
Bump @ptgott |
|
|
||
| Next, define an authentication connector. Create a file called `connector.yaml` | ||
| based on one of the following examples. | ||
| Next, define an authentication connector. We recommend the usage of helper |
There was a problem hiding this comment.
What would you think of adding step-by-step instructions for using a helper command to create the connector? We're already showing example snippets, so I think it would make sense to create a seamless step-by-step experience. We could use a Tabs component for this, with one TabItem per connector type.
There was a problem hiding this comment.
Hmm, not sure what that should look like? Do you mean to move individual steps in this guide into tabs? I'm probably missing the right idea here...
There was a problem hiding this comment.
It would be something like this:
Next, define an authentication connector using the `tctl sso configure`
command:
<Tabs>
<TabItem title="OIDC">
Here is how to use `tctl sso configure oidc`.
</TabItem>
<TabItem title="SAML">
Here is how to use `tctl sso configure saml`.
</TabItem>
<TabItem title="GitHub">
Here is how to use `tctl sso configure gh`.
</TabItem
</Tabs>This way, the reader wouldn't need to find the relevant documentation on their own.
| Note: | ||
| - Manually pasting the XML to `entity_descriptor` field is error prone. We recommend using `tctl sso configure saml -e entity_descriptor.xml ...` command instead. | ||
| - You may use `entity_descriptor_url`, in lieu of `entity_descriptor`, to fetch the entity descriptor from | ||
| your IDP. Though, we recommend "pinning" the entity descriptor by including the XML rather than fetching from a URL. |
There was a problem hiding this comment.
Does the helper command add the XML to pin the entity descriptor? If so, we should indicate this here, since that's the recommended approach.
There was a problem hiding this comment.
The command is a replacement for editing. If the argument to -e is a file, the result is the same: we fill in entity_descriptor field (which is the recommended "pinning"). If the argument is a URL, we will fill the entity_descriptor_url field ("floating" approach). I agree the paragraph could use rephrasing to make it clear.
| Teleport will request only the `read:org` OAuth scope. Read more about OAuth scopes in GitHub's documentation: | ||
| Teleport will request only the `read:org` OAuth scope. Read more about OAuth scopes in [GitHub's documentation](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). | ||
|
|
||
| [GitHub OAuth scopes](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/) |
There was a problem hiding this comment.
| [GitHub OAuth scopes](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/) |
| [GitHub OAuth scopes](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/) | ||
|
|
||
| Finally, create the connector using `tctl`: | ||
| To ensure the connector is working as intended: SSO flow is passing, roles are assigned as intended etc., you can now test it using [`tctl sso test`](../reference/cli.mdx#tctl-sso-test) command. |
There was a problem hiding this comment.
| To ensure the connector is working as intended: SSO flow is passing, roles are assigned as intended etc., you can now test it using [`tctl sso test`](../reference/cli.mdx#tctl-sso-test) command. | |
| To ensure that the SSO flow is working and roles are assigned as intended, you can now test your GitHub connector using the `tctl sso test` command. |
Removing the link since we'll be explaining the command here. We can add links to the CLI reference in a "Next steps" section. Also tightening up this sentence a bit.
|
|
||
| Finally, create the connector using `tctl`: | ||
| To ensure the connector is working as intended: SSO flow is passing, roles are assigned as intended etc., you can now test it using [`tctl sso test`](../reference/cli.mdx#tctl-sso-test) command. | ||
|
|
There was a problem hiding this comment.
I think we should add a sentence explaining what this command does.
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
|
@Tener Sorry for the delay on this. I've answered some of your questions. Please let me know if you don't have the bandwidth for any of my suggested changes and I can either propose them as issues or make time to work on them myself. |
@ptgott I can work on these points at low intensity, no problem. It is taking a considerable time though, and I lack a coherent vision of what the SSO guides should look like. The guides have grown organically over the years - perhaps it would be a good idea to refresh them in bulk? That would have to be a Docs team BoW item, though. |
|
I'll raise a request in the Docs queue using this PR as reference. |
4 participants
Update SSO guides to take into account new commands:
tctl sso test,tctl sso configure:This PR is one of a series; see #12941 (comment).
Parent: #9270