tm1-auth

A Python library for authenticating with IBM Planning Analytics (TM1) in environments that use Cognos Access Manager (CAM) with multi-factor authentication.

TM1py requires a cam_passport to connect to CAM-secured environments, but obtaining one programmatically is non-trivial when MFA is involved. tm1-auth handles the browser-based login flow for you and captures the passport automatically.

---

Features

• Automated CAM passport retrieval via a browser login window
• Works alongside TM1py — pass the retrieved passport directly to TM1Service
• Supports system browsers (Edge, Chrome) as well as Playwright's bundled Chromium
• Persistent passport caching via KeyringCache (OS credential manager)
• In-memory passport caching via PassportCache
• Cross-platform: Windows, macOS, Linux

---

Requirements

• Python 3.8+
• Playwright

pip install playwright
python -m playwright install chromium

---

Installation

pip install tm1-auth

---

Quick start

from tm1_auth import get_cam_passport
from TM1py import TM1Service

passport = get_cam_passport(
    auth_url="https://your-cognos-server/ibmcognos/bi/v1/disp"
)

with TM1Service(address="your-tm1-server", port=5001,
                cam_passport=passport, ssl=True) as tm1:
    print(tm1.server.get_product_version())

A browser window opens, you complete the login flow (including MFA), and the passport is captured automatically. The window closes once the passport is detected.

---

Multiple environments

By default all calls share the same browser profile (~/.tm1_auth/browser_profile). Whether this is useful depends on your setup.

Isolated sessions — use when environments have different credentials, or you want explicit login control for each:

dev_passport = get_cam_passport(
    auth_url="https://dev-cognos/ibmcognos/bi/v1/disp",
    profile_dir="~/.tm1_auth/dev",
)

prd_passport = get_cam_passport(
    auth_url="https://prd-cognos/ibmcognos/bi/v1/disp",
    profile_dir="~/.tm1_auth/prd",
)

Each call gets its own browser session and will prompt for login independently.

Shared session — use when environments share the same identity provider and you want to avoid repeated logins:

dev_passport = get_cam_passport(
    auth_url="https://dev-cognos/ibmcognos/bi/v1/disp",
)

prd_passport = get_cam_passport(
    auth_url="https://prd-cognos/ibmcognos/bi/v1/disp",
)

Both calls use the default shared profile. If your identity provider supports SSO, the second call may complete without prompting for credentials or MFA again. This is not guaranteed — it depends entirely on your IdP configuration and session policies.

---

Caching passports

Persistent cache (recommended for IDE use)

KeyringCache stores passports in the OS credential manager (Windows Credential Manager, macOS Keychain, Linux Secret Service). Passports survive process restarts so the browser only opens when a passport has actually expired — not every time you run your script.

from tm1_auth import get_cam_passport, KeyringCache
from TM1py import TM1Service

cache    = KeyringCache()
auth_url = "https://your-cognos/ibmcognos/bi/v1/disp"

passport = cache.get(auth_url)
if not passport:
    passport = get_cam_passport(auth_url)
    cache.set(auth_url, passport)

with TM1Service(address="tm1-server", port=5001,
                cam_passport=passport, ssl=True) as tm1:
    print(tm1.server.get_product_version())

If a passport is rejected by TM1py, invalidate it and re-authenticate:

try:
    tm1 = TM1Service(address="tm1-server", port=5001,
                     cam_passport=passport, ssl=True)
except Exception:
    cache.invalidate(auth_url)
    passport = get_cam_passport(auth_url)
    cache.set(auth_url, passport)
    tm1 = TM1Service(address="tm1-server", port=5001,
                     cam_passport=passport, ssl=True)

In-memory cache

PassportCache is an alternative that keeps passports in memory only. Useful for long-running scripts that connect to TM1 multiple times in one session, but does not persist across process restarts.

from tm1_auth import get_cam_passport, PassportCache

cache = PassportCache(ttl_seconds=3600)

def get_passport(auth_url):
    passport = cache.get(auth_url)
    if not passport:
        passport = get_cam_passport(auth_url)
        cache.set(auth_url, passport)
    return passport

---

API reference

get_cam_passport

get_cam_passport(
    auth_url: str,
    profile_dir: str | None = None,
    timeout_seconds: int = 90,
    headless: bool = False,
    executable_path: str | None = None,
    verbose: bool = True,
) -> str

Parameter	Description
auth_url	The Cognos dispatcher URL (e.g. .../ibmcognos/bi/v1/disp)
profile_dir	Persistent browser profile directory. Same directory = shared session. Different directories = isolated sessions. Defaults to ~/.tm1_auth/browser_profile.
timeout_seconds	Seconds to wait for login before raising PassportTimeoutError. Default 90.
headless	Run without a visible browser window. Not recommended for MFA flows. Default False.
executable_path	Path to a specific browser executable. If not set, tries system Edge then Chrome then Playwright's bundled Chromium.
verbose	Print progress messages to stdout. Default True.

Returns: The cam_passport cookie value as a string.

Raises:

• AuthenticationError — browser failed to launch or could not navigate to the auth URL
• PassportTimeoutError — no passport detected within timeout_seconds

---

KeyringCache

KeyringCache(service: str = "tm1-auth")

Persistent cache backed by the OS credential manager. Survives process restarts.

Method	Description
get(auth_url)	Return stored passport or None if not found
set(auth_url, passport)	Store a passport in the OS credential manager
invalidate(auth_url)	Remove a specific entry

---

PassportCache

PassportCache(ttl_seconds: int = 3600)

In-memory cache. Does not persist across process restarts.

Method	Description
get(auth_url)	Return cached passport or None if missing/expired
set(auth_url, passport)	Cache a passport
invalidate(auth_url)	Remove a specific entry
clear()	Remove all entries

---

Exceptions

from tm1_auth.exceptions import AuthenticationError, PassportTimeoutError

Both inherit from AuthenticationError. Catch AuthenticationError to handle all auth failures, or the specific subclass for finer control.

---

Contributing

Contributions welcome. Please open an issue before submitting a pull request for significant changes.

---

Licence

MIT