Updated Auth Connectors Examples and Documentation.

* Update all connector YAML configs
* User <cluster-url> as standard
* Leverage markdown_include.include
* Include screenshots for Buttons based on Display.

build.assets/docs.dockerfile

@@ -1,4 +1,4 @@
-FROM quay.io/gravitational/mkdocs-base:1.0.4
+FROM quay.io/gravitational/mkdocs-base:1.0.3-1
 
 ARG UID
 ARG GID

docs/4.2.yaml

@@ -15,7 +15,8 @@ theme:
     custom_dir: 'theme/'
     include_search_page: true
 markdown_extensions:
-  - markdown_include.include
+  - markdown_include.include:
+      base_path: '../'
   - admonition
   - def_list
   - footnotes

docs/4.2/enterprise/ssh_sso.md

@@ -76,7 +76,7 @@ metadata:
 spec:
   # display allows to set the caption of the "login" button
   # in the Web interface
-  display: "Login with Okta SSO"
+  display: "Okta"
 
   acs: https://teleport-proxy.example.com:3080/v1/webapi/saml/acs
   attributes_to_roles:
@@ -153,6 +153,17 @@ SAML and OIDC types:
 * [SSH Authentication with ADFS](../ssh_adfs.md)
 * [SSH Authentication with OAuth2 / OpenID Connect](../oidc.md)
 
+## SSO Customization 
+
+| Provider | YAML | Example |
+|----------|------|---------|
+| Github |`display: Github`|![github](../img/teleport-sso/github.png)|
+| Microsoft |`display: Microsoft`|![microsoft](../img/teleport-sso/microsoft.png)|
+| Google |`display: Google`|![google](../img/teleport-sso/google.png)|
+| BitBucket | `display: Bitbucket` | ![bitbucket](../img/teleport-sso/bitbucket.png)|
+| OpenID | `display: OpenID` | ![bitbucket](../img/teleport-sso/openId.png)|
+| Custom Provider | `display: Homegrown SSO` | ![bitbucket](../img/teleport-sso/custom-content.png)|
+
 ## Troubleshooting
 
 Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator

docs/4.2/oidc.md

@@ -60,37 +60,10 @@ from the identity provider then mapping the value to either to `admin` role or
 the `user` role depending on the value returned for `group` within the claims.
 
 ```yaml
-# oidc-connector.yaml
-kind: oidc
-version: v2
-metadata:
-  name: "example-oidc-connector"
-spec:
-  # display allows to set the caption of the "login" button
-  # in the Web interface
-  display: "Login with Example"
-  issuer_url: "https://oidc.example.com"
-  client_id: "xxxxxxxx.example.com"
-  client_secret: "zzzzzzzzzzzzzzzzzzzzzzzz"
-  redirect_url: "https://teleport-proxy.example.com:3080/v1/webapi/oidc/callback"
-
-  # scope instructs Teleport to query for 'group' scope to retrieve
-  # user's group membership
-  scope: ["group"]
-
-  # once Teleport retrieves the user's groups, this section configures
-  # the mapping from groups to Teleport roles
-  claims_to_roles:
-     - { claim: "group", value: "admin", roles: ["admin"] }
-     - { claim: "group", value: "user", roles: ["user"] }
-     # note that wildcards can also be used. the next line instructs Teleport
-     # to assign "admin" role to any user who has the OIDC claim that begins with "admin":
-     - { claim: "group", value: "admin*", roles: ["admin"] }
-     # regular expressions with capture are also supported. the next line instructs Teleport
-     # to assign users to roles `admin-1` if his OIDC "group" claim equals 'ssh_admin_1':
-     - { claim: "group", value: "^ssh_admin_(.*)$", roles: ["admin-$1"] }
+{!examples/resources/oidc-connector.yaml!}
 ```
 
+
 Create the connector:
 
 ```bsh

docs/4.2/ssh_adfs.md

@@ -10,7 +10,9 @@ like:
 * Developers must never SSH into production servers.
 * ... and many others.
 
-!!! warning "Version Warning":
+!!! warning "Version Warning"
+
+
     This guide requires a commercial edition of Teleport. The open source
     edition of Teleport only supports [Github](admin-guide.md#github-oauth-20) as
     an SSO provider.
@@ -128,26 +130,10 @@ This role declares:
 Next, create a SAML connector [resource](admin-guide.md#resources):
 
 ```yaml
