SAML 2.0 lets your people sign in to wxrks with the identity provider (IdP) your company already uses, such as Okta, Microsoft Entra ID or OneLogin. This guide shows what to copy between your IdP and wxrks, how users are created the first time they sign in, how to require SSO for the whole account, and how long a session lasts. For OIDC sign-in with Okta, OneLogin or Microsoft Entra ID, and for the overview of single sign-on at wxrks, see wxrks Single Sign-On (SSO).

💡 Who is this for? This guide is for the Account Admin who needs to connect a SAML 2.0 identity provider to wxrks, together with the IT administrator who manages the IdP.

Sign-in always starts at wxrks. Users open the SP-initiated Login URL from wxrks, wxrks sends them to your IdP, and your IdP sends them back to wxrks with a signed assertion.
Sign-in started from the IdP is not supported. If a user clicks an IdP tile that sends an assertion directly to wxrks, wxrks rejects it. Point the tile or bookmark at the SP-initiated Login URL instead.
wxrks matches the user by email address. The NameID your IdP sends must be the user's email.
The user must already exist in wxrks, unless you turn on automatic user creation (see Create users on first login).

Step 1: Copy the values from wxrks

Go to Settings > Account Settings > Identity & Security, open the Single Sign-On tab and find the SAML 2.0 card. It shows Configured or Not configured.

Identity & Security > Single Sign-On tab with a red box around the expanded SAML 2.0 card: the IdP Entity ID, IdP SSO URL and IdP X.509 Certificate fields with the Import button, the SP Entity ID field, and the Integration URLs section with the Assertion Consumer Service (ACS) URL and the SP-initiated Login URL, each with a copy button.

Copy these three values for your IdP:

Assertion Consumer Service (ACS) URL. In your IdP this is also called the reply URL, recipient or destination.
SP Entity ID. It is optional in wxrks. When you leave it blank, wxrks uses the ACS URL as its entity ID, so your IdP's audience must then be the ACS URL.
SP-initiated Login URL. This is the address your users open to sign in.

ℹ️ Note: wxrks does not offer SP metadata as a file or a URL. Enter the values above in your IdP by hand.

Step 2: Configure your identity provider

Create a SAML 2.0 application for wxrks in your IdP and set:

ACS / reply URL: the ACS URL from wxrks.
Audience: the SP Entity ID from wxrks, or the ACS URL if you left it blank.
NameID: the user's email address. wxrks does not ask for a specific NameID format, so use the one your IdP offers for email.
Signing: sign the assertion. A signed response alone is not accepted. wxrks does not support encrypted assertions, so turn assertion encryption off in your IdP.
Role attribute (optional): to assign roles on first login, send an attribute named Role, role, roles, Roles, groups or Group.

From your IdP, copy the issuer (entity ID), the SSO URL and the signing certificate.

Step 3: Enter the IdP values in wxrks

Back on the SAML 2.0 card, fill in:

IdP Entity ID: the issuer from your IdP.
IdP SSO URL: the IdP's single sign-on URL.
IdP X.509 Certificate: the IdP's public signing certificate in PEM format. Paste it, or click Import to load it from a file. It is not a secret, and wxrks stores it encrypted.
SP Entity ID (optional): leave it blank unless your IdP requires a specific audience.

Click Save SAML2 Configuration, then click OK to confirm. All three IdP fields are required. After saving, the certificate shows Certificate configured, with Replace if you need to upload a new one.

To disconnect SAML, click Remove SAML2 Configuration and confirm. This also removes the automatic user creation settings.

⚠️ Warning: The SAML URLs are derived from the account's SSO Security Key. If you click Rotate SSO Key, the ACS URL and the SP-initiated Login URL change, and you must update your IdP.

Open the SP-initiated Login URL in a browser. You are sent to your IdP, sign in there, and land in wxrks. Give your users this link, or add it as a bookmark or as the link of the IdP tile.

