> For the complete documentation index, see [llms.txt](https://docs.elsaworkflows.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elsaworkflows.io/guides/authentication/external-authentication/installation.md).

# Installation

> **Preview feature:** External Authentication is available starting with **Elsa 3.8 preview** packages. At the time of writing it is published from the [Elsa Feedz preview feed](https://f.feedz.io/elsa-workflows/elsa-3/nuget/index.json), not as a stable NuGet.org release, and remains under active development. Test upgrades in a non-production environment and expect configuration or API changes before general availability.

External Authentication makes Elsa Server a broker between Elsa Studio and one or more upstream identity providers. Elsa owns the sign-in transaction, issues the Elsa access and refresh tokens that Studio consumes, and can centrally manage connections, identity links, sessions, and permission mapping. The first supplied provider adapter is OpenID Connect.

This is different from Studio's existing direct OpenID Connect mode, in which Studio talks directly to the identity provider. See [Migration from Direct OpenID Connect](/guides/authentication/external-authentication/migration-from-direct-oidc.md) before changing an existing Studio host.

## Prerequisites

* An Elsa **3.8 preview** application with Elsa Identity enabled. The broker issues Elsa credentials, so it needs Elsa Identity token signing and a user/role provider.
* An upstream OpenID Connect provider with a confidential client registration for Elsa Server.
* A public HTTPS address for Elsa Server. It is used to derive the fixed provider callbacks.
* For production or multiple nodes, a relational database supported by the selected persistence provider and a shared ASP.NET Core Data Protection key store. See [Production](/guides/authentication/external-authentication/production.md).

Use a real secret manager, environment variables, or another configuration provider for keys and client secrets. The examples deliberately use placeholders only.

## Configure the preview feed

Add the Feedz source to `NuGet.config` alongside NuGet.org:

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="Elsa 3 preview" value="https://f.feedz.io/elsa-workflows/elsa-3/nuget/index.json" />
  </packageSources>
</configuration>
```

Install preview packages and keep all Elsa Core packages on one compatible `3.8.0-preview.*` build. Pin the resolved build centrally for repeatable deployments; do not mix preview packages with a released 3.x package set.

## Choose packages

Install the foundation and at least one protocol adapter:

```bash
dotnet add package Elsa.ExternalAuthentication --prerelease
dotnet add package Elsa.ExternalAuthentication.OpenIdConnect --prerelease
```

The available packages are:

| Package                                                     | When to install it                                                                                                                                    |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Elsa.ExternalAuthentication`                               | Required foundation: broker, connection model, management and broker APIs, in-memory development stores, permission mapping, and local-login support. |
| `Elsa.ExternalAuthentication.OpenIdConnect`                 | Installs the `openid-connect` upstream provider adapter.                                                                                              |
| `Elsa.ExternalAuthentication.Secrets`                       | Optional bridge to Elsa Secrets for Elsa-managed client secrets. It is not needed for secrets read from standard .NET configuration.                  |
| `Elsa.ExternalAuthentication.Persistence.EFCore`            | Shared EF Core persistence base. It is normally brought in transitively by a provider package.                                                        |
| `Elsa.ExternalAuthentication.Persistence.EFCore.Sqlite`     | EF Core persistence for SQLite.                                                                                                                       |
| `Elsa.ExternalAuthentication.Persistence.EFCore.SqlServer`  | EF Core persistence for SQL Server.                                                                                                                   |
| `Elsa.ExternalAuthentication.Persistence.EFCore.PostgreSql` | EF Core persistence for PostgreSQL.                                                                                                                   |
| `Elsa.ExternalAuthentication.Persistence.EFCore.MySql`      | EF Core persistence for MySQL.                                                                                                                        |
| `Elsa.ExternalAuthentication.Persistence.EFCore.Oracle`     | EF Core persistence for Oracle.                                                                                                                       |

For example, a SQL Server deployment adds:

```bash
dotnet add package Elsa.ExternalAuthentication.Persistence.EFCore.SqlServer --prerelease
```

The provider-specific package is required for its migrations and, in a CShells host, to make the corresponding shell feature discoverable. Identity persistence and External Authentication persistence are separate features: adding `Elsa.Persistence.EFCore.*` or enabling an Identity persistence feature does **not** make broker state durable.

## Classic `AddElsa` host

Register Elsa Identity, the broker, and the OIDC adapter. Use `BindExternalAuthenticationOptions` rather than plain configuration binding: it also reconstructs the JSON settings carried by adapters, policies, and permission grant sources.

```csharp
using Elsa.Extensions;
using Microsoft.Extensions.Configuration;

builder.Services.AddElsa(elsa =>
{
    elsa.UseIdentity(identity =>
    {
        identity.TokenOptions = options =>
        {
            options.SigningKey = builder.Configuration["Identity:SigningKey"]
                ?? throw new InvalidOperationException("Identity signing key is required.");
            options.Issuer = "https://elsa.example.com";
            options.Audience = "https://elsa.example.com";
        };
    });

    elsa.UseExternalAuthentication(feature =>
    {
        feature.ConfigureOptions = options =>
            builder.Configuration.GetSection("ExternalAuthentication")
                .BindExternalAuthenticationOptions(options);
    });
});

builder.Services.AddOpenIdConnectExternalAuthentication();
```

This registration uses in-memory stores and is appropriate only for local, single-node development. Add the selected EF Core feature for a durable host. The SQLite form illustrates the classic feature composition:

```csharp
using Elsa.ExternalAuthentication.Persistence.EFCore.Sqlite.Extensions;

builder.Services.AddElsa(elsa =>
{
    elsa.UseExternalAuthentication(externalAuthentication =>
    {
        externalAuthentication.UseEntityFrameworkCore(ef =>
            ef.UseSqlite("Data Source=external-authentication.db;Cache=Shared"));
    });
});
```

Keep this in the same Elsa configuration that enables the broker. Replace `UseSqlite` with `UseSqlServer`, `UsePostgreSql`, `UseMySql`, or `UseOracle` when using the matching provider package. Apply that provider's `ExternalAuthenticationElsaDbContext` migration through your normal migration deployment process.

If a connection or authentication client uses Elsa-managed secrets, register the optional bridge as well:

```csharp
builder.Services.AddElsaSecretsExternalAuthentication();
```

## CShells / Modular Server

CShells hosts discover External Authentication through shell features. Ensure the application references the adapter package and, for durable state, the matching persistence package. Enable the feature names in the shell configuration:

```json
{
  "CShells": {
    "Shells": {
      "Default": {
        "Features": {
          "ExternalAuthentication": {
            "Redirects": {
              "ExternalCallbackBaseUri": "https://elsa.example.com/elsa/api/"
            }
          },
          "OpenIdConnectExternalAuthentication": {},
          "SqlServerExternalAuthenticationPersistence": {
            "ConnectionString": "<external-authentication-database-connection-string>"
          }
        }
      }
    }
  }
}
```

Replace `Default` with the configured shell name when the host uses another shell. The feature-local settings path is therefore `CShells:Shells:<shell-name>:Features:ExternalAuthentication`.

The persistence feature names are `SqliteExternalAuthenticationPersistence`, `SqlServerExternalAuthenticationPersistence`, `PostgreSqlExternalAuthenticationPersistence`, `MySqlExternalAuthenticationPersistence`, and `OracleExternalAuthenticationPersistence`.

To resolve managed bindings from Elsa Secrets, also enable `ElsaSecretsExternalAuthentication`; it depends on both `ExternalAuthentication` and the Elsa `Secrets` feature. The OIDC feature depends on `ExternalAuthentication`. A Modular Server reference host demonstrates these packages and features.

## Confirm the installation

After startup, the broker APIs live below Elsa's API route prefix, for example `https://elsa.example.com/elsa/api/external-authentication`.

1. Configure an Authentication Client and at least one connection as described in [Configuration](/guides/authentication/external-authentication/configuration.md).
2. Request `GET /external-authentication/login-methods?clientId=<your-client-id>`.
3. Confirm that the response lists the local method (unless disabled) and your enabled connection, without provider settings or secrets.
4. For a persisted setup, verify that the selected External Authentication persistence feature is enabled and its migrations are applied.

The management UI is provided by the companion Elsa Studio External Authentication modules. Once those modules are installed, open **Administration → Identity & access → Identity provider connections** (`/security/external-authentication/connections`) to manage database-owned connections; configuration-owned connections are inspect-only.