SSoT for administration/auth docs

- Make sure we have type defined in the frontmatter
- Add troubleshooting sections where absent
- Meaningful intros where absent

doc/administration/auth/README.md

 ---
 comments: false
+type: index
 ---
-# Authentication and Authorization
+# GitLab authentication and authorization
 GitLab integrates with the following external authentication and authorization
-providers.
-- [LDAP](ldap.md) Includes Active Directory, Apple Open Directory, Open LDAP,
-  and 389 Server
+providers:
+- [Auth0](../../integration/auth0.md)
+- [Authentiq](authentiq.md)
+- [Azure](../../integration/azure.md)
+- [Bitbucket Cloud](../../integration/bitbucket.md)
+- [CAS](../../integration/cas.md)
+- [Crowd](../../integration/crowd.md)
+- [Facebook](../../integration/facebook.md)
+- [GitHub](../../integration/github.md)
+- [GitLab.com](../../integration/gitlab.md)
+- [Google](../../integration/google.md)
+- [JWT](jwt.md)
+- [Kerberos](../../integration/kerberos.md)
+- [LDAP](ldap.md): Includes Active Directory, Apple Open Directory, Open LDAP,
+  and 389 Server.
   - [LDAP for GitLab EE](ldap-ee.md): LDAP additions to GitLab Enterprise Editions **(STARTER ONLY)**
-- [OmniAuth](../../integration/omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google,
-  Bitbucket, Facebook, Shibboleth, Crowd, Azure, Authentiq ID, and JWT
-- [CAS](../../integration/cas.md) Configure GitLab to sign in using CAS
-- [SAML](../../integration/saml.md) Configure GitLab as a SAML 2.0 Service Provider
-- [Okta](okta.md) Configure GitLab to sign in using Okta
-- [Authentiq](authentiq.md): Enable the Authentiq OmniAuth provider for passwordless authentication
-- [Smartcard](smartcard.md) Smartcard authentication **(PREMIUM ONLY)**
+  - [Google Secure LDAP](google_secure_ldap.md)
+- [Okta](okta.md)
+- [Salesforce](../../integration/salesforce.md)
+- [SAML](../../integration/saml.md)
+- [SAML for GitLab.com groups](../../user/group/saml_sso/index.md) **(SILVER ONLY)**
+- [Shibboleth](../../integration/shibboleth.md)
+- [Smartcard](smartcard.md) **(PREMIUM ONLY)**
+- [Twitter](../../integration/twitter.md)
+- [UltraAuth](../../integration/ultra_auth.md)

doc/administration/auth/authentiq.md

+---
+type: reference
+---
+
 # Authentiq OmniAuth Provider
 To enable the Authentiq OmniAuth provider for passwordless authentication you must register an application with Authentiq.
@@ -66,3 +70,15 @@ On the sign in page there should now be an Authentiq icon below the regular sign
 - If not they will be prompted to download the app and then follow the procedure above.
 If everything goes right, the user will be returned to GitLab and will be signed in.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/administration/auth/crowd.md

+---
+type: reference
+---
+
 # Atlassian Crowd OmniAuth Provider
+Authenticate to GitLab using the Atlassian Crowd OmniAuth provider.
+
 ## Configure a new Crowd application
 1. Choose 'Applications' in the top menu, then 'Add application'.

doc/administration/auth/google_secure_ldap.md

+---
+type: reference
+---
+
 # Google Secure LDAP **(CORE ONLY)**
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/46391) in GitLab 11.9.
@@ -204,3 +208,15 @@ values obtained during the LDAP client configuration earlier:
 [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart]: ../restart_gitlab.md#installations-from-source
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md

 ---
-author: Chris Wilson
-author_gitlab: MrChrisW
-level: intermediary
-article_type: admin guide
-date: 2017-05-03
+type: howto
 ---
 # How to configure LDAP with GitLab CE
