SAML authentication for Admin Site / Workspace

SAML authentication is set at site level under Site Management => Pragatix Settings.

Four options for SAML identity provider:
None - SAML is not configured (default)
AzureAD - Microsoft Entra ID (Azure AD) is used as the SAML provider
Okta - Okta is used as the SAML provider
Keycloak - Keycloak is used as the SAML provider

Open

Important:

1. If some provider is configured (not None) - the whole site will work only with SAML and optionally Agat login (email) - Azure and Google authentication types will be not available for any account.

2. Must restart the Admin Site after changing SAML configuration

Required settings for SAML provider:
SAML Entity ID - copy value of “Microsoft Entra Identifier” from the Azure app or “IdP Entity ID / Issuer“ from Okta

In Azure app Single Sign-On settings:

Open

SAML Metadata URL - copy the value of “App Federation Metadata Url” from the Azure app or “IdP Metadata URL” from Okta

In Azure app Single Sign-On settings:

Open

Azure app for our testing: search for “Azure SAML Enterprise Application“ in LastPass

1. Create Enterprise application

2. In Properties set Assignment required? to No to allow all tenant users, or Yes and then add users to Users and groups.

3. Configure Single Sign On: add Admin Site URL to Identifier (Entity ID) and Reply URL:
   Reply URL should finish with /Saml2/Acs
   
   

Open

When the identity provider requires signed SAML authentication requests, Admin Site signs each AuthnRequest with the private key of a certificate installed in LocalMachine\My on the Admin Site server. Upload only the matching public certificate to the identity provider.

The application pool identity must have read access to the certificate's private key. The certificate must be current, have an RSA private key, and permit digital signatures. A TLS/SSL certificate can technically be reused when it meets these conditions, but a dedicated SAML signing certificate is recommended because it can be renewed and rotated independently from the website certificate.

If the certificate is installed or replaced outside the installer, grant the permission manually:

1. Sign in to the Admin Site server with an administrator account and run certlm.msc.

2. Open Certificates (Local Computer) > Personal > Certificates.

3. Locate the exact certificate selected for SAML signing, right-click it, and select All Tasks > Manage Private Keys.

4. Select Add. Enter IIS AppPool\<application-pool-name>, replacing the placeholder with the Admin Site IIS application-pool name, and select Check Names. For example, if the pool is named AdminSite, enter IIS AppPool\AdminSite.

5. Grant the identity Allow: Read. Full Control and Write permissions are not required.

6. Select Apply and OK, then restart or recycle the Admin Site application pool.

Open

1. Install the certificate, including its private key, in Certificates (Local Computer) > Personal > Certificates.

2. Grant the Admin Site IIS application-pool identity read access to the certificate's private key.

3. Open Site Management > Pragatix Settings and select the SAML provider.

This setting controls whether Admin Site digitally signs the SAML AuthnRequest that starts service-provider-initiated sign-in.

When the signing behavior is not Never, configure SAML Signing Certificate Thumbprint:

• Select from the list: open the dropdown and choose the certificate that Admin Site should use. The list contains eligible certificates from LocalMachine\My that are currently valid, have an RSA private key, allow digital signatures, and whose private key is accessible to the Admin Site process. Each option shows the certificate name and expiration date.

• Enter manually: choose Manual and paste the certificate thumbprint. Spaces and common invisible direction characters are removed when the thumbprint is processed. Manual entry does not install the certificate or grant permissions: the matching certificate must still exist in LocalMachine\My, include an RSA private key, permit signing, be valid, and be readable by the IIS application-pool identity.

If Never is selected, the thumbprint is not required and Admin Site does not use a certificate to sign authentication requests.

4. Save the settings and restart the Admin Site.

5. Start sign-in from the Admin Site URL and confirm that the identity provider accepts the signed request.

1. In the Microsoft Entra admin center, go to Entra ID > Enterprise applications > All applications and open the Admin Site enterprise application.

2. Open Single sign-on.

3. Under SAML Certificates, locate Verification certificates (optional) and select Edit.

Open

4. Select Require verification certificates.

5. Select Upload certificate, choose the public .cer file exported from the Admin Site certificate, and save the configuration.

6. Leave Allow requests signed with RSA-SHA1 disabled. Admin Site uses RSA-SHA256.

Open

After saving, the verification certificate should appear as active. Requiring verification certificates applies to service-provider-initiated sign-in. Microsoft Entra's Test single sign-on, My Apps, and Microsoft 365 app-launcher IdP-initiated flows are not suitable for testing this signed-request configuration; start sign-in from the Admin Site URL.

Create and configure the SAML application

1. In the Okta Admin Console, go to Applications > Applications, select Create App Integration, choose SAML 2.0, and continue.

2. Enter a name such as Pragatix Admin Site and continue to Configure SAML.

