SAML docs

DesktopHub/overview.md

@@ -23,7 +23,7 @@ All products also require a license key from Inedo. The hub can request a free o
 
 ## Upgrades {#upgrades data-title="Upgrades"}
 
-You can upgrade products to any greater version number by clicking on the Upgrade button and selecting the desired version. By default, the latest stable version is selected, but you can choose a lower version or a later prerelease version as well.
+You can upgrade products to any greater version number by clicking on the Upgrade button and selecting the desired version. By default, the latest stable version is selected, but you can choose a lower version or a later [prerelease version](#prerelease) as well.
 
 Upgrades also required a connection string. By default, the connection string used by the application is used, but you may supply an alternative one to use for the upgrade instead (this is necessary if the software runs as a lower-privilege user not able to make schema changes and you are not using integrated authentication).
 
@@ -46,3 +46,21 @@ The Inedo Hub has no background services and only occupies a few megabytes of di
 That said, The hub itself may be uninstalled by either using the Programs and Features dialog in Windows or executing the InedoHubUninstaller.exe program directly.
 
 Uninstalling the hub will **not** uninstall all of the individual Inedo products automatically. If you want to uninstall everything, use the hub to uninstall each product first.
+
+## Prerelease Product Versions {#prerelease data-title="Prerelease Product Versions"}
+
+::: {.attention .best-practice}
+<img src="/resources/images/icons/best-practices.png" alt="Check" />
+
+Note that prerelease versions should be considered "beta", and should not be used in a production environment.
+:::
+
+The Inedo Hub may be configured to install prerelease product versions of any Inedo product, including CI and public beta versions. However, these versions are hidden by default. 
+
+To configure the Inedo Hub to access prerelease versions, click on the `[config]` link at the bottom-left corner of the Inedo Hub and set the package source to:
+
+```
+https://proget.inedo.com/upack/PrereleaseProducts
+```
+
+Once this value is changed, restart the Inedo Hub, and prerelease versions will appear in the version dropdowns.

Various/saml/#.md

@@ -0,0 +1,6 @@
+---
+title: SAML Authentication (Beta)
+sequence: 700
+keywords: authentication, saml, single-sign-on
+---
+

Various/saml/azure-ad.md

@@ -0,0 +1,45 @@
+---
+title: Azure AD Single Sign-on
+sequence: 100
+keywords: authentication,saml,azure
+show-headings-in-nav: true
+---
+
+::: {.attention .technical}
+SAML support is currently only available in prerelease versions of certain Inedo products. It is still considered a proof-of-concept, and may be removed at any time.
+:::
+
+## Overview
+
+This documentation is specific to configuring SAML with Azure Active Directory. Refer to the [SAML Authentication Overview](overview) for more information.
+
+## Configuring Azure AD {#azure-ad data-title="Configuring Azure AD"}
+
+### 1. Obtain App Registration ID {#step-1 data-title="Register App"}
+
+Before an Inedo product can authenticate with Azure, an App Registration must be created in Azure. When creating one, make sure to add a redirect URI of:
+
+```
+https://{inedo-product-host}/saml-acs-callback
+```
+
+Once created, the overview for the Azure App Registration will display a **Application (client) ID**, a GUID that should be used as the **SAML issuer** within the Inedo product configuration.
+
+### 2. Obtain SAML Metadata {#step-2 data-title="Obtain SAML Metadata"}
+
+The SAML metadata for Azure is found at the URL:
+
+```
+https://login.microsoftonline.com/{tenant-id}/FederationMetadata/2007-06/FederationMetadata.xml
+```
+
+The value for `{tenant-id}` is a GUID found in the App Registration under **Directory (tenant) ID**.
+
+### 3. Inedo Product Configuration {#step-3 data-title="Inedo Product Configuration"}
+
+{.docs}
+ - **SAML issuer** - use **Application (client) ID** from App Registration in step 1
+ - **Display name attribute** - `http://schemas.microsoft.com/identity/claims/displayname`
+ - **Email attribute** - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
+ - **SAML metadata** - copy/paste whole XML file contents from step 2
+

Various/saml/overview.md

@@ -0,0 +1,128 @@
+---
+title: SAML Authentication Overview
+sequence: 30
+keywords: authentication,saml
+show-headings-in-nav: true
+---
+
+::: {.attention .technical}
+SAML support is currently only available in prerelease versions of [certain Inedo products](#supported-versions). It is still considered a proof-of-concept, and may be removed at any time.
+:::
+
+## Overview {#overview data-title="Overview"}
+
+SAML-based single sign-on is an authentication mechanism that uses a third-party identity provider to verify the identity of user, and relay user metadata back into the Inedo product, effectively replacing the Inedo product login page, with that of the identity provider's, or removes it altogether if a user is already signed-in to the identity provider. 
+
+## Supported Product Versions {#supported-versions data-title="Supported Inedo Products"}
+
+SAML authentication is currently in beta, installable from the Inedo Hub. This functionality is available in the following prerelease product versions:
+
+{.docs}
+ - **ProGet** - v5.2.15 and later *(currently in the latest `ci` version)* - Basic or Enterprise edition only
+ - **BuildMaster** - *coming soon*
+ - **Otter** - *coming soon*
+
+## Configuring SAML {#configuration data-title="Configuring SAML"}
+
+### 1. Obtain a Prerelease Version
+
+In order to install a prerelease version, the Inedo Hub must be configured to display them. Visit the [Inedo Hub documentation](/docs/desktophub/overview#prerelease) for more information.
+
+### 2. BETA: Enable Prerelease Features
+
+Once a product version that [supports SAML](#supported-versions) is installed, visit the *Administration* > *Advanced Settings* page to enable the `Web.PrereleaseFeaturesEnabled` setting.
+
+### 3. Configure Identity Provider
+
+In general, configuring an identity provider requires the following steps to enable SAML authentication:
+
+{.docs}
+ - Create an entity or application
+ - Configure a SSO login callback/redirect URL in that application
+ - Obtain SAML metadata XML file contents
+
+Instructions for the following specific identity providers can be found here:
+
+{.docs}
+ - [Azure Active Directory](azure-ad)
+ - [PingID](ping-id)
+
+### 4. Configure Inedo Product
+
+Once the identity provider is configured to support authentication in an Inedo product, the following properties must be configured on the *Administration* > *Enable Single Sign-on (SAML)* page:
+
+{.docs}
+ - **User directory** - configures an "external" user directory that enables a third-party identity provider to automatically create/update users in the Inedo product when they are authenticated. You will be asked to create one on first use, and the directory should be unique per identity provider and identity provider application. *Note: all authenticated users are configured to be administrators by default on initial creation*
+ - **SAML issuer** - a name supplied by the identity provider, commonly referred to as an "application". Depending on what the identity provider expects, it could be a simple name, GUID, or URL
+ - **Display name attribute** - the SAML attribute that represents the display name in the Inedo Product *(will display "logged in as" this value)*
+ - **Email attribute** - the SAML attribute that represents the email address of the user *(this is not used by ProGet)*
+ - **SAML metadata** - the contents of the [SAML metadata XML](https://en.wikipedia.org/wiki/SAML_Metadata) obtained from your identity provider. The contents of this file will attempt to be parsed in order to extract public key signing certificates *(used to validate the SAML responses)* and the SAML SSO endpoint that the Inedo product sign-in page will redirect to
+
+Once these settings are saved, they will be validated and any errors will appear on the page. If successful, SAML authentication will be enabled, and selecting "Log In" from the user dropdown will present a sign-in button instead of username and password fields.
+
+::: {.attention .technical}
+**Beta note:**  Once enabled, there may be errors related to the web application restarting and/or cookies. Simply click the *Clear Authentication Cookies* button to resolve this once the site restarts. See the [troubleshooting](#troubleshooting) section if you get locked out.
+:::
+
+## Technical Limitations {#limitations data-title="Technical Limitations"}
+
+{.docs}
+ - SAML authentication requires the user of a web browser, which means all other means of authentication to an Inedo product would need to be done using API keys.
+ - There is no way to "test" that SAML authentication is working other than by enabling it and trying it. If there are any issues, see the [locked out](#locked-out) troubleshooting section below.
+ - At this time, role-based permissions are not automatically resolved from the identity provider, and must be configured within the Inedo product itself under the associated directory provider, and may require adding users to groups in the Inedo product for granular permissions
+
+## Troubleshooting {#troubleshooting data-title="Troubleshooting"}
+
+### Locked out: Resetting the built-in user directory and Admin account {#locked-out}
+
+To reset the configured user directory to the *built-in* directory, and reset the *Admin* account to the password *Admin*, a server administrator must run the following command on the Inedo product's server:
+
+<tab-block>
+<tab name="ProGet">
+
+```
+(proget-installation-directory)\Service> .\ProGet.Service.exe resetadminpassword
+```
+</tab>
+<tab name="BuildMaster">
+
+```
+(buildmaster-installation-directory)\Service> .\BuildMaster.Service.exe resetadminpassword
+```
+</tab>
+<tab name="Otter">
+
+```
+(otter-installation-directory)\Service> .\Otter.Service.exe resetadminpassword
+```
+</tab>
+</tab-block>
+
+Once the user directory and Admin account are reset, the web application must be restarted. To restart the Integrated Web Server, run the following PowerShell command:
+
+<tab-block>
+<tab name="ProGet">
+
+```
+Restart-Service INEDOPROGETWEBSVC
+```
+
+</tab>
+<tab name="BuildMaster">
+
+```
+Restart-Service INEDOBUILDMASTERWEBSVC
+```
+
+</tab>
+<tab name="Otter">
+
+```
+Restart-Service INEDOOTTERWEBSVC
+```
+</tab>
+</tab-block>
+
+If your Inedo product is installed to run on IIS, use the *Restart-WebAppPool* command or recycle it directly in the IIS management UI. By default, the application pool is named ProGetAppPool, BuildMasterAppPool, or OtterAppPool, but may have been changed by a system administrator during installation.
+
+The next time you visit after running these commands, there may be stale authentication cookies that can be cleared from the corresponding error page, (if they are automatically detected) or by simply clearing web browser cookies manually. When testing access, make sure to visit the root URL (for example: `https://proget-server/`).

Various/saml/ping-id.md

@@ -0,0 +1,58 @@
+---
+title: PingID Single Sign-on
+sequence: 200
+keywords: authentication,saml,pingid
+show-headings-in-nav: true
+---
+
+::: {.attention .technical}
+SAML support is currently only available in prerelease versions of certain Inedo products. It is still considered a proof-of-concept, and may be removed at any time.
+:::
+## Overview
+
+This documentation is specific to configuring SAML with PingID. Refer to the [SAML Authentication Overview](overview) for more information.
+
+## Configuring PingID
+
+### 1. Configure Application / Connection {#step-1 data-title="Configure Application"}
+
+In the PingOne console, the *Connections* tab has a list of applications that will connect. To create one:
+
+1. Click the `[+ Application]` button
+2. Choose "Web App"
+3. Choose connection type "SAML"
+4. Use the Inedo product as the name i.e. `ProGet`
+5. Add an *ACS URL* of: `https://{inedo-product-host}/saml-acs-callback` - **Note: PingID requires an HTTPS URL**
+6. Specify *ENTITY ID* of whatever you want (i.e. `ProGet`), and this value will be used as the **SAML issuer** value
+7. Leave defaults for everything else
+8. Once created, **ensure the application is enabled** (they are disabled by default)
+
+### 2. Map Attributes {#step-2 data-title="Map Attributes"}
+
+An Inedo product can use any attributes for display name or email, but the following mappings will require no additional configuration on the Inedo product end:
+
+| PingOne Attribute | Application Attribute |
+|-|-|
+| `Formatted` | `DisplayName` |
+| `Email Address` | `Email` |
+
+### 3. Obtain SAML Metadata {#step-3 data-title="Obtain SAML Metadata"}
+
+It is easiest just to expand the *Configuration* sub-tab of an application, and locate the **IDP METADATA URL** text field, then browse to it.
+
+Otherwise, the SAML metadata for PingID is found at the URL:
+
+```
+https://auth.pingone.com/{environment-id}/saml20/metadata/{application-id}
+```
+
+The value for `{environment-id}` is a GUID found in the PingOne Console *Settings* tab under **ENVIRONMENT ID**. The value for `{application-id}` is a GUID found in the *Connections* tab when the application is expanded under **CLIENT ID**.
+
+### 4. Inedo Product Configuration {#step-4 data-title="Inedo Product Configuration"}
+
+{.docs}
+ - **SAML issuer** - use **ENTITY ID** from the app's *SAML Settings*
+ - **Display name attribute** - `DisplayName`, or a custom application attribute
+ - **Email attribute** - `Email`, or a custom application attribute
+ - **SAML metadata** - copy/paste whole XML file contents from step 3
+