# Sign-in & security

| Topic | Who | Where |
| --- | --- | --- |
| [Password](#password) and [two-factor authentication](#2fa) | every user for themselves | name at the bottom left → **Your profile** → **Password and authentication** |
| [MFA requirement for the company](#mfa) | **Admin** | **Settings** → **Company** → **Multi-Factor Authentication** |
| [Single sign-on with Microsoft Entra ID](#entra-id) | **Admin** | **Settings** → **Company** → **Single Sign On** |
| [Single sign-on with SAML](#saml) | **Admin** | **Settings** → **Company** → **SAML** |
| [API keys](#api-keys) | **IT**, **Admin** | **Settings** → **Integrations** → **API Integrations** |

## Signing in {#sign-in}

On the sign-in page you sign in with **Email address** and **Password**. If single sign-on is set up for your company, click **Login without password (SSO)** instead, see [Signing in via SSO](#sso-sign-in).

- After 10 sign-in attempts within 2 minutes, Workist briefly blocks further attempts for this email address ("Too many attempts, try again later.").
- If you have forgotten your password, click **Forgot your Password?**. Workist sends you a link for setting a new password. The link is valid for 7 days.

## Password {#password}

To change your password:

1. Click your name at the bottom left → **Your profile** and select **Password and authentication** on the left.
2. Under **Change password**, enter your **Current password**, then the new password twice (**New password**, **Confirm new password**).
3. Click **Change password**.

A password must be at least 12 characters long, must not consist of digits only, must not be a commonly used password and must not be too similar to your name or email address.

Users with the **Manager** and **Admin** roles can send employees an email to reset their password, see [Managing employees](/en/docs/administration/users-and-roles.md#employees). People who sign in via SSO usually have no Workist password and cannot reset one either, see [Single sign-on](#sso).

## Two-factor authentication {#2fa}

With two-factor authentication (2FA), Workist asks for a second factor in addition to the password at sign-in. You set it up under **Password and authentication** in the **Two-factor authentication** section:

| Method | How it works |
| --- | --- |
| **Passkeys** | You confirm the sign-in by fingerprint, face recognition, device PIN or security key. Click **Add** → **Setup passkey**, follow your browser and click **Save**. Your browser must support passkeys. |
| **Authenticator apps** | An app or browser extension generates one-time codes. Click **Add**, scan the QR code or enter the setup key, enter the current code under **Enter the verification code** and click **Save**. |
| **Recovery codes** | Six emergency codes in case you have no access to your other methods. Each code works once. Keep the codes in a safe place. |

To add or remove a method, Workist asks for your Workist password (**Register device** or **Unregister device**). You can give every method a device name so you recognise it later.

**First setup:** as long as you have not set up a method, Workist shows the **Two-Factor Authentication** page after every sign-in with password. There you set up a passkey or an authenticator app, click **Continue**, create your recovery codes and finish with **I saved the codes and want to continue**. Without the MFA requirement you can skip the step with **Continue without two-factor authentication**.

**Sign-in:** once you have set up a method, Workist asks for the second factor at every sign-in with password. **Use other device** lets you pick another method, e.g. a recovery code.

When you sign in via SSO, Workist does not ask for a second factor. Your identity provider takes care of that.

### Lost access {#2fa-lost}

If you no longer have access to your methods, sign in with a recovery code and then set up a new method. If you have no recovery codes left either, contact Workist support. An Admin of your company cannot reset two-factor authentication.

## Requiring MFA for the whole company {#mfa}

An **Admin** can make multi-factor authentication mandatory for all employees:

1. Open **Settings** → **Company** and select **Multi-Factor Authentication** on the left.
2. Turn on **Multi-Factor Authentication (MFA) is required for every employee**.
3. Click **Save**.

Employees without a method are asked to set one up after their next sign-in. Until they have set up a method, they cannot use Workist; the step can no longer be skipped.

:::warning MFA requirement and SSO
The MFA requirement also applies to users who sign in via SSO. To set up a method, Workist asks for the Workist password, and users who sign in via SSO usually have none. They then cannot set up a method and can no longer use Workist. If you use SSO, leave the MFA requirement in Workist turned off and require multi-factor authentication in your identity provider.
:::

## Single sign-on {#sso}

With single sign-on (SSO), your employees sign in with their company account instead of a Workist password. Workist supports two methods:

- **Microsoft Entra ID** (formerly Azure AD), set up on the **Single Sign On** page
- **SAML 2.0** with any identity provider, set up on the **SAML** page

Only users with the **Admin** role set up SSO. Use only one of the two methods for your company: Workist always signs existing users in through the same configuration of your company, regardless of the domain of their email address.

### Signing in via SSO {#sso-sign-in}

1. The user clicks **Login without password (SSO)** on the sign-in page.
2. They enter their email address and click **Sign in**.
3. Workist forwards them to your identity provider and back after sign-in.

The email address entered must exactly match the address the identity provider reports for this user; for Microsoft Entra ID this is the user principal name (UPN). If the addresses differ, sign-in fails. If there is no matching configuration or Workist account for the address, Workist shows: "SSO is not enabled for your company or your user account isn't enabled for SSO."

### Setting up Microsoft Entra ID {#entra-id}

**Step 1: register an app in Microsoft Entra ID**

1. In the Microsoft Entra admin center, create a new registration under **App registrations**. Accounts in your organizational directory are sufficient as the account type.
2. Enter this redirect URI for the **Web** platform: `https://wb.workist.com/login/providers/azure/authorized`
3. Under **Certificates & secrets**, create a client secret and copy its **Value**. Note the expiry date.
4. Under **API permissions**, check that the delegated Microsoft Graph permission `User.Read` is present. Workist uses it to read the signed-in user's name and user principal name.
5. In the **Overview**, note the **Application (client) ID** and the **Directory (tenant) ID**.

**Step 2: create the configuration in Workist**

1. Open **Settings** → **Company** and select **Single Sign On** on the left. The page lists the existing configurations.
2. Click **Add SSO Configuration** and fill in the form:

   | Field | What to enter |
   | --- | --- |
   | **SSO is required for every employee** | **Yes:** employees can only sign in via SSO. Sign-in with email and password is rejected. |
   | **Provider Name** | Enter `azure` (Microsoft Entra ID). |
   | **Domain** | Domain of the email addresses, e.g. `company.com`. Workist uses it to assign new users to your company during self-registration. |
   | **Allow Self Registration** | **Yes:** anyone with an email address of this domain who has no Workist account yet gets one automatically at their first SSO sign-in (role **Member**, default team). **No:** only existing users can sign in. |
   | **Tenant ID** | **Directory (tenant) ID** from the app registration in Microsoft Entra ID. |
   | **Client ID** | **Application (client) ID** of the app registration. |
   | **Client Secret** | **Value** of the client secret. Workist hides it after saving. If you leave the field empty, the stored value is kept. |

3. Click **Create**.

Use a row's pencil icon to edit a configuration and the trash icon to delete it.

**Step 3: test.** Sign in via SSO with a test user before you turn on **SSO is required for every employee**.

**Several domains:** each configuration applies to one domain. If your employees have email addresses with different domains, create one configuration per domain, all with the same app registration (same tenant ID, client ID and client secret) and the same setting for **SSO is required for every employee**.

**What changes for users:**

- After the first sign-in via Microsoft Entra ID, Workist disables the user's Workist password. From then on they only sign in via SSO; **Forgot your Password?** no longer helps them either.
- Employees you invite while SSO is set up get no Workist password, but an invitation to sign in via SSO.

:::warning The client secret expires
A client secret in Microsoft Entra ID has an expiry date. After it, nobody can sign in via SSO. Create a new secret in time and enter its value in Workist under **Client Secret**.
:::

### Setting up SAML {#saml}

**Step 1: get Workist's addresses**

1. Open **Settings** → **Company** and select **SAML** on the left.
2. Enter the **Domain** and click **Save**. The page then shows, after a reload if needed, the **SP Metadata URL** and the **Assertion Consumer Service (ACS) URL**.

**Step 2: create an application in your identity provider**

Create a SAML application in your identity provider. Many identity providers import the values directly from the **SP Metadata URL**. Otherwise enter:

- the **SP Entity ID** from the Workist page as entity ID or audience,
- the **Assertion Consumer Service (ACS) URL** as reply URL (ACS),
- the user's email address as NameID in the `emailAddress` format.

The email address must exactly match the user's email address in Workist.

**Step 3: enter your identity provider's details in Workist**

| Field | What to enter |
| --- | --- |
| **SAML is required for every employee** | **Yes:** employees can only sign in via SAML. Sign-in with email and password is rejected. |
| **Domain** | Domain of your employees' email addresses, e.g. `company.com`. |
| **Allow Self Registration** | Has no effect for SAML. Only users who already exist in Workist can sign in. |
| **IdP Entity ID** | Entity ID (issuer) of your identity provider. |
| **IdP SSO URL** | Single sign-on URL of your identity provider for the HTTP-Redirect binding. |
| **IdP SLO URL (Single Logout)** | Optional. |
| **IdP X.509 Certificate** | Signing certificate of your identity provider (Base64). Workist hides it after saving. If you leave the field empty, the stored certificate is kept. |
| **SP Entity ID** | Read-only. Workist's identifier. Enter it at your identity provider as entity ID or audience. |
| **SP Name ID Format** | Read-only. Workist expects the email address as NameID (`emailAddress`). |
| **SP Metadata URL** | Read-only, shown after the first save. Workist's metadata; many identity providers can import the settings from this address. |
| **Assertion Consumer Service (ACS) URL** | Read-only, shown after the first save. Reply URL that you enter at your identity provider. |
| **Require Signed Assertions** | **Yes:** Workist only accepts signed assertions. Recommended. |
| **Require Signed Messages** | **Yes:** Workist also requires the whole SAML response to be signed. |
| **Attribute Mapping (JSON)** | Optional. Only needed if your identity provider sends the email address neither as NameID nor in the attribute `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. Example: `{"email": "mail"}`. Workist only reads the email address from the response. |

Click **Save**.

**Step 4: create users and test.** Only users who already exist in Workist can sign in via SAML. Invite your employees, see [Inviting employees](/en/docs/administration/users-and-roles.md#invite), and test the sign-in before you turn on **SAML is required for every employee**.

Keep in mind:

- Always start the sign-in on the Workist sign-in page via **Login without password (SSO)**. Workist does not support signing in from your identity provider's portal.
- Signing in via SAML does not disable the Workist password. If nobody should use the password any more, turn on **SAML is required for every employee**.

### Allowing sign-in via SSO only {#sso-required}

With **SSO is required for every employee** (Microsoft Entra ID) or **SAML is required for every employee**, Workist rejects sign-in with email and password for all users of your company, including Admins. They get the message "Login via SSO is required for this account." Only turn the option on once sign-in via SSO works.

## API keys {#api-keys}

With an API key, your systems access Workist via the [Workist API](/en/docs/api-documentation.md). A key belongs to the company, not to a person. Users with the **IT** and **Admin** roles manage keys under **Settings** → **Integrations** → **API Integrations**:

- **Create:** **Add Integration** → enter an **Integration name**, optionally pick an **Expiration Date** and decide which channels the key applies to: **Grant access to all channels** or individual channels per document type. Then **Create Integration**.
- **Copy the key:** Workist shows the key only once. Copy it right away and store it securely.
- **Expiration date:** after the expiration date, Workist rejects requests with this key. Extend the date via **Edit integration**.
- **Renew:** **Renew API key** generates a new key. The old one stops working immediately.
- **Delete:** **Delete integration** invalidates the key immediately.

Keys that Workist creates for an [Outlook add-in](/en/docs/data-exchange/outlook-add-in.md) do not appear in this list.