Go to the User Provisioning tab and open the SAML JIT Provisioning card. If SAML is not configured yet, the card tells you to set it up first.

Identity & Security > User Provisioning tab with the SAML JIT Provisioning card expanded and four numbered red boxes: the switch to automatically create users on first successful SAML login, the Role Mapping row with Add Role Mapping, the Default Organizational Unit selector and the Save JIT Provisioning button.

Turn on Automatically create users on first successful SAML login.
Under Role Mapping, click Add Role Mapping and pair each value your IdP sends in the role attribute (Role in your Identity Provider) with a wxrks role: Account Admin, Project Manager, Client or Vendor.
Choose the Default Organizational Unit for new users. It must belong to your account.
Click Save JIT Provisioning, then click OK to confirm.

The new user is active, and their email is their username.
Every new user gets the basic user role. Mapped roles are added on top. If no role attribute matches, the user keeps only the basic role until you assign one in People > Users.
Users that already exist are matched by email and are not changed.
Nothing is synced ahead of time. If you need accounts created, updated and deactivated automatically, use SCIM: see the SCIM user provisioning reference.

Require SSO for the whole account

Go to the Security Policies tab. The Login Method card has the switch Require Single Sign-On for every user on this account. Turn it on and click Save Security Policies.

Identity & Security > Security Policies tab with a red box around the Login Method card and its switch to require single sign-on for every user on this account. Below it are the Multi-Factor Authentication, Session Timeout and Password Policy cards and the Save Security Policies button.

When it is on, password and magic-code sign-in are blocked. Users can only sign in through your identity providers (OIDC or SAML).
API keys are not affected.

⚠️ Warning: Configure and test SSO before you turn this on, or nobody could sign in. The confirmation message warns that this includes your own administrator access.

The other cards on this tab apply to password sign-in only. Multi-Factor Authentication (TOTP) and the Password Policy (minimum length, expiry in days) do not apply to users who sign in through SSO. For those users, multi-factor authentication is your IdP's job.

Session lifetime

A session lasts 10 days by default, counted from sign-in. There is no idle timeout.
To change it, set Session timeout (minutes) on the Security Policies tab, from 15 minutes to 30 days (43,200 minutes), and click Save Security Policies. A shorter value applies to new sign-ins only.
Revoke all active sessions signs out everyone, including you. It does not affect API keys.

How long your identity provider keeps its own session is set in the IdP, not in wxrks.

Troubleshooting

Sign-in fails after the IdP step. Check that your IdP signs the assertion, that its issuer equals the IdP Entity ID, that the audience equals the SP Entity ID (or the ACS URL when it is blank), and that the destination is the ACS URL. The clocks of the IdP and wxrks may differ by at most 2 minutes.
Clicking the tile in the IdP does nothing in wxrks. Sign-in started from the IdP is not supported. Use the SP-initiated Login URL.
"User not found" or no access after signing in. The NameID must be the user's email, and the user must exist in wxrks, or SAML JIT Provisioning must be on.
Everything worked, then stopped. Someone may have clicked Rotate SSO Key. Copy the new ACS URL and login URL into your IdP.

Quick reference

Item	Value
Where	Settings > Account Settings > Identity & Security
From wxrks to the IdP	ACS URL, SP Entity ID (or the ACS URL), SP-initiated Login URL
From the IdP to wxrks	IdP Entity ID, IdP SSO URL, IdP X.509 certificate (PEM)
NameID	The user's email
Signing	The assertion must be signed; encrypted assertions are not supported
Login	Started from wxrks only (SP-initiated)
Session	10 days by default, 15 minutes to 30 days

wxrks Single Sign-On (SSO) — supported protocols and providers, OIDC sign-in with Okta, OneLogin and Microsoft Entra ID, and SCIM provisioning.
SCIM user provisioning reference

Set up SAML 2.0 single sign-on

How SAML sign-in works