Configuring Authentication for PingCastle Enterprise

Authentication

PingCastle Enterprise supports multiple authentication methods that can work simultaneously. You can configure any combination of Local Authentication, Windows Authentication, OpenID Connect, Entra ID Authentication, Header Authentication, SAML2, and Client Certificate authentication, allowing users to choose their preferred login method.

Set up each method's identity provider using the instructions on this page, then enter the resulting values on the Login options, Windows authentication, Certificate authentication, Header authentication, OIDC Connect, and SAML screens under Configuration > Settings in the PingCastle Enterprise web interface.

note

Most changes on these screens take effect within about 30 seconds, without a restart. Two setting groups — HTTPS redirection and allowed hosts settings, and database schema changes — restart PingCastle Enterprise automatically: it stops itself about 1 second after you save, then IIS restarts it. Six other restart-flagged settings — the three file logging settings, maximum concurrent scans, and both SCIM rate limit settings — require you to restart PingCastle Enterprise manually after saving.

tip

You can enable OpenID Connect, SAML2, Windows Authentication, and Disable Password Login during installation, on the Authentication method screen of the installer. See Step 2 - Run PingCastleEnterpriseInstaller.exe (production). The instructions on this page apply whether you configure a method during installation or afterward on the Configuration > Settings screens.

Local Authentication

Local authentication

PingCastle Enterprise enables local authentication by default, using a username and password stored in the PingCastle Enterprise database. It needs no additional configuration.

To hide the local authentication option when you configure other authentication methods, enable Disable Password Login on Configuration > Settings > Login options.

warning

When you enable both Disable Password Login and Windows Authentication, any account calling the API must be a member of the Windows group you set in Windows Group.

Windows Authentication

Windows authentication

If you haven't already, enable Windows Authentication

Step 1: Install Windows Authentication Package

Ensure you have installed the Windows Authentication package. It may not be part of the default IIS installation on older Windows Server versions.

Open Server Manager > Manage > Add Roles and Features > Server Roles > Web Server (IIS) > Web Server > Security and select Windows Authentication.

Step 2: Enable Windows Authentication in IIS

1. Close and reopen the IIS Manager console to refresh the available options.
2. Select the PingCastleEnterprise website in the left-hand tree view.
3. Double-click the Authentication icon in the center panel.

4. In the Authentication settings, ensure the following:
   • Anonymous Authentication: Enabled (should already be enabled)
   • Windows Authentication: Right-click and select Enable

Windows Authentication uses Active Directory groups to provision access to PingCastle Enterprise. Create two security groups in Active Directory. You can call these whatever you like. This document uses the following names as examples:

• PingCastle_Users: Members of this group can log in and access PingCastle Enterprise
• PingCastle_Admins: Members of this group have administrator privileges

Add users to the appropriate groups based on the level of access they require.

Getting AD Group SIDs

PingCastle Enterprise needs the Security Identifiers (SIDs) of the groups for setup. Use the tabs to choose a method for retrieving them.

Active Directory PowerShell

This method uses the ActiveDirectory PowerShell module to retrieve the group SIDs

Get-ADGroup "PingCastle_Users" | Select-Object Name, SID
Get-ADGroup "PingCastle_Admins" | Select-Object Name, SID

ADSI Search

This method uses PowerShell with the native ADSI Searcher class to get the group SIDs

$searcher = [ADSISearcher]"(&(objectClass=group)(name=PingCastle_Users))"
$group = $searcher.FindOne()
$sid = New-Object System.Security.Principal.SecurityIdentifier($group.Properties["objectsid"][0], 0)
$sid.Value

$searcher = [ADSISearcher]"(&(objectClass=group)(name=PingCastle_Admins))"
$group = $searcher.FindOne()
$sid = New-Object System.Security.Principal.SecurityIdentifier($group.Properties["objectsid"][0], 0)
$sid.Value

whoami (Current User)

If you're already a member of the groups and have rebooted since joining them, run whoami /all to get your group memberships and find the SID in the output

Configuration

On Configuration > Settings > Windows authentication, enter the SIDs you retrieved into the matching fields:

Setting	Description
Windows Group	SID of the Active Directory group that grants login access (e.g., PingCastle_Users)
Windows Group Admin	SID of the Active Directory group that grants administrator privileges (e.g., PingCastle_Admins)

PingCastle Enterprise can also remove a user's access if they no longer belong to the group set in Windows Group. The RemoveUserIfNotInWindowsGroupAnymore configuration key controls this behavior; PingCastle Enterprise checks the key at every Windows login. The key is off by default and has no toggle on the Settings screens — enable it by adding it to the application configuration.

note

Windows Authentication doesn't provide an email address when PingCastle Enterprise creates accounts. PingCastle Enterprise sets email addresses to a default value that disables notifications.

Want to hide the local authentication prompt?

To hide the internal username/password login option, enable Disable Password Login on Configuration > Settings > Login options.

API Access

This setup affects all pages for authentication. When you enable Disable Password Login with Windows Authentication, API calls require both an API key and a calling account that belongs to the group you set in Windows Group.

