Redesign Group SAML settings instructions
What
- Split instructions on Group SAML steps into numbered steps with instructions next to each step
- Consider expanding on instructions for required assertions and having this as the second step
Why
- Large amount of text instructions can make it hard to scan for where to start
- Assertions are a large part of the setup and one of the key things SAML admins will need to know. This will help avoid us redirecting them to the docs, and help avoid the chance this step is missed. When we add ability to control access levels with assertions this will also help users discover this functionality.
Design
| Original | New Design |
|---|---|
 |
Previous discussion
@jamedjo in https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4549?view=inline#note_63905527:
When I see that large wall of text it feels hard to scan for where to start, and was thinking the above might help users skip to the URLs.
Could some of this text be moved to documentation?
Maybe for a future design iteration we'd split this into numbered steps keeping descriptive text alongside each stage:
- Set up your identity provider, using the URLs below when asked. (See documentation for popular services)
- Assertion Consumer Service URL
- Issuer
- Set up required assertions. Also known as claims or attributes, see documentation for further details
- NameID: Must be configured to ...
- Email: Is required
- Optional fields: name, first_name, last_name
- Configure GitLab with fields below:
- SSO URL
- Fingerprint
@pedroms in https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4549?view=inline#note_64196724:
@jamedjo thanks for sharing your feedback and explorations. I agree that the numbered steps would be ideal. And maybe even collapsing the setup info after the first setup, so you don't have to see it every time you visit the integration page.
Currently, I feel like having the setup text and the copy-paste info together helps group the necessary elements to get started. In the future, we'll have to improve this, but let's keep it as it is for this iteration.