User Login (MS Active Directory)

Audience: Low-code Engineers

Skill Prerequisites: Actions, Tokens, Connectors, Users

Signs a user in with their Microsoft Active Directory account. The action checks the username and password against Active Directory. If they're valid, it creates or updates a matching user account on the site and signs the user in.

On success, the [User:*] tokens, such as [User:UserID] or [User:FirstName], refer to the signed-in user in the actions that follow.

note

This action is part of the Active Directory add-on (PlantAnApp.ActiveDirectory). The add-on is installed separately and needs the MSAD feature in your license. If it isn't licensed, the action fails with a "not licensed" error. If you don't see the action, the add-on isn't installed.

It isn't available in Automation (workflows and scheduled jobs), because signing in needs a browser to receive the login cookie.

Typical Use Cases

• Let employees sign in to an intranet app with their Windows (domain) username and password
• Create site accounts automatically the first time a domain user signs in
• Keep site roles in step with Active Directory groups, for example give members of Sales the Sales role

Don't use it to

• Sign in users with a site account. Use User Login instead.
• Sign in users from an OpenLDAP server. Use User Login (OpenLdap) instead.
• Sync all directory users in advance. The action only creates or updates the user who signs in.

Related Actions

Action Name	Description
User Login	Signs in a user with a site username and password.
User Login (OpenLdap)	Signs in a user with an OpenLDAP account.
Add Connector	Creates a connector, such as the Active Directory connector.
Test Connector	Checks that a connector works.
Grant User Role	Adds a role that isn't covered by the group mapping.
Update User Profile	Saves more profile properties after sign-in.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Username	The user's Active Directory account name (SAMAccountName), for example jsmith, without the domain. Pick a field, or switch to an expression and use a token.	Yes	empty string	Yes
Password	The user's Active Directory password. Pick a field, or switch to an expression and use a token.	Yes	empty string	Yes
Connector	The Active Directory (LDAP) connector. See The connector. When using an expression, the value must be the connector ID.	Yes	none	Yes
Path	The part of the directory to check against, for example OU=Staff,DC=example,DC=com. Users outside this path can't sign in. If it's empty, the whole domain is used.	Yes	empty string	No
User Attribute Mapping	Pairs of an Active Directory attribute name and a site profile property name, for example telephoneNumber and Telephone. The values are copied to the user's profile on every sign-in.	Yes	empty	No
User Roles Mapping	Pairs of an Active Directory group name and a site role name, for example Sales and Sales. See Group to role mapping.	Yes	empty	No
Output Token Name	The name of the token to save the Active Directory user details in, for example ADUser.	No	empty string	No
On Error	Actions to run when the sign-in fails. The [Exception] token holds the full error and [ExceptionMessage] the message. See Errors.	No	empty	No

Output Parameters Reference

Token	Description
[<Output Token Name>:$json]	The Active Directory user details as JSON, including the user principal, the groups and the mapped attributes.
[<Output Token Name>:IsNewUser]	True if the site account was created during this sign-in, otherwise False.
[User:*]	After the action, these tokens refer to the signed-in user.

The connector

Create a connector of type Active Directory (LDAP) with:

Setting	Description
Domain	The domain or domain controller to connect to, for example example.com.
Principal Username	An account the site uses to connect to Active Directory. If it's empty, the site connects with the identity its application pool runs as.
Principal Password	The password of that account. It's stored encrypted.

How the sign-in works

1. The action connects to the domain at Path and checks the username and password.
2. It finds the user by account name. The account must be enabled in Active Directory.
3. It looks for a site account called AD- followed by the user's security ID (SID), for example AD-S-1-5-21-....
4. If there's no such account, it creates one. The account is authorized and gets a random password, which nobody knows, so the user can only sign in through this action.
5. It copies the first name, last name, email, display name and the mapped attributes to the site account. This happens on every sign-in, so changes in Active Directory flow to the site.
6. It applies the User Roles Mapping.
7. It signs the user in with a persistent login cookie.

Because the site account name is based on the SID, renaming the user in Active Directory doesn't create a second account.

Group to role mapping

For each row in User Roles Mapping:

• If the user is in the group, the action adds the role, if the user doesn't have it yet.
• If the user isn't in the group, the action removes the role, if the user has it.

Roles that aren't in the mapping aren't touched. If a role name doesn't exist on the site, the row is skipped. Group names are compared without regard to case.

The mapping can grant powerful roles, such as Administrators. Only map those to groups you control closely.

Errors

If anything goes wrong, end users see Login failed! Invalid username or password (status LOGIN_FAILURE). Administrators see a technical message. The detailed reason, such as Invalid credentials., User not found. or User not enabled., is in the log and in the [Exception] token.

The On Error actions run first. If none of them ends the flow, for example with a redirect, the error is raised after they finish.

Considerations

• Use a secure connection. The action connects to Active Directory with a simple bind and doesn't turn on SSL. Passwords may travel over the network unencrypted. Make sure the connection between the web server and the domain controller is protected.
• Use HTTPS on the login page, because the password is sent from the browser.
• Email as username. If the site is set to use the email as the username, the first sign-in creates the account with the email as username. Later sign-ins then look for AD-<SID>, don't find it, and fail because an account with that username already exists. Don't use this action on such sites.
• Site account status isn't checked. Once Active Directory accepts the password, the user is signed in, even if the site account was unauthorized or locked on the site. To block a user, disable them in Active Directory or remove them from Path.
• Existing site accounts aren't linked. A user who already has a site account with the same email gets a second, separate account. If the site requires unique emails, creating the account fails instead.
• Mapped profile properties must exist on the site. Values are saved as text.
• Not in Automation. Workflows and scheduled jobs run without a web request, so there's no browser to sign in.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Sign in domain users and map groups to roles

This action signs in users from the Staff OU with the values of the Username and Password fields. It copies the phone number to the profile, and keeps the Sales and Managers roles in step with the matching groups. Replace the connector ID with your own.

{
    "Title": "User Login (MS Active Directory)",
    "ActionType": "PlantAnApp.ActiveDirectory.UserLogin",
    "Description": "Sign in with the company domain account",
    "Parameters": {
        "UserName": "[Username]",
        "Password": "[Password]",
        "Credentials": {
            "Entry": "00000000-0000-0000-0000-000000000000"
        },
        "Path": "OU=Staff,DC=example,DC=com",
        "UserAttributeMapping": [
            {
                "name": "telephoneNumber",
                "value": "Telephone"
            }
        ],
        "UserRoleMapping": [
            {
                "name": "Sales Team",
                "value": "Sales"
            },
            {
                "name": "Managers",
                "value": "Managers"
            }
        ],
        "OutputTokenName": "ADUser"
    }
}

Revised 09/28/2026