mirror of
https://github.com/gravitational/teleport
synced 2024-10-20 01:03:40 +00:00
Docs: Update ADFS SSO guide (#27650)
* 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:
parent
cb84fbf564
commit
f04468795b
BIN
docs/img/adfs-add-provider-trust.png
Normal file
BIN
docs/img/adfs-add-provider-trust.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 267 KiB |
BIN
docs/img/adfs-add-teleport-cert.png
Normal file
BIN
docs/img/adfs-add-teleport-cert.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 451 KiB |
|
@ -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
|
||||
|
|
|
@ -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` should be a mapping of the LDAP Attribute `E-Mail-Addresses` to
|
||||
`Name ID`.
|
||||
|
||||
![Name ID Configuration](../../../img/adfs-1.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)
|
||||
|
||||
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`.
|
||||
- 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!)
|
||||
|
|
Loading…
Reference in a new issue