API Reference¶

Main module¶

class pycas_sso.cas.CASClient¶

Bases: object

Factory class to create CASClient instances based on available HTTP libraries.

This class provides a factory pattern implementation to instantiate the appropriate CASClient subclass based on the specified HTTP library. It automatically detects available libraries and creates compatible client instances.

Examples

>>> # Auto-detect available HTTP library
>>> client = CASClient.create(
...     'https://cas.example.com',
...     'https://myapp.example.com',
...     'https://myapp.example.com/login'
... )

>>> # Explicitly specify HTTP library
>>> client = CASClient.create(
...     'https://cas.example.com',
...     'https://myapp.example.com',
...     'https://myapp.example.com/login',
...     http_lib='httpx'
... )

static create(provider: str, service_url: str, callback_url: str, *args, http_lib: str = 'default', **kwargs) → CASClientBase¶

Create and return a CASClient instance using the specified HTTP library.

This factory method automatically detects or uses the specified HTTP library to instantiate the appropriate CASClient subclass. If no suitable library is found, a ValueError is raised.

Parameters:

provider (str) – The CAS server provider URL. Example: ‘https://cas.example.com’
service_url (str) – The service URL to validate against the CAS server. Example: ‘https://myapp.example.com’
callback_url (str) – The callback URL for login. Example: ‘https://myapp.example.com/login’
*args – Positional arguments to pass to the CASClient subclass constructor.
http_lib (str, optional) – The HTTP library to use for requests. Defaults to ‘default’ (auto-detect). Supported values: ‘default’, ‘httpx’, ‘requests’, ‘aiohttp’
**kwargs – Keyword arguments to pass to the CASClient subclass constructor.

Returns:

An instance inheriting from CASClientBase.

Return type:

CASClient

Raises:

ValueError – If no supported HTTP library is installed or if http_lib contains an unsupported value.

Examples

>>> # Auto-detect available library
>>> client = CASClient.create(
...     'https://cas.example.com',
...     'https://myapp.example.com',
...     'https://myapp.example.com/login'
... )

>>> # Use specific library
>>> client = CASClient.create(
...     'https://cas.example.com',
...     'https://myapp.example.com',
...     'https://myapp.example.com/login',
...     http_lib='requests'
... )

>>> # With additional arguments
>>> client = CASClient.create(
...     'https://cas.example.com',
...     'https://myapp.example.com',
...     'https://myapp.example.com/login',
...     http_lib='httpx',
...     timeout=30
... )

Client interface¶

Never use client interface directly, use factory method pycas_sso.cas.CASClient.create instead.

class pycas_sso.clients.core.CASClientBase(provider: str, service_url: str, callback_url: str, is_async: bool = False)¶

Bases: object

Base class for CAS client implementations.

This abstract base class defines the interface for interacting with a CAS server. It provides methods for authentication, service validation, proxy handling, and SAML validation. Subclasses should implement the HTTP transport layer for specific HTTP libraries (requests, httpx, aiohttp).

The class supports both synchronous and asynchronous operations through corresponding method pairs (e.g., login() and alogin()).

provider¶

