> For the complete documentation index, see [llms.txt](https://docs.appfarm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appfarm.io/reference/configuration/login/custom-auth-providers.md).

# Custom auth providers

Appfarm supports third-party authentication by integrating with authentication providers using OAuth 2.0.

Using a custom auth provider allows you to manage users in an external directory such as Microsoft Entra ID (Azure AD). To enable custom auth you must first complete any necessary setup with the provider, and then configure the provider in Appfarm Create.

In Appfarm Create, custom auth providers are managed under **Configuration** > **Login**, on the **Custom auth providers** tab next to **Login config**.

For detailed walkthroughs on how to configure a number of different providers, see [How to configure third-party authentication](/how-to/authentication-and-access-control/third-party-authentication.md).

## **Checklist**

Follow these steps to correctly setup and configure a custom auth provider.

In your auth provider:

* Create a new application. Please refer to your provider's documentation for details.
* When creating an OAuth application, it will require at least one callback URL. Use `https://accounts.appfarm.io/v1/callback`.
* Make note of the *Client ID* and *Client Secret* provided when you create the OAuth application.

In Appfarm Create:

* Add a new custom auth provider and select its **Account binding** in the **New custom auth provider** dialog. For a solution-bound provider, also enter the provider settings the dialog asks for. See [Account binding](#account-binding).
* Enter the provided *Client ID* into **Client ID**.
* Create a [secret](/reference/security/secrets.md) to store the *Client Secret* and select it from the **Client secret** list.
* Depending on what kind of provider you are using, fill in the **Tenant ID** or **OpenID discovery endpoint**.
* Add the custom auth provider in a login configuration under [Custom auth](/reference/configuration/login.md#custom-auth).

## General settings

<table><thead><tr><th width="235">Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>A descriptive reference used only in Appfarm Create.</td></tr><tr><td><strong>Provider</strong></td><td><p>The auth provider. The following options are available:</p><ul><li>Google</li><li>Azure AD</li><li>Auth0</li><li>Custom</li></ul><p>Set at creation and read-only for solution-bound providers.</p></td></tr><tr><td><strong>Client ID</strong></td><td>The identifier of the application created in your auth provider. Usually this is a unique application used only to authenticate users for this Appfarm solution. Set at creation and read-only for solution-bound providers.</td></tr><tr><td><strong>Client secret</strong></td><td>The secret for the application as provided by your auth provider. This value must be stored in Appfarm as a <a href="/reference/security/secrets.md">secret</a>.</td></tr><tr><td><strong>Tenant ID</strong></td><td><p>Only for <em>Azure AD</em> and <em>Auth0</em>. Set at creation and read-only for solution-bound providers.<br></p><p>The unique identifier for your tenant. Appfarm needs this value to fetch the configuration for this auth provider. The format of this value differs depending on your provider.</p><p><strong>Microsoft Entra ID (Azure AD)</strong><br>The identifier can be found inside the Microsoft Azure portal. The format is typically <code>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</code>.</p><p><br><strong>Auth0</strong><br>The identifier used in Auth0 is the entire hostname ending with <code>auth0.com</code>. For example: <code>appfarm.eu.auth0.com</code>.</p></td></tr><tr><td><strong>OpenID discovery endpoint</strong></td><td>Only for <em>Custom</em>. Set at creation and read-only for solution-bound providers.<br><br>The URL holding the configuration of your OpenID Connect Server. For example: <code>https://HOST_NAME/.well-known/openid-configuration</code><br><br><strong>Important:</strong> The hostname is used together with <strong>Client ID</strong> to uniquely identify this provider. If you change the host, users that have already logged in with this provider must log in again to be able to use credentials returned by this provider.</td></tr><tr><td><strong>Custom scope</strong></td><td><p>By default, the following scope will be requested:</p><ul><li>openid</li><li>profile</li><li>email</li></ul><p>Add any additional scopes as needed. Note that if you need to save additional scopes to the User object (more than the name, email and phone - e.g. a Social Security Number), you may save these by adding user-specific <a href="/reference/security/secrets.md#properties">secrets</a>. Add a new Secret, and select Secret Type <code>OAuth2 value</code>. You may then use a Service to update e.g. an Employee or Person object with these secret values after login.</p></td></tr><tr><td><strong>Remove default scope</strong></td><td>Remove <code>openid</code>, <code>profile</code> and <code>email</code> from scope. When selected, only scopes entered in <strong>Custom scope</strong> will be used.</td></tr></tbody></table>

## Appfarm account options

<table><thead><tr><th width="239">Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Account binding</strong></td><td>Where the accounts that sign in through this provider live: <strong>Global</strong> or <strong>Solution-bound</strong>. Chosen when the provider is created and read-only afterwards. See <a href="#account-binding">Account binding</a>.</td></tr><tr><td><strong>Identity namespace</strong></td><td>Only for solution-bound providers. Names the set of accounts this provider signs in. See <a href="#identity-namespace">Identity namespace</a>.</td></tr><tr><td><strong>Auto-create account</strong></td><td>Automatically create a <a href="/reference/security/users.md">user</a> in the solution when a new user authenticates.</td></tr><tr><td><strong>Initial roles</strong></td><td>Assign one or more roles when a new user is created.</td></tr></tbody></table>

## Advanced options

<table><thead><tr><th width="244">Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Disable same-browser validation</strong></td><td><p><strong>Warning:</strong> This option should be used with caution and an understanding of the security implications.</p><p><br>For added security Appfarm checks that a callback from a third-party authentication provider is made by the same browser that initiated the login. By selecting this option, that check will be disabled.<br><br>This might be desirable to improve the authentication user experience. If, for example, the login flow involves a magic link sent to the user's email address, the user may not open the link in the same browser that the login was initiated from. This will normally result in the login attempt failing. By disabling same browser validation, the login attempt in this case would succeed.</p></td></tr><tr><td><strong>Auth timeout</strong></td><td><p>The amount of time a user can spend authenticating with the provider before returning to Appfarm.</p><p>Normally the default (15 minutes) will be more than sufficient. In some cases, for example when the authentication involves sending a link to email, this timeout may be too short.</p><p>The default is 900 seconds (15 minutes), and the maximum is 86400 seconds (24 hours).</p></td></tr></tbody></table>

## Account binding

Each custom auth provider has an account binding, which decides where the accounts that sign in through it live. You choose the binding in the **New custom auth provider** dialog that opens when you add a provider. The binding is permanent. To change it, create a new provider.

| Binding            | Description                                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Global**         | Ordinary Appfarm accounts, identified by email address and shared across every solution the user belongs to. Used when no binding is selected. |
| **Solution-bound** | Accounts that exist only inside this solution, identified by the provider instead of by an email address.                                      |

All provider types can be solution-bound.

When you select **Solution-bound**, the dialog also asks for the settings that identify the provider's issuer. They are required, and they can't be changed after the provider is created.

| Provider        | Required settings                                                                     |
| --------------- | ------------------------------------------------------------------------------------- |
| Google          | **Client ID**                                                                         |
| Azure AD, Auth0 | **Client ID** and **Tenant ID**                                                       |
| Custom          | **Client ID** and **OpenID discovery endpoint**. The endpoint must be an `https` URL. |

**Client secret** and the remaining settings are set on the provider after it is created, and stay editable.

{% hint style="warning" %}
**Important**

The account binding and the provider settings above can't be changed after the provider is created. To correct one, delete the provider and create a new one. Accounts carry over between solution-bound providers only by [adopting the identity namespace](#identity-namespace). Global accounts can never become solution-bound, or the other way round.
{% endhint %}

### Solution-bound accounts

A solution-bound account is identified by the subject identifier (`sub`) the provider returns, within the provider's [identity namespace](#identity-namespace). It does not depend on an email address:

* The provider does not need to send an email claim. If it sends one, the claim is not used to identify the account and never becomes the account's email address.
* The account gets a generated email address in the form `sb-<24 hexadecimal characters>@scoped.appfarm.invalid`. This is the address shown for the user in **Users** and on the User object in apps.

A solution-bound account can only be used in its own solution, and only by signing in through the provider:

* It has no Appfarm password, passkey or authenticator app, and can't sign in with **Login link**, **One-time password login** or **Google**.
* It can't sign in to Appfarm Create, the [Appfarm account](/reference/security/manage-your-appfarm-account.md) pages or other solutions, and can't connect [external clients](/reference/flows/mcp-servers.md#external-clients).
* It can't be added to another solution. Users can't be added by its generated address in any solution.

A user gets a solution-bound account by signing in through the provider. Select **Auto-create account** so that the account is created on the user's first sign-in, with the selected **Initial roles**.

Solution-bound and global accounts never merge. A person who signs in both through a solution-bound provider and with a global account has two separate accounts. If a login configuration offers both, see [Custom auth](/reference/configuration/login.md#custom-auth) in Login.

{% hint style="info" %}
**Good to know**

If the provider issues a different subject identifier (`sub`) for the same person, that person gets a new account on their next sign-in. The old account is kept but is no longer used.
{% endhint %}

{% hint style="warning" %}
**Important**

Emails sent with the [Send email](/library/action-nodes/send-email.md) action node to a solution-bound user go to the generated `@scoped.appfarm.invalid` address and are not delivered.
{% endhint %}

## Identity namespace

The identity namespace names the set of accounts a solution-bound provider signs in. A namespace is assigned when the provider is created. It has the form `ns_` followed by 26 lowercase letters and digits from 2 to 7, for example `ns_k3mfq7xw2pzr4tbn6yhd5cva2e`. The value is not a secret. It outlives the provider, so a replacement provider can take over the same accounts.

The namespace is shown in the provider's **Identity namespace** setting. Click the copy icon next to the value to copy it.

| Action       | Description                                                                                                                                                                                                                                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Generate** | Gives this provider a new namespace with no accounts.                                                                                                                                                                                                                                                        |
| **Adopt**    | Points this provider at the namespace of an earlier solution-bound provider in this solution. Paste the namespace and click **Adopt**. Its accounts then sign in through this provider, and the confirmation shows how many accounts that is. The namespace must have at least one account in this solution. |

After either action, accounts under the previous namespace can no longer sign in through this provider. They are kept, and adopting the previous namespace again restores them.

{% hint style="warning" %}
**Important**

* Copy the current namespace before you click **Generate** or **Adopt** if you might need those accounts again.
* After **Adopt**, anyone this provider authenticates can use the adopted accounts. Only adopt a namespace into a provider that authenticates the same people.
  {% endhint %}

## Delete a custom auth provider

A provider that a login configuration uses can't be deleted. Remove it from the login configuration first.

Deleting a provider never deletes accounts. Before the provider is deleted, a confirmation dialog counts the accounts that sign in through it. **Delete provider** is available once the count has loaded.

For a solution-bound provider with accounts, the dialog shows how many accounts are orphaned and the provider's identity namespace. Orphaned accounts can no longer sign in, but they are kept. To recover them, copy the namespace before you delete the provider, then create a new solution-bound provider and [adopt](#identity-namespace) the namespace. If other solution-bound providers share the namespace, the dialog lists them instead, and the accounts stay with those providers.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appfarm.io/reference/configuration/login/custom-auth-providers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
