Skip to content
Documentation

Single sign-on with SAML

Connect an Enterprise identity provider with SAML.

Last updated 2026-10-23

Single sign-on with SAML

Enterprise Owners can connect their identity provider under Settings > Single sign-on. Ask your IT administrator to follow these steps. Password sign-in stays available if SAML fails.

Before you start

Have provider-admin access and your two-step verification device. Saving needs confirmation within the last five minutes. Keep your signed-in setup tab open until the test works.

What your identity provider must support

  • SAML 2.0 started from PoultryDesk, with both response and assertion signed.
  • RSA with SHA-256; a valid certificate using RSA 2048 bits or greater, or EC P-256, P-384 or P-521.
  • Email-format Name ID, an HTTPS sign-in URL, and email/name attributes.

Complete sign-in within five minutes. Provider clocks must be within two minutes.

Step 1: copy PoultryDesk's details

Copy Entity ID / Audience, ACS URL and Metadata URL from Service provider details. Use your organization's actual address. For a branded address, activate the custom domain first.

Step 2: create the application in your identity provider

Microsoft Entra ID

  1. Create a non-gallery Enterprise application and choose SAML.
  2. Copy Entity ID and ACS into Identifier and Reply URL. Set Sign on URL to your farm address plus /api/auth/saml/login.
  3. Add email from user.mail and displayName from user.displayname, both with empty Namespace.
  4. Choose Sign SAML response and assertion. Download Certificate (Base64) and copy Login URL and Microsoft Entra Identifier.
  5. Assign the users or groups who should have access.

Okta

  1. Create a SAML 2.0 application.
  2. Set Single sign-on URL to ACS, Audience URI to Entity ID, Name ID format to EmailAddress and Application username to Email.
  3. Map email to user.email and displayName to user.displayName.
  4. In advanced settings, sign both response and assertion. Copy the issuer, sign-in URL and certificate from View SAML setup instructions.
  5. Assign permitted users. Configure the portal tile to start at PoultryDesk's /api/auth/saml/login.

Keycloak

  1. Create a SAML client with Client ID equal to PoultryDesk's Entity ID.
  2. Set Valid redirect URIs and Master SAML Processing URL to ACS; Name ID format to email.
  3. Enable Sign documents and Sign assertions; choose RSA_SHA256.
  4. Map email and displayName with Basic attribute-name format.
  5. Copy the RSA signing certificate from Realm settings > Keys. The issuer is https://your-keycloak-host/realms/<realm>; sign-in URL adds /protocol/saml. HTTPS is required.

Step 3: paste the details into PoultryDesk

Enter IdP entity ID, HTTPS IdP sign-in URL, and the full PEM IdP signing certificate, including its BEGIN/END lines. Set Email attribute and Name attribute to the exact claim names, normally email and displayName. Keep Enable SAML sign-in off and save with two-step confirmation.

Step 4: turn it on and test

  1. Enable SAML sign-in and save.
  2. In a private window, open your farm address plus /api/auth/saml/login.
  3. Sign in at the provider and check you reach the dashboard.

If refused, keep the original setup tab open and use the checks below.

How your team signs in

Share your farm's /api/auth/saml/login link. Sign-in must start there, including from a provider portal tile. Add ?callbackUrl=/lots for a different landing page.

Who gets an account

Email matches keep existing memberships and roles; pending invitations are accepted. New members receive Worker. Suspended or revoked memberships stay blocked. Provider assignment therefore grants access: remove leavers there and review members and roles. Changes and sign-ins are audited.

If you use a custom domain

Activate the domain, then open SAML settings from that address. Copy its Entity ID, ACS and sign-in values. Update the provider if you change addresses later.

Turning single sign-on off

Untick Enable SAML sign-in and save. Password sign-in remains; settings and memberships are kept. Remove unwanted members separately.

When something is not working

  • Sign-in returns to the login page: sign both response and assertion; start from PoultryDesk's link and check provider clocks.
  • Certificate rejected: paste the complete, current certificate with an accepted key size.
  • URL rejected: use HTTPS.
  • One colleague cannot sign in: check provider assignment and membership.
  • Wrong access: review their Worker role.
  • Sudden failures: check for an expired or rotated certificate.

If locked out, sign in with your password.

Organization settings · Your account