Building Custom Login, Registration, and Password Reset Flows in OutSystems

Open Service Studio with your module. Press **Ctrl+Q** (Manage Dependencies). In the Producer search box, type **Users**. Expand the Users module → Logic section → check these actions: - **User_Login** — authenticates a user - **User_Logout** — ends the session - **User_CreateOrUpdate** — creates or updates a user account - **User_ResetPassword** — sends a password reset email - **User_ChangePassword** — changes password with old password verification Also add **Structures** → **User** (for user data) and **Entities** → **User** (for querying). Click **Apply** → Service Studio adds the dependencies. TrueChange confirms there are no broken references.

Go to **Interface tab → UI Flows → MainFlow** (or your main UI flow). Right-click → **Add Screen** → choose **Empty** template → name it `Login`. Set **Roles** property to `Anonymous` so unauthenticated users can access it. From the Toolbox, drag a **Form** widget onto the canvas. Inside the Form, add: - **Input** widget → name it `UsernameInput` → Variable: create Local Variable `Username` (Text) - **Input** widget → name it `PasswordInput` → Variable: create Local Variable `Password` (Text) → InputType: Password - **Button** widget → Label: 'Sign In' → Is Form Default: Yes Add a **Text** widget below the form for error messages → name it `ErrorMessage` → bind Value to a Local Variable `LoginError` (Text) → Visible: `LoginError <> ""`

Double-click the **Sign In** button → Service Studio asks to create or select a client action → create `OnSignInClick` Client Action. Since User_Login requires a server call, create a new **Server Action**: Logic tab → Server Actions → right-click → **Add Server Action** → name it `DoLogin`. Add Input Parameters: `Username` (Text), `Password` (Text). Add Output Parameters: `Success` (Boolean), `ErrorMessage` (Text). Action flow: ``` Start → User_Login Username = Username Password = Password PersistLogin = True → If User_Login.Success [True] → Assign Success = True → End [False] → Assign Success = False, ErrorMessage = "Invalid username or password" → End ``` In `OnSignInClick` Client Action: ``` Start → DoLogin (call server action) Username = UsernameInput.Value Password = PasswordInput.Value → If DoLogin.Success [True] → Navigate to Home screen [False] → Assign LoginError = DoLogin.ErrorMessage → End ```

1/* DoLogin Server Action — Output parameters */
2Success: Boolean
3ErrorMessage: Text
4
5/* Action Flow */
6Start
7→ User_Login
8     Username = Username  /* Input parameter */
9     Password = Password  /* Input parameter */
10     PersistLogin = True  /* Keeps session across browser restarts */
11→ If User_Login.Success
12     [True]
13       → Assign: Success = True
14       → End
15     [False]
16       → Assign: Success = False
17       → Assign: ErrorMessage = "Invalid username or password"
18       → End

In **Interface tab → UI Flows → MainFlow**, right-click → **Add Screen** → Empty → name it `Register`. Set Roles to `Anonymous`. Create a Form with these inputs (each bound to a Local Variable): - `FullName` (Text) - `Email` (Text) → InputType: email, Mandatory: Yes - `Password` (Text) → InputType: Password, Mandatory: Yes - `ConfirmPassword` (Text) → InputType: Password, Mandatory: Yes Create Server Action `RegisterUser` with these inputs. Action flow: ``` Start → If Password = ConfirmPassword [False] → Assign ErrorMessage = "Passwords do not match" → End → GetUserByUsername (Aggregate: filter User.Username = Email) → If NOT GetUserByUsername.List.Empty [True] → Assign ErrorMessage = "An account with this email already exists" → End → User_CreateOrUpdate User.Username = Email User.Password = Password User.Name = FullName User.Email = Email User.IsActive = True → User_Login (auto-login after registration) Username = Email Password = Password → End (Success = True) ```

1/* RegisterUser Server Action inputs */
2FullName:         Text
3Email:            Text
4Password:         Text
5ConfirmPassword:  Text
6
7/* Outputs */
8Success:          Boolean
9ErrorMessage:     Text
10
11/* Aggregate: GetUserByUsername */
12/* Sources: User entity */
13/* Filter: User.Username = Email */
14
15/* User_CreateOrUpdate key parameters */
16User.Username  = Email
17User.Email     = Email
18User.Name      = FullName
19User.Password  = Password  /* Stored as salted hash by OutSystems */
20User.IsActive  = True

Create two screens: 1. `ForgotPassword` — collects the user's email address (Roles: Anonymous) 2. `ResetPassword` — takes a reset token from the URL and sets a new password (Roles: Anonymous) **ForgotPassword screen logic** (Server Action `SendResetEmail`): ``` Start → GetUserByEmail (Aggregate: filter User.Email = InputEmail) → If NOT GetUserByEmail.List.Empty [True] → User_ResetPassword UserId = GetUserByEmail.List.Current.User.Id [This sends an email with reset link automatically] → /* Always show success message regardless — prevent email enumeration */ → Assign SuccessMessage = "If an account exists, a reset link has been sent." → End ``` **ResetPassword screen** must receive `?NewPasswordKey=<token>` as an Input Parameter from the URL. The Users module's reset email links to `/[YourModule]/ResetPassword?NewPasswordKey=TOKEN`. Set screen Input Parameter `NewPasswordKey` (Text). ResetPassword logic (Server Action `DoResetPassword`): ``` Start → User_ChangePasswordWithResetKey UserId = ... (from token lookup) NewPasswordKey = NewPasswordKey NewPassword = NewPassword → On Success: Navigate to Login ```

1/* ForgotPassword screen — Input Variables */
2InputEmail: Text (bound to Email input)
3
4/* SendResetEmail Server Action */
5Start
6→ GetUserByEmail
7     /* Aggregate filter: User.Email = InputEmail AND User.IsActive = True */
8→ If NOT GetUserByEmail.List.Empty
9   [True]
10   → User_ResetPassword
11        UserId = GetUserByEmail.List.Current.User.Id
12→ Assign
13     ShowConfirmation = True
14→ End
15
16/* ResetPassword screen — Input Parameters */
17NewPasswordKey: Text  /* Passed in URL: ?NewPasswordKey=abc123 */
18
19/* The email generated by User_ResetPassword automatically
20   contains a link to:
21   https://[environment]/[module]/ResetPassword?NewPasswordKey=[token]
22   Configure the reset email template in Service Center →
23   Administration → Email → Users_ResetPassword template */

By default, OutSystems redirects unauthenticated users to the built-in `/Users` login screen. To redirect to your custom Login screen instead: In Service Studio, go to **Data tab → Site Properties**. Look for Site Property `DefaultLoginScreen` (added by referencing the Users module). Set its **Default Value** to the path of your custom Login screen. Alternatively, in your module's **Exceptional Handling** flow: Interface tab → UI Flows → Common → **OnException** flow → update the Security Exception handler to navigate to your Login screen instead of the default. For Reactive Web apps, the most reliable method is: Interface tab → UI Flows → Common → **InvalidPermissions** screen → replace its content with a redirect Client Action that navigates to your Login screen with the current URL as a ReturnURL parameter.

1/* InvalidPermissions screen — OnInitialize Client Action */
2/* Replace default content with redirect to custom login */
3
4Start
5→ Navigate to Screen: Login
6     ReturnURL = GetOwnerURLPath()
7→ End
8
9/* Login screen OnInitialize — handle ReturnURL after login */
10/* In OnSignInClick after DoLogin.Success = True: */
11If ReturnURL <> "" Then
12    Navigate External: ReturnURL
13Else
14    Navigate to Screen: Home
15End If