SAML Authentication Overview

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:

• Azure Active Directory
• PingID

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:

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

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