To restrict NTLM authentication to specific pages, edit the web.config file using the <location> directive to restrict authentication to the WindowsAuth page. See IIS URL Authorization documentation.

OpenID Connect

OpenID Connect

PingCastle Enterprise supports OpenID Connect authentication using the ASP.NET Core API. Configuration options are documented here.

Proxy settings rely on the current user proxy configuration, which you can define using netsh for IIS running as SYSTEM.

Configuring Entra ID for OpenIDConnect Authentication

You can configure Entra ID as an OpenID Connect provider.

Entra ID Portal Configuration

1. Navigate to Entra ID Portal and go to "App registrations"

2. Register a new application

3. Set the Redirect URI as Web with the URL: https://your-pingcastle-server.com/signin-oidc

   

   warning

   The URL must end with /signin-oidc

4. Go to the API permissions page

   

5. Click "Grant admin consent" for the application

   

6. Verify the Status shows as granted

   

7. Note the Application (client) ID and Directory (tenant) ID

   

8. Go to the Authentication tab and enable ID tokens

   

Configuration

On Configuration > Settings > OIDC Connect, enable OIDC login and enter the values from your identity provider:

Setting	Description
Enabled	Turns on OIDC login.
Display Name	The text shown on the OIDC login button.
Client ID	The application (client) ID your identity provider assigned when you registered PingCastle Enterprise.
Client Secret	The client secret your identity provider issued for the application.
Authority	The base URL of your identity provider, used to discover its OIDC endpoints.
Callback Path	The path on PingCastle Enterprise where your identity provider redirects users after they sign in.
Response Type	The OIDC response type PingCastle Enterprise uses during the authentication flow, such as code.
Use PKCE	Enables Proof Key for Code Exchange (PKCE), which adds a layer of protection to the authorization code exchange.
Map Inbound Claims	Controls whether PingCastle Enterprise maps claim names from the identity provider to their .NET equivalents.
Scope	The list of OIDC scopes PingCastle Enterprise requests, such as openid, profile, and email.
Require HTTPS Metadata	Requires your identity provider to serve the OIDC metadata endpoint over HTTPS.

All fields except Scope depend on your OpenID provider. To hide the internal username/password login option, enable Disable Password Login on Login options.

Header Authentication

Header authentication

Header authentication delegates authentication to a reverse proxy, which sets a header indicating the authenticated user.

Configuration

On Configuration > Settings > Header authentication, enable Header Authentication and enter the header name your reverse proxy sets.

When a user accesses the login page, PingCastle checks for the specified header. If present, PingCastle considers the user authenticated and uses the header value as the username.

Security Requirement

A reverse proxy must isolate the PingCastle application and prevent unauthenticated users from setting their own authentication header. Failure to properly secure this configuration allows authentication bypass.

To hide the internal username/password login option, enable Disable Password Login on Login options.

SAML2 Authentication

SAML2 authentication

PingCastle Enterprise supports SAML2 authentication using the ITfoxtec Identity SAML 2.0 package. Advanced configuration settings are documented here.

Proxy settings rely on the current user proxy configuration, which you can define using netsh for IIS running as SYSTEM.

Configuring SAML2 with Okta

Configure PingCastle Enterprise with Okta as your SAML2 identity provider using the following steps.

Step 1 Access Okta Admin Portal

Log in to your Okta tenant and switch to the admin portal.

Step 2 Create New Application

1. Click Applications > Add Application > Create New App
2. Select SAML 2.0 and click Create

Step 3 Name Your Application

Give your app a name and click Next.

Step 4 Configure SAML Settings

Configure the following SAML settings:

Setting	Value
Single Sign on URL	https://your-pingcastle-server.com/Saml2/AssertionConsumerService
Audience URI	PingCastle (or match your Issuer setting)

Step 5 Get IdP Metadata URL

Locate the IdP metadata URL for use in your PingCastle configuration.

Step 6 Assign Users

Assign users to the application: Assignments > Assign > Assign to People

Step 7 Restart and Test

Restart the application. A SAML2 login option will appear on the login screen.

Configuration

On Configuration > Settings > SAML, enable SAML login and enter the values from your identity provider:

Setting	Description
Enabled	Turns on SAML login.
Display Name	The text shown on the SAML login button.
Issuer	The identifier PingCastle Enterprise presents to your identity provider as the SAML issuer.
IdP Metadata	The URL of your identity provider's SAML metadata, used to fetch signing certificates and endpoint information automatically.
Single Sign-On Destination	The SSO endpoint on your identity provider, used when you configure SAML manually instead of through IdP metadata.
Certificate	The base64-encoded signing certificate from your identity provider, used when you configure SAML manually.
Ignore Certificate Validation	Skips validation of the identity provider's certificate. Use this only for testing, since it removes a security check.

Set IdP Metadata to fetch your identity provider's signing certificate and endpoints automatically, as with Okta or ADFS metadata URLs.

Availability Requirement

