Migrate Active Directory users to FoxIDs
Move Active Directory (AD) users and application sign-ins to FoxIDs while keeping AD as the user directory, gradually move password validation to FoxIDs, or import users and let them choose a new password.
This technical guide covers users in Active Directory Domain Services (AD DS), their passwords and application accounts. The Directory Connector for Active Directory guide provides the installation and configuration steps.
| Approach | Password handling | User management |
|---|---|---|
| Keep AD as the directory | FoxIDs validates the user's password against AD through Directory Connector. | AD remains authoritative for users and the attributes returned by the connector. |
| Migrate passwords gradually | FoxIDs saves a local password hash after successful AD password validation. Local validation takes over when the connector is disabled. | Users are provisioned through the connector and later managed in FoxIDs. |
| Import users for password setup | Users choose a new FoxIDs password using an email code at first login. | Users are imported from CSV with the FoxIDs Seed Tool and managed in FoxIDs. |
Prepare the destination and applications
A dedicated test environment lets you try the selected approach with a small group of users and an application before moving to production.
- If you want a custom domain, configure it before connecting applications or external identity providers. Changing the domain later requires updating the external configurations that use FoxIDs URLs.
- Every environment has a default Login authentication method named
login. Customise its branding and login UI and enable the required login identifiers, such as email or username. - Register the applications in FoxIDs and configure their redirect URLs, logout behaviour and required claims. Protocol bridging supports applications using different protocols during the transition.
FoxIDs can apply multi-factor authentication to users who sign in through Login, including users whose passwords are validated against AD. FoxIDs Cloud provides email and SMS delivery depending on the selected FoxIDs Cloud plan.
Keep AD as the directory
Install Directory Connector for Active Directory on a Windows/IIS server that can reach the domain controllers. FoxIDs communicates with the connector over HTTPS. Configure its AD user lookup, returned attributes and any group claims used by the applications.
Enable the connector under Settings > Environment > Directory connector settings, using its API URL and secret. On the Login authentication method, enable password authentication and the identifiers returned by the connector. Disable user creation on Login; new users are created in AD and provisioned in FoxIDs through the connector.
When a user enters their identifier, FoxIDs retrieves their current AD account and creates or updates the internal FoxIDs user. The connector uses the AD objectGUID to keep the account linked when login identifiers change. Password authentication validates the submitted password against AD. A CSV import is not needed for this approach.
AD continues to manage passwords and the user data returned by the connector. FoxIDs can keep this connection as a permanent integration. The optional local password copy supports a later migration; it is not used for authentication while the connector is enabled.
Migrate passwords gradually
Start with the connector configuration above and keep Save local password enabled, which is the default. The transition works as follows:
- Users sign in through FoxIDs Login with their existing AD passwords.
- After successful password validation, FoxIDs stores a local password hash on the same internal user. Password changes and resets completed through FoxIDs also update the local hash.
- Disable Directory Connector in the environment settings to switch to local FoxIDs password validation. The existing FoxIDs users and their saved passwords remain available.
Directory Connector is configured for the whole environment, so disabling it switches the environment to local validation. After the switch, users, passwords and access changes are managed in FoxIDs; AD changes no longer update those users through the connector.
The local password copy reflects the latest successful password validation, change or reset through FoxIDs. A later password change made only in AD becomes available locally after the user next authenticates with that password through FoxIDs.
Users who have not yet been provisioned can be imported using the CSV approach below. Existing users without a local password copy can use Forgot your password? after the switch, with password reset by email or SMS enabled on the Login authentication method. Recovery uses their existing FoxIDs accounts.
You can try the transition in a test environment by signing in with an AD user, disabling the connector and starting a fresh password login. The same password then authenticates locally. A user without a saved password can instead complete the configured password setup or recovery flow.
Import users for password setup
For a direct move to local FoxIDs users, retrieve the selected AD users and convert their attributes into the Seed Tool CSV format. Microsoft's Get-ADUser command supports selecting users by filter or search base and retrieving the required attributes.
Map the data needed by the application:
| AD information | FoxIDs import |
|---|---|
Email address, usually mail |
Email. |
Chosen login name, such as sAMAccountName or userPrincipalName |
Username when username login is required. |
| Disabled or expired account | DisableAccount=true if the account is included in the import. |
| Given name, surname and other application attributes | The corresponding entries in Claims. |
| Group membership | The roles or access assignments required by the application. |
Retain the AD objectGUID and the association with the existing application account in the migration mapping. Set EmailVerified from the known verification state; an AD email attribute alone does not establish that state.
Enable email login, password authentication and password setup by email on the Login authentication method. Save the CSV as UTF-8 with case-sensitive headers and semicolon separators. This example imports a fictitious user without a password:
Email;Username;EmailVerified;SetPasswordEmail;DisableAccount
alice@example.com;alice;false;true;false
Configure the FoxIDs Seed Tool, set SeedSettings.UsersSvcPath to the CSV file and select U to upload the users. The tool bulk loads the users into the configured FoxIDs environment through the Control API.
At first login, the user receives an email code, enters it on the login page and chooses a new password. Password setup takes place during login; uploading the CSV only creates the accounts. The new password is managed in FoxIDs independently of AD.
Preserve application accounts
FoxIDs creates its own persistent user ID for both connector-provisioned and CSV-imported users. The AD directory binding does not automatically make an application's existing identifier its FoxIDs sub or SAML NameID.
Keep the association between the AD user and the existing application account. Where an application expects an existing subject value, make that value available as a user claim and configure a claim transform on the Login authentication method to produce the required sub. For SAML applications, configure the required NameID and format on the SAML application registration. Applications that identify accounts by issuer and subject also need to associate the FoxIDs issuer with the existing accounts.
After the connector is disabled, group and attribute changes used for application access are maintained in FoxIDs or the application. A test login lets you inspect the resulting subject, roles and account association.
Move applications from AD FS
If applications currently use AD FS, FoxIDs can connect to AD FS with SAML 2.0 while those applications move to FoxIDs. AD FS remains the identity provider during this stage.
Applications can later use FoxIDs Login with Directory Connector to authenticate directly against AD, or use local FoxIDs users after migration. AD can remain the directory when AD FS is removed from the application sign-in flow.
A login through AD FS does not give FoxIDs the user's password. Gradual password migration therefore takes place when users sign in through FoxIDs Login and Directory Connector. Preserve the application's account association when changing between these authentication methods.