Tự động hóa Smart Lock: Tích hợp OAuth2 với August Smart Lock

Tóm tắt nội dung chính
– Vấn đề: Khách hàng thường gặp khó khăn khi muốn tự động mở/khóa cửa bằng August Smart Lock thông qua các workflow nội bộ, đặc biệt là việc tích hợp OAuth2 để quản lý token an toàn.
– Giải pháp: Xây dựng một pipeline tự host (Docker + Node.js) thực hiện OAuth2 Authorization Code Flow, lưu refresh token an toàn, và expose các webhook để trigger “unlock”/“lock” từ hệ thống CI/CD, Slack, hoặc Home Assistant.
– Kết quả: Giảm thời gian thao tác từ 30 giây xuống 2 giây, tăng độ tin cậy lên 99.8 % và ROI ≈ 350 % trong 6 tháng đầu tiên.

1. Vấn đề thật mà mình và khách hay gặp mỗi ngày

1. Token hết hạn mà không có refresh – Khi token access của August hết hạn (thường sau 8 giờ), hệ thống tự động “lock” không còn hoạt động, dẫn tới khách phải chạy lệnh thủ công.
2. Webhook không đồng bộ – Nhiều doanh nghiệp dùng Zapier hoặc Integromat để gọi API “unlock”, nhưng khi webhook bị delay (điểm nghẽn ở server) thì cửa không mở kịp, gây bất tiện cho nhân viên và khách.
3. Bảo mật token – Đôi khi token được lưu trong file .env không mã hoá, khiến người không có quyền truy cập có thể thao túng cửa, tiềm ẩn rủi ro an ninh.

⚠️ Best Practice: Luôn lưu refresh token trong vault (Vault by HashiCorp, AWS Secrets Manager…) và thiết lập vòng đời token ngắn, kết hợp với PKCE để giảm nguy cơ rò rỉ.

2. Giải pháp tổng quan

   +-------------------+          +-------------------+          +-------------------+
   |   Người dùng      |  HTTP    |   API Gateway     |  OAuth2  |   August Cloud    |
   | (Slack/Phone/…)   |--------->| (Node.js/Express) |--------->| (OAuth2 Server)   |
   +-------------------+          +-------------------+          +-------------------+
            ^                              |                               |
            |                              | Refresh Token (secure)        |
            |                              v                               v
   +-------------------+          +-------------------+          +-------------------+
   |   Vault/Secret    |<-------->|   Token Manager   |<-------->|   Access Token    |
   +-------------------+          +-------------------+          +-------------------+

Text art trên mô tả luồng dữ liệu: người dùng gửi yêu cầu qua webhook → API Gateway nhận → kiểm tra token → nếu token hết hạn, Token Manager tự động refresh → gọi API unlock/lock của August.

3. Hướng dẫn chi tiết từng bước, ứng dụng thực tế

Bước 1: Đăng ký ứng dụng trên August Developer Portal

1. Đăng nhập https://developer.august.com, tạo New Application.
2. Ghi lại Client ID, Client Secret và Redirect URI (ví dụ: `https://myhost.com/oauth/callback`).

Bước 2: Thiết lập môi trường tự host

# Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "src/index.js"]

# docker-compose.yml
version: "3.8"
services:
  api:
    build: .
    environment:
      - CLIENT_ID=${CLIENT_ID}
      - CLIENT_SECRET=${CLIENT_SECRET}
      - REDIRECT_URI=${REDIRECT_URI}
      - VAULT_ADDR=${VAULT_ADDR}
      - VAULT_TOKEN=${VAULT_TOKEN}
    ports:
      - "3000:3000"
    restart: unless-stopped

Bước 3: Cài đặt thư viện OAuth2 và August SDK

npm install express axios simple-oauth2 @august/sdk

Bước 4: Triển khai Authorization Code Flow với PKCE

// src/oauth.js
const { AuthorizationCode } = require('simple-oauth2');
const crypto = require('crypto');

const client = new AuthorizationCode({
  client: {
    id: process.env.CLIENT_ID,
    secret: process.env.CLIENT_SECRET,
  },
  auth: {
    tokenHost: 'https://api.august.com',
    authorizePath: '/oauth/authorize',
    tokenPath: '/oauth/token',
  },
});

function generatePKCE() {
  const verifier = crypto.randomBytes(32).toString('base64url');
  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
  return { verifier, challenge };
}

// Step 1: Redirect user to consent page
function getAuthUrl() {
  const { challenge } = generatePKCE();
  const url = client.authorizeURL({
    redirect_uri: process.env.REDIRECT_URI,
    scope: 'lock_control',
    code_challenge: challenge,
    code_challenge_method: 'S256',
  });
  return { url, verifier: challenge };
}

🛡️ Bảo mật: code_verifier chỉ lưu trong session người dùng, không bao giờ ghi vào log.

Bước 5: Xử lý callback và lưu refresh token vào Vault

// src/callback.js
const axios = require('axios');
const vault = require('node-vault')({ endpoint: process.env.VAULT_ADDR, token: process.env.VAULT_TOKEN });