-kind: saml
-version: v2
-metadata:
-  name: "adfs"
-spec:
-  # display allows to set the caption of the "login" button
-  # in the Web interface
-  display: "MS Active Directory"
-  provider: "adfs"
-  acs: "https://localhost:3080/v1/webapi/saml/acs"
-  entity_descriptor_url: "https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml"
-  attributes_to_roles:
-    - name: "http://schemas.xmlsoap.org/claims/Group"
-      value: "teleadmins"
-      roles: ["admins"]
-    - name: "http://schemas.xmlsoap.org/claims/Group"
-      value: "teleusers"
-      roles: ["users"]
+{!examples/resources/adfs-connector.yaml!}
 ```
 
+
 The `acs` field should match the value you set in ADFS earlier and you can
 obtain the `entity_descriptor_url` from ADFS under _"ADFS -> Service -> Endpoints -> Metadata"_.
 

docs/4.2/ssh_gsuite.md

@@ -85,26 +85,7 @@ Now, create a OIDC connector [resource](admin-guide.md#resources).
 Write down this template as `gsuite-connector.yaml`:
 
 ```yaml
-kind: oidc
-metadata:
-  name: gsuite
-spec:
-  claims_to_roles:
-  - claim: groups
-    roles:
-    - admin
-    value: dev@practice.io
-  client_id: GSUITE_CLIENT_ID.apps.googleusercontent.com
-  client_secret: OAUTH_CLIENT_SECRET
-  display: G Suite Group
-  google_admin_email: GSUITE_EMAIL
-  google_service_account_uri: file:///var/lib/teleport/gsuite-creds.json
-  issuer_url: https://accounts.google.com
-  redirect_url: https://TELEPORT_PROXY:3080/v1/webapi/oidc/callback
-  scope:
-  - openid
-  - email
-version: v2
+{!examples/resources/gsuite-connector.yaml!}
 ```
 
 Create the connector using `tctl` tool:

docs/4.2/ssh_okta.md

@@ -50,17 +50,13 @@ statements (special signed metadata exposed via a SAML XML response).
 GENERAL
 
 - Single sign on URL `https://teleport-proxy.example.com:3080/v1/webapi/saml/acs`
-
 - Audience URI (SP Entity ID)`https://teleport-proxy.example.com:3080/v1/webapi/saml/acs`
-
 - Name ID format `EmailAddress`
-
 - Application username `Okta username`
 
 GROUP ATTRIBUTE STATEMENTS
 
 - Name: `groups` | Name format: `Unspecified`
-
 -  Filter: `Matches regex` |  `.*`
 
 ![Configure APP](img/okta-saml-3.png)
@@ -96,7 +92,7 @@ metadata:
 spec:
   # display allows to set the caption of the "login" button
   # in the Web interface
-  display: "Login with Okta SSO"
+  display: "Okta SSO"
 
   acs: https://teleport-proxy.example.com:3080/v1/webapi/saml/acs
   attributes_to_roles:
@@ -106,6 +102,7 @@ spec:
     <paste SAML XML contents here>
 ```
 
+
 Create the connector using `tctl` tool:
 
 ```bsh

docs/4.2/ssh_one_login.md

