Skip to main content

Create a SAML federation for AD FS

For your information

AD FS configuration in these instructions is described using Windows Server 2019 as an example; steps may differ for other versions.

Active Directory Federation Services (AD FS) must be configured in accordance with Microsoft guidelines for deploying AD FS clusters and proxy servers.

  1. If you do not have a certificate issued by AD FS, issue one.
  2. Create a federation on the Selectel side.
  3. Configure trust relationships.
  4. If, when creating the federation on the Selectel side, you selected the Sign authentication requests checkbox, upload the request signing certificate.
  5. Configure Claims Mapping.
  6. If you enabled automatic user creation when creating the federation on the Selectel side, configure user group mapping.

1. Issue a certificate

Issue a certificate on the AD FS side; for more information, see the Certificates instructions.

You can create a federation without a certificate and add it later, but without a certificate, the federation will not work.

2. Create a federation on the Selectel side

  1. In the control panel, in the top menu, click IAM.

  2. Go to the Federations section.

  3. Click Add federation and select SAML.

  4. In the Federation settings block:

    4.1. Enter the federation name.

    4.2. Optional: enter a description of the federation.

    4.3. Change the session lifetime or leave the default value (24 hours). The session defines the time during which a user will be authorized without needing to re-authenticate. You can specify a value from 1 to 720 hours.

  5. In the IdP settings block:

    5.1. In the IdP Issuer field, enter the identity provider identifier — http://<idp_url>/adfs/services/trust.

    Specify <idp_url> — your identity provider URL.

    5.2. Specify the link to the identity provider login page where users will be redirected for SSO authentication — https://<idp_url>/adfs/ls.

    Specify <idp_url> — your identity provider URL.

    5.3. To create users automatically upon their first login to the control panel via SSO, select the User auto-creation checkbox.

    If the checkbox is selected, you will need to configure user group mapping. Users will be created with the permissions you specify when configuring mapping. If you enable user auto-creation without configuring mapping, users will be created without permissions and will not have access to the control panel.

    If you do not select the User auto-creation checkbox, you will need to add users manually.

    5.4. Optional: to sign authentication requests, select the Sign authentication requests checkbox.

    5.5. Optional: to require users to authenticate via SSO on every login, select the Force authentication in IdP checkbox. If you do not select the checkbox, users will not need to authenticate as long as cookies are active.

  6. Click Continue. You will be redirected to the certificate addition page.

  7. Enter the certificate name.

  8. Paste the certificate that you issued in step 1. It must start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----.

  9. Click Add certificate → Finish adding federation.

3. Configure trust relationships

  1. On the AD FS server, open Server Manager.

  2. From the Tools menu, select AD FS Management.

  3. In the Actions section, select Relying Party Trust → Add Relying Party Trust.

  4. At the Welcome step:

    4.1. Select Claims aware.

    4.2. Click Start.

  5. At the Select Data Source step:

    5.1. Select Enter data about the relying party manually.

    5.2. Click Next.

  6. At the Specify Display Name step:

    6.1. In the Display name field, enter a name for the trust relationship.

    6.2. Click Next.

  7. At the Configure Certificate step:

    7.1. If you selected the Sign authentication requests checkbox when creating the federation on the Selectel side, download the request signing certificate and insert it.

    7.2. Click Next.

  8. At the Configure URL step:

    8.1. Select the Enable support for the SAML 2.0 WebSSO protocol checkbox.

    8.2. In the URL field, enter the address to which users will be redirected after authentication — https://api.selectel.ru/v1/auth/federations/<federation_id>/saml/acs. Specify <federation_id> — the federation ID on the Selectel side, which can be found in the control panel: in the top menu, click IAM → Federations → federation row → ID field.

    8.3. Click Next.

  9. At the Configure Identifiers step:

    9.1. In the URL field, enter the address — https://api.selectel.ru/v1/federations/saml/<federation_id>. Specify <federation_id> — the federation ID on the Selectel side, which can be found in the control panel: in the top menu, click IAM → Federations → federation row → ID field.

    9.2. Click Add → Next.

  10. At the Choose Access Control Policy step:

    10.1. Optional: specify who will have access to authentication using this federation. By default, the Permit for everyone policy is selected, which allows access for all users.

    10.2. Click Next.

  11. At the Ready to Add Trust step:

    11.1. Check the data.

    11.2. Click Close.

4. Upload a request signing certificate

A request signing certificate must be uploaded if during federation creation on the Selectel side in step 2 you selected the Sign authentication requests checkbox.

  1. On the AD FS server, open the Service → Relaying Party Trust folder.
  2. Click the created Relaying Party Trust.
  3. On the right, in the Actions section, in the block with the name of the created Relying Party Trust, click Properties.
  4. Open the Signature tab.
  5. Click Add.
  6. Upload the request signing certificate that you downloaded during trust relationship configuration in step 7.1.

5. Configure Claims Mapping

After successful authentication in AD FS, a SAML message will be sent to Selectel. To correctly identify the user, you need to map user data to the SAML message elements.

  1. On the AD FS server, open the Service → Relying Party Trusts folder.

  2. Right-click your Relying Party Trusts and select Edit Claim Issuance Policy.

  3. Click Add Rule.

  4. At the Choose Rule Type step:

    4.1. In the Claim rule template field, select Send LDAP Attributes as Claims.

    4.2. Click Next.

  5. At the Configure Claim Rule step:

    5.1. In the Claim rule name field, enter the rule name.

    5.2. In the Attribute store field, select Active Directory.

    5.3. In the LDAP Attribute column, specify what will be passed as the user identifier (External ID). You can specify:

    • User-Principal-Name — username;
    • E-Mail-Addresses — email.

    5.4. In the Outgoing Claim Type column, select Name ID.

  6. Click Finish → OK.

6. Configure user group mapping

Group mapping must be configured if you enabled automatic user creation when creating the federation on the Selectel side at step 2. Follow the Configure group mapping subsection of the User group mapping instructions.