SAML Authentication Overview
  • 11 Mar 2024
  • 3 Minutes to read
  • Dark
    Light
  • PDF

SAML Authentication Overview

  • Dark
    Light
  • PDF

Article Summary

SAML support is currently only available in certain Inedo product versions.

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

SAML authentication is is available in the following product versions:

  • ProGet Enterprise -v5.3 and later (preview feature available in v5.2.20+)
  • BuildMaster Enterprise - v2022 and later (not yet available as preview)
  • Otter Enterprise - v2022 and later (not yet available as preview)

Configuring SAML

1. Enable Prerelease Features (ProGet 5.2 Only)

If you are using ProGet 5.2, visit the Administration > Advanced Settings page to enable the Web.PrereleaseFeaturesEnabled setting.

2. Configure Identity Provider

In general, configuring an identity provider requires the following steps to enable SAML authentication:

  • 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:

3. 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:

  • 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 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.

Troubleshooting 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 section if you get locked out.

Technical Limitations

  • 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 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

Locked out: Resetting the built-in user directory and Admin account

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:

ProGet

(proget-installation-directory)\Service> .\ProGet.Service.exe resetadminpassword

BuildMaster

(buildmaster-installation-directory)\Service> .\BuildMaster.Service.exe resetadminpassword

Otter

(otter-installation-directory)\Service> .\Otter.Service.exe resetadminpassword

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:

ProGet

Restart-Service INEDOPROGETWEBSVC

BuildMaster

Restart-Service INEDOBUILDMASTERWEBSVC

Otter

Restart-Service INEDOOTTERWEBSVC

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/).


Was this article helpful?