SAML Configuration Example: ADFS


SAML Configuration Example: ADFS

This example illustrates how to configure a Windows Server 2008 R2 running SAML 2.0 ADFS as an IdP for the Zscaler service. It assumes that ADFS 2.0 is already installed on the Windows server. Refer to the Windows ADFS documentation for additional information about the steps in the example.

Prerequisites

Ensure that you have the following before you start configuring the ADFS server:

  • ADFS account with admin privileges
  • The Zscaler public certificate (See How do I configure SAML? for instructions on how to download the certificate from the admin portal.)

Configuring the Zscaler Service in ADFS

To add the Zscaler to ADFS, go to Start > ADFS Management 2.0 to launch the ADFS management application and complete the following tasks.

  1. Add the Zscaler service as a relying party trust.
  2. Add the signature verification certificate from Zscaler.
  3. Add a claim rule, which is a statement that provides information about a user. It is used by the Zscaler service to determine whether a user is allowed access.
  4. Export the certificate from ADFS.
  5. Optionally, restrict the groups that are federated.
  6. Test the Configuration.

See below for instructions on each task.

Adding a Relying Party Trust

In ADFS, a relying party is a Federation Service or application that requests and consumes claims from a claims provider in a particular transaction. Configure the Zscaler service as a relying party trust.

  1. In the ADFS 2.0 Management window, open the Trust Relationships folder, and then right-click Relying Party Trust to add a relying party trust.
    See image.
  2. When the Add Relying Party Trust wizard appears, click Start.
    See image.
  3. In Select Data Source, choose Enter data about the relying party manually and click Next.
    See image.
  4. In Specify Display Name, enter a display name for the Zscaler service, such as Zscaler-SAML, and then click Next.
  5. In Choose Profile, select AD FS 2.0 Profile, and click Next.
  6. In Configure Certificate, click Next to and proceed to the next step.
  7. In Configure URL, select Enable support for the SAML 2.0 WebSSO protocol and enter the Zscaler SSO URL in the following format: https://login.zscaler_cloud:443/sfc_sso. The zscaler_cloud depends on the Zscaler administrative URL. If your organization logs into https://admin.zscalerone.net, then the Zscaler SSO URL is https://login.zscalerone.net:443/sfc_sso
    See image.
  8. In Configure Identifiers, enter the Zscaler service domain name. This depends on the domain name in the administrative URL you use to log in to the service. For example, if you log in to https://admin.zscalertwo.net, then enter zscalertwo.net, and then click Add to add it to the list of identifiers, as shown in the following figure. The domain name must be in lower case.
    See image.
  9. In Choose Issuance Authorization Rules, select Permit all users to access this relying party and click Next.
  10. In Ready to Add Trust, the wizard displays the configured settings. Click Next.
  11. Click Finish to add the relying party trust to the database. Clear the option to open the Edit Claim Rules dialog. Before you define a claim rule, you will first upload the Zscaler certificate.

Uploading the Zscaler SAML Certificate

Edit the Zscaler SAML configuration on the ADFS server so you can add the Zscaler signature verification certificate:

  1. In the ADFS 2.0 Management window, open the Trust Relationships > Relying Party Trusts folder.
  2. Right-click the relying party trust that you created and open its Properties.
  3. Do the following:
    • In the Signature tab, click Add, navigate to the Zscaler certificate, and then click Open.
      See image.
    • In the Advanced tab, select SHA-1 from the Secure hash algorithm menu, and then click OK.

Adding a Claim Rule

Configure the SAML Assertions to be federated to Zscaler for identifying the user, which includes the group membership, department and full name parameters.

To add a claim rule:

  1. In the ADFS 2.0 Management window, open the Trust Relationships > Relying Party Trusts folder.
  2. Right-click the relying party trust that you created and select Edit Claim Rules.
  3. When the Edit Claim Rules window appears, click Add Rule.
    See image.
  4. In Choose Rule Type of the Add Transform Claim Rule wizard, select Send LDAP Attributes as Claims as the claim rule template so the claims contain LDAP attribute values from the attribute store, AD. Then click Next.
    See image.
  5. In Configure Claim Rule, do the following and click Next:
    • Enter a name for the claim rule.
    • From the Attribute Store menu, choose Active Directory.
    • Map the LDAP attributes that represent the user's login name, full name, department, and group to fields in the outgoing claim.
      • Map the LDAP attribute for login name to an outgoing claim type.

From the LDAP Attribute column, select the attribute for the login name. Select SAM-Account-Name only if you have one domain hosted by the Zscaler service. Otherwise, select User-Principal-Name. Selecting E-Mail-Addresses is not recommended because users can have multiple email addresses and this could result in multiple user credentials in the Zscaler service.

From the Outgoing Claim Type column, select Name ID. (Note that Name ID is entered as two words, with a space in between them.)

  • Map the LDAP attribute for full name to an outgoing claim type. Select Display-Name from the LDAP Attribute column, and type in displayName in the Outgoing Claim Type column.
  • Map the LDAP attribute for department to an outgoing claim type. This attribute is used to populate the Department field in the reports produced by the Zscaler service. 