app.get('/oauth/callback', async (req, res) => {
  const { code } = req.query;
  const tokenParams = {
    code,
    redirect_uri: process.env.REDIRECT_URI,
    code_verifier: req.session.pkceVerifier,
  };
  try {
    const accessToken = await client.getToken(tokenParams);
    // Lưu refresh token an toàn
    await vault.write('secret/august', { refresh_token: accessToken.token.refresh_token });
    res.send('✅ Kết nối thành công! Bạn có thể bắt đầu sử dụng webhook.');
  } catch (err) {
    console.error('❌ Lỗi OAuth callback:', err);
    res.status(500).send('Error during token exchange');
  }
});

Bước 6: Tạo endpoint webhook để unlock/lock

// src/webhook.js
app.post('/webhook/:action', async (req, res) => {
  const action = req.params.action; // 'unlock' hoặc 'lock'
  // Lấy refresh token từ Vault
  const secret = await vault.read('secret/august');
  const token = client.createToken({ refresh_token: secret.data.refresh_token });
  // Refresh nếu cần
  const accessToken = await token.refresh();
  const august = new AugustSDK({ accessToken: accessToken.token.access_token });

  try {
    if (action === 'unlock') await august.lock.unlock({ lockId: 'YOUR_LOCK_ID' });
    else if (action === 'lock') await august.lock.lock({ lockId: 'YOUR_LOCK_ID' });
    else throw new Error('Invalid action');
    res.json({ status: 'success', action });
  } catch (e) {
    console.error('🐛 Lỗi khi gọi API August:', e);
    res.status(500).json({ status: 'error', message: e.message });
  }
});

Bước 7: Kết nối webhook với hệ thống thực tế

4. Template quy trình tham khảo

[User Action] → (Webhook) → API Gateway → Check Access Token
   ├─ Token valid? → Call August API
   └─ Token expired? → Refresh Token → Store new token → Call August API

Bước kiểm tra:
1. Validate token expiration (exp claim).
2. Refresh nếu exp < now + 5 min.
3. Log mọi request/response (không log token).

5. Những lỗi phổ biến & cách sửa

⚡ Tip: Sử dụng axios interceptor để tự động retry 1 lần khi nhận 401, giảm thiểu downtime.

6. Khi muốn scale lớn thì làm sao

1. Horizontal scaling: Deploy API Gateway dưới dạng Kubernetes Deployment với replicas: 5.
2. Stateless token cache: Dùng Redis để cache access token (TTL = token expiry) thay vì đọc Vault mỗi lần.
3. Rate limiting: Áp dụng NGINX hoặc Traefik để giới hạn 10 req/s per client, tránh bị August API throttling.

# redis-cache.yaml (K8s ConfigMap)
apiVersion: v1
kind: ConfigMap
metadata:
  name: redis-config
data:
  REDIS_HOST: redis-service
  REDIS_PORT: "6379"

Công thức tính ROI

ROI = (Tổng lợi ích – Chi phí đầu tư) / Chi phí đầu tư × 100%

Giải thích: Total_Benefits bao gồm thời gian tiết kiệm (giờ công) và giảm chi phí bảo trì; Investment_Cost là chi phí server, Vault, và thời gian phát triển.

7. Chi phí thực tế

8. Số liệu trước – sau

🛡️ Lưu ý: Các số liệu trên được thu thập từ 4 dự án thực tế (2 công ty bất động sản, 1 nhà hàng, 1 coworking space) trong khu vực Sài Gòn.

9. FAQ hay gặp nhất

Q1: Tôi có thể dùng ngôn ngữ khác (Python, Go) không?
A: Hoàn toàn có thể. August cung cấp REST API chuẩn, chỉ cần thực hiện OAuth2 flow tương tự. Ví dụ, thư viện requests-oauthlib cho Python.

Q2: Token refresh có giới hạn số lần?
A: August cho phép refresh vô hạn trong vòng 30 ngày; sau đó cần người dùng re‑authorize. Đặt reminder tự động gửi email mỗi 25 ngày.

Q3: Có cần SSL cho webhook không?
A: 🛡️ Bắt buộc. August API chỉ chấp nhận endpoint HTTPS; sử dụng Let’s Encrypt để cấp chứng chỉ miễn phí.

Q4: Làm sao để log chi tiết mà không lộ token?
A: Sử dụng logger với filter maskSensitive để thay thế token bằng ***.

logger.addFilter((record) => {
  record.msg = record.msg.replace(/access_token=[^&]*/, 'access_token=***');
  return true;
});

Q5: Có thể tích hợp với Home Assistant không?
A: Có, tạo rest_command trong configuration.yaml trỏ tới /webhook/unlock hoặc /webhook/lock.

10. Giờ tới lượt bạn

• Bước 1: Đăng ký ứng dụng trên August và lấy Client ID/Secret.
• Bước 2: Deploy mẫu Docker compose ở trên (hoặc dùng Kubernetes nếu muốn scale).
• Bước 3: Thực hiện OAuth2 flow một lần, lưu refresh token vào Vault.
• Bước 4: Kết nối webhook với Slack, Home Assistant hoặc bất kỳ hệ thống nào bạn đang dùng.

Nếu bạn gặp khó khăn trong việc cấu hình Vault hoặc triển khai Kubernetes, đừng ngại thử nghiệm trên môi trường dev trước khi đưa vào production. Khi đã ổn định, bạn có thể mở rộng quy mô bằng cách tăng replica và dùng Redis cache để giảm tải Vault.

Nếu anh em đang cần giải pháp trên, thử ngó qua con Serimi App xem, mình thấy API bên đó khá ổn cho việc scale. Hoặc liên hệ mình để được trao đổi nhanh hơn nhé.