cas-system-client 2.0.0__py3-none-any.whl

cas_client/__init__.py

@@ -0,0 +1,5 @@
+"""CAS SSO Client for Python"""
+from .client import CasClient
+
+__version__ = '2.0.0'
+__all__ = ['CasClient']

cas_client/client.py

@@ -0,0 +1,264 @@
+"""
+CAS SSO Client for Python
+Provides SSO authentication, token validation, HMAC signing, and role management.
+"""
+
+import hashlib
+import hmac
+import json
+import time
+import logging
+from typing import Optional, Dict, List, Any
+from urllib.parse import urlencode
+
+import requests
+
+logger = logging.getLogger('cas_client')
+
+
+class CasClient:
+    """
+    CAS SSO Client for Python applications.
+
+    Args:
+        server_url: CAS server URL (e.g., https://your-cas-server.com). Used as
+            the internal/back-channel base for server-to-server calls
+            (token validation, logout, token generation).
+        client_id: Registered client ID
+        client_secret: Registered client secret
+        callback_url: OAuth callback URL
+        public_url: Public, browser-facing CAS base URL used ONLY when building
+            the browser login redirect (``get_login_url``). In split-horizon
+            deployments the browser must reach CAS at a public host while the
+            server reaches it at a different internal host. Optional; when empty
+            the login URL falls back to ``server_url`` (single-url dev).
+        signature_secret: HMAC signature secret (optional)
+        enable_signature_validation: Enable HMAC request signing (default: False)
+        timeout: Request timeout in seconds (default: 30)
+        verify_ssl: Verify SSL certificates (default: True)
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        client_id: str,
+        client_secret: str,
+        callback_url: str = '',
+        public_url: str = '',
+        signature_secret: str = '',
+        enable_signature_validation: bool = False,
+        timeout: int = 30,
+        verify_ssl: bool = True,
+    ):
+        if not server_url:
+            raise ValueError('server_url is required')
+        if not client_id:
+            raise ValueError('client_id is required')
+        if not client_secret:
+            raise ValueError('client_secret is required')
+
+        self.config = {
+            'server_url': server_url.rstrip('/'),
+            # Public/browser-facing base for the login redirect only. Falls back
+            # to server_url when not provided so single-url setups are unchanged.
+            'public_url': (public_url or '').rstrip('/'),
+            'client_id': client_id,
+            'client_secret': client_secret,
+            'callback_url': callback_url,
+            'signature_secret': signature_secret or 'default-signature-secret',
+            'enable_signature_validation': enable_signature_validation,
+            'timeout': timeout,
+            'verify_ssl': verify_ssl,
+        }
+
+        self._session = requests.Session()
+        self._session.headers.update({'Content-Type': 'application/json'})
+        self._session.verify = verify_ssl
+        self._session.timeout = timeout
+
+        # In-memory token cache
+        self._cache: Dict[str, Dict[str, Any]] = {}
+
+    def get_login_url(self, return_url: Optional[str] = None) -> str:
+        """Generate CAS SSO login URL.
+
+        The CAS server expects only ``client_id`` on the login redirect; it
+        looks up the client's registered callback URL server-side and appends
+        the token to it (``{callback_url}?token={JWT}``).
+
+        This is the URL the user's BROWSER is redirected to, so it is built from
+        ``public_url`` when configured (the public, browser-facing CAS host),
+        falling back to ``server_url`` otherwise. Server-to-server calls still
+        use ``server_url`` (the internal back-channel host).
+
+        Args:
+            return_url: Unused by the CAS server (the registered callback URL
+                is always used). Accepted for backwards compatibility.
+
+        Returns:
+            Full CAS login URL string
+        """
+        params = {
+            'client_id': self.config['client_id'],
+        }
+        base = self.config['public_url'] or self.config['server_url']
+        return f"{base}/sso/login?{urlencode(params)}"
+
+    def generate_sso_token(self, username: str) -> Optional[Dict[str, Any]]:
+        """Generate SSO token for a user via client credentials.
+
+        Args:
+            username: Username to generate token for
+
+        Returns:
+            Token data dict with 'token' and 'redirect_url', or None
+        """
+        try:
+            timestamp = int(time.time())
+            request_data = {
+                'client_id': self.config['client_id'],
+                'client_secret': self.config['client_secret'],
+                'username': username,
+            }
+
+            headers = {
+                'X-Client-ID': self.config['client_id'],
+                'X-Timestamp': str(timestamp),
+            }
+
+            if self.config['enable_signature_validation']:
+                headers['X-Signature'] = self._generate_signature(
+                    'POST', '/api/sso/token', request_data, timestamp
+                )
+
+            response = self._session.post(
+                f"{self.config['server_url']}/api/sso/token",
+                json=request_data,
+                headers=headers,
+                timeout=self.config['timeout'],
+            )
+
+            if response.status_code == 200:
+                data = response.json()
+                if 'token' in data:
+                    return data
+
+            return None
+        except Exception as e:
+            logger.error(f'CAS SSO token generation failed: {e}')
+            return None
+
+    def validate_token(self, token: str) -> Optional[Dict[str, Any]]:
+        """Validate SSO token with CAS server.
+
+        Args:
+            token: JWT token to validate
+
+        Returns:
+            User data dict or None
+        """
+        try:
+            timestamp = int(time.time())
+            request_data = {
+                'token': token,
+                'client_id': self.config['client_id'],
+                'client_secret': self.config['client_secret'],
+            }
+
+            headers = {
+                'X-Client-ID': self.config['client_id'],
+                'X-Timestamp': str(timestamp),
+            }
+
+            if self.config['enable_signature_validation']:
+                headers['X-Signature'] = self._generate_signature(
+                    'POST', '/api/sso/validate', request_data, timestamp
+                )
+
+            response = self._session.post(
+                f"{self.config['server_url']}/api/sso/validate",
+                json=request_data,
+                headers=headers,
+                timeout=self.config['timeout'],
+            )
+
+            if response.status_code == 200:
+                data = response.json()
+                # CAS server signals success with {"valid": true, "user": {...},
+                # "expires_at": "<datetime>"}. Honor the explicit "valid" flag.
+                if data.get('valid') and 'user' in data:
+                    cache_key = hashlib.md5(token.encode()).hexdigest()
+                    self._cache[cache_key] = {
+                        'data': data['user'],
+                        'expires': time.time() + 3600,
+                    }
+                    return data['user']
+
+            return None
+        except Exception as e:
+            logger.error(f'CAS token validation failed: {e}')
+            return None
+
+    def get_user_from_token(self, token: str) -> Optional[Dict[str, Any]]:
+        """Get cached user data from token.
+
+        Args:
+            token: JWT token
+
+        Returns:
+            Cached user data or None
+        """
+        cache_key = hashlib.md5(token.encode()).hexdigest()
+        cached = self._cache.get(cache_key)
+        if cached and cached['expires'] > time.time():
+            return cached['data']
+        self._cache.pop(cache_key, None)
+        return None
+
+    def logout(self, token: Optional[str] = None) -> bool:
+        """Logout from CAS server.
+
+        Args:
+            token: JWT token to invalidate cache for
+
+        Returns:
+            True if successful
+        """
+        try:
+            if token:
+                cache_key = hashlib.md5(token.encode()).hexdigest()
+                self._cache.pop(cache_key, None)
+
+            response = self._session.post(
+                f"{self.config['server_url']}/api/logout",
+                timeout=self.config['timeout'],
+            )
+            return response.status_code == 200
+        except Exception as e:
+            logger.error(f'CAS logout failed: {e}')
+            return False
+
+    @staticmethod
+    def user_has_role(user: Dict[str, Any], role: str) -> bool:
+        """Check if user has a specific role."""
+        return role in (user.get('roles') or [])
+
+    @staticmethod
+    def user_has_any_role(user: Dict[str, Any], roles: List[str]) -> bool:
+        """Check if user has any of the specified roles."""
+        user_roles = set(user.get('roles') or [])
+        return bool(user_roles & set(roles))
+
+    @staticmethod
+    def user_has_all_roles(user: Dict[str, Any], roles: List[str]) -> bool:
+        """Check if user has all specified roles."""
+        user_roles = set(user.get('roles') or [])
+        return set(roles).issubset(user_roles)
+
+    def _generate_signature(self, method: str, uri: str, data: dict, timestamp: int) -> str:
+        """Generate HMAC SHA-256 signature for request."""
+        body = json.dumps(data)
+        payload = '|'.join([method, uri, body, str(timestamp), self.config['client_id']])
+        secret = self.config['signature_secret']
+        signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
+        return f'sha256={signature}'

cas_client/middleware.py

@@ -0,0 +1,172 @@
+"""
+Django and Flask middleware for CAS SSO authentication.
+"""
+
+import logging
+from typing import Optional, List
+
+logger = logging.getLogger('cas_client')
+
+
+# =============================================================================
+# Django Middleware
+# =============================================================================
+
+class DjangoCasMiddleware:
+    """
+    Django middleware for CAS authentication.
+
+    Add to MIDDLEWARE in settings.py:
+        'cas_client.middleware.DjangoCasMiddleware',
+
+    Configure in settings.py:
+        CAS_CLIENT = CasClient(...)
+        CAS_PROTECTED_PATHS = ['/dashboard', '/admin']
+        CAS_LOGIN_URL = '/auth/login'
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        from django.conf import settings
+        from django.shortcuts import redirect
+        from django.http import JsonResponse
+
+        protected_paths = getattr(settings, 'CAS_PROTECTED_PATHS', [])
+        login_url = getattr(settings, 'CAS_LOGIN_URL', '/auth/login')
+        cas_client = getattr(settings, 'CAS_CLIENT', None)
+
+        is_protected = any(request.path.startswith(p) for p in protected_paths)
+
+        if is_protected:
+            cas_user = request.session.get('cas_user')
+
+            # Check Bearer token if no session user
+            if not cas_user and cas_client:
+                auth_header = request.META.get('HTTP_AUTHORIZATION', '')
+                if auth_header.startswith('Bearer '):
+                    token = auth_header[7:]
+                    cas_user = cas_client.get_user_from_token(token)
+                    if not cas_user:
+                        cas_user = cas_client.validate_token(token)
+                    if cas_user:
+                        request.session['cas_user'] = cas_user
+
+            if cas_user:
+                request.cas_user = cas_user
+            else:
+                if request.content_type == 'application/json':
+                    return JsonResponse({'error': 'Authentication required'}, status=401)
+                return redirect(f'{login_url}?return_url={request.path}')
+
+        response = self.get_response(request)
+        return response
+
+
+def django_role_required(*roles: str):
+    """
+    Django decorator to require specific roles.
+
+    Usage:
+        @django_role_required('admin', 'manager')
+        def admin_view(request):
+            ...
+    """
+    from functools import wraps
+
+    def decorator(view_func):
+        @wraps(view_func)
+        def wrapper(request, *args, **kwargs):
+            from django.http import JsonResponse
+
+            cas_user = getattr(request, 'cas_user', None) or request.session.get('cas_user')
+            if not cas_user:
+                return JsonResponse({'error': 'Authentication required'}, status=401)
+
+            user_roles = set(cas_user.get('roles', []))
+            if not user_roles & set(roles):
+                return JsonResponse({'error': 'Insufficient permissions'}, status=403)
+
+            return view_func(request, *args, **kwargs)
+        return wrapper
+    return decorator
+
+
+# =============================================================================
+# Flask Middleware / Decorators
+# =============================================================================
+
+def flask_cas_required(cas_client):
+    """
+    Flask decorator for CAS authentication.
+
+    Usage:
+        from cas_client.middleware import flask_cas_required
+
+        @app.route('/dashboard')
+        @flask_cas_required(cas)
+        def dashboard():
+            user = flask.session['cas_user']
+            return f'Hello {user["username"]}'
+    """
+    from functools import wraps
+
+    def decorator(f):
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            import flask
+
+            cas_user = flask.session.get('cas_user')
+            if cas_user:
+                flask.g.cas_user = cas_user
+                return f(*args, **kwargs)
+
+            # Check Bearer token
+            auth = flask.request.headers.get('Authorization', '')
+            if auth.startswith('Bearer '):
+                token = auth[7:]
+                user = cas_client.get_user_from_token(token)
+                if not user:
+                    user = cas_client.validate_token(token)
+                if user:
+                    flask.g.cas_user = user
+                    flask.session['cas_user'] = user
+                    return f(*args, **kwargs)
+
+            if flask.request.is_json:
+                return flask.jsonify({'error': 'Authentication required'}), 401
+            login_url = flask.current_app.config.get('CAS_LOGIN_URL', '/auth/login')
+            return flask.redirect(f'{login_url}?return_url={flask.request.path}')
+        return wrapper
+    return decorator
+
+
+def flask_role_required(cas_client, *roles: str):
+    """
+    Flask decorator for role-based access control.
+
+    Usage:
+        @app.route('/admin')
+        @flask_cas_required(cas)
+        @flask_role_required(cas, 'admin')
+        def admin():
+            ...
+    """
+    from functools import wraps
+
+    def decorator(f):
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            import flask
+
+            cas_user = getattr(flask.g, 'cas_user', None) or flask.session.get('cas_user')
+            if not cas_user:
+                return flask.jsonify({'error': 'Authentication required'}), 401
+
+            if not cas_client.user_has_any_role(cas_user, list(roles)):
+                return flask.jsonify({'error': 'Insufficient permissions'}), 403
+
+            return f(*args, **kwargs)
+        return wrapper
+    return decorator

