RemoteIdentityProvider
Client-side SDK for authenticating users against your enterprise IDP. Routes IAM operations through the Identity Bridge so your client code never handles IDP credentials.
Constructor
Initialize a connection to the Identity Bridge. Auto-detects endpoint and API key from config if not provided.
RemoteIdentityProvider(
endpoint: str = None, # Auto-detected from config
api_key: str = None # Auto-detected from config
)| Parameter | Type | Description |
|---|---|---|
endpoint | str | MACAW Core endpoint. Unix socket path or HTTP URL. Auto-detected if not provided. |
api_key | str | Workspace API key for shared service authentication. Auto-detected if not provided. |
Methods
Authentication
login(username, password, scopes=None)→Tuple[str, dict]Authenticate against tenant's IDP. Returns JWT token and validated principal with claims.
login_browser(timeout=300, open_browser=True)→Tuple[str, dict]Authenticate a user through the tenant's IDP in the browser. Returns JWT token and validated principal with claims.
validate(jwt_token)→dictValidate existing token with tenant's IDP. Returns validated principal if valid.
Examples
User Authentication
Authenticate a user and create a client with their enterprise identity.
from macaw_client import MACAWClient
from macaw_client import RemoteIdentityProvider
# Initialize (reads config automatically)
idp = RemoteIdentityProvider()
# Authenticate user
token, principal = idp.login("alice@company.com", password)
# principal contains: user_id, roles, groups, department, etc.
# Create client with authenticated identity
client = MACAWClient(
app_name="sales-assistant",
agent_type="user",
iam_token=token
)
client.register()
# All operations now carry user's identity
result = client.invoke_tool("crm", {"customer_id": "12345"})Browser Sign-In
Authenticate a user through the IDP's sign-in page in the browser. Requires the redirect URI described in Identity Bridge.
from macaw_client import MACAWClient, RemoteIdentityProvider
idp = RemoteIdentityProvider()
# Opens the IDP's sign-in page in the browser
token, principal = idp.login_browser()
client = MACAWClient(
app_name="approvals",
agent_type="user",
user_name="bob",
iam_token=token
)
client.register()Token Validation
Validate an existing JWT from an external source or refresh flow.
# Validate token from request header, cookie, etc.
idp = RemoteIdentityProvider()
try:
principal = idp.validate(existing_jwt)
# principal.user_id, principal.roles, etc.
except Exception as e:
# Token invalid or expired
print(f"Validation failed: {e}")Architecture
Identity Bridge Flow
All authentication routes through the server-side Identity Bridge. IDP credentials never reach client code.
Client App MACAW Core Enterprise IDP
│ │ │
│ login(user,pass) │ │
├───────────────────>│ │
│ │ OAuth2/OIDC │
│ ├──────────────────────>│
│ │ │
│ │ JWT (claims) │
│ │<──────────────────────┤
│ │ │
│ (token, principal)│ │
│<───────────────────┤ │Tenant Isolation
RemoteIdentityProvider uses tenant-specific IDP configuration. Each workspace has its own Identity Bridge settings, and the SDK automatically routes requests to the correct tenant's IDP.
What This Means
- • Each workspace admin configures their own IdP
- • SDK uses your workspace's API key to route to correct IdP
- • Credentials validated against your workspace's provider
- • No cross-tenant credential or token access
Automatic Routing
The API key in your SDK configuration identifies your workspace. All IAM operations (login, login_browser, validate) are automatically routed to the correct tenant's Identity Bridge and IDP configuration.