Customers are commonly confused by DAST authentication issues. Let's improve our documentation to help customers onboard more easily and also to reduce the number of related support cases that come in.
@jwanjohi , I added some additional detail on potential improvements that can be made to the page. I think better explaining why each auth variable matters/when it should be used is the thing that would be most helpful.
@rdickenson I know you had mentioned being available to help with this issue. There are quite a few improvements I think we can make, so it would be great if we can collaborate on it. Let me know if you think there are other improvements we should make that haven't been listed in this issue's description.
Maybe we should reconsider whether the variables should be listed twice like this. Rather than listing the auth-related variables in two different places, one possibility would be to add another column to the overall variable list that indicates what the variable is related to (auth, timeouts, etc). @rdickenson@jwanjohi@cam_swords do you have any thoughts on this?
add another column to the overall variable list that indicates what the variable is related to (auth, timeouts, etc)
The renamed variables are namespaced, so this might not be necessary. For example, all auth variables have the prefix DAST_AUTH_. All crawl variables have the prefix DAST_CRAWL_, etc.
Some variables cover more than one area. For example, DAST_SCOPE_EXCLUDE_URLS is useful for excluding the Logout URL as well as other URLs on the site.
Good call, thank you @cam_swords . @jwanjohi , let's put this on hold (as well as the other variable docs issue) until we've published the new variables.
@jwanjohi I've got some ideas for improvements of this page. I'll collate my ideas and add them to this issue. I know this issue is on hold, pending the renaming of the variables, but we can do some preparation.
@jwanjohi Here's a high-level proposal for improvements to this page. I've taken into account what Sara has described in this issue's description, but I may have missed something. I'd leave it up to you to write the new content, and reorganize the existing content, but I'm keen to collaborate on this issue. My proposal describes only what I think we should do regarding the content, not its structure.
What do you think of my proposal? I welcome your ideas as to how we can help DAST (BBD) users configure authentication.
Proposal:
Provide a more opinionated guide on how users should configure authentication. In other words, guide them from their application's authentication method to the relevant docs section, to a prescriptive explanation of how to configure the DAST job. It should not be up to the reader to find their own way to a suitable configuration. To use an analogy, if someone has a two-level home, where the front door is key locked and located on the second level, we should be able to direct them to selecting the right tools to have them unlocking the front door easily. It should not be up to them to figure out through trial and error that they need a ladder to reach the second level, also a physical door key to gain access.
Ensure all DAST CI/CD authentication variables are included and described on the "DAST authentication" page. Remove all CI/CD authentication-specific variables from the parent DAST (BBD) page.
Review and edit the "Getting started" and "Prerequisites" sections, possibly combine them. I think we're asking too much upfront, when we need to provide more explanation of the available options.
Available CI/CD variables section
Move it to near the end of the page, possibly the very end.
Remove the table format, instead break it up into categories and have the CI/CD variables described in the relevant sections. Providing a reference list of variables definitely has value, but it has more value if we provide more explanation and context.
Demonstration videos: either move them all to a "Videos" section, or link to them from the relevant subsection.
I think this is great @rdickenson, thanks for sharing your thoughts, it would be awesome to collaborate with you on this!
Provide a more opinionated guide on how users should configure authentication. In other words, guide them from their application's authentication method to the relevant docs section, to a prescriptive explanation of how to configure the DAST job. It should not be up to the reader to find their own way to a suitable configuration.
I agree with you on this, it would be a good idea to give the user more structured guidance on how to navigate the configuration process more effectively. Would it make sense as a first step to consolidate the different configuration methods under each authentication type, i.e. move configuration for HTTP authentication to be under HTTP authentication and move configuration for single step, multi-step and SSO login forms to Form authentication? We could then create a new section that these fall under, something like Types of authentication that follows after the combined Getting started and Prerequisites sections?
That way, the user avoids having to jump across the documentation to figure out how to setup authentication? We'd then add more detailed, step-by-step guidance to provide the user with a full end-to-end journey based on the authentication type they use. Then within the different configuration authentication methods, we should be able to link to the specific required CI/CD variables in the categories we create in the Available CI/CD variables section, as mentioned in your point above. WDYT?
Ensure all DAST CI/CD authentication variables are included and described on the "DAST authentication" page. Remove all CI/CD authentication-specific variables from the parent DAST (BBD) page.
Review and edit the "Getting started" and "Prerequisites" sections, possibly combine them. I think we're asking too much upfront, when we need to provide more explanation of the available options.
Makes sense, we can rework the two sections to make them one and we could also probably move the general prerequisites to be a list under the first bullet point in Getting started to allow for better readability flow, and move the mention of single-step login and multi-step login descriptions (points 3 & 4) in the Getting started section to feature as part of the third general prerequisite point?
Available CI/CD variables section
Move it to near the end of the page, possibly the very end.
By moving to the end of the page, do you mean past the Known Limitations and Troubleshooting sections? Would the intention be to make it more like an appendix-style sort of reference?
Another option I was thinking of is to have the section somewhere before the Verifying authentication is successful section to prevent the user from scrolling all the way down and also help with the user flow i.e Getting started -> Types of authentication and how to configure for different authentication types -> Available CI/CD variables -> Verifying if auth is successful -> Known limitations -> Troubleshooting?
Remove the table format, instead break it up into categories and have the CI/CD variables described in the relevant sections. Providing a reference list of variables definitely has value, but it has more value if we provide more explanation and context.
Demonstration videos: either move them all to a "Videos" section, or link to them from the relevant subsection.
I'm okay with either option, though it might be easier for the user to watch a video based on the subsection they are in. @smeadzinger do we have any existing videos that you feel would be useful for this page in addition to the ones you have listed in the description?
Love both of your ideas here @jwanjohi and @rdickenson ! I agree that it would be better to place videos in each subsection. So you navigate to the subsection, then you can either read the section or watch the related video, or both. We do not have any relevant existing videos that I am aware of. If neither of you wants to make short demo videos, I am happy to do it.
After chatting with an SA, it's clear to me that we also need to demonstrate and document how to turn MFA off for a test app because many customers don't know how to do this. I added Document Disabling MFA for a test app (#443599) to track that.
I'll try to incorporate some of your ideas into the checklist, but please feel free to edit it too.