diff --git a/docs/config.json b/docs/config.json index 2ab99299922a4..5d177afc2bcdf 100644 --- a/docs/config.json +++ b/docs/config.json @@ -53,7 +53,7 @@ "slug": "/setup/admin/", "entries": [ { - "title": "Github SSO", + "title": "GitHub SSO", "slug": "/setup/admin/github-sso/" }, { diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index 75c569e2d969e..de5d88a19cd5b 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -1,62 +1,90 @@ --- title: SSO for SSH -description: How to set up single sign-on (SSO) for SSH using Gravitational Teleport +description: How to set up single sign-on (SSO) for SSH using Teleport h1: Single Sign-On (SSO) for SSH --- -Users of the Enterprise edition of Teleport can login with SSH, Kubernetes, Databases and Web applications -through a Single Sign-On (SSO) provider used the rest of the organization. +Users of the Enterprise edition of Teleport can log in to servers, Kubernetes +clusters, databases, web applications, and Windows desktops through their +organization's Single Sign-On (SSO) provider. + + + + + Learn how to use Teleport's SSO integrations in Teleport Cloud. + + + Learn how to use Teleport's SSO integrations in Teleport Enterprise. + + + + + - Configure Azure Active Directory SSO for SSH, Kubernetes, Database and Web apps. + Configure Azure Active Directory SSO for SSH, Kubernetes, databases, desktops and web apps. - Configure Windows Active Directory SSO for SSH, Kubernetes, Database and Web apps. + Configure Windows Active Directory SSO for SSH, Kubernetes, databases, desktops and web apps. - Configure Gsuite SSO for SSH, Kubernetes, Database and Web apps. + Configure Google Workspace SSO for SSH, Kubernetes, databases, desktops and web apps. - Configure Gitlab SSO for SSH, Kubernetes, Database and Web apps. + Configure GitLab SSO for SSH, Kubernetes, databases, desktops and web apps. - Configure OneLogin SSO for SSH, Kubernetes, Database and Web apps. + Configure OneLogin SSO for SSH, Kubernetes, databases, desktops and web apps. - Configure OIDC SSO for SSH, Kubernetes, Database and Web apps. + Configure OIDC SSO for SSH, Kubernetes, databases, desktops and web apps. - Configure Okta SSO for SSH, Kubernetes, Database and Web apps. + Configure Okta SSO for SSH, Kubernetes, databases, desktops and web apps. ## How does SSO work? -Users need to execute the following command login in the CLI or login using UI: +Execute the following command to log in to your Teleport cluster using the CLI. -```bsh -# this command will automatically open the default web browser and take a user -# through the login process with an SSO provider: -$ tsh login --proxy=proxy.example.com +```code +# This command will automatically open the default web browser and take a user +# through the login process with an SSO provider +$ tsh login --proxy=proxy.example.com --auth=github +``` -# output: +The command opens a browser window and shows a URL the user can visit in the +terminal to complete their SSO flow: + +```text If browser window does not open automatically, open it by clicking on the link: http://127.0.0.1:45235/055a310a-1099-43ea-8cf6-ffc41d88ad1f ``` -Teleport will wait for up to 3 minutes for a user to authenticate. If authentication -succeeds, Teleport will retrieve an SSH and X.509 certificates and will store them in -`~/.tsh/keys/proxy.example.com` directory. The tool will also will add SSH cert to an -SSH agent if there's one running. +Teleport will wait for up to 3 minutes for a user to authenticate. If +authentication succeeds, Teleport will retrieve SSH and X.509 certificates and +store them in the `~/.tsh/keys/` directory. The tool will also will +add SSH cert to an SSH agent if there's one running. ## Configuring SSO -Teleport works with SSO providers by relying on a concept called -*"authentication connector"*. An auth connector is a plugin which controls how -a user logs in and which group he or she belongs to. +Teleport works with SSO providers by relying on the concept of an +**authentication connector**. An authentication connector is a plugin that +controls how a user logs in and which group they belong to. + +### Supported connectors -The following connectors are supported: +The following authentication connectors are supported: - `local` connector type uses the built-in user database. This database can be manipulated by the `tctl users` command. @@ -65,64 +93,132 @@ The following connectors are supported: - `oidc` connector type uses the [OpenID Connect protocol](https://en.wikipedia.org/wiki/OpenID_Connect) to authenticate users and query their group membership. -To configure SSO, a Teleport administrator must: +### Creating an authentication connector -- Update `/etc/teleport.yaml` on the auth server to set the default - authentication connector. -- Define the connector [resource](../setup/reference/resources.mdx) and save it into - a YAML file (like `connector.yaml`) -- Create the connector using `tctl create connector.yaml`. +Before you can create an authentication connector, you must enable +authentication via that connector's protocol. -```yaml -# snippet from /etc/teleport.yaml on the auth server: -auth_service: - # defines the default authentication connector type: +To set the default authentication type as `saml` or `oidc`, either modify your Auth Service configuration file +or create a `cluster_auth_preference` resource. + + + + Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon. + ```yaml + auth_service: + authentication: + # Set as saml or oidc + type: saml|oidc + ``` + + + Create a file called `cap.yaml`: + ```yaml + kind: cluster_auth_preference + metadata: + name: cluster-auth-preference + spec: authentication: - type: saml + # set as saml or oidc + type: saml|oidc + version: v2 + ``` + + Create the resource: + + + + ```code + # Log in to your cluster with tsh so you can run tctl commands. + # You can also run tctl directly on the Auth Service host. + $ tsh login --proxy=teleport.example.com --user=myuser + $ tctl create -f cap.yaml + ``` + + + + + ```code + # Log in to your cluster with tsh so you can run tctl commands. + $ tsh login --proxy=mytenant.teleport.sh --user=myuser + $ tctl create -f cap.yaml + ``` + + + + + + +Next, define an authentication connector. Create a file called `connector.yaml` +based on one of the following examples. + + + + +```yaml +(!/examples/resources/okta-connector.yaml!) ``` -An example of a connector: + + ```yaml -# connector.yaml -kind: saml -version: v2 -metadata: - name: corporate -spec: - # display allows to set the caption of the "login" button - # in the Web interface - display: "Okta" - - acs: https://teleport-proxy.example.com:3080/v1/webapi/saml/acs - attributes_to_roles: - - {name: "groups", value: "okta-admin", roles: ["access"]} - - {name: "groups", value: "okta-dev", roles: ["dev"]} - - # note that wildcards can also be used. the next line instructs Teleport - # to assign "access" role to any user who has the SAML attribute that begins with "admin": - - { name: "group", value: "admin*", roles: ["access"] } - # regular expressions with capture are also supported. the next line instructs Teleport - # to assign users to roles `admin-1` if his SAML "group" attribute equals 'ssh_admin_1': - - { name: "group", value: "^ssh_admin_(.*)$", roles: ["admin-$1"] } - - entity_descriptor: | - +(!/examples/resources/onelogin-connector.yaml!) ``` -- See [examples/resources](https://github.com/gravitational/teleport/tree/master/examples/resources) - directory in the Teleport Github repository for examples of possible connectors. -- 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. + + + +```yaml +(!/examples/resources/oidc-connector.yaml!) +``` + + + + +```yaml +(!/examples/resources/gworkspace-connector-inline.yaml!) +``` + + + + +```yaml +(!/examples/resources/adfs-connector.yaml!) +``` + + + + +```yaml +(!/examples/resources/saml-connector.yaml!) +``` + + + + + +You may use `entity_descriptor_url`, in lieu of `entity_descriptor`, to fetch +the entity descriptor from your IDP. + +We recommend "pinning" the entity descriptor by including the XML rather than +fetching from a URL. + +Create the connector: + +```code +$ tctl create -f connector.yaml +``` ### User Logins Often it is required to restrict SSO users to their unique UNIX logins when they -connect to Teleport nodes. To support this: +connect to Teleport Nodes. To support this: -- Use the SSO provider to create a field called *"unix_login"* (you can use another name). -- Make sure it's exposed as a claim via SAML/OIDC. -- Update a Teleport SSH role to include `{{external.unix_login}}` variable into the list of allowed logins: +- Use the SSO provider to create a field called `unix_login` (you can use another name). +- Make sure the `unix_login` field is exposed as a claim via SAML/OIDC. +- Update a Teleport role to include the `{{external.unix_login}}` variable in the list of allowed logins: ```yaml kind: role @@ -157,10 +253,10 @@ At this time, the `spec.provider` field should not be set for any other identity ## Working with External Email Identity Along with sending groups, an SSO provider will also provide a user's email address. -In many organizations, the username that a person uses to log into a system is the -same as the first part of their email address - the 'local' part. For example, `dave.smith@acme.com` might log in with the username `dave.smith`. Teleport provides an easy way to extract the first part of an email address so it can be used as a username - this is the `{{email.local}}` function. +In many organizations, the username that a person uses to log in to a system is the +same as the first part of their email address, the "local" part. For example, `dave.smith@acme.com` might log in with the username `dave.smith`. Teleport provides an easy way to extract the first part of an email address so it can be used as a username. This is the `{{email.local}}` function. -If the email claim from the identity provider (which can be accessed via `{{external.email}}`) is sent and contains an email address, you can extract the 'local' part of the email address before the @ sign like this: `{{email.local(external.email)}}` +If the email claim from the identity provider (which can be accessed via `{{external.email}}`) is sent and contains an email address, you can extract the "local" part of the email address before the @ sign like this: `{{email.local(external.email)}}` Here's how this looks in a Teleport role: @@ -240,6 +336,7 @@ If something is not working, we recommend to: - Double-check the host names, tokens and TCP ports in a connector definition. + ### Using the Web UI If you get "access denied" or other login errors, the number one place to check is the Audit @@ -278,6 +375,7 @@ traits correctly. For a user to see a Node in Teleport, the result of populating template variable in a role's `allow.logins` must match at least one of a user's `traits.logins`. + In this example a user will have usernames `ubuntu`, `debian` and usernames from the SSO trait `logins` for Nodes that have a `env: dev` label. If the SSO trait username is `bob` then the usernames would include `ubuntu`, `debian`, and `bob`. ```yaml @@ -291,3 +389,4 @@ spec: 'env': 'dev' version: v5 ``` + diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx index a1a2271a7afb2..cc0651c03fd86 100644 --- a/docs/pages/enterprise/sso/adfs.mdx +++ b/docs/pages/enterprise/sso/adfs.mdx @@ -4,7 +4,7 @@ description: How to configure SSH access with Active Directory Federation Servic h1: Single Sign-On with Active Directory Federation Services --- -This guide will cover how to configure Active Directory Federation Services +This guide will explain how to configure Active Directory Federation Services ([ADFS](https://en.wikipedia.org/wiki/Active_Directory_Federation_Services)) to be a single sign-on (SSO) provider to issue SSH credentials to specific groups of users. When used in combination with role @@ -15,12 +15,33 @@ like: - Developers must never SSH into production servers. - ... and many others. - - This guide requires a commercial edition of Teleport. - + + This guide requires Teleport Cloud or Teleport Enterprise. + + View this guide as the user of another Teleport edition: + + + + + + + + + + + + +## Prerequisites + +- ADFS installation with Admin access and users assigned to at least two groups. +- Teleport role with access to maintaining `saml` resources. This is available in the default `editor` role. + +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) (!docs/pages/includes/enterprise/samlauthentication.mdx!) @@ -186,3 +207,5 @@ automatically in a browser. ## Troubleshooting (!docs/pages/includes/sso/loginerrortroubleshooting.mdx!) + + diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx index ca5ec60a35619..62c4871a9735b 100644 --- a/docs/pages/enterprise/sso/azuread.mdx +++ b/docs/pages/enterprise/sso/azuread.mdx @@ -12,21 +12,37 @@ SSH credentials to specific groups of users with a SAML Authentication Connector The following steps configure an example SAML authentication connector matching Azure AD groups with security roles. You can choose to configure other options. - - This guide requires either an Enterprise version of Teleport or a Teleport Cloud account. - + + This guide requires Teleport Cloud or Teleport Enterprise. + + View this guide as the user of another Teleport edition: + + + + + + + + + + + ## Prerequisites Before you get started you’ll need: -- Either an Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)) or a Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup/)). - An Azure AD admin account with access to creating non-gallery applications (P2 License) - To register one or more users in the directory - To create at least two security groups in Azure AD and assign one or more users to each group +- Teleport role with access to maintaining `saml` resources. This is available in the default `editor` role. + +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) (!docs/pages/includes/enterprise/samlauthentication.mdx!) @@ -61,7 +77,7 @@ Before you get started you’ll need: ![Edit Basic SAML Configuration](../../../img/azuread/azuread-7-editbasicsaml.png) 8. For **Entity ID** and **Reply URL**, enter the same proxy URL. - + For self-hosted deployments, the URL will be similar to `https://teleport.example.com:3080/v1/webapi/saml/acs`. For Teleport Cloud users, the URL will be similar to `https://mytenant.teleport.sh`. @@ -329,7 +345,7 @@ spec: private_key: | -----BEGIN RSA PRIVATE KEY----- New private key - -----END RSA PRIVATE KEY----- + -----END RSA PRIVATE KEY----- signing_key_pair: cert: | -----BEGIN CERTIFICATE----- @@ -346,7 +362,7 @@ version: v2 Update the connector: ```code -$ tctl create -f azure-out.yaml +$ tctl create -f azure-out.yaml ``` ### Activate token encryption @@ -387,3 +403,5 @@ Change the Name ID format to use email instead: ## Further reading - [Teleport Configuration Resources Reference](../../setup/reference/resources.mdx) + + \ No newline at end of file diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx index 44fba6f4c18fd..4e9826a2250b6 100644 --- a/docs/pages/enterprise/sso/gitlab.mdx +++ b/docs/pages/enterprise/sso/gitlab.mdx @@ -15,12 +15,33 @@ like: - Only members of "ProductionKubernetes" can access production Kubernetes clusters - Developers must never SSH into production servers. - - This guide requires a commercial edition of Teleport. - + + This guide requires Teleport Cloud or Teleport Enterprise. + + View this guide as the user of another Teleport edition: + + + + + + + + + + + + +## Prerequisites + +- At least two groups in GitLab with users assigned. +- Teleport role with access to maintaining `oidc` resources. This is available in the default `editor` role. + +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) ## Enable default OIDC authentication @@ -179,3 +200,5 @@ automatically in a browser). ## Troubleshooting (!docs/pages/includes/sso/loginerrortroubleshooting.mdx!) + + \ No newline at end of file diff --git a/docs/pages/enterprise/sso/google-workspace.mdx b/docs/pages/enterprise/sso/google-workspace.mdx index 49c78a32ae4c7..19b9410aa0c3b 100644 --- a/docs/pages/enterprise/sso/google-workspace.mdx +++ b/docs/pages/enterprise/sso/google-workspace.mdx @@ -5,9 +5,7 @@ h1: SSH Authentication with Google Workspace (G Suite) videoBanner: WTLWc6nnPfk --- -## Google Workspace as SSO for SSH - -This guide will cover how to configure [Google Workspace](https://workspace.google.com/) to be a +This guide will explain how to configure [Google Workspace](https://workspace.google.com/) to be a single sign-on (SSO) provider to issue SSH credentials to specific groups of users. When used in combination with role based access control (RBAC) it allows SSH administrators to define policies like: @@ -16,61 +14,37 @@ to define policies like: - Developers must never SSH into production servers. - ... and many others. - This guide requires Teleport Cloud or Teleport Enterprise. - - -## Prerequisites - -Before you get started you’ll need: - - - - -- A running Teleport cluster. For details on how to set this up, see our Enterprise - [Getting Started](/docs/enterprise/getting-started) guide. - -- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=), - which you can download by visiting the - [customer portal](https://dashboard.gravitational.com/web/login). + View this guide as the user of another Teleport edition: - ```code - $ tctl version - # Teleport v(=teleport.version=) go(=teleport.golang=) + + + + + + - $ tsh version - # Teleport v(=teleport.version=) go(=teleport.golang=) - ``` + - - - -- A Teleport Cloud account. If you do not have one, visit the - [sign up page](https://goteleport.com/signup/) to begin your free trial. - -- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=). - To download these tools, visit the [Downloads](/docs/cloud/downloads) page. + - ```code - $ tctl version - # Teleport v(=teleport.version=) go(=teleport.golang=) +## Prerequisites - $ tsh version - # Teleport v(=teleport.version=) go(=teleport.golang=) - ``` +Before you get started you’ll need: - - - A Google Workspace super administrator account. We recommend setting up a separate super admin account with 2FA as opposed to granting your daily user super admin privileges. - Ability to create a Google Cloud project, which requires signing up for Google Cloud. Note that this guide will not require using any paid Google Cloud services. - Ability to set up Google Workspace groups. +- Teleport role with access to maintaining `oidc` resources. This is available in the default `editor` role. + +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) ## Step 1/4. Enable default OIDC authentication @@ -346,3 +320,5 @@ automatically in a browser). - [Google Workspace Cloud Identity API](https://cloud.google.com/identity) - [Google Workspace Directory API](https://developers.google.com/admin-sdk/directory) - [How nested Google Workspace groups work](https://support.google.com/a/answer/167100?hl=en) + + \ No newline at end of file diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx index 0be966beb89da..1d07f4b1afb9d 100644 --- a/docs/pages/enterprise/sso/oidc.mdx +++ b/docs/pages/enterprise/sso/oidc.mdx @@ -4,7 +4,7 @@ description: How to configure SSH access with OAuth2 or OIDC (OpenID connect) us h1: OAuth2 / OIDC Authentication for SSH --- -This guide will cover how to configure an SSO provider using [OpenID Connect](http://openid.net/connect/) +This guide will explain how to configure an SSO provider using [OpenID Connect](http://openid.net/connect/) (also known as OIDC) to issue SSH credentials to a specific groups of users. When used in combination with role based access control (RBAC) it allows SSH administrators to define policies like: @@ -13,12 +13,33 @@ administrators to define policies like: - Developers must never SSH into production servers. - ... and many others. - - This guide requires an Enterprise edition of Teleport. - + + This guide requires Teleport Cloud or Teleport Enterprise. + + View this guide as the user of another Teleport edition: + + + + + + + + + + + + +## Prerequisites + +- Admin access to the SSO/IdP being integrated with users assigned to groups/roles. +- Teleport role with access to maintaining `oidc` resources. This is available in the default `editor` role. + +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) ## Enable default OIDC authentication @@ -66,10 +87,26 @@ the `user` role depending on the value returned for `group` within the claims. Create the connector: -```bsh + + +```code +# Log in to your Teleport cluster so you can use tctl remotely. +# You can also run tctl on your Auth Service host. +$ tsh login --proxy=teleport.example.com --user=myuser $ tctl create oidc-connector.yaml ``` + + + +```code +# Log in to your Teleport cluster so you can use tctl remotely +$ tsh login --proxy=mytenant.teleport.sh --user=myuser +$ tctl create oidc-connector.yaml +``` + + + ## Create Teleport Roles The next step is to define Teleport roles. They are created using the same @@ -221,3 +258,5 @@ identity provider if you are not automatically redirected. ## Troubleshooting (!docs/pages/includes/sso/loginerrortroubleshooting.mdx!) + + \ No newline at end of file diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx index 925517768d037..cf2f9848ede34 100644 --- a/docs/pages/enterprise/sso/okta.mdx +++ b/docs/pages/enterprise/sso/okta.mdx @@ -15,12 +15,33 @@ like: - Only members of "DBA" group can SSH into machines running PostgreSQL. - Developers must never SSH into production servers. - - This guide requires a commercial edition of Teleport. - + + This guide requires Teleport Cloud or Teleport Enterprise. + + View this guide as the user of another Teleport edition: + + + + + + + + + + + + +## Prerequisites + +- Okta account with admin access. Your account must include users and at least two groups. +- Teleport role with access to maintaining `saml` resources. This is available in the default `editor` role. + +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) (!docs/pages/includes/enterprise/samlauthentication.mdx!) @@ -106,11 +127,11 @@ $ tctl create okta-connector.yaml ## Create a Developer Teleport Role -We are going to create a new role that'll pull in external information from Okta. Notice -`{{external.username}}` login. It configures Teleport to look at *"username"* Okta claim -and use that field as an allowed login for each user. This example uses email as the -username format. The `email.local(external.trait)` function will remove the `@domain` -and just have the username prefix. +We are going to create a new role that'll pull in external information from Okta. Notice +`{{external.username}}` login. It configures Teleport to look at *"username"* Okta claim +and use that field as an allowed login for each user. This example uses email as the +username format. The `email.local(external.trait)` function will remove the `@domain` +and just have the username prefix. ```yaml kind: role @@ -169,3 +190,5 @@ automatically in a browser). ## Troubleshooting (!docs/pages/includes/sso/loginerrortroubleshooting.mdx!) + + \ No newline at end of file diff --git a/docs/pages/enterprise/sso/one-login.mdx b/docs/pages/enterprise/sso/one-login.mdx index f4e2b843d6985..9093bd462dc18 100644 --- a/docs/pages/enterprise/sso/one-login.mdx +++ b/docs/pages/enterprise/sso/one-login.mdx @@ -4,9 +4,7 @@ description: How to configure SSH access using One Login as an SSO provider h1: SSH Authentication with OneLogin --- -## Using OneLogin as a single sign-on (SSO) provider for SSH - -This guide will cover how to configure [OneLogin](https://www.onelogin.com/) to issue +This guide will explain how to configure [OneLogin](https://www.onelogin.com/) to issue SSH credentials to specific groups of users. When used in combination with role based access control (RBAC) it allows SSH administrators to define policies like: @@ -15,12 +13,33 @@ like: - Developers must never SSH into production servers. - ... and many others. - - This guide requires an Enterprise edition of Teleport. - + + This guide requires Teleport Cloud or Teleport Enterprise. + + View this guide as the user of another Teleport edition: + + + + + + + + + + + + +## Prerequisites + +- One Login account with admin access and users assigned to at least two groups. +- Teleport role with access to maintaining `saml` resources. This is available in the default `editor` role. + +(!docs/pages/includes/commercial-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) (!docs/pages/includes/enterprise/samlauthentication.mdx!) @@ -114,7 +133,7 @@ $ tctl create onelogin-connector.yaml ## Create a new Teleport Role We are going to create a new that'll use external username data from OneLogin -to map to a host linux login. +to map to a host linux login. In the below role, Devs are only allowed to login to nodes labelled with `access: relaxed` Teleport label. Developers can log in as either `ubuntu` to a username that @@ -175,3 +194,5 @@ automatically in a browser). ## Troubleshooting (!docs/pages/includes/sso/loginerrortroubleshooting.mdx!) + + \ No newline at end of file diff --git a/docs/pages/includes/commercial-prereqs-tabs.mdx b/docs/pages/includes/commercial-prereqs-tabs.mdx new file mode 100644 index 0000000000000..69d6c0cea7ec9 --- /dev/null +++ b/docs/pages/includes/commercial-prereqs-tabs.mdx @@ -0,0 +1,39 @@ + + + +- A running Teleport cluster. For details on how to set this up, see our Enterprise + [Getting Started](/docs/enterprise/getting-started) guide. + +- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=), + which you can download by visiting the + [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + + + +- A Teleport Cloud account. If you do not have one, visit the + [sign up page](https://goteleport.com/signup/) to begin your free trial. + +- The `tctl` admin tool and `tsh` client tool version >= (=cloud.version=). + To download these tools, visit the [Downloads](/docs/cloud/downloads) page. + + ```code + $ tctl version + # Teleport v(=cloud.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=cloud.version=) go(=teleport.golang=) + ``` + + + \ No newline at end of file diff --git a/docs/pages/includes/enterprise/oidcauthentication.mdx b/docs/pages/includes/enterprise/oidcauthentication.mdx index a609ee7c6d925..a901b50a5f13a 100644 --- a/docs/pages/includes/enterprise/oidcauthentication.mdx +++ b/docs/pages/includes/enterprise/oidcauthentication.mdx @@ -1,18 +1,30 @@ Configure Teleport to use OIDC authentication as the default instead of the local -user database. You can use Dynamic Resources for Teleport Cloud as well as self-hosted deployments. +user database. + + + +You can either edit your Teleport configuration file or create a dynamic +resource. + + - + + Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon. + ```yaml auth_service: authentication: type: oidc ``` + + Create a file called `cap.yaml`: + ```yaml kind: cluster_auth_preference metadata: diff --git a/docs/pages/includes/enterprise/samlauthentication.mdx b/docs/pages/includes/enterprise/samlauthentication.mdx index e553fb34baa93..d515376d0a164 100644 --- a/docs/pages/includes/enterprise/samlauthentication.mdx +++ b/docs/pages/includes/enterprise/samlauthentication.mdx @@ -1,10 +1,17 @@ ## Enable default SAML authentication Configure Teleport to use SAML authentication as the default instead of the local -user database. You can use Dynamic Resources for Teleport Cloud as well as self-hosted deployments. +user database. + + + +You can either edit your Teleport configuration file or create a dynamic +resource. + + - + Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon. ```yaml auth_service: diff --git a/docs/pages/setup/admin/github-sso.mdx b/docs/pages/setup/admin/github-sso.mdx index e68874f45dbd9..b36d784b84e9c 100644 --- a/docs/pages/setup/admin/github-sso.mdx +++ b/docs/pages/setup/admin/github-sso.mdx @@ -1,6 +1,6 @@ --- title: Set up Single Sign-On with GitHub -description: Setting up Github SSO +description: Setting up GitHub SSO videoBanner: XjgN2WWFCX8 --- @@ -11,6 +11,7 @@ Teleport. ## Prerequisites - A GitHub organization with at least one team. +- Teleport role with access to maintaining `github` resources for using `tctl` from the Desktop. This is available in the default `editor` role. (!docs/pages/includes/edition-prereqs-tabs.mdx!) @@ -67,7 +68,7 @@ GitHub OAuth App you created earlier. Teleport will request only the `read:org` OAuth scope. Read more about OAuth scopes in GitHub's documentation: -[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`: diff --git a/examples/resources/okta-connector.yaml b/examples/resources/okta-connector.yaml new file mode 100644 index 0000000000000..3ba2582fbb388 --- /dev/null +++ b/examples/resources/okta-connector.yaml @@ -0,0 +1,24 @@ +# connector.yaml +kind: saml +version: v2 +metadata: + name: corporate +spec: + # display allows to set the caption of the "login" button + # in the Web interface + display: "Okta" + + acs: https://teleport-proxy.example.com:3080/v1/webapi/saml/acs + attributes_to_roles: + - {name: "groups", value: "okta-admin", roles: ["access"]} + - {name: "groups", value: "okta-dev", roles: ["dev"]} + + # note that wildcards can also be used. the next line instructs Teleport + # to assign "access" role to any user who has the SAML attribute that begins with "admin": + - { name: "group", value: "admin*", roles: ["access"] } + # regular expressions with capture are also supported. the next line instructs Teleport + # to assign users to roles `admin-1` if his SAML "group" attribute equals 'ssh_admin_1': + - { name: "group", value: "^ssh_admin_(.*)$", roles: ["admin-$1"] } + + entity_descriptor: | + \ No newline at end of file