-## Introduction
-
 Managing a large number of users in GitLab can become a burden for system administrators. As an organization grows so do user accounts. Keeping these user accounts in sync across multiple enterprise applications often becomes a time consuming task.
 In this guide we will focus on configuring GitLab with Active Directory. [Active Directory](https://en.wikipedia.org/wiki/Active_Directory) is a popular LDAP compatible directory service provided by Microsoft, included in all modern Windows Server operating systems.
@@ -268,3 +262,15 @@ have extended functionalities with LDAP, such as:
 - Multiple LDAP servers
 Read through the article on [LDAP for GitLab EE](../how_to_configure_ldap_gitlab_ee/index.md) **(STARTER ONLY)** for an overview.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md

 ---
-author: Chris Wilson
-author_gitlab: MrChrisW
-level: intermediary
-article_type: admin guide
-date: 2017-05-03
+type: howto
 ---
 # How to configure LDAP with GitLab EE **(STARTER ONLY)**
-## Introduction
-
-The present article follows [How to Configure LDAP with GitLab CE](../how_to_configure_ldap_gitlab_ce/index.md). Make sure to read through it before moving forward.
+This article expands on [How to Configure LDAP with GitLab CE](../how_to_configure_ldap_gitlab_ce/index.md). Make sure to read through it before moving forward.
 ## GitLab Enterprise Edition - LDAP features
@@ -117,3 +111,15 @@ Integration of GitLab with Active Directory (LDAP) reduces the complexity of use
 It has the advantage of improving user permission controls, whilst easing the deployment of GitLab into an existing [IT environment](https://www.techopedia.com/definition/29199/it-infrastructure). GitLab EE offers advanced group management and multiple LDAP servers.
 With the assistance of the [GitLab Support](https://about.gitlab.com/support) team, setting up GitLab with an existing AD/LDAP solution will be a smooth and painless process.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/administration/auth/jwt.md

+---
+type: reference
+---
+
 # JWT OmniAuth provider
 To enable the JWT OmniAuth provider, you must register your application with JWT.
@@ -70,3 +74,15 @@ will be redirected to GitLab and will be signed in.
 [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart GitLab]: ../restart_gitlab.md#installations-from-source
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/administration/auth/ldap-ee.md

+---
+type: reference
+---
+
 # LDAP Additions in GitLab EE **(STARTER ONLY)**
 This is a continuation of the main [LDAP documentation](ldap.md), detailing LDAP

doc/administration/auth/ldap.md

+---
+type: reference
+---
+
 <!-- If the change is EE-specific, put it in `ldap-ee.md`, NOT here. -->
 # LDAP
@@ -494,6 +498,13 @@ be mandatory and clients cannot be authenticated with the TLS protocol.
 ## Troubleshooting
+If a user account is blocked or unblocked due to the LDAP configuration, a
+message will be logged to `application.log`.
+
+If there is an unexpected error during an LDAP lookup (configuration error,
+timeout), the login is rejected and a message will be logged to
+`production.log`.
+
 ### Debug LDAP user filter with ldapsearch
 This example uses ldapsearch and assumes you are using ActiveDirectory. The
@@ -527,18 +538,9 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt  -b "$ba
   sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production
   ```
-### Connection Refused
+### Connection refused
 If you are getting 'Connection Refused' errors when trying to connect to the
 LDAP server please double-check the LDAP `port` and `encryption` settings used by
 GitLab. Common combinations are `encryption: 'plain'` and `port: 389`, OR
 `encryption: 'simple_tls'` and `port: 636`.
-
-### Troubleshooting
-
-If a user account is blocked or unblocked due to the LDAP configuration, a
-message will be logged to `application.log`.
-
-If there is an unexpected error during an LDAP lookup (configuration error,
-timeout), the login is rejected and a message will be logged to
-`production.log`.

doc/administration/auth/oidc.md

+---
+type: reference
+---
+
 # OpenID Connect OmniAuth provider
 GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) as an OmniAuth provider.
@@ -146,7 +150,7 @@ for more details:
  }
 ```
-### Troubleshooting
+## Troubleshooting
 If you're having trouble, here are some tips:

doc/administration/auth/okta.md

+---
+type: reference
+---
+
 # Okta SSO provider
 Okta is a [Single Sign-on provider](https://www.okta.com/products/single-sign-on/) that can be used to authenticate
@@ -157,3 +161,15 @@ Make sure the groups exist and are assigned to the Okta app.
 You can take a look of the [SAML documentation](../../integration/saml.md#marking-users-as-external-based-on-saml-groups) on external groups since
 it works the same.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/administration/auth/smartcard.md

+---
+type: reference
+---
+
 # Smartcard authentication **(PREMIUM ONLY)**
 GitLab supports authentication using smartcards.
@@ -22,7 +26,7 @@ To use a smartcard with an X.509 certificate to authenticate against a local
 database with GitLab, `CN` and `emailAddress` must be defined in the
 certificate. For example:
-```
+```text
 Certificate:
     Data:
         Version: 1 (0x0)
@@ -212,3 +216,15 @@ attribute. As a prerequisite, you must use an LDAP server that:
 1. Save the file and [restart](../restart_gitlab.md#installations-from-source)
    GitLab for the changes to take effect.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->