Skip to main content

Create a SAML federation for AD FS

Last update:
For your information

The AD FS configuration in this instruction 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 recommendations 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 the relying party trust.
  4. If you checked the Sign authentication requests checkbox when creating the federation on the Selectel side, upload the certificate for signing requests.
  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 details, see the Certificates guide.

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

2. Create a federation on the Selectel side

  1. In the control panel, on 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 — props.IdIssuer.

    Specify <idp_url> — your identity provider URL.

    5.2. Specify the link to the identity provider login page, where users will be redirected to authenticate through SSO — props.Link.

    Specify <idp_url> — your identity provider URL.

    5.3. To have users created automatically upon their first login to the control panel via SSO, select the Auto-create users 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 auto-creation of users and do not configure mapping, users will be created without permissions and will not have access to the control panel.

    If you do not select the Auto-create users checkbox, users will need to be added manually.

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

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

  6. Click Continue. You will be redirected to the Add Certificate 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 the relying party trust

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

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

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

  4. At the Welcome stage:

    4.1. Select Claims aware.

    4.2. Click Start.

  5. At the Select Data Source stage:

    5.1. Select Enter data about the relying party manually.

    5.2. Click Next.

  6. At the Specify Display Name stage:

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

    6.2. Click Next.

  7. At the Configure Certificate stage:

    7.1. If you checked the Sign authentication requests checkbox when creating the federation on the Selectel side, download the certificate for signing requests and upload it.

    7.2. Click Next.

  8. At the Configure URL stage:

    8.1. Check 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.

    8.3. Click Next.

  9. At the Configure Identifiers stage:

    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.

    9.2. Click Add → Next.

  10. At the Choose Access Control Policy stage:

    10.1. Optional: specify who will have access to authentication via 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 stage:

    11.1. Verify the data.

    11.2. Click Close.

4. Upload the certificate for signing requests

The certificate for signing requests must be uploaded if you checked the Sign authentication requests checkbox when creating the federation on the Selectel side at step 2.

  1. On the AD FS server, open the Service → Relaying Party Trust.
  2. Click on the created Relying 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 certificate for signing requests that you downloaded when configuring the relying party trust at 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 SAML message elements.

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

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

  3. Click Add Rule.

  4. At the Choose Rule Type stage:

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

    4.2. Click Next.

  5. At the Configure Claim Rule stage:

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

    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 — user name;
    • E-Mail-Addresses — email.

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

  6. Click Finish → OK.

6. Configure user group mapping

You must configure group mapping if you enabled automatic user creation when creating the federation on the Selectel side at step 2. Use the Configure group mapping subsection of the User group mapping guide.