> ## Documentation Index
> Fetch the complete documentation index at: https://ekso.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Configure login methods — forms-based authentication with password policies, Microsoft Entra ID SSO, and two-factor verification.

## Overview

Ekso supports two authentication methods: **forms-based login** (email and password) and **Microsoft Entra ID** (single sign-on). You can enable one or both at the same time. Administrators can always sign in with email and password, even if forms authentication is disabled — this prevents system lock-out.

Authentication settings are configured under **Settings > Authentication**.

## Forms authentication

Forms authentication lets users sign in with an email address and password. When active, Ekso enforces password policies and optionally requires two-factor authentication.

### Password policies

Password policies control the complexity and lifecycle of user passwords.

| Setting                  | Description                                                                    | Default       |
| ------------------------ | ------------------------------------------------------------------------------ | ------------- |
| Password change interval | Days before a password change is required. Set to 0 to disable forced changes. | 0 (never)     |
| Minimum length           | Shortest allowed password                                                      | 8 characters  |
| Maximum length           | Longest allowed password                                                       | 40 characters |
| Require number           | Password must contain at least one digit                                       | On            |
| Require uppercase letter | Password must contain at least one uppercase letter                            | On            |
| Require lowercase letter | Password must contain at least one lowercase letter                            | On            |
| Require symbol           | Password must contain at least one symbol (`!@#$%^&*()-=_+`)                   | Off           |

Ekso also prevents password reuse — users cannot set a new password that matches their previous password.

### Two-factor authentication

When enabled, Ekso sends a verification code to the user's email address after they enter their password. The user must enter this code to complete sign-in.

| Setting                   | Description                                      | Default |
| ------------------------- | ------------------------------------------------ | ------- |
| Two-factor authentication | Enable or disable 2FA                            | Off     |
| 2FA code length           | Number of digits in the verification code (6–10) | 6       |

<Note>
  Two-factor codes are sent by email, not SMS or authenticator app. Make sure your mail configuration is working before enabling 2FA.
</Note>

## Microsoft Entra ID

Microsoft Entra ID (formerly Azure Active Directory) enables single sign-on for organizations on Microsoft 365. Users sign in with their Microsoft account instead of a separate Ekso password.

To connect Entra ID, you need:

| Setting                 | Description                                    |
| ----------------------- | ---------------------------------------------- |
| Tenant ID               | Your Microsoft Entra directory ID              |
| Application (client) ID | The app registration ID from your Entra tenant |

<Tip>
  Use Entra ID if your organization is on Microsoft 365. It removes the need for separate passwords and supports your organization's conditional access policies.
</Tip>

### Setting up Entra ID

<Steps>
  <Step title="Register an application">
    In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **App registrations** → **+ New registration** (or select an existing app). Note the **Application (client) ID** and **Directory (tenant) ID** from the app's overview page.
  </Step>

  <Step title="Add an SPA redirect URI">
    Open the app's **Authentication** blade → **+ Add a platform** → **Single-page application**, then add the following redirect URI:

    ```
    https://ekso.acme.com/auth/entra/callback
    ```

    Replace `ekso.acme.com` with your Ekso install's hostname — the `PublicUrl` you set during the `/startup` wizard (for example, `https://ekso.acme.com/auth/entra/callback`). Entra requires an exact match — scheme, host, and path must all line up — so add a separate entry for each install URL you sign in from (production, staging, dev, and so on).

    <Note>
      The **Single-page application** platform type configures Entra for the OAuth 2.0 authorization code flow with PKCE, which is what Ekso's frontend uses. Do not register the same URL under the **Web** platform — that flow expects a server-side client secret and will fail for a browser app.
    </Note>
  </Step>

  <Step title="Add API permissions">
    Click **API permissions** → **+ Add a permission** → **Microsoft Graph** → **Delegated permissions**. Add the following permissions:

    | Permission       | Type      | Description                                         | Admin consent |
    | ---------------- | --------- | --------------------------------------------------- | ------------- |
    | `offline_access` | Delegated | Maintain access to data you have given it access to | No            |
    | `openid`         | Delegated | Sign users in                                       | No            |
    | `profile`        | Delegated | View users' basic profile                           | No            |
    | `User.Read`      | Delegated | Sign in and read user profile                       | No            |

    <Note>
      These are **Delegated** permissions — they act on behalf of a signed-in user during the SSO login flow. They do not require admin consent. If you also use Ekso's [mailbox connection](/guide/concepts/mailbox#azure-app-registration), the same app registration will need additional **Application** permissions for mail access.
    </Note>
  </Step>

  <Step title="Configure in Ekso">
    Go to **Settings > Authentication > Microsoft Entra** and enter the tenant ID and client ID.
  </Step>

  <Step title="Enable the integration">
    Toggle **Active** on. Users can now sign in with their Microsoft account.
  </Step>
</Steps>

<Warning>
  If you disable forms authentication while Entra ID is not properly configured, non-administrator users will be unable to sign in. Administrators can always sign in with email and password as a safety mechanism.
</Warning>

## How authentication methods work together

You can run both authentication methods at the same time. When a user signs in:

* If only **forms** is active, users sign in with email and password
* If only **Entra** is active, users are redirected to Microsoft for sign-in (administrators can still use email and password)
* If **both** are active, users can choose either method