# Authentication Overview

*Secure your Ivy application with integrated authentication providers including Auth0, Clerk, Supabase, Authelia, and Microsoft Entra ID.*

The `ivy auth add` command lets you add and configure authentication in your Ivy project. Ivy supports multiple providers and automatically updates your project setup to integrate them.

## Adding an Authentication Provider

To add authentication to your Ivy project, run:

```terminal
>ivy auth add
```

If you run this command without additional options, Ivy will guide you through an interactive setup:

1. **Select a Provider**: Choose from the available authentication providers
2. **Configure the Provider**: Enter the necessary configuration details (for example, domain and client ID for Auth0, or project URL and API key for Supabase)
3. **Project Setup**: Ivy updates your [Program.cs](../../02_Concepts/01_Program.md) and stores sensitive values in [.NET user secrets](../../02_Concepts/14_Secrets.md), so your project is ready to use authentication.

### Command Options

`--provider <PROVIDER>` or `-p <PROVIDER>` - Specify the authentication provider directly:

```terminal
>ivy auth add --provider Auth0
```

Available providers: `Auth0`, `Clerk`, `Supabase`, `MicrosoftEntra`, `Authelia`, `Basic`

`--connection-string <CONNECTION_STRING>` - Provide provider-specific configuration using connection string syntax. When used with `--provider`, this option allows you pass all required configuration inline, rather than being prompted interactively during setup:

```terminal
>ivy auth add --provider Auth0 --connection-string YourConnectionString
```

`--verbose` or `-v` - Enable verbose output for detailed logging:

```terminal
>ivy auth add --verbose
```

### How Ivy Updates Program.cs

Ivy automatically updates your [Program.cs](../../02_Concepts/01_Program.md) to configure authentication. Here are a few examples of code that it may add:

**Basic Auth**

```csharp
server.UseAuth<BasicAuthProvider>();
```

**Auth0**

```csharp
server.UseAuth<Auth0AuthProvider>(c => c.UseEmailPassword().UseGoogle().UseApple());
```

**Supabase**

```csharp
server.UseAuth<SupabaseAuthProvider>(c => c.UseEmailPassword().UseGoogle().UseGithub());
```

Before making any changes to your Program.cs, Ivy checks whether an authentication provider is already configured.
- If you selected a **different provider** than what is already configured, Ivy will ask you to confirm before overwriting the existing configuration.
- If you selected the **same provider**, Ivy reuses the existing configuration as defaults for your new setup.

> **Note:** Only one authentication provider can be active at a time. However, some providers (such as Auth0 or Supabase) support multiple login methods (like Google, GitHub, or username/password), so you can still offer users a variety of login options.

### Security and Secrets Management

Ivy automatically configures [.NET user secrets](../../02_Concepts/14_Secrets.md) for secure authentication configuration. To view configured secrets:

```terminal
>dotnet user-secrets list
```

#### Environment Variables

Instead of .NET user secrets, you can also use environment variables to store authentication secrets. For example, you might configure Auth0 like so:

**Windows (PowerShell):**

```terminal
>$env:Auth0__Domain="your-domain.auth0.com"
>$env:Auth0__ClientId="your-client-id"
>$env:Auth0__ClientSecret="your-client-secret"
>$env:Auth0__Audience="https://your-domain.auth0.com/api/v2"
>$env:Auth0__Namespace="https://ivy.app/"
```

**Mac/Linux (Bash):**
```terminal
>export Auth0__Domain="your-domain.auth0.com"
>export Auth0__ClientId="your-client-id"
>export Auth0__ClientSecret="your-client-secret"
>export Auth0__Audience="https://your-domain.auth0.com/api/v2"
>export Auth0__Namespace="https://ivy.app/"
```

If configuration is present in both .NET user secrets and environment variables, Ivy will use the values in [user secrets](../../02_Concepts/14_Secrets.md).

## Authentication Flow

### OAuth2 Flow (Auth0, Supabase, Microsoft Entra)

1. User visits your application.
2. User clicks "Login" and is redirected to the identity provider.
3. User authenticates with the identity provider (e.g., Google, Microsoft, GitHub).
4. The identity provider redirects back to your application's callback URL with an authorization code.
5. Ivy exchanges the authorization code for an access token, and in some cases a refresh token.
6. Ivy uses the token(s) to establish an authenticated session for the user.

