Custom Databases

Connect your own database or API for user storage and authentication.

---

What are Custom Databases?

Custom Database Connections allow you to:

• Use your existing user database (SQL or NoSQL)
• Authenticate users against your own data via API
• Maintain full control over user storage
• Migrate users gradually to SyAuth without schema changes

---

Supported Connections

Connection Type	Status	Script Language
PostgreSQL	✅ Available	SQL
MySQL	✅ Available	SQL
MongoDB	✅ Available	JSON
REST API	✅ Available	JSON

---

How It Works

---

Setting Up Custom Database

Step 1: Add Connection

1. Go to Custom Databases in the sidebar.
2. Click Add Connection.
3. Select your Database Type.
4. Enter your Connection String:
   • PostgreSQL: postgresql://user:pass@host:port/db
   • MySQL: mysql://user:pass@host:port/db
   • MongoDB: mongodb://user:pass@host:port/db
   • REST API: https://api.yourdomain.com/auth

Step 2: Configure Scripts

Custom connections require action scripts to perform operations. SyAuth provides default templates for each connection type.

Script	Purpose	Required
Login	Validate credentials and return user profile	✅
Get User	Retrieve user by email	✅
Create User	Register new users into your DB	❌
Change Password	Update user passwords	❌
Verify Email	Mark user email as verified	❌

Step 3: Activate Connection

Once scripts are saved and tested, click Activate. SyAuth will now route authentication requests for this workspace to your custom database.

---

Action Scripts (SQL)

Used for PostgreSQL and MySQL. Use %(key)s for parameter substitution.

Login Script

SELECT id, email, password_hash, first_name, last_name, is_active
FROM users 
WHERE email = %(email)s AND is_active = true;

Create User Script

INSERT INTO users (id, email, password_hash, first_name, last_name, created_at)
VALUES (%(id)s, %(email)s, %(password_hash)s, %(first_name)s, %(last_name)s, NOW())
RETURNING id, email;

---

Action Scripts (JSON)

Used for MongoDB and REST API.

MongoDB Login Script

{
  "collection": "users",
  "operation": "findOne",
  "filter": {"email": "%(email)s", "is_active": true}
}

REST API Login Script

{
  "method": "POST",
  "endpoint": "/v1/auth/login",
  "body": {
    "username": "%(email)s",
    "password": "%(password)s"
  }
}

---

Password Compatibility

SyAuth automatically supports standard password hashing algorithms stored in your database:

• BCrypt
• Argon2
• PBKDF2 (Django standard)
• SHA256

If your hashes use these standards, your users can log in immediately without resetting their passwords.

---

---

Testing Your Connection

Before activating, you should verify that SyAuth can reach your database:

1. In the Connection Settings section of the connection form, click Test Connection.
2. SyAuth will attempt to connect and perform a simple SELECT 1 or ping.
3. If successful, you will see a green checkmark. If not, check your firewall settings and connection string.

---

Security Considerations

Consideration	Recommendation
SSL/TLS	Always use encrypted connection strings (e.g., ?sslmode=require)
Least Privilege	Create a specific DB user with access only to the necessary tables
Whitelisting	Whitelist SyAuth outbound IP addresses in your firewall

---

Limitations

• Only one custom database can be active per workspace.
• The connection must be reachable from the public internet (or via a tunnel).
• Some built-in SyAuth analytics may be disabled when using custom storage.

---

Next Steps

• Managing Users - How users appear in the dashboard