3. Configure the service-provider values. Replace https://admin-site.example.com with the public Admin Site URL:

   • Single sign-on URL: https://admin-site.example.com/Saml2/Acs

   • Keep Use this for Recipient URL and Destination URL selected.

   • Audience URI (SP Entity ID): the exact Admin Site URL configured as the Admin Site application URL, for example https://admin-site.example.com. The scheme, host, port, and trailing-slash form must match the issuer sent by Admin Site.

   • Default RelayState: leave empty.

   • Name ID format: EmailAddress.

   • Application username: Email.

4. Under Attribute Statements, add:

   Name	Name format	Value	Purpose

   Name	Name format	Value	Purpose
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	URI Reference	user.email	Required. Admin Site uses it as the user's email and account domain.
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	URI Reference	user.firstName + " " + user.lastName	Recommended display name.

5. In Show Advanced Settings, use RSA-SHA256/SHA-256 and configure Okta to sign the SAML assertion or response. Leave assertion encryption disabled unless encryption has been configured separately in Admin Site.

6. Finish the wizard and assign the required users or groups to the application.

Copy the Okta identity-provider values to Admin Site

1. Open the application's Sign On tab and select View SAML setup instructions or open its metadata details.

2. Copy the Identity Provider Issuer into SAML Entity ID in Admin Site.

3. Copy the Okta Identity Provider metadata URL into SAML Metadata URL in Admin Site.

Require signed requests from Admin Site

1. Edit the application's SAML Settings and expand Show Advanced Settings.

2. Under Signature Certificate, upload the public certificate selected in Admin Site. Okta expects PEM certificate data. If necessary, convert the Base-64 X.509 .cer to a PEM file with -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers.

3. Enable Signed Requests, finish, and save.

4. Set Admin Site signing behavior to Always unless Okta metadata explicitly declares that signed authentication requests are required.

Create and configure the SAML client

1. In the Keycloak Admin Console, select the realm, open Clients, and select Create client.

2. Set Client type to SAML.

3. Set Client ID to the exact external Admin Site URL, including a non-default port when used, for example https://admin-site.example.com:4449. It must exactly match the issuer in the Admin Site SAML request.

4. Save the client, then configure:

   • Root URL and Home URL: the exact external Admin Site URL.

   • Valid Redirect URIs: https://admin-site.example.com:4449/Saml2/Acs and https://admin-site.example.com:4449/Saml2/Logout. Use exact URLs, not a broad wildcard.

   • Master SAML Processing URL: https://admin-site.example.com:4449/Saml2/Acs.

   • Force POST Binding: enabled.

   • Name ID format: use the format configured for the stable user identifier emitted by Keycloak. Email is commonly used.

   • Sign Documents and/or Sign Assertions: enabled.

   • Signature Algorithm: RSA-SHA256.

   • Encrypt Assertions: disabled unless assertion encryption is configured separately.

Configure Keycloak to validate signed Admin Site requests

1. Open https://admin-site.example.com:4449/Saml2/Metadata and confirm that it returns the Admin Site service-provider XML descriptor.

2. In the Keycloak client, open Settings > Signature and Encryption.

3. Set Metadata descriptor URL to https://admin-site.example.com:4449/Saml2/Metadata.

4. Enable Use metadata descriptor URL. Keycloak then downloads and caches the Admin Site public signing certificate.

5. Open the Keys tab and enable Client Signature Required.

6. In Admin Site, set the SAML authentication request signing behavior to Always, save, and restart the Admin Site.

If Use metadata descriptor URL is disabled, import the public certificate selected in Admin Site manually on the Keycloak Keys tab. Never upload the private key.

Configure user attributes

Open the client's Client scopes or Mappers configuration and ensure these values are emitted:

Copy the Keycloak identity-provider values to Admin Site

1. Select Keycloak as the SAML provider.

2. Set SAML Metadata URL to https://keycloak.example.com/realms/<realm-name>/protocol/saml/descriptor.

3. Open that descriptor and copy its exact EntityDescriptor entityID value into SAML Entity ID.

Migrate an existing Windows account

• Set SAML Account Domain (BG_SamlAccountDomain) to the existing Windows account domain, for example agat.lan, before enabling SAML.

• The Keycloak email/UPN may use a different suffix. The configured SAML account domain selects the existing Admin Site account.

• Ensure each SAML identity can match exactly one existing Windows user by stable provider user ID, email, or company email. The account remains Windows until the first existing user is matched successfully, then it changes to SAML.

• Do not add the Keycloak email suffix as a second database account domain only to make migration work.

Keycloak's realm certificate in the identity-provider metadata is used by Admin Site to validate Keycloak responses. It is separate from the Admin Site service-provider certificate that Keycloak uses to validate signed Admin Site requests.

Before the selected certificate expires, install the replacement certificate and grant the application pool access to its private key. Upload the replacement public certificate to the identity provider, select the replacement certificate in Admin Site, save, restart the site, and test service-provider-initiated sign-in before removing the old certificate.

• Microsoft Entra ID: Enforce signed SAML authentication requests

• Okta: Application Integration Wizard SAML field reference

• Keycloak Server Administration Guide: SAML clients