### Email/Password Flow (Basic Auth, Authelia)

1. User visits your application.
2. User is prompted for a username and password.
3. Credentials are validated by the configured authentication provider.
4. If valid, Ivy establishes an authenticated session for the user.

## Using IAuthService in Views

Use [UseService](../../02_Concepts/01_Program.md) to obtain `IAuthService` in your [views](../../02_Concepts/02_Views.md):

```csharp
var auth = UseService<IAuthService>();

await auth.LoginAsync(email, password);
var user = await auth.GetUserInfoAsync();
await auth.LogoutAsync();
```

## Supported Authentication Providers

Ivy supports the following authentication providers. Click on any provider for detailed setup instructions:

- **[Auth0](02_Auth0.md)** - Universal authentication with social logins and enterprise integrations
- **[Clerk](02_Clerk.md)** - Modern authentication platform with passwordless login, social connections, and comprehensive user management
- **[Supabase](02_Supabase.md)** - Email/password, magic links, social auth, and Row Level Security integration
- **[Microsoft Entra](02_MicrosoftEntra.md)** - Enterprise SSO, conditional access, and Microsoft Graph integration
- **[Authelia](02_Authelia.md)** - Self-hosted identity provider with LDAP and forward auth
- **[Basic Auth](02_BasicAuth.md)** - Simple username/password authentication for development and internal tools

## Examples

**Auth0 Setup**

```terminal
>ivy auth add --provider Auth0 --connection-string YourConnectionString
```

**Clerk Setup**

```terminal
>ivy auth add --provider Clerk --connection-string YourConnectionString
```

**Supabase Auth Setup**

```terminal
>ivy auth add --provider Supabase --connection-string YourConnectionString
```

**Basic Auth Setup**

```terminal
>ivy auth add --provider Basic --connection-string YourConnectionString
```

## Complete Custom Login View

For complete control over the login experience, you can replace the entire login view:

```csharp
server.UseAuth<BasicAuthProvider>(viewFactory: () => new MyCustomLoginApp());
```

## Customizing Authentication Cookies

Ivy allows you to customize authentication cookie settings globally from your [Program.cs](../../02_Concepts/01_Program.md) using the `Server.ConfigureAuthCookieOptions` static property. This enables you to override default cookie settings (such as expiration time, SameSite policy, Secure flag, etc.) based on your application's specific security requirements.

### Default Cookie Settings

By default, Ivy authentication cookies are configured with:
- **HttpOnly**: `true` (prevents JavaScript access)
- **Secure**: `true` in production, `false` in development (requires HTTPS)
- **SameSite**: `Lax` (provides CSRF protection while allowing cross-site navigation)
- **Expires**: 1 year from creation
- **Path**: `/` (available site-wide)

### Customizing Cookie Options

To override these defaults, set `Server.ConfigureAuthCookieOptions` in your `Program.cs` before calling `server.RunAsync()`:

```csharp
Server.ConfigureAuthCookieOptions = options => 
{
    options.Expires = DateTimeOffset.UtcNow.AddDays(30);
};
```

> **Note**: Custom configuration is applied after Ivy sets the default values, allowing you to override any setting. It's recommended to keep `HttpOnly = true` for security.

## Best Practices

**Security** - Always use HTTPS in production, store sensitive configuration in user secrets or environment variables, regularly rotate client secrets, use strong passwords for Basic Auth, and implement proper session management.

**Configuration** - Use descriptive names for your authentication providers, keep configuration separate from code, use environment-specific settings, and document your authentication setup.

**Testing** - Test authentication flows in development, verify token validation works correctly, and ensure logout functionality works properly.

## Troubleshooting

**Authentication Provider Issues** - Verify your provider configuration is correct, check that your project is properly registered with the identity provider, ensure callback URLs are correctly configured, and verify network connectivity to the authentication provider.

**Token Validation Issues** - Check that your JWT tokens are properly signed, verify audience and issuer claims, and ensure your system clock is set correctly.

**Configuration Issues** - Ensure authentication settings are properly stored in [user secrets](../../02_Concepts/14_Secrets.md) (or verify environment variables are correctly set), and check that your [Program.cs](../../02_Concepts/01_Program.md) includes the necessary authentication config.

### Related Commands

- `ivy init` - Initialize a new Ivy project
- `ivy db add` - Add database connections
- `ivy app create` - Create apps
- `ivy deploy` - Deploy your project