self-hosted/teleport
self-hosted/teleport
1
0
Fork 0
mirror of https://github.com/gravitational/teleport synced 2024-10-20 01:03:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Update ADFS SSO guide (#27650)

Browse source 
* Update ADFS SSO guide

* Update docs/pages/access-controls/sso/adfs.mdx

* Update docs/pages/access-controls/sso/adfs.mdx

Co-authored-by: Gus Luxton <gus@goteleport.com>

* update link for new heading

---------

Co-authored-by: Gus Luxton <gus@goteleport.com>
This commit is contained in:
Alex Fornuto 2023-06-14 16:27:11 -05:00 committed by GitHub
parent cb84fbf564
commit f04468795b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 62 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
docs/img/adfs-add-provider-trust.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 267 KiB

BIN
docs/img/adfs-add-teleport-cert.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 451 KiB

2
docs/pages/access-controls/sso.mdx
View file

@ -453,7 +453,7 @@ flow. These provider-specific changes can be enabled by setting the
values to match your identity provider:
- `adfs` (SAML): Required for compatibility with Active Directory (ADFS); refer
to the full [ADFS guide](./sso/adfs.mdx#create-teleport-roles) for details.
to the full [ADFS guide](./sso/adfs.mdx#step-23-create-teleport-roles) for details.
- `netiq` (OIDC): Used to enable NetIQ-specific ACR value processing; refer to
the [OIDC guide](./sso/oidc.mdx#optional-acr-values) for details.
- `ping` (SAML and OIDC): Required for compatibility with Ping Identity (including

99
docs/pages/access-controls/sso/adfs.mdx
View file

@ -1,15 +1,14 @@
---
title: SSO with Active Directory Federation Services
description: How to configure SSH access with Active Directory Federation Services using Teleport
description: How to configure Teleport access with Active Directory Federation Services
h1: Single Sign-On with 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
based access control (RBAC), it allows SSH administrators to define policies
like:
a single sign-on (SSO) provider to issue login credentials to specific groups
of users. When used in combination with role based access control (RBAC), it
allows Teleport administrators to define policies like:
- Only members of "DBA" group can SSH into machines running PostgreSQL.
- Developers must never SSH into production servers.
@ -23,42 +22,49 @@ like:
- (!docs/pages/includes/tctl.mdx!)
(!docs/pages/includes/enterprise/samlauthentication.mdx!)
## Configure ADFS
## Step 1/3. Configure ADFS
You'll need to configure ADFS to export claims about a user (Claims Provider
Trust in ADFS terminology) and you'll need to configure ADFS to trust
Teleport (a Relying Party Trust in ADFS terminology).
For Claims Provider Trust configuration, you'll need to specify at least the
following two incoming claims: `Name ID` and `Group`. `Name ID` should be a
mapping of the LDAP Attribute `E-Mail-Addresses` to `Name ID`. A group
membership claim should be used to map users to roles (for example to
separate normal users and admins).
For Claims Provider Trust configuration, open the **AD FS** management window.
Under **Claims Provider Trusts**, right-click on **Active Directory** and
select **Edit Claim Rules**. You'll need to specify at least the following two
incoming claims: `Name ID` and `Group`.
![Name ID Configuration](../../../img/adfs-1.png)
![Group Configuration](../../../img/adfs-2.png)
- `Name ID` should be a mapping of the LDAP Attribute `E-Mail-Addresses` to
`Name ID`.
In addition, if you are using dynamic roles (see below), it may be useful to map
the LDAP Attribute `SAM-Account-Name` to `Windows account name` and create
another mapping of `E-Mail-Addresses` to `UPN`.
![Name ID Configuration](../../../img/adfs-1.png)
![WAN Configuration](../../../img/adfs-3.png)
![UPN Configuration](../../../img/adfs-4.png)
- A group membership claim should be used to map users to roles (for example to
separate normal users and admins).
![Group Configuration](../../../img/adfs-2.png)
- If you are using dynamic roles (see below), it may be useful to map the LDAP
Attribute `SAM-Account-Name` to `Windows account name`:
![WAN Configuration](../../../img/adfs-3.png)
- And create another mapping of `E-Mail-Addresses` to `UPN`:
![UPN Configuration](../../../img/adfs-4.png)
You'll also need to create a Relying Party Trust. Use the below information to
help guide you through the Wizard. Note that for development purposes we recommend
using `https://localhost:3080/v1/webapi/saml/acs` as the Assertion Consumer
Service (ACS) URL, but for production you'll want to change this to a domain
that can be accessed by other users as well.
help guide you through the Wizard.
- Create a claims aware trust.
- Create a Relaying Party Trust:
![Add a Claims Provider Trust](../../../img/adfs-add-provider-trust.png)
- Enter data about the relying party manually.
- Set the display name to something along the lines of `Teleport`.
- Skip the token encryption certificate.
- Select *"Enable support for SAML 2.0 Web SSO protocol"* and set the URL to `https://localhost:3080/v1/webapi/saml/acs`.
- Set the relying party trust identifier to `https://localhost:3080/v1/webapi/saml/acs` as well.
- Select *"Enable support for SAML 2.0 Web SSO protocol"* and set the URL to
`https://teleport.example.com/v1/webapi/saml/acs`, replacing the domain name
with your Teleport proxy URL.
- Set the relying party trust identifier to
`https://teleport.example.com/v1/webapi/saml/acs` as well.
- For access control policy select *"Permit everyone"*.
Once the Relying Party Trust has been created, update the Claim Issuance Policy
@ -72,7 +78,7 @@ associated with it. To check this open Server Manager then
*"Tools -> Active Directory Users and Computers"* and select the user and right
click and open properties. Make sure the email address field is filled out.
## Create Teleport roles
## Step 2/3. Create Teleport roles
Let's create two Teleport roles: one for administrators and the other for
normal users. You can create them using the `tctl create {file name}` CLI command
@ -121,17 +127,24 @@ This role declares:
re-configure the Teleport cluster.
The login
`{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}`
<nobr>`{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}`</nobr>
configures Teleport to look at the
`http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname`
ADFS claim and use that field as an allowed login for each user. Note the
double quotes (`"`) and square brackets (`[]`) around the claim name—these are
important.
Next, create a SAML connector [resource](../../reference/resources.mdx):
## Step 3/3. Create a SAML connector
```yaml
(!examples/resources/adfs-connector.yaml!)
Create a SAML connector resource using `tctl`:
```code
$ tctl sso configure saml --acs https://teleport.example.com/v1/webapi/saml/acs \
--preset adfs \
--entity-descriptor https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml \
--attributes-to-roles http://schemas.xmlsoap.org/claims/Group,Administrators,editor \
--attributes-to-roles http://schemas.xmlsoap.org/claims/Group,Users,access \
> adfs.yaml
```
The `acs` field should match the value you set in ADFS earlier and you can
@ -143,19 +156,27 @@ name is `http://schemas.xmlsoap.org/claims/Group` with a value of *"admins"*
to the *"admin"* role. Groups with the value *"users"* is being mapped to the
*"users"* role.
## Export the signing key
You can test this connector before applying it (`cat adfs.yaml | tctl sso test`),
but until we complete the next step the authentication process will not complete.
Apply the connector:
```code
$ tctl create -f adfs.yaml
```
### Export the signing key
For the last step, you'll need to export the signing key:
```code
$ tctl saml export adfs
$ tctl saml export adfs > saml.cer
```
Save the output to a file named `saml.crt`, return back to ADFS, open the
"Relying Party Trust" and add this file as one of the signature verification
certificates.
Copy `saml.cer`, to ADFS server, open the "Relying Party Trust" and add this
file as one of the signature verification certificates:
## Testing
![adfs-add-teleport-cert.png](../../../img/adfs-add-teleport-cert.png)
The Web UI will now contain a new button: "Login with MS Active Directory". The CLI is
the same as before:
@ -175,6 +196,8 @@ automatically in a browser.
can be passed via `tsh login --auth=connector_name`
</Admonition>
(!docs/pages/includes/enterprise/samlauthentication.mdx!)
## Troubleshooting
(!docs/pages/includes/sso/loginerrortroubleshooting.mdx!)