The base URL of the CAS server (e.g., ‘https://cas.example.com/cas’).

Type:: str

service_url¶

The service URL registered with the CAS server.

Type:: str

callback_url¶

The callback URL for login.

Type:: str

is_async¶

Flag indicating whether this client is used for async operations.

Type:: bool

Example

Subclasses should implement HTTP fetching methods and context managers:

>>> class MyCustomClient(CASClientBase):
...     def fetch_service_validate(self, ticket, pgt_url=None, renew=False, version=2):
...         # Implement HTTP request to serviceValidate provider
...         pass

Usage:

>>> with CASClient.create(provider, service, callback) as client:
...     client.service_validate(ticket)

>>> # Or in async context:
... async with CASClient.create(provider, service, callback, is_async=True) as client:
...     await client.aservice_validate(ticket)

async aclose()¶: Close any underlying HTTP connections or sessions asynchronously. Called automatically when used as an async context manager.

async afetch_proxy(pgt: str, target_service: str) → bytes¶: Same as fetch_proxy() but for asynchronous operation.

async afetch_proxy_validate(ticket: str, pgt_url: str | None = None, renew: bool = False, version: int = 2) → bytes¶: Same as fetch_proxy_validate() but for asynchronous operation.

async afetch_saml_validate(ticket: str, request_id: str | None = None, issued_at: datetime | None = None) → bytes¶: Same as fetch_saml_validate() but for asynchronous operation.

async afetch_service_validate(ticket: str, pgt_url: str | None = None, renew: bool = False, version: int = 2) → bytes¶: Same as fetch_service_validate() but for asynchronous operation.

async afetch_validate(ticket: str, renew: bool = False) → str¶: Same as fetch_validate() but for asynchronous operation.

async alogin(username: str, password: str, remember: bool = False, warn: bool = False, extra_data: dict | None = None) → CASLoginData¶: Same as login() but for asynchronous operation.

async alogout() → bool¶: Same as logout() but for asynchronous operation.

async aproxy(pgt: str, target_service: str) → CASProxyData¶: Same as proxy() but for asynchronous operation.

async aproxy_validate(ticket: str, pgt_url: str | None = None, renew: bool = False, version: int = 2) → CASServiceValidateData¶: Same as proxy_validate() but for asynchronous operation.

async asaml_validate(ticket: str, request_id: str | None = None, issued_at: datetime | None = None) → CASServiceValidateData¶: Same as saml_validate() but for asynchronous operation.

async aservice_validate(ticket: str, pgt_url: str | None = None, renew: bool = False, version: int = 2) → CASServiceValidateData¶: Same as service_validate() but for asynchronous operation.

async avalidate(ticket: str, renew: bool = False) → CASServiceValidateData¶: Same as validate() but for asynchronous operation.

close()¶: Close any underlying HTTP connections or sessions. Called automatically when used as a context manager.

fetch_proxy(pgt: str, target_service: str) → bytes¶

Fetch a proxy ticket using the provided Proxy Granting Ticket (PGT) and target service.: This method is only responsible for making the HTTP request. If you want to perform full proxy ticket retrieval, use the proxy() method.

fetch_proxy_validate(ticket: str, pgt_url: str | None = None, renew: bool = False, version: int = 2) → bytes¶

Fetch proxy validation result for the given ticket. This method is: only responsible for making the HTTP request. If you want to perform full proxy validation, use the proxy_validate() method.

Parameters:

ticket (str) – The CAS ticket to validate.
pgt_url (str|None) – Proxy Granting Ticket URL, if applicable.
renew (bool) – If True, adds the ‘renew’ parameter to the validation request.
version (int) – The CAS protocol version (2 or 3).
Returns
bytes – The raw XML content returned by the CAS server.

Raises:

CASServiceAuthenticationFailure – If ticket validation fails.

fetch_saml_validate(ticket: str, request_id: str | None = None, issued_at: datetime | None = None) → bytes¶

Fetch SAML validation result for the given ticket. This method is: only responsible for making the HTTP request. If you want to perform full SAML validation, use the saml_validate() method.

Parameters:

ticket (str) – The CAS ticket to validate.
request_id (str|None) – Optional request ID for the SAML request.
issued_at (datetime|None) – Optional issue timestamp for the SAML request.

Returns:

The raw XML content returned by the CAS server.

Return type:

bytes

fetch_service_validate(ticket: str, pgt_url: str | None = None, renew: bool = False, version: int = 2) → bytes¶

Fetch service validation result for the given ticket. This method is: only responsible for making the HTTP request. If you want to perform full service validation, use the service_validate() method.

Parameters:

ticket (str) – The CAS ticket to validate.
pgt_url (str|None) – Proxy Granting Ticket URL, if applicable.
renew (bool) – If True, adds the ‘renew’ parameter to the validation request.
version (int) – The CAS protocol version (2 or 3).

Returns:

The raw XML content returned by the CAS server.

Return type:

bytes

Raises:

CASServiceAuthenticationFailure – If ticket validation fails.

fetch_validate(ticket: str, renew: bool = False) → str¶

Fetch validation result for the given ticket. This method is: only responsible for making the HTTP request. If you want to perform full validation, use the validate() method.

Parameters:

ticket (str) – The CAS ticket to validate.
renew (bool) – If True, adds the ‘renew’ parameter to the validation request.

Returns:

The username associated with the validated ticket.

Return type:

str

Raises:

CASServiceAuthenticationFailure – If ticket validation fails.

login(username: str, password: str, remember: bool = False, warn: bool = False, extra_data: dict | None = None) → CASLoginData¶

Parameters:

username (str) – The username for authentication.
password (str) – The password for authentication.
remember (bool) – If True, sets the ‘remember me’ option.
warn (bool) – If True, sets the ‘warn’ option.
extra_data (dict|None) – Additional form data to include in the login request.

Returns:

The result of the login attempt.

Return type:

CASLoginData

login_form_url(gateway: bool = False, renew: bool = False, use_post: bool = False) → str¶

Construct the URL for the CAS login form.

Parameters:

gateway (bool) – If True, adds the ‘gateway’ parameter to the URL.
renew (bool) – If True, adds the ‘renew’ parameter to the URL.
use_post (bool) – If True, adds the ‘method=POST’ parameter to the URL.

Returns:

The constructed login form URL.

Return type:

str

Example

>>> with CASClient.create(provider, service) as client:
...     login_url = client.login_form_url()

login_url(**kwargs)¶

Construct the URL for the CAS login provider with optional parameters.

Parameters:: **kwargs – Additional query parameters to include in the URL. Must include ‘service’ parameter.
Returns:: The constructed login URL.
Return type:: str

logout() → bool¶

Logout from the CAS server.

Returns:: True if logout was successful, False otherwise.
Return type:: bool

logout_url(**kwargs) → str¶

Construct the URL for the CAS logout provider with optional parameters.

Parameters:: **kwargs – Additional query parameters to include in the URL. Must include ‘service’ parameter.
Returns:: The constructed logout URL.
Return type:: str

static parse_logout_request(content: bytes) → CASLogoutData¶

Parse a SAML logout request XML content and return a CASLogoutData object.

Parameters:: content (bytes) – The SAML logout request XML content.
Returns:: The parsed logout data.
Return type:: CASLogoutData

proxy(pgt: str, target_service: str) → CASProxyData¶

Retrieve a proxy ticket against CAS server for the specified target service: using the provided PGT.

Parameters:

pgt (str) – The Proxy Granting Ticket.
target_service (str) – The target service for which to obtain the proxy ticket.

Returns:

The result containing the proxy ticket.

Return type:

CASProxyData

Raises:

CASProxyFailure – If proxy ticket retrieval fails.

proxy_url(**kwargs)¶

Construct the URL for the CAS proxy provider with optional parameters.

Parameters:: **kwargs – Additional query parameters to include in the URL. Must include ‘pgt’ and ‘targetService’ parameters.
Returns:: The constructed proxy URL.
Return type:: str

proxy_validate(ticket: str, pgt_url: str | None = None, renew: bool = False, version: int = 2) → CASServiceValidateData¶: Same as service_validate() but it can additionnaly validate proxy tickets.

proxy_validate_url(version=2, **kwargs)¶

Construct the URL for the CAS proxyValidate provider with optional parameters.

Parameters:

version (int) – The CAS protocol version (2 or 3).
**kwargs – Additional query parameters to include in the URL. Must include ‘service’ and ‘ticket’ parameters.

Returns:

The constructed proxyValidate URL.

Return type:

str

saml_validate(ticket: str, request_id: str | None = None, issued_at: datetime | None = None) → CASServiceValidateData¶

Validate the given ticket against CAS server using SAML and return the validation data.

Parameters:

ticket (str) – The CAS ticket to validate.
request_id (str|None) – Optional request ID for the SAML request.
issued_at (datetime|None) – Optional issue timestamp for the SAML request. If not provided, the current time will be used.

Returns:

The result of the ticket validation.

Return type:

CASServiceValidateData

Raises:

CASServiceAuthenticationFailure – If ticket validation fails.

saml_validate_url(**kwargs)¶

Construct the URL for the CAS samlValidate provider with optional parameters.

Parameters:: **kwargs – Additional query parameters to include in the URL. Must include ‘TARGET’ parameter.
Returns:: The constructed samlValidate URL.
Return type:: str

service_validate(ticket: str, pgt_url: str | None = None, renew: bool = False, version: int = 2) → CASServiceValidateData¶

Validate the given ticket against CAS server and return the validation data.

Parameters:

ticket (str) – The CAS ticket to validate.
pgt_url (str|None) – Proxy Granting Ticket URL, if applicable.
renew (bool) – If True, adds the ‘renew’ parameter to the validation request.
version (int) – The CAS protocol version (2 or 3).

Returns:

The result of the ticket validation.

Return type:

CASServiceValidateData

Raises:

CASServiceAuthenticationFailure – If ticket validation fails.

service_validate_url(version=2, **kwargs)¶

Construct the URL for the CAS serviceValidate provider with optional parameters.

Parameters:

version (int) – The CAS protocol version (2 or 3).
**kwargs – Additional query parameters to include in the URL. Must include ‘service’ and ‘ticket’ parameters.

Returns:

The constructed serviceValidate URL.

Return type:

str

ticket_from_url(url: str) → str¶

Extract the CAS ticket from a given URL.

Parameters:: url (str) – The URL containing the CAS ticket as a query parameter.
Returns:: The extracted CAS ticket, or an empty string if not found.
Return type:: str

validate(ticket: str, renew: bool = False) → CASServiceValidateData¶

Validate the given ticket against CAS server and return the validation data.

Parameters:

ticket (str) – The CAS ticket to validate.
renew (bool) – If True, adds the ‘renew’ parameter to the validation request.

Returns:

The result of the ticket validation.

Return type:

CASServiceValidateData

Raises:

CASServiceAuthenticationFailure – If ticket validation fails.

validate_url(**kwargs)¶

Construct the URL for the CAS validate provider with optional parameters.

Parameters:: **kwargs – Additional query parameters to include in the URL. Must include ‘service’ and ‘ticket’ parameters.
Returns:: The constructed validate URL.
Return type:: str

Specific client interface¶

Never use client interface directly, use factory method pycas_sso.cas.CASClient.create instead.

class pycas_sso.clients.httpx.CASClient_Httpx(provider: str, service_url: str, callback_url: str, is_async: bool = False, **kwargs)¶: CASClient implementation using the httpx library.

class pycas_sso.clients.requests.CASClient_Requests(provider: str, service_url: str, callback_url: str, is_async: bool = False, **kwargs)¶: CASClient implementation using the requests library.

Note

Asynchronous operations is not supported by requests library.

class pycas_sso.clients.aiohttp.CASClient_AIOHttp(provider: str, service_url: str, callback_url: str, is_async: bool = True, **kwargs)¶: CASClient implementation using the aiohttp library.

Note

Only asynchronous operations are supported by aiohttp library.

Exceptions¶

CAS-related error definitions and exceptions.

exception pycas_sso.errors.CASProxyFailure(client, code: str, message: str = '')¶

Bases: Exception

Exception raised when CAS proxy request fails.

exception pycas_sso.errors.CASServiceAuthenticationFailure(client, code: str, message: str = '')¶

Bases: Exception

Exception raised when CAS service authentication fails.

Miscellaneous¶

class pycas_sso.schemas.CASLoginData(client: CASClientBase, success: bool, http_status: int, redirect_url: str = '')¶

Bases: object

Data returned after a login attempt.

class pycas_sso.schemas.CASLogoutData(request_id: str, issued_at: datetime | str, session_id: str)¶

Bases: object

Data returned after parsing a logout callback content from CAS server.

class pycas_sso.schemas.CASProxyData(client: CASClientBase, proxy_ticket: str)¶

Bases: object

Data returned after a proxy ticket request.

class pycas_sso.schemas.CASServiceValidateData(client: CASClientBase, username: str, proxy_granting_ticket: str | None = None, attrs: dict | None = None, proxies: list | None = None)¶

Bases: object

Data returned after a service validation, proxy validation or: saml validation attempt.