When using IdP Metadata, PingCastle Enterprise accesses the metadata URL at application startup. If the URL is unavailable, PingCastle Enterprise will be unavailable until the metadata becomes accessible again.

To avoid a startup dependency on the metadata URL, leave IdP Metadata blank and set Single Sign-On Destination and Certificate instead, using the values from your identity provider's metadata:

To hide the internal username/password login option, enable Disable Password Login on Login options.

Client Certificate

Client certificate authentication

Client certificate authentication requires users to present a valid SSL client certificate when accessing PingCastle Enterprise.

IIS Configuration

Configure IIS to require or accept client certificates. This requires HTTPS access.

The server requests a certificate when a user accesses the website.

API Access

Set the certificate requirement to Accept (not Require) to allow API access without certificates, or configure a separate virtual host for API access.

Browser Cache

Close and reopen the browser after changing certificate settings to avoid connection cache reuse.

PingCastle Configuration

On Configuration > Settings > Certificate authentication, enable Certificate Authentication. If your environment doesn't have CRL or OCSP revocation endpoints available, also enable Skip Revocation Check to skip certificate revocation checking.

When a user visits /Account/Login, PingCastle evaluates the certificate for trust (chain building, online verification) and maps it to a user account.

Certificate Mapping

PingCastle maps certificates to user accounts using these identifiers (in order):

1. DNS Name (CN from subject)
2. UPN from SubjectAlternateName
3. RFC email from SubjectAlternateName

User Account Setup

Create a user account with a login matching the certificate subject (DNS form). You don't need to set a password. Use an external user account for this, though any account type works.

Troubleshooting

If PingCastle can't recognize the certificate, it displays an error. Ensure the user account login matches one of the preceding certificate identifiers.

Passkeys

Passkeys let users with local accounts verify their identity with a device or security key that supports the WebAuthn and FIDO2 standards. Users can use a passkey as a second factor after their password, or, if you allow it, to sign in without a password. Users register and manage their own passkeys. See Sign-in security.

Passkeys are available only to local accounts. Users who sign in with Windows, OpenID Connect, SAML2, or another external method can't use them.

Passkey requirements

• PingCastle Enterprise must use HTTPS. Passkeys don't work over HTTP.
• Users must reach PingCastle Enterprise through a DNS name. Passkeys don't work on localhost or an IP address.
• Users must browse to PingCastle Enterprise using the address you set in Allowed Origins.

The installer sets up passkeys for you when you enter an HTTPS address. When you upgrade from an earlier version that already uses HTTPS and has a web host configured, the upgrade fills in the passkey settings from that web host and enables passkeys.

Configure passkeys

Configure passkeys on Configuration > Settings > Authentication, in the Passkeys section.

Field	Description
Passkeys	Turns passkeys on or off. When you turn this off, users can't register or use passkeys, and passwordless sign-in is also turned off.
Allow passwordless sign-in	Lets users sign in with a passkey alone, without a password or second factor. When this is off, users can use passkeys only as a second factor.
Server Domain	The host name users browse to, with no https:// prefix or port. For example, pingcastle.contoso.com.
Allowed Origins	The exact address the browser reports, in the form https://<host>[:<port>]. For example, https://pingcastle.contoso.com.

You can't turn on passkeys while Server Domain is empty. These changes take effect without a restart.

warning

Changing Server Domain or Allowed Origins invalidates every registered passkey. PingCastle Enterprise asks you to confirm, then deletes them. Users sign in with their password and register their passkeys again.

Revoke passkeys by authenticator type

You can revoke every passkey of one authenticator type at once. Use this when a vulnerability affects a type of authenticator, when you retire a type of device, or when you migrate users to a different one. For example, you can revoke all passkeys created with one vendor's security keys and leave the rest in place.

1. Go to Configuration > Settings > Authentication.

2. In the Passkeys section, scroll below all the settings to the table of authenticator types and find the type you want to revoke.

3. Click Revoke next to it, and confirm.

Affected users see nothing different. They sign in with their password, and if passkeys are still enabled, they can register a passkey again.

Troubleshooting passkey availability

When passkeys aren't available, a banner on the page explains why. Administrators see how to fix the problem, and other users see a message to contact an administrator. The banner appears when:

• HTTPS is turned off.
• The address in the browser doesn't match Allowed Origins.
• Server Domain is empty.

Passkey controls stay disabled until you resolve the cause.

Login options

The Login options screen also includes these fields:

Field	Description
Minimum Password Length	The minimum number of characters required for local authentication passwords. Applies only when you enable Local Authentication.
Session Timeout	The number of minutes a user session can remain idle before PingCastle Enterprise logs the user out.

Custom login message

You can display a custom message on the login page, such as an internal notice or an authorized-use banner, by setting Custom Login Message on Configuration > Settings > Login options.

Example:

<p>The PingCastle UK Instance for Consto</p>

The custom message appears on the login page within about 30 seconds:

Security Note

The Custom Login Message setting renders raw HTML without escaping. While this allows formatting flexibility using Bootstrap CSS styles, Content Security Policy (CSP) protections prevent injection of custom CSS or JavaScript.