authly-sso 0.4.0__tar.gz

authly_sso-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Authly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

authly_sso-0.4.0/PKG-INFO

@@ -0,0 +1,400 @@
+Metadata-Version: 2.4
+Name: authly-sso
+Version: 0.4.0
+Summary: Authly SSO OAuth2 integratsiyasi uchun yagona Python / Django SDK
+Author: Authly
+License: MIT
+Keywords: sso,authly,oauth2,django,drf,authentication
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: Django
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Requires-Dist: djangorestframework>=3.14.0; extra == "django"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 🛡️ Authly SSO
+
+Loyiha va xizmatlar uchun yagona **Authly SSO (Single Sign-On / OAuth 2.0)** integratsiya kutubxonasi.
+
+[![PyPI version](https://badge.fury.io/py/authly-sso.svg)](https://badge.fury.io/py/authly-sso)
+[![Python](https://img.shields.io/pypi/pyversions/authly-sso)](https://pypi.org/project/authly-sso/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## ✨ Imkoniyatlar
+
+- **Backend va Frontend domenlari ajratilgan**:
+  - `AUTHLY_BACKEND_URL` — Token olish, profil yuklash va barcha server-to-server API so'rovlari.
+  - `AUTHLY_FRONTEND_URL` — Foydalanuvchini brauzerda SSO login sahifasiga yo'naltirish havolasini yasash.
+- **Django & DRF tayyor integratsiyasi** — 4 ta tayyor endpoint:
+  - `login-url/` — Authly SSO ga yo'naltiruvchi login havolasini olish.
+  - `callback/` — OAuth2 code orqali tizimga kirish va tokenlar qaytarish.
+  - `webhook/` — Authly SSO dan avtomatik foydalanuvchi ma'lumotlarini yangilash.
+  - `sync/` — Foydalanuvchi profilini qo'lda Authly bilan sinxronlashtirish.
+- **Dinamik `redirect_uri`** — Har bir so'rovda `redirect_uri` ni so'rov orqali uzatish mumkin (settings.py da ham belgilash mumkin).
+- **To'liq ma'lumotlar sinxronizatsiyasi** — `authly_id`, `first_name`, `last_name`, `email`, `phone`/`phone_number`, `avatar`, `birth_date` avtomatik to'ldiriladi.
+- **HMAC SHA-256 Webhook xavfsizligi** — `X-SSO-Signature` imzosini avtomatik tekshirish.
+- **Avtomatik JWT** — `djangorestframework-simplejwt` mavjud bo'lsa `access` va `refresh` tokenlar generatsiya qilinadi.
+- **500 xatoliksiz** — Barcha xatoliklar (`AuthlySDKError`, `IntegrityError`, `DatabaseError`, `PermissionDenied` va h.k.) DRF `Response` sifatida qaytariladi.
+
+---
+
+## 📦 O'rnatish
+
+```bash
+# Faqat Python (FastAPI, Flask, skriptlar uchun):
+pip install authly-sso
+
+# Django / DRF bilan:
+pip install "authly-sso[django]"
+```
+
+---
+
+## ⚙️ Sozlash
+
+`settings.py` ga quyidagilarni qo'shing:
+
+```python
+AUTHLY_BACKEND_URL  = "https://api.authly.uz"
+AUTHLY_FRONTEND_URL = "https://authly.uz"
+AUTHLY_CLIENT_ID    = "sizning-client-id"
+AUTHLY_CLIENT_SECRET = "sizning-client-secret"
+
+# Ixtiyoriy — frontend har so'rovda dinamik yuborsa kerak emas:
+AUTHLY_REDIRECT_URI = "https://saytingiz.uz/api/v1/auth/authly/callback/"
+
+# Webhook xavfsizligi uchun:
+AUTHLY_WEBHOOK_SECRET = "sizning-webhook-secret"
+
+# Ixtiyoriy (standart: 10 soniya):
+AUTHLY_TIMEOUT = 10
+```
+
+---
+
+## 🛠 Django / DRF da ishlatish
+
+### 1. `urls.py` ga uling
+
+```python
+from django.urls import path, include
+
+urlpatterns = [
+    path("api/v1/auth/authly/", include("authly.urls")),
+]
+```
+
+4 ta endpoint faollashadi:
+
+| Endpoint | Method | Tavsif |
+|----------|--------|--------|
+| `login-url/` | `GET` | Authly SSO login havolasini qaytaradi |
+| `callback/` | `GET`, `POST` | OAuth2 code → foydalanuvchi & tokenlar |
+| `webhook/` | `POST` | Authly dan avtomatik yangilash |
+| `sync/` | `GET`, `POST` | Foydalanuvchi profilini qo'lda yangilash |
+
+---
+
+### 2. Login havolasini olish
+
+```http
+GET /api/v1/auth/authly/login-url/?redirect_uri=https://saytingiz.uz/callback
+```
+
+**Parametrlar (query string):**
+
+| Parametr | Majburiy | Tavsif |
+|----------|----------|--------|
+| `redirect_uri` | Ha\* | Callback URL. `AUTHLY_REDIRECT_URI` settings da belgilangan bo'lsa ixtiyoriy. |
+| `scope` | Yo'q | Ruxsatlar doirasi (standart: `read`) |
+| `state` | Yo'q | CSRF himoyasi yoki holat parametri |
+
+**Javob:**
+```json
+{
+  "data": {
+    "url": "https://authly.uz/login?client_id=...&redirect_uri=...&scope=read"
+  },
+  "error": null,
+  "success": true
+}
+```
+
+---
+
+### 3. Callback (tizimga kirish)
+
+```http
+GET /api/v1/auth/authly/callback/?code=<CODE>&redirect_uri=<URI>
+POST /api/v1/auth/authly/callback/
+Content-Type: application/json
+
+{"code": "...", "redirect_uri": "..."}
+```
+
+**Parametrlar:**
+
+| Parametr | Tavsif |
+|----------|--------|
+| `code` | Authly SSO dan kelgan bir martalik kod |
+| `redirect_uri` | Login havolasi yasashda ishlatilgan xuddi shu URL |
+| `code_verifier` | PKCE ishlatilsa (ixtiyoriy) |
+
+**Muvaffaqiyatli javob:**
+```json
+{
+  "data": {
+    "is_new_user": false,
+    "user": {
+      "id": 1,
+      "authly_id": "c1f7a0b3-1234-4567-89ab-cdef01234567",
+      "username": "authly_c1f7a0b3-1234-4567-89ab-cdef01234567",
+      "full_name": "Ism Familiya",
+      "first_name": "Ism",
+      "last_name": "Familiya",
+      "email": "user@example.com",
+      "phone": "+998901234567",
+      "avatar": "https://api.authly.uz/media/users/avatar/2026/10/avatar.jpg",
+      "birth_date": "1995-05-15"
+    },
+    "access": "<LOCAL_JWT_ACCESS_TOKEN>",
+    "refresh": "<LOCAL_JWT_REFRESH_TOKEN>",
+    "authly_access_token": "<AUTHLY_OAUTH_ACCESS_TOKEN>"
+  },
+  "error": null,
+  "success": true
+}
+```
+
+> **Muhim:** `authly_access_token` — bu Authly serveriga murojaat qilish uchun OAuth tokeni.
+> `access` va `refresh` esa loyihangiz (lokal) JWT tokenlari.
+> Frontend `authly_access_token` ni saqlashi va `/sync/` endpointiga shu tokenni yuborishi mumkin.
+
+---
+
+### 4. Profil sinxronizatsiyasi (Manual Sync)
+
+Foydalanuvchi Authly portalida o'z ma'lumotlarini o'zgartirib qaytganda profilini yangilash:
+
+```http
+POST /api/v1/auth/authly/sync/
+Authorization: Bearer <LOCAL_JWT>
+Content-Type: application/json
+
+{"access_token": "<AUTHLY_OAUTH_ACCESS_TOKEN>"}
+```
+
+> ⚠️ `access_token` sifatida lokal JWT emas, callback da kelgan **`authly_access_token`** yuboriladi.
+
+**Muvaffaqiyatli javob:**
+```json
+{
+  "data": {
+    "status": "success",
+    "updated_fields": ["first_name", "avatar"],
+    "user": {
+      "id": 1,
+      "authly_id": "c1f7a0b3-...",
+      "first_name": "Yangi Ism",
+      "last_name": "Familiya",
+      "email": "user@example.com",
+      "phone": "+998901234567",
+      "avatar": "https://api.authly.uz/media/users/avatar/2026/10/new_avatar.jpg",
+      "birth_date": "1995-05-15",
+      "region_info": { "id": "...", "name": "Toshkent shahri" },
+      "district_info": { "id": "...", "name": "Yunusobod tumani" }
+    }
+  },
+  "error": null,
+  "success": true
+}
+```
+
+---
+
+### 5. Webhook (Avtomatik sinxronizatsiya)
+
+Authly SSO foydalanuvchi ma'lumotlari o'zgarganda webhook yuboradi. SDK:
+1. `X-SSO-Signature` (HMAC SHA-256) imzosini tekshiradi.
+2. Foydalanuvchini `authly_id` → `phone_number` → `email` ketma-ketligida topadi.
+3. Barcha o'zgargan maydonlarni avtomatik yangilaydi.
+
+```http
+POST /api/v1/auth/authly/webhook/
+X-SSO-Signature: sha256=<HMAC>
+Content-Type: application/json
+
+{
+  "event": "user.updated",
+  "timestamp": "2026-10-31T12:00:00.000Z",
+  "user": {
+    "id": "c1f7a0b3-...",
+    "authly_id": "c1f7a0b3-...",
+    "first_name": "Alisher",
+    "last_name": "Valiyev",
+    "phone": "+998901234567",
+    "email": "alisher@example.com",
+    "avatar": "https://api.authly.uz/media/users/avatar/2026/10/new_avatar.jpg",
+    "birth_date": "1998-05-15",
+    "region": { "id": "...", "name": "Toshkent shahri" },
+    "district": { "id": "...", "name": "Yunusobod tumani" }
+  }
+}
+```
+
+---
+
+## 🧩 Maxsus moslashtirish (Override)
+
+### Viloyat/Tuman bog'lash va bloklash tekshiruvi
+
+```python
+from authly.views import AuthlyCallbackAPIView, AuthlyWebhookAPIView
+from rest_framework.exceptions import PermissionDenied
+from apps.users.models import Region, District
+
+class CustomAuthlyCallbackView(AuthlyCallbackAPIView):
+    def get_or_create_user(self, user_data: dict):
+        user, created = super().get_or_create_user(user_data)
+
+        region_data = user_data.get("region_info") or user_data.get("region")
+        district_data = user_data.get("district_info") or user_data.get("district")
+
+        if region_data and hasattr(user, "region"):
+            user.region = Region.objects.filter(
+                name__iexact=region_data.get("name")
+            ).first()
+        if district_data and hasattr(user, "district"):
+            user.district = District.objects.filter(
+                name__iexact=district_data.get("name")
+            ).first()
+
+        user.save()
+
+        if getattr(user, "is_blocked", False):
+            raise PermissionDenied("Hisobingiz administrator tomonidan bloklangan.")
+
+        return user, created
+
+
+class CustomAuthlyWebhookView(AuthlyWebhookAPIView):
+    def sync_user(self, user_data: dict):
+        user = super().sync_user(user_data)
+        # Qo'shimcha logika...
+        return user
+```
+
+### Javob formatini o'zgartirish
+
+```python
+class CustomAuthlyCallbackView(AuthlyCallbackAPIView):
+    def get_response_data(self, user, user_data, created, tokens, authly_access_token=None):
+        data = super().get_response_data(user, user_data, created, tokens, authly_access_token)
+        data["my_custom_field"] = "qiymat"
+        return data
+```
+
+---
+
+## 🐍 Sof Python / FastAPI / Flask da ishlatish
+
+```python
+from authly import AuthlyClient, AuthlySDKError
+
+client = AuthlyClient(
+    backend_url="https://api.authly.uz",
+    frontend_url="https://authly.uz",
+    client_id="sizning-client-id",
+    client_secret="sizning-client-secret",
+    redirect_uri="https://saytingiz.uz/callback",
+    webhook_secret="sizning-webhook-secret",
+)
+
+# 1. Login havolasi:
+url = client.get_authorization_url(scope="read", state="csrf_token")
+
+# 2. Code → profil + authly access_token:
+try:
+    profile, authly_access_token = client.authenticate_code(
+        code="authorization_code_here",
+        redirect_uri="https://saytingiz.uz/callback",
+    )
+    print(profile)              # {"authly_id": "...", "first_name": "...", ...}
+    print(authly_access_token)  # "eyJ..." — Authly OAuth tokeni
+except AuthlySDKError as e:
+    print(f"Xatolik: {e}")
+
+# 3. access_token bilan profil olish:
+profile = client.get_user_profile(access_token=authly_access_token)
+
+# 4. Webhook imzosini tekshirish:
+is_valid = client.verify_webhook_signature(
+    payload_bytes=raw_body,
+    signature=request.headers.get("X-SSO-Signature"),
+)
+```
+
+---
+
+## ⚠️ Xatoliklar (Exceptions)
+
+| Sinf | Sababi |
+|------|--------|
+| `AuthlySDKError` | Barcha SDK xatoliklari uchun asosiy sinf |
+| `AuthlyTokenExchangeError` | Kodni tokenga almashtirishdagi xatolik |
+| `AuthlyProfileFetchError` | Profil olishdagi xatolik |
+| `AuthlyWebhookSignatureError` | Webhook imzosi xatoligi |
+
+---
+
+## 📋 Jarayon diagrammasi
+
+```
+Frontend                Backend (SDK)           Authly Server
+   |                        |                       |
+   |-- GET /login-url/ ---> |                       |
+   |                        |-- get_authorization_url()
+   |<-- {"url": "https://authly.uz/login?..."} ----|
+   |                        |                       |
+   |-- redirect to Authly login page -------------> |
+   |<-- redirect back with ?code=<CODE> ----------- |
+   |                        |                       |
+   |-- POST /callback/ ---> |                       |
+   |   {code, redirect_uri} |-- exchange_code_for_token() --> Authly
+   |                        |<-- {access_token, ...} <------- Authly
+   |                        |-- get_user_profile(access_token) -> Authly
+   |                        |<-- {authly_id, phone, ...} <--- Authly
+   |                        |-- find_or_create_user()
+   |                        |-- generate_jwt_tokens()
+   |<-- {user, access, refresh, authly_access_token}
+```
+
+---
+
+## 📄 Litsenziya
+
+MIT litsenziyasi ostida tarqatiladi.
+Savollar va takliflar uchun **Authly** jamoasiga murojaat qiling.