diff --git a/docs/img/adfs-add-provider-trust.png b/docs/img/adfs-add-provider-trust.png new file mode 100644 index 0000000000000..4822b79ed16f8 Binary files /dev/null and b/docs/img/adfs-add-provider-trust.png differ diff --git a/docs/img/adfs-add-teleport-cert.png b/docs/img/adfs-add-teleport-cert.png new file mode 100644 index 0000000000000..7b38942ee2d5a Binary files /dev/null and b/docs/img/adfs-add-teleport-cert.png differ diff --git a/docs/pages/access-controls/sso.mdx b/docs/pages/access-controls/sso.mdx index 75b1c11997362..301f98989defb 100644 --- a/docs/pages/access-controls/sso.mdx +++ b/docs/pages/access-controls/sso.mdx @@ -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 diff --git a/docs/pages/access-controls/sso/adfs.mdx b/docs/pages/access-controls/sso/adfs.mdx index 7d3c75fd3183a..e45bc32e71ec3 100644 --- a/docs/pages/access-controls/sso/adfs.mdx +++ b/docs/pages/access-controls/sso/adfs.mdx @@ -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). -![Name ID Configuration](../../../img/adfs-1.png) -![Group Configuration](../../../img/adfs-2.png) + ![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) -![UPN Configuration](../../../img/adfs-4.png) + ![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"]}}` +`{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}` 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` +(!docs/pages/includes/enterprise/samlauthentication.mdx!) + ## Troubleshooting (!docs/pages/includes/sso/loginerrortroubleshooting.mdx!)