ENTERPRISE
Configuring SAML SSO with ADFS
-
Last updated: September 14, 2023
-
Read time: 4 Minutes
This section explains how to configure SAML SSO using Active Directory Federation Services (ADFS) as your identity provider. You may also need to refer to the ADFS documentation.
Before you start
Make sure your web server URL includes protocol and port information. For more information, see Configuring your web server.
Note
The relying party trust information is dependent on your web server URL.
Step 1: Add Burp Suite Enterprise Edition to your trusted applications
To add Burp Suite Enterprise Edition to your trusted applications:
- Log in to Burp Suite Enterprise Edition as an administrator.
- From the settings menu , select Integrations.
- On the SAML tile, click Configure. Notice that you can copy both the Relying party trust identifier and the Relying party service URL.
- In ADFS, run the Add Relying Party Trust wizard.
- Paste the Relying party service URL into the Relying party SAML 2.0 SSO Service URL field.
- Paste the Relying party trust identifier into the Relying party trust identifier field.
Step 2: Obtain key details from ADFS
To configure Burp Suite Enterprise Edition, you need to obtain some key details from ADFS. For more information, refer to the ADFS documentation. Obtain the following details:
-
The Entity ID. This is the URL that is sent as the
Issuer
value in SAML responses. - The SSO URL. Burp Suite Enterprise Edition sends users to this URL when they choose to log in using SAML.
- The token-signing certificate. Burp Suite Enterprise Edition uses this to verify that the SAML response was genuinely issued by ADFS.
Step 3: Enter the key details in Burp Suite Enterprise Edition
To enter the key details in Burp Suite Enterprise Edition:
- In Burp Suite Enterprise Edition, make sure that you're still on the SAML page.
- In Company details, enter your company name.
- Enter the key details in the relevant fields.
- Click Save.
Step 4: Configure how groups are managed
To make sure that the group membership of your users is sent to Burp Suite Enterprise Edition in a format that it can recognize, you have the following options:
- Create a central claim issuance policy that sends all of your groups to Burp Suite Enterprise Edition automatically.
- Configure claim rules for each group that you want to expose to Burp Suite Enterprise Edition individually.
Note
You can also use a combination of both approaches. In this case, the groups available to Burp Suite Enterprise Edition would be the union of the groups covered by the claim issuance policy and any additional groups for which you created individual claim rules.
Create a central claim issuance policy
To expose all of your users' groups to Burp Suite Enterprise Edition, configure a central claim issuance policy. This allows you to manage the claim rules for all of your groups in one place. It also removes the need to configure claim rules each time you add a new group.
The downside to this approach is that your groups must keep their existing group names. For example, if your group is called BSEE_View_Scans
in Active Directory, you will need to use this exact name for the corresponding user group in Burp Suite Enterprise Edition. For more information, see Configuring user permissions for SSO.
- Open the ADFS Management tool and go to the list of relying party trusts.
- Right-click on the entry you created for Burp Suite Enterprise Edition and select Edit claim issuance policy.
- Use the wizard to configure the following rules:
Rule 1
- Template: Send LDAP attributes as claims
- Name:
Send UPN as nameId
- Rule:
User-Principle-Name
=>Name ID
Rule 2
- Template: Send LDAP attributes as claims
- Name:
AccountName
- Rule:
SAM-Account-Name
=Windows Account Name
Rule 3
- Template: Send claims using a custom rule
- Name:
nameDN
- Rule:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => add(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameDN"), query = ";distinguishedName;{0}", param = c.Value);
Rule 4
- Template: Send claims using a custom rule
- Name:
Group
- Rule:
c1:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] && c2:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameDN"] => add(store = "Active Directory", types = ("http://schemas.xmlsoap.org/claims/Group"), query = "(member:1.2.840.113556.1.4.1941:={1});samaccountname;{0}", param = c1.Value, param = c2.Value);
Rule 5
- Template: Pass through or filter an incoming claim
- Name:
IssuedGroup
- Rule: Group - Pass through all claim values
All the groups that the user belongs to are sent with every claim to Burp Suite Enterprise Edition. If you add new groups, these rules automatically apply to them as well.
Create claim rules for each group individually
You can create claim rules on a group-by-group basis. This gives you more granular control over which groups and related information are exposed to Burp Suite Enterprise Edition in each claim.
You can output the group with a different name than the one used in Active Directory. For example, if your group is called BSEE_View_Scans
, you can output this with a more user-friendly name, such as "Scan viewers". You can then use this name for the corresponding group in Burp Suite Enterprise Edition. For more information, see Configuring user permissions for SSO.
- Open the ADFS Management tool and go to the list of relying party trusts.
- Right-click on the entry you created for Burp Suite Enterprise Edition and select Edit claim issuance policy.
- From the Claim rule template drop-down list, select Send Group Membership as Claim and click Next.
- Enter a name for the claim rule.
- To configure a claim rule, select User's group and select the group.
- From the Outgoing claim type drop-down list, select Group.
- In the Outgoing claim value field, enter a new name that you want to use for this group when sending a claim.
- Repeat this process for each group that you want to expose to Burp Suite Enterprise Edition.
If you add new groups in the future, you will need to repeat this process for each of them.