You can specify any attribute that identifies the information that should appear in the Department field. For example, you can choose Department or Organizational-Unit from the LDAP Attribute column. Type in department in the Outgoing Claim Type column.

  • Map the LDAP attribute for group to an outgoing claim type. Select Token Groups – Unqualified Names from the LDAP Attribute column, and type in memberOf in the Outgoing Claim Type column.

Using the Is-Member-Of-DL attribute from the LDAP Attribute column is not advisable, as the groups can be displayed in the form of LDAP paths instead of just the group name. 
See image.

  1. When the wizard displays the newly added claim rule in the list, click OK
    See image.

Exporting the Certificate

To export the certificate that you will import to the Zscaler service:

  1. In the ADFS 2.0 Management window, open the Service > Certificates folder, right-click the Token-signing certificate, and click View Certificate.
    See image.
  2. In the Certificate window, go to the Details tab and click Copy to File… to open the Certificate Export wizard.
    See image.
  3. Start the Certificate Export Wizard.
  4. In Export Private Key, choose No, do not export the private key and click Next.
  5. In Export File Format, choose Base-64 encoded as the file format of the certificate you want to export and click Next.
    See image.
  6. In File to Export, either click Browse to navigate to the file you want to export or enter the file name. Click Next.
  7. Click Finish to exit the wizard.
  8. Navigate to the certificate that you downloaded and ensure the following
    • The certificate file name has a .pem extension. (Rename it to adfs.pem for example.) The Zscaler service accepts certificates with the .pem extension only.
    • The file name contains one dot (“.”) only.

You can then do the following:

  • Restrict the groups that are federated.
  • Import the certificate file into the Zscaler service. (See How do I configure SAML? for instructions on how to download the certificate from the admin portal.)
  • If you've also configured the Zscaler service, you can test the configuration.

Restricting Groups

AD FS 2.0 federates all the groups of a user, by default. You can restrict the groups to only those to which policies will be applied. Zscaler recommends putting users in groups that begin with a specific word, such as Internet, to facilitate applying restrictions on group federations, For example, you can create groups such as Internet general, Internet Restricted, etc.

To restrict the groups:

  1. Remove the group mapping from the rule that you created when you added a claim rule. (See Adding a Claim Rule above.)
  2. Create a new rule for group membership.

Testing the Configuration

After you configure ADFS and the Zscaler service, you can then test the configuration.

If you are already logged in to the Zscaler service, browse to https://login.zscaler.net/zscaler.portal (or replace zscaler.net with the cloud name you are using), and click Logout.

Otherwise, ensure that your traffic is being forwarded to the Zscaler service and then browse to a web site. When prompted for authentication, provide your SAML login credentials to login. (If any error occurs, see SAML Troubleshooting Guidelines.)

To edit the existing claim rule:

  1. In the AD FS 2.0 Management window, open the Trust Relationships > Relying Party Trusts folder.
  2. Right-click the relying party trust that you created and select Edit Claim Rules.
  3. When the Edit Claim Rules window appears, click Edit Rule to modify the rule that you created when adding a claim rule.
  4. In the Configure Claim Rule window, delete the row that mapped the LDAP attribute for group to a claim rule type.
  5. Click OK.

To add a new rule for group membership:

  1. In the ADFS 2.0 Management window, open the Trust Relationships > Relying Party Trusts folder.
  2. Right-click the relying party trust that you created and select Edit Claim Rules.
  3. When the Edit Claim Rules window appears, click Add Rule.
  4. Select Send Claims Using a Custom Rule and click Next.
  5. In the Custom Rule window, do the following:
    • Enter a name for this rule, such as “Return Group Membership”.

In the custom rule box, enter the following text to enumerate the group membership and put it into an array called memberOf):

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => add(store = "Active Directory", types = ("memberOf"), query = ";tokenGroups;{0}", param = c.Value);
  1. Click Finish.
  2. Click Add Rule.
  3. Select Send Claims Using a Custom Rule, and click Next.
  4. In the Custom Rule window, do the following:
    • Enter a name for this rule, such as  “Restrict Group Membership”.
    • In the custom rule box enter something like the following:
c:[Type == "memberOf", Value =~ "Internet.+"] => issue(claim = c);
The preceding regular expression matches any group name that begins with “Internet”.  E.g. ‘Internet Access’ or ‘InternetGroup3’ or ‘Internet Restricted’
c:[Type == "memberOf", Value =~ “Sales|Marketing|HR”] => issue(claim = c);
The preceding regular expression matches only 3 groups - “Sales”, “Marketing” and “HR”
c:[Type == "memberOf", Value =~ “AccessLevel[1-9]”] => issue(claim = c); 
The preceding regular expression matches any group name that begins with “AccessLevel” and then has a number 1 to 9.  E.g. ‘AccessLevel1’ or ‘AccessLevel7’
  1. Click Finish.

You can do the following:

  • Import the certificate file into the Zscaler service. (See How do I configure SAML? for instructions.)
  • If you've also configured the Zscaler service, you can test the configuration.

1

2

3

7

8

3b

3c

4c

5c

6c

1d

2d

5d