cas_system_client-2.0.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: cas-system-client
+Version: 2.0.0
+Summary: Python client for CAS (Central Authentication Service) SSO integration
+Home-page: https://github.com/InSol-2021/one-system
+Author: CAS System
+Author-email: support@innovativesolution.com.np
+License: MIT
+Project-URL: Source, https://github.com/InSol-2021/one-system/tree/master/packages/python-cas-client
+Project-URL: Bug Tracker, https://github.com/InSol-2021/one-system/issues
+Keywords: cas sso authentication jwt single-sign-on
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.0
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: flask
+Requires-Dist: flask>=3.0; extra == "flask"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Python CAS Client
+
+A Python package for seamless integration with **One System** CAS (Central Authentication Service) SSO servers. Works with Django, Flask, FastAPI, and any Python framework.
+
+**Requirements:** Python 3.9+ and `requests >= 2.32`. The optional `[django]` extra requires Django 4.2+, and the `[flask]` extra requires Flask 3.0+.
+
+## Features
+
+- 🔐 **Secure SSO Authentication** — JWT token-based authentication
+- 🛡️ **HMAC Signature Validation** — Request signing with SHA-256
+- 👥 **Role-Based Access Control** — Decorators for role protection
+- 🐍 **Django & Flask Support** — Built-in middleware and decorators
+- 📦 **Type Hints** — Full typing support for IDE autocomplete
+- 🔄 **Token Caching** — In-memory cache for validated tokens
+
+## Installation
+
+```bash
+pip install cas-system-client
+
+# With Django support
+pip install cas-system-client[django]
+
+# With Flask support
+pip install cas-system-client[flask]
+```
+
+## Quick Start
+
+### 1. Initialize the Client
+
+```python
+from cas_client import CasClient
+
+cas = CasClient(
+    server_url='https://your-cas-server.com',
+    client_id='your_client_id',
+    client_secret='your_client_secret',
+    callback_url='https://your-app.com/cas/callback',
+)
+```
+
+### How the One System SSO flow works
+
+1. Send the browser to `cas.get_login_url()` — this redirects to
+   `GET {server_url}/sso/login?client_id=...`.
+2. One System authenticates the user and redirects back to your registered
+   `callback_url` with a single-use JWT appended as `?token=<JWT>`.
+3. In your callback, call `cas.validate_token(token)`. The client validates the
+   token **server-to-server** (sending `client_id` + `client_secret`) and returns
+   the user dict `{id, username, email, ...}` on success, or `None`. Tokens are
+   single-use — validate once, then rely on your framework session.
+
+### 2. Django Integration
+
+```python
+# settings.py
+import os
+from cas_client import CasClient
+
+CAS_CLIENT = CasClient(
+    server_url=os.environ['CAS_SERVER_URL'],
+    client_id=os.environ['CAS_CLIENT_ID'],
+    client_secret=os.environ['CAS_CLIENT_SECRET'],
+    callback_url=os.environ['CAS_CALLBACK_URL'],
+)
+CAS_PROTECTED_PATHS = ['/dashboard', '/admin']
+CAS_LOGIN_URL = '/auth/login'
+
+MIDDLEWARE = [
+    ...
+    'cas_client.middleware.DjangoCasMiddleware',
+]
+
+# views.py
+from cas_client.middleware import django_role_required
+
+@django_role_required('admin')
+def admin_view(request):
+    user = request.cas_user
+    return JsonResponse({'user': user['username']})
+```
+
+### 3. Flask Integration
+
+```python
+from cas_client import CasClient
+from cas_client.middleware import flask_cas_required, flask_role_required
+
+cas = CasClient(
+    server_url='https://your-cas-server.com',
+    client_id='your_client_id',
+    client_secret='your_client_secret',
+)
+
+@app.route('/dashboard')
+@flask_cas_required(cas)
+def dashboard():
+    user = flask.g.cas_user
+    return f'Hello {user["username"]}'
+
+@app.route('/admin')
+@flask_cas_required(cas)
+@flask_role_required(cas, 'admin')
+def admin():
+    return 'Admin area'
+```
+
+### 4. Manual Authentication
+
+```python
+# Generate SSO token
+token_data = cas.generate_sso_token('john_doe')
+
+# Validate token
+user = cas.validate_token(token)
+
+# Role checks
+if cas.user_has_role(user, 'admin'):
+    print('User is admin')
+
+# Logout
+cas.logout(token)
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `get_login_url(return_url)` | Generate CAS login URL |
+| `generate_sso_token(username)` | Generate SSO token |
+| `validate_token(token)` | Validate token, returns user dict |
+| `get_user_from_token(token)` | Get cached user data |
+| `logout(token)` | Logout from CAS server |
+| `user_has_role(user, role)` | Check single role |
+| `user_has_any_role(user, roles)` | Check any of roles |
+| `user_has_all_roles(user, roles)` | Check all roles |
+
+## License
+
+MIT

cas_system_client-2.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cas_client/__init__.py,sha256=djdPNo6AtrY_wQ2m5-NAdaB9kRHgvuuUgLuaVVQne2k,109
+cas_client/client.py,sha256=Gf-9Zv8CrwWivMv8oj4z4YgnTfuCEAQh-uPR4WLs1VY,9545
+cas_client/middleware.py,sha256=E2_tuh5WpAxoe-Lr-z8ooj9q7TuX031JOelfgVqB5b8,5631
+cas_system_client-2.0.0.dist-info/licenses/LICENSE,sha256=DJasJTjN70sO3GUtoYI66h5DY19DVdsDFhN-Eymwav0,1067
+cas_system_client-2.0.0.dist-info/METADATA,sha256=KIBB68vEnbuPrwfPjCMu5GzyrC176bzHZwLh9S6nmS0,5461
+cas_system_client-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cas_system_client-2.0.0.dist-info/top_level.txt,sha256=e3BIAWc0mI-JIPNH4UvpD3EYQM3xlrYD9k0jk_kDk8s,11
+cas_system_client-2.0.0.dist-info/RECORD,,

cas_system_client-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cas_system_client-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InSol-2021
+
+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.

cas_system_client-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cas_client