botbook/src/06-gbdialog/templates/auth.md

Authentication Template

The authentication template demonstrates secure user verification flows including login, registration, password validation, and session management.

Topic: User Authentication & Security

This template is perfect for:

• User login systems
• Account verification
• Password recovery flows
• Session management
• Two-factor authentication

The Code

REM Authentication Flow with Retry Logic

PARAM username AS string LIKE "john.doe"
DESCRIPTION "Username or email for authentication"

PARAM password AS string LIKE "********"
DESCRIPTION "User's password (masked input)"

SET max_attempts = 3
SET attempts = 0

TALK "Welcome! Please enter your username:"
HEAR username

LABEL auth_loop

TALK "Enter your password:"
HEAR password AS PASSWORD   ' Masked input

' Verify credentials
user = FIND "users", "username='" + username + "'"

IF user = NULL THEN
    TALK "Username not found. Would you like to register? (yes/no)"
    HEAR register_choice
    IF register_choice = "yes" THEN
        GOTO registration
    ELSE
        TALK "Goodbye!"
        EXIT
    END IF
END IF

IF user.password = HASH(password) THEN
    SET BOT MEMORY "authenticated_user", username
    SET BOT MEMORY "session_start", NOW()
    TALK "Welcome back, " + user.name + "! You are now logged in."
    EXIT
ELSE
    SET attempts = attempts + 1
    IF attempts >= max_attempts THEN
        TALK "Too many failed attempts. Your account is temporarily locked."
        SEND MAIL user.email, "Security Alert", "Multiple failed login attempts detected."
        EXIT
    END IF
    TALK "Incorrect password. " + (max_attempts - attempts) + " attempts remaining."
    GOTO auth_loop
END IF

LABEL registration
TALK "Let's create your account. Enter your email:"
HEAR email
TALK "Create a password (min 8 characters):"
HEAR new_password AS PASSWORD

IF LEN(new_password) < 8 THEN
    TALK "Password too short. Please try again."
    GOTO registration
END IF

INSERT "users", username, email, HASH(new_password), NOW()
TALK "Account created! You can now log in."

Sample Dialogs

These conversations show how the authentication template works in real-world scenarios.

Dialog 1: Successful Login

🔐

Auth Bot

online

Today

Auth Bot

Welcome! Please enter your username:

09:00

maria.santos

09:00

Enter your password:

09:00

••••••••

09:01

Welcome back, Maria! You are now logged in. ✅

09:01

Dialog 2: Failed Login with Retry

🔐

Auth Bot

online

Enter your password:

14:30

••••••••

14:30

Incorrect password. 2 attempts remaining. ⚠️

14:30

Enter your password:

14:30

••••••••

14:31

Welcome back, João! You are now logged in. ✅

14:31

Dialog 3: Account Locked

🔐

Auth Bot

online

Incorrect password. 1 attempt remaining. ⚠️

16:45

Enter your password:

16:45

••••••••

16:45

Too many failed attempts. Your account is temporarily locked. 🔒

A security alert has been sent to your email.

16:45

Session ended

Dialog 4: New User Registration

🔐

Auth Bot

online

Username not found. Would you like to register? (yes/no)

10:15

yes

10:15

Let's create your account. Enter your email:

10:15

carlos@email.com

10:16

Create a password (min 8 characters):

10:16

••••••••••

10:16

Account created! 🎉 You can now log in.

10:16

Keywords Used

Keyword	Purpose
PARAM	Define expected input parameters
SET	Assign values to variables
TALK	Send messages to the user
HEAR	Capture user input
HEAR AS PASSWORD	Masked password input
FIND	Query database for user
IF/ELSE	Conditional logic
GOTO/LABEL	Flow control for retry loop
HASH	Secure password hashing
SET BOT MEMORY	Store session data
SEND MAIL	Send security alerts
INSERT	Create new user record
EXIT	End the dialog

How It Works

1. Username Input: Collects the username first
2. User Lookup: Checks if user exists in database
3. Password Verification: Compares hashed password
4. Retry Logic: Allows 3 attempts before lockout
5. Session Creation: Stores auth state in bot memory
6. Registration: Offers new account creation if user not found

Security Features

Password Hashing

' Never store plain text passwords!
hashed = HASH(password)
INSERT "users", username, email, hashed

Rate Limiting

IF attempts >= max_attempts THEN
    SET BOT MEMORY "locked_" + username, NOW()
    TALK "Account locked for 15 minutes."
END IF

Two-Factor Authentication

' Send OTP after password verification
otp = RANDOM(100000, 999999)
SET BOT MEMORY "otp_" + username, otp
SEND MAIL email, "Your verification code", "Code: " + otp

TALK "Enter the 6-digit code sent to your email:"
HEAR user_otp

IF user_otp = GET BOT MEMORY "otp_" + username THEN
    TALK "Two-factor authentication successful!"
ELSE
    TALK "Invalid code."
END IF

Customization Ideas

Add "Forgot Password"

TALK "Forgot your password? (yes/no)"
HEAR forgot
IF forgot = "yes" THEN
    reset_token = RANDOM_STRING(32)
    SET BOT MEMORY "reset_" + username, reset_token
    SEND MAIL user.email, "Password Reset", "Click here: /reset/" + reset_token
    TALK "Password reset link sent to your email."
END IF

Session Timeout

session_start = GET BOT MEMORY "session_start"
IF DATEDIFF("minute", session_start, NOW()) > 30 THEN
    TALK "Session expired. Please log in again."
    SET BOT MEMORY "authenticated_user", ""
END IF

Social Login

TALK "Login with: 1) Password 2) Google 3) GitHub"
HEAR login_method

SWITCH login_method
    CASE "2"
        ' Redirect to OAuth
        url = GET "auth/google/redirect"
        TALK "Click to login: " + url
    CASE "3"
        url = GET "auth/github/redirect"
        TALK "Click to login: " + url
    DEFAULT
        ' Standard password flow
END SWITCH

Related Templates

• start.bas - Basic greeting flow
• enrollment.bas - Data collection patterns

---