@@ -66,23 +66,7 @@ Now, create a SAML connector [resource](admin-guide.md#resources).
 Write down this template as `onelogin-connector.yaml`:
 
 ```yaml
-kind: saml
-version: v2
-metadata:
-  name: OneLogin
-  namespace: default
-spec:
-  acs: https://teleport.example.com/v1/webapi/saml/acs
-  attributes_to_roles:
-    - {name: "groups", value: "admin", roles: ["admin"]}
-    - {name: "groups", value: "dev", roles: ["dev"]}
-  display: OneLogin
-  issuer: https://app.onelogin.com/saml/metadata/123456
-  sso: https://mycompany.onelogin.com/trust/saml2/http-redirect/sso/123456
-  cert: |
-    -----BEGIN CERTIFICATE-----
-    ... do not forget to indent the value
-    -----END CERTIFICATE-----
+{!examples/resources/onelogin-connector.yaml!}
 ```
 
 To fill in the fields, open `SSO` tab:
@@ -95,7 +79,7 @@ To fill in the fields, open `SSO` tab:
 
 !!! tip "Important"
 
-    Make sure to replace `http-post` with `http-redirect`!
+    Make sure to replace `http-post` with `http-redirect`.
 
 * `cert` - download certificate, by clicking "view details link" and add to `cert` section
 
@@ -114,7 +98,7 @@ root and is capable of administrating the cluster and non-privileged dev.
 
 ```yaml
 kind: role
-version: v3"
+version: v3
 metadata:
   name: admin
 spec:

examples/resources/adfs-connector.yaml

@@ -3,22 +3,26 @@
 kind: saml
 version: v2
 metadata:
-  name: "adfs_connector"
+  name: adfs_connector
 spec:
   # display allows to set the caption of the "login" button
   # in the Web interface
-  display: "Login with SSO"
+  # Using the work 'Microsoft' will show the windows symbol in the UI. 
+  display: Microsoft
 
   # "adfs" provider setting tells Teleport that this SAML connector uses ADFS
   # as a provider
-  provider: "adfs"
+  provider: adfs
 
   # entity_descriptor XML can either be copied into connector or fetched from a URL
   entity_descriptor: |
     <EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
     ...
     </md:EntityDescriptor>
-  entity_descriptor_url: "https://example.com"
+  # entity_descriptor_url is commented out, as only one is required to setup adfs.
+  # if you're running Teleport in FIPS mode entity_descriptor_url with Azure AD may 
+  # fail 
+  #entity_descriptor_url: "https://example.com"
 
   # issuer typically comes from the "entity_descriptor" but can be overridden here
   issuer: "foo"
@@ -30,11 +34,11 @@ spec:
     ...
     -----END RSA PRIVATE KEY-----
 
-  acs: "https://teleport-proxy.example.com:3080/v1/webapi/saml/acs"
+  acs: "https://<cluster-url>.example.com:3080/v1/webapi/saml/acs"
   # if "service_provider_issuer" is not set, comes from "acs"
-  service_provider_issuer: "https://teleport-proxy.example.com:3080/v1/webapi/saml/acs"
+  service_provider_issuer: "https://<cluster-url>.example.com:3080/v1/webapi/saml/acs"
   # if "audience" is not set, comes from "acs"
-  audience: "https://teleport-proxy.example.com:3080/v1/webapi/saml/acs"
+  audience: "https://<cluster-url>.example.com:3080/v1/webapi/saml/acs"
 
   # if "signing_key_pair" is not set, teleport will generate a self signed
   # signing key pair
@@ -50,8 +54,8 @@ spec:
 
   attributes_to_roles:
     - name: "http://schemas.xmlsoap.org/claims/Group"
-      value: "teleadmins"
-      roles: ["admins"]
+      value: "Administrators"
+      roles: ["admin"]
     - name: "http://schemas.xmlsoap.org/claims/Group"
-      value: "teleusers"
-      roles: ["users"]
+      value: "Users"
+      roles: ["user"]

examples/resources/admin.yaml

@@ -0,0 +1,31 @@
+#
+# Example: Default Admin Role
+#
+kind: role
+metadata:
+  name: admin
+spec:
+  allow:
+    kubernetes_groups:
+    - '{{internal.kubernetes_groups}}'
+    logins:
+    - '{{internal.logins}}'
+    - root
+    node_labels:
+      '*': '*'
+    rules:
+    - resources:
+      - '*'
+      verbs:
+      - '*'
+  deny:
+    logins: null
+  options:
+    cert_format: standard
+    enhanced_recording:
+    - command
+    - network
+    forward_agent: true
+    max_session_ttl: 30h0m0s
+    port_forwarding: true
+version: v3

examples/resources/github.yaml

@@ -0,0 +1,21 @@
+kind: github
+version: v3
+metadata:
+  name: new_github_connector
+spec:
+  # Github OAuth app client ID
+  client_id: <client-id>
+  # Github OAuth app client secret
+  client_secret: <client-secret>
+  # Github will make a callback to this URL after successful authentication
+  # cluster-url is the address the cluster UI is reachable at
+  redirect_url: "https://<cluster-url>/portalapi/v1/github/callback"
+  # connector display name that will be appended to the title of "Login with"
+  # button on the cluster login screen so it will say "Login with Github"
+  display: Github
+  # mapping of Github team memberships to Teleport cluster roles
+  teams_to_logins:
+    - organization: <github-org>
+      team: admins
+      logins:
+        - "admin"

examples/resources/gsuite-connector.yaml

@@ -0,0 +1,20 @@
+kind: oidc
+metadata:
+  name: gsuite
+spec:
+  claims_to_roles:
+  - claim: groups
+    roles:
+    - admin
+    value: <gsuite-group-email>
+  client_id: <GSUITE_CLIENT_ID>.apps.googleusercontent.com
+  client_secret: <OAUTH_CLIENT_SECRET>
+  display: Google
+  google_admin_email: <GSUITE_EMAIL>
+  google_service_account_uri: file:///var/lib/teleport/gsuite-creds.json
+  issuer_url: https://accounts.google.com
+  redirect_url: https://<cluster-url>:3080/v1/webapi/oidc/callback
+  scope:
+  - openid
+  - email
+version: v2

examples/resources/oidc-connector.yaml

@@ -1,34 +1,43 @@
+#
+# Example resource for an OIDC connector
+# We recommend using OIDC for G Suite, Auth0 and Keycloak
+#
 kind: oidc
 version: v2
 metadata:
-  name: "oidc_connector"
+  name: oidc_connector
 spec:
   # name of the OIDC provider, like "keycloak".
   provider: example
 
   # This value will be used in the Web UI for "[login with example]" button
-  display: "Login with Example"
+  # button on the cluster login screen so it will say "Login with Google". 
+  # Teleport will provide custom CSS for 'Google'. 
+  display: Google
 
   # these values must come from the OIDC provider configuration
-  client_id: client.example.com
-  client_secret: secret-secret
-  issuer_url: https://oidc.example.com
+  client_id: <client id>
+  client_secret: <client secret>
+  issuer_url: https://<External-ODIC-url>
 
   # the redirect URL must be accessible by all users 
-  redirect_url: https://teleport-proxy.example.com:3080/v1/webapi/oidc/callback
+  redirect_url: https://<cluster-url>.example.com:3080/v1/webapi/oidc/callback
   redirect_timeout: 90s
 
   # acr_values are optional (for OIDC providers that require them).
-  acr_values: foo
+  # acr_values: foo
 
   # this section tells Teleport to evaluate claim "group" and:
   #  - if the claim value is "admin", give a user "admin" role
   #  - if the claim value is "user", give a user "user" role
   scope: ["group"]
+  # the mapping from groups to Teleport roles
   claims_to_roles:
-    - claim: "group"
-      value: "admin"
-      roles: ["admin"]
-    - claim: "group"
-      value: "user"
-      roles: ["user"]
+     - { claim: "group", value: "admin", roles: ["admin"] }
+     - { claim: "group", value: "user", roles: ["user"] }
+     # note that wildcards can also be used. the next line instructs Teleport
+     # to assign "admin" role to any user who has the OIDC claim that begins with "admin":
+     - { claim: "group", value: "admin*", roles: ["admin"] }
+     # regular expressions with capture are also supported. the next line instructs Teleport
+     # to assign users to roles `admin-1` if his OIDC "group" claim equals 'ssh_admin_1':
+     - { claim: "group", value: "^ssh_admin_(.*)$", roles: ["admin-$1"] }

examples/resources/onelogin-connector.yaml

@@ -0,0 +1,16 @@
+kind: saml
+version: v2
+metadata:
+  name: OneLogin
+spec:
+  acs: https://<cluster-url>/v1/webapi/saml/acs
+  attributes_to_roles:
+    - {name: "groups", value: "admin", roles: ["admin"]}
+    - {name: "groups", value: "dev", roles: ["dev"]}
+  display: OneLogin
+  issuer: https://app.onelogin.com/saml/metadata/123456
+  sso: https://mycompany.onelogin.com/trust/saml2/http-redirect/sso/123456
+  cert: |
+    -----BEGIN CERTIFICATE-----
+    ... do not forget to indent the value
+    -----END CERTIFICATE-----

examples/resources/role.yaml

@@ -16,6 +16,12 @@ spec:
     # forward_agent turns on/off SSH agent forwarding
     forward_agent: true
 
+    cert_format: standard
+
+    enhanced_recording:
+    - command
+    - network
+
   # allow section declares a list of resource/verb combinations that are
   # allowed for the users of this role. by default nothing is allowed.
   allow:

examples/resources/saml-connector.yaml

@@ -1,4 +1,4 @@
-# 
+#
 # Example resource for a SAML connector
 # This connector can be used for SAML endpoints like Okta
 #
@@ -8,17 +8,18 @@ metadata:
   # the name of the connector
   name: new_saml_connector
 spec:
-  # display allows to set the caption of the "login" button
-  # in the Web interface
-  display: "Login with SSO"
-  # acs is the Assertion Consumer Service URL. This should be the address of
-  # the Teleport proxy that your identity provider will communicate with.
-  acs: https://teleport-proxy.example.com:3080/v1/webapi/saml/acs
+  # connector display name that will be appended to the title of "Login with"
+  # button on the cluster login screen so it will say "Login with Okta"
+  display: Okta
+  # SAML provider will make a callback to this URL after successful authentication
+  # cluster-url is the address the cluster UI is reachable at
+  acs: https://<cluster-url>/portalapi/v1/saml/callback
   attributes_to_roles:
     - {name: "groups", value: "okta-admin", roles: ["admin"]}
     - {name: "groups", value: "okta-dev", roles: ["dev"]}
   # Note that the entire XML document is indented by 4 spaces. This is
   # required because the pipe symbol indicates what follows is raw text.
+  # Below is an Example. Replace with your XML
   entity_descriptor: |
     <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.example.com/00000000000000000000">
       <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

examples/resources/trusted_cluster.yaml

@@ -11,11 +11,11 @@ spec:
   # this field allows to create tunnels that are disabled, but can be enabled later.
   # this is the only field that can be changed later.
   enabled: true
-  # the token expected by the "main" cluster:
+  # the token expected by the "root" cluster:
   token: secret-token-to-add-new-clusters
   # the address in 'host:port' form of the reverse tunnel listening port on the
-  # "master" proxy server:
-  tunnel_addr: proxy.main:3024
+  # "root" proxy server:
+  tunnel_addr: <root-cluster-url>:3024
   # the address in 'host:port' form of the web listening port on the
-  # "master" proxy server:
-  web_proxy_addr: proxy.main:3080
+  # "root" proxy server:
+  web_proxy_addr: <root-cluster-url>:3080

examples/resources/trusted_cluster_enterprise.yaml

@@ -12,14 +12,14 @@ spec:
   # this field allows to create tunnels that are disabled, but can be enabled later.
   # this is the only field that can be changed later.
   enabled: true
-  # the token expected by the "main" cluster:
+  # the token expected by the "root" cluster:
   token: secret-token-to-add-new-clusters
   # the address in 'host:port' form of the reverse tunnel listening port on the
-  # "master" proxy server:
-  tunnel_addr: proxy.main:3024
+  # "root" proxy server:
+  tunnel_addr: <cluster-url>:3024
   # the address in 'host:port' form of the web listening port on the
-  # "master" proxy server:
-  web_proxy_addr: proxy.main:3080
+  # "root" proxy server:
+  web_proxy_addr: <cluster-url>:3080
   # RBAC for trusted clusters: it says that the users who have the role 'admin'
   # on a remote cluster will be mapped to the local role 'guest'
   role_map:

examples/resources/user.yaml

@@ -0,0 +1,60 @@
+#
+# Example: Example User Role with less permissions
+#
+kind: role
+metadata:
+  name: user
+spec:
+  allow:
+    kubernetes_groups:
+    - '{{internal.kubernetes_groups}}'
+    logins:
+    - '{{internal.logins}}'
+    node_labels:
+    # This example user can only log into staging.
+      environment: staging
+    rules:
+    - resources:
+      - role
+      verbs:
+      - list
+      - create
+      - read
+    - resources:
+      - session
+      verbs:
+      - list
+      - read
+    - resources:
+      - trusted_cluster
+      verbs:
+      - connect
+      - list
+      - read
+  deny:
+    logins: null
+    rules:
+    - resources:
+      - role
+      verbs:
+        - update
+        - delete
+    - resources:
+      - auth_connector
+      verbs:
+      - '*'
+    - resources:
+      - trusted_cluster
+      verbs:
+      - create
+      - update
+      - delete
+  options:
+    cert_format: standard
+    enhanced_recording:
+    - command
+    - network
+    forward_agent: true
+    max_session_ttl: 30h0m0s
+    port_forwarding: true
+version: v3