# Adding Authentication

> Source: https://parallelworks.com/docs/organization-admin/settings/authentication

# Adding Authentication

ACTIVATE allows you to configure how users authenticate to your organization. You can set up multiple authentication methods, including passwords, LDAP, and OpenID Connect (OIDC), to match your organization's security requirements.

## Navigating to Authentication Settings

From the **Organizations** list, select your organization. In the sidebar, under **Settings**, click **Authentication**.

The Authentication page displays a table of all configured authentication methods with the following columns:

- **Name** — The display name of the method (clickable for LDAP and OIDC methods)
- **Type** — The method type (`cac`, `ldap`, `oidc`, or `password`)
- **Delete** — A trash icon to remove the method

If no methods have been configured, the page displays: "No authentication options configured."

## Adding Authentication Methods

Click the **Add method** dropdown button to see the available options:

- **Password** — Creates a password-based login immediately with no additional configuration. This option is only shown if no password method already exists.
- **LDAP** — Opens the LDAP configuration page.
- **OIDC** — Opens the OIDC configuration page.

## Password Authentication

Password authentication requires no configuration. Select **Password** from the **Add method** dropdown and the method is created immediately.

Only one password method is allowed per organization. Once a password method exists, the **Password** option is hidden from the dropdown. Password methods can be deleted like any other method.

## LDAP Authentication

To add a new LDAP method, select **LDAP** from the **Add method** dropdown. To edit an existing LDAP method, click its name in the authentication methods table.

### Basic Connection Settings

| Field | Required | Description |
|-------|----------|-------------|
| **Name** | Yes | Display name shown on the login page. |
| **Domain** | Yes | LDAP server domain (e.g., `example.com`). |
| **Filter** | Yes | User lookup filter. Use `__USERNAME__` as a placeholder for the authenticating user's name (e.g., `(uid=__USERNAME__)`). |
| **Base DN** | No | Starting point for LDAP searches (e.g., `ou=orgUnit,dc=example,dc=com`). |

### Service Account

Toggle **Use Service Account** to enable or disable service account authentication.

- **When enabled:** Two additional fields appear:
  - **Service Account Bind** — The full distinguished name (DN) of the service account.
  - **Service Account Password** — The password for the service account.
- **When disabled:** The system attempts an anonymous bind.

### TLS / Security

Toggle **Use TLS** to enable or disable Transport Layer Security when connecting to the LDAP server.

- **When enabled:** Two additional fields appear:
  - **Client Certificate** — Paste the PEM-encoded client certificate (textarea).
  - **Client Key** — Paste the PEM-encoded client key (textarea). Required when creating a new LDAP method.

### User Attribute Mapping

These fields control how LDAP attributes map to ACTIVATE user properties.

| Field | Default | Description |
|-------|---------|-------------|
| **Unique Identifier** | `cn` | Attribute that uniquely identifies users. |
| **Username** | `uid` | Attribute used as the username. |
| **Full Name** | `cn` | Attribute used as the display name. |
| **Email** | `mail` | Attribute used as the email address. |
| **UID Number** | *(none)* | Unix UID used during account creation. If not set, a UID is auto-generated. |

### Test Connection

Before saving, you can verify the LDAP configuration by testing a connection.

1. Enter a **Username** and **Password** for a known LDAP account.
2. Click **Test Connection**.
3. The system will attempt to authenticate using the current configuration and report the result.

## OIDC Authentication

To add a new OIDC method, select **OIDC** from the **Add method** dropdown. To edit an existing OIDC method, click its name in the authentication methods table.

### Basic Information

| Field | Default | Description |
|-------|---------|-------------|
| **Name** | `oidc` | Internal identifier. Must be lowercase alphanumeric characters and hyphens only. |
| **Display Name** | `OIDC` | The label shown on the login page. |

### Endpoint Discovery

Toggle **Discover Endpoints?** to control how OIDC endpoints are configured. This toggle is enabled by default.

**When enabled:** Enter only the **Issuer URL**. All other endpoints (user info, token, authorization, and end session) are discovered automatically from the provider's well-known configuration.

**When disabled:** Enter each endpoint manually:

| Field | Required | Description |
|-------|----------|-------------|
| **User Info Endpoint** | Yes | URL for retrieving user profile information. |
| **Token Endpoint** | Yes | URL for exchanging authorization codes for tokens. |
| **Authorization Endpoint** | Yes | URL where users are redirected to authenticate. |
| **End Session Endpoint** | No | URL for logging users out of the identity provider. |

### Client Configuration

| Field | Default | Description |
|-------|---------|-------------|
| **Client ID** | *(none)* | The client ID from your identity provider. Required. |
| **Scopes** | `openid profile email` | Space-separated list of OAuth scopes to request. Required. |

### Authentication Method

The **Token Endpoint Auth Method** dropdown determines how the ACTIVATE platform authenticates with your identity provider's token endpoint. The available options are:

- **`client_secret_post`** — The client secret is sent in the POST body of token requests.
- **`client_secret_basic`** — The client secret is sent in the Authorization header as a Base64-encoded string.
- **`private_key_jwt`** — A JWT signed with a private key is used for authentication.

**Credentials** change based on the selected auth method:

- For **`client_secret_post`** or **`client_secret_basic`**: A **Client Secret** text field is displayed.
- For **`private_key_jwt`**: A **Private Key PEM** textarea is displayed where you paste the PEM-encoded private key.

### Registration Options

| Option | Default | Description |
|--------|---------|-------------|
| **Title Case** | Off | Converts usernames to title case for normalization. |
| **Skip Platform MFA Verification** | Off | Bypasses the additional MFA step after OIDC login. |
| **Create account on first login** | On | Automatically creates ACTIVATE accounts for new OIDC users. When disabled, only users with existing ACTIVATE accounts can log in via OIDC. |

### Redirect URI

A read-only field at the bottom of the configuration page displays the callback URL:

```
https://your-domain/api/sso/oidc/callback
```

Copy this value and configure it as an allowed redirect URI in your identity provider.

## Deleting Authentication Methods

To delete any authentication method:

1. Click the trash icon next to the method in the authentication methods table.
2. A confirmation modal appears: *"Are you sure you want to delete this authentication option? Users will no longer be able to login with this option."*
3. Confirm the deletion.

## Supported Identity Providers

OIDC authentication supports any standards-compliant OpenID Connect identity provider, including:

- [Azure Active Directory (Entra ID)](https://www.microsoft.com/en-us/security/business/identity-access/azure-active-directory)
- [Google Workspace](https://workspace.google.com/)
- [Okta](https://www.okta.com/)
- [Keycloak](https://www.keycloak.org/)
- [Auth0](https://auth0.com/)
- [Login.gov](https://login.gov/)