Add Geo guidance and troubleshooting about SAML configuration
Problem
Configuring and troubleshooting Geo and SAML (and probably SSO generally) is difficult.
Proposal
What if we could show the admins a message like this (somehow, maybe in
rake gitlab:geo:check
?):"Gitlab is currently configured using SAML authentication. This can cause problems for transparent Geo request proxying. Please see the following document if you are having difficulties logging in to Geo sites via SAML: https://...."
The doc in question describes why SAML (and others?) can have issues with this configuration, and how to fix it (add the following ACS URLs to the SAML configuration).
- Add a Geo document about configuring SAML (or maybe SSO generally)
- Describe general guidance for configuration (for example, "auth provider configuration on a secondary site is ignored")
- Add a Troubleshooting section
- One example to add is #372490 (closed) for 15.1 through 15.5. On fix is to add the secondary site's external URL as an ACS URL in your SAML Identity Provider.
- Cross-link between relevant docs https://docs.gitlab.com/ee/integration/saml.html, https://docs.gitlab.com/ee/user/group/saml_sso/troubleshooting.html, etc
- Add a check to the Geo check rake task, which links to the doc if you have SAML configured => Follow up #385677
- Add a test to make sure that removing the
assertion_consumer_service_url
from your SAML provider gitlab.rb configuration continues to cause the desired behavior for Geo with separate URLs with proxying. => Follow up #385678
References
#372490 (closed) has most of the historical context
Edited by Michael Kozono