SSO (OIDC + SAML + LDAP)

Overview

The sso client manages OIDC and SAML 2.0 enterprise connections, domain-based enforcement, JIT provisioning, and sessions. It also exposes the current LDAP direct-bind preview; that preview is not a general LDAP directory integration and has the limitations documented below. Access the SSO client via client.sso.

from grantex import Grantex, CreateSsoConnectionParams

with Grantex(api_key="gx_live_...") as client:
    conn = client.sso.create_connection(CreateSsoConnectionParams(
        name="Okta Production",
        protocol="oidc",
        issuer_url="https://mycompany.okta.com",
        client_id="your-client-id",
        client_secret="your-client-secret",
        domains=["mycompany.com"],
        jit_provisioning=True,
    ))

Enterprise SSO Connections

Create Connection

Create a new SSO identity provider connection. You can create multiple connections for different domains or providers.

from grantex import Grantex, CreateSsoConnectionParams

with Grantex(api_key="gx_live_...") as client:
    conn = client.sso.create_connection(CreateSsoConnectionParams(
        name="Okta Production",
        protocol="oidc",
        issuer_url="https://mycompany.okta.com",
        client_id="your-okta-client-id",
        client_secret="your-okta-client-secret",
        domains=["mycompany.com", "mycompany.org"],
        jit_provisioning=True,
        default_role="member",
    ))

    print(f"ID: {conn.id}")                    # 'sso_conn_01HX...'
    print(f"Name: {conn.name}")                # 'Okta Production'
    print(f"Protocol: {conn.protocol}")        # 'oidc'
    print(f"Status: {conn.status}")            # 'active'
    print(f"Domains: {conn.domains}")          # ['mycompany.com', 'mycompany.org']
    print(f"JIT: {conn.jit_provisioning}")     # True
    print(f"Created: {conn.created_at}")       # '2026-03-29T12:00:00Z'

SAML example

from grantex import CreateSsoConnectionParams

saml_conn = client.sso.create_connection(CreateSsoConnectionParams(
    name="Azure AD SAML",
    protocol="saml",
    metadata_url="https://login.microsoftonline.com/.../federationmetadata/2007-06/federationmetadata.xml",
    assertion_consumer_service_url="https://yourapp.com/sso/saml/callback",
    entity_id="https://yourapp.com/saml/metadata",
    domains=["contoso.com"],
    jit_provisioning=True,
    attribute_mapping={
        "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/displayname",
    },
))

CreateSsoConnectionParams

Field	Type	Required	Description
`name`	`str`	Yes	A human-readable name for this connection.
`protocol`	`str`	Yes	`"oidc"`, `"saml"`, or `"ldap"`.
`issuer_url`	`str`	OIDC only	The OIDC issuer URL.
`client_id`	`str`	OIDC only	OAuth 2.0 client ID from your IdP.
`client_secret`	`str`	OIDC only	OAuth 2.0 client secret from your IdP.
`metadata_url`	`str`	SAML only	The SAML metadata URL.
`assertion_consumer_service_url`	`str`	SAML only	The SAML ACS URL.
`entity_id`	`str`	SAML only	The SAML service provider entity ID.
`domains`	`list[str]`	No	Email domains to associate with this connection.
`jit_provisioning`	`bool`	No	Enable just-in-time user provisioning. Defaults to `False`.
`default_role`	`str`	No	Default role for JIT-provisioned users.
`attribute_mapping`	`dict[str, str]`	No	Custom attribute mapping for SAML assertions.

SsoConnection

Field	Type	Description
`id`	`str`	Unique connection identifier.
`name`	`str`	The connection display name.
`protocol`	`str`	`"oidc"`, `"saml"`, or `"ldap"`.
`status`	`str`	`"active"`, `"inactive"`, or `"error"`.
`domains`	`list[str]`	Associated email domains.
`jit_provisioning`	`bool`	Whether JIT provisioning is enabled.
`created_at`	`str`	ISO 8601 creation timestamp.
`updated_at`	`str`	ISO 8601 last-updated timestamp.

Note: The client_secret is never returned in responses. It is stored securely on the server.

List Connections

List all SSO connections for your organization.

connections = client.sso.list_connections()

for conn in connections.connections:
    print(f"{conn.name} ({conn.protocol}) - {conn.status}")
    print(f"  Domains: {', '.join(conn.domains)}")

SsoConnectionList

Field	Type	Description
`connections`	`list[SsoConnection]`	Array of SSO connection objects.

Get Connection

Retrieve a single SSO connection by ID.

conn = client.sso.get_connection("sso_conn_01HX...")

print(f"Name: {conn.name}")         # 'Okta Production'
print(f"Protocol: {conn.protocol}") # 'oidc'
print(f"Status: {conn.status}")     # 'active'

Parameters

Parameter	Type	Required	Description
`connection_id`	`str`	Yes	The connection ID to retrieve.

Update Connection

Update an existing SSO connection.

from grantex import UpdateSsoConnectionParams

updated = client.sso.update_connection("sso_conn_01HX...", UpdateSsoConnectionParams(
    name="Okta Production (updated)",
    jit_provisioning=False,
    domains=["mycompany.com", "mycompany.org", "subsidiary.com"],
))

print(f"Name: {updated.name}")      # 'Okta Production (updated)'
print(f"Domains: {updated.domains}") # ['mycompany.com', 'mycompany.org', 'subsidiary.com']

UpdateSsoConnectionParams

Field	Type	Required	Description
`name`	`str`	No	Updated display name.
`domains`	`list[str]`	No	Updated list of associated email domains.
`jit_provisioning`	`bool`	No	Enable or disable JIT provisioning.
`default_role`	`str`	No	Updated default role for JIT-provisioned users.
`attribute_mapping`	`dict[str, str]`	No	Updated SAML attribute mapping.

Delete Connection

Delete an SSO connection. Users associated with this connection will no longer be able to log in via SSO.

client.sso.delete_connection("sso_conn_01HX...")
# Returns None -- connection is removed

Parameters

Parameter	Type	Required	Description
`connection_id`	`str`	Yes	The connection ID to delete.

Warning: Deleting a connection immediately disables SSO login for all users routed through it. Ensure you have an alternative authentication method configured before removing a connection.

Test Connection

Test an SSO connection to verify that the IdP configuration is correct and reachable.

test = client.sso.test_connection("sso_conn_01HX...")

print(f"Success: {test.success}")            # True
print(f"Message: {test.message}")            # 'Connection verified successfully'
print(f"Response time: {test.response_time}") # 142 (ms)

Parameters

Parameter	Type	Required	Description
`connection_id`	`str`	Yes	The connection ID to test.

SsoTestResult

Field	Type	Description
`success`	`bool`	Whether the connection test passed.
`message`	`str`	Human-readable result message.
`response_time`	`int`	IdP response time in milliseconds.

Enforcement

Set Enforcement

Enforce SSO login for your organization. When enabled, all members must authenticate through an SSO connection.

from grantex import SsoEnforcementParams

enforcement = client.sso.set_enforcement(SsoEnforcementParams(
    enforced=True,
    exempt_roles=["owner"],
))

print(f"Enforced: {enforcement.enforced}")         # True
print(f"Exempt roles: {enforcement.exempt_roles}") # ['owner']

SsoEnforcementParams

Field	Type	Required	Description
`enforced`	`bool`	Yes	Whether SSO login is enforced for all members.
`exempt_roles`	`list[str]`	No	Roles exempt from SSO enforcement.

SsoEnforcement

Field	Type	Description
`enforced`	`bool`	Whether SSO enforcement is active.
`exempt_roles`	`list[str]`	Roles exempt from the enforcement policy.

Session Management

List Sessions

List active SSO sessions for your organization.

sessions = client.sso.list_sessions()

for session in sessions.sessions:
    print(f"{session.email} - {session.connection_name} - expires {session.expires_at}")

SsoSessionList

Field	Type	Description
`sessions`	`list[SsoSession]`	Array of active SSO session objects.

SsoSession

Field	Type	Description
`id`	`str`	Session identifier.
`email`	`str`	The user’s email address.
`connection_id`	`str`	The SSO connection used for this session.
`connection_name`	`str`	Display name of the SSO connection.
`created_at`	`str`	ISO 8601 session creation timestamp.
`expires_at`	`str`	ISO 8601 session expiration timestamp.

Revoke Session

Revoke an active SSO session, forcing the user to re-authenticate.

client.sso.revoke_session("sso_sess_01HX...")
# Returns None -- session is revoked

Parameters

Parameter	Type	Required	Description
`session_id`	`str`	Yes	The session ID to revoke.

Get the SSO authorization URL for a user based on their email domain. The domain is matched against configured connections to route the user to the correct IdP.

from grantex import SsoLoginParams

login = client.sso.get_login_url(SsoLoginParams(
    domain="mycompany.com",
    redirect_uri="https://yourapp.com/sso/callback",
))

print(f"Redirect to: {login.authorize_url}")
print(f"Connection: {login.connection_id}")  # 'sso_conn_01HX...'
print(f"Protocol: {login.protocol}")         # 'oidc'

SsoLoginParams

Field	Type	Required	Description
`domain`	`str`	Yes	Email domain to match against SSO connections.
`redirect_uri`	`str`	No	Override the redirect URI for this login request.

SsoLoginResponse

Field	Type	Description
`authorize_url`	`str`	The full authorization URL. Redirect the user here.
`connection_id`	`str`	The matched SSO connection ID.
`protocol`	`str`	The protocol of the matched connection.

Handle OIDC Callback

Handle the callback from an OIDC identity provider. Exchanges the authorization code for user information and provisions the user if JIT is enabled.

from grantex import SsoOidcCallbackParams

result = client.sso.handle_oidc_callback(SsoOidcCallbackParams(
    code="oidc_auth_code",
    state="csrf_state",
))

print(f"Email: {result.email}")               # 'alice@mycompany.com'
print(f"Name: {result.name}")                 # 'Alice Smith'
print(f"Subject: {result.sub}")               # 'okta|abc123'
print(f"Developer ID: {result.developer_id}") # 'dev_01HXYZ...'
print(f"Connection: {result.connection_id}")  # 'sso_conn_01HX...'
print(f"Provisioned: {result.provisioned}")   # True (if JIT-created)

SsoOidcCallbackParams

Field	Type	Required	Description
`code`	`str`	Yes	The authorization code from the OIDC callback.
`state`	`str`	Yes	The state parameter for CSRF protection.

SsoCallbackResponse

Field	Type	Description
`email`	`str \| None`	The user’s email address from the IdP.
`name`	`str \| None`	The user’s display name from the IdP.
`sub`	`str \| None`	The user’s subject identifier from the IdP.
`developer_id`	`str`	The Grantex developer ID.
`connection_id`	`str`	The SSO connection that handled this authentication.
`provisioned`	`bool`	Whether the user was JIT-provisioned during this login.

Handle SAML Callback

Handle the callback from a SAML 2.0 identity provider. Validates the SAML assertion and provisions the user if JIT is enabled.

from grantex import SsoSamlCallbackParams

result = client.sso.handle_saml_callback(SsoSamlCallbackParams(
    saml_response=request.form["SAMLResponse"],
    relay_state=request.form.get("RelayState"),
))

print(f"Email: {result.email}")               # 'bob@contoso.com'
print(f"Name: {result.name}")                 # 'Bob Jones'
print(f"Developer ID: {result.developer_id}") # 'dev_01HXYZ...'
print(f"Connection: {result.connection_id}")  # 'sso_conn_02HX...'
print(f"Provisioned: {result.provisioned}")   # False

SsoSamlCallbackParams

Field	Type	Required	Description
`saml_response`	`str`	Yes	The base64-encoded SAML response from the IdP.
`relay_state`	`str`	No	The RelayState parameter from the SAML callback.

Response

Returns the same SsoCallbackResponse as handle_oidc_callback().

Handle LDAP Callback

Authenticate a user with the LDAP direct-bind preview. Unlike OIDC and SAML, credentials are submitted directly. The built-in client binds a service account, constructs a user DN from ldap_search_filter plus ldap_search_base, and binds that DN with the submitted password. It does not search entries, read attributes, or retrieve group memberships.

from grantex import SsoLdapCallbackParams

result = client.sso.handle_ldap_callback(SsoLdapCallbackParams(
    username="alice",
    password="user-password",
    connection_id="sso_conn_03HX...",
    org="org_01HXYZ...",
))

print(f"Email: {result.email}")               # None
print(f"Name: {result.name}")                 # None
print(f"Groups: {result.groups}")             # ()
print(f"Mapped scopes: {result.mapped_scopes}") # default_scopes only
print(f"Developer ID: {result.developer_id}") # 'dev_01HXYZ...'
print(f"Session: {result.session_id}")        # 'ssosess_01HXYZ...'

SsoLdapCallbackParams

Field	Type	Required	Description
`username`	`str`	Yes	Username interpolated into the configured filter to construct the user DN; the built-in preview does not search.
`password`	`str`	Yes	The user’s LDAP password for bind authentication.
`connection_id`	`str`	Yes	The SSO connection ID for the LDAP directory.
`org`	`str`	Yes	Organization/developer ID that owns the LDAP connection.

Response

Returns SsoCallbackResult. With the built-in LDAP client, groups is empty, name and email are None, and mapped_scopes therefore contains only configured default scopes.

Note: LDAP credentials are never stored by Grantex. They are used only for the bind operations and discarded after authentication. LDAP search, attribute retrieval, group lookup/mapping, and broad provider compatibility are not supported by the built-in preview client.

Full Enterprise SSO Flow Example

from flask import Flask, request, redirect
from grantex import (
    Grantex,
    CreateSsoConnectionParams,
    SsoEnforcementParams,
    SsoLoginParams,
    SsoOidcCallbackParams,
    SsoSamlCallbackParams,
)
import os

app = Flask(__name__)
client = Grantex(api_key=os.environ["GRANTEX_API_KEY"])

# Step 1: Create SSO connections (one-time setup)
client.sso.create_connection(CreateSsoConnectionParams(
    name="Okta Production",
    protocol="oidc",
    issuer_url="https://mycompany.okta.com",
    client_id=os.environ["OKTA_CLIENT_ID"],
    client_secret=os.environ["OKTA_CLIENT_SECRET"],
    domains=["mycompany.com"],
    jit_provisioning=True,
    default_role="member",
))

client.sso.create_connection(CreateSsoConnectionParams(
    name="Azure AD SAML",
    protocol="saml",
    metadata_url=os.environ["AZURE_METADATA_URL"],
    assertion_consumer_service_url="https://yourapp.com/sso/saml/callback",
    entity_id="https://yourapp.com/saml/metadata",
    domains=["contoso.com"],
    jit_provisioning=True,
))

# Step 2: Enforce SSO for the organization
client.sso.set_enforcement(SsoEnforcementParams(
    enforced=True,
    exempt_roles=["owner"],
))

# Step 3: Redirect user to SSO login based on email domain
@app.route("/sso/login")
def sso_login():
    domain = request.args["domain"]
    login = client.sso.get_login_url(SsoLoginParams(
        domain=domain,
        redirect_uri="https://yourapp.com/sso/callback",
    ))
    return redirect(login.authorize_url)

# Step 4a: Handle OIDC callback
@app.route("/sso/callback")
def sso_callback():
    result = client.sso.handle_oidc_callback(SsoOidcCallbackParams(
        code=request.args["code"],
        state=request.args["state"],
    ))

    print(f"Welcome, {result.name} ({result.email})")
    if result.provisioned:
        print("New user provisioned via JIT")
    return redirect("/dashboard")

# Step 4b: Handle SAML callback
@app.route("/sso/saml/callback", methods=["POST"])
def sso_saml_callback():
    result = client.sso.handle_saml_callback(SsoSamlCallbackParams(
        saml_response=request.form["SAMLResponse"],
        relay_state=request.form.get("RelayState"),
    ))

    print(f"Welcome, {result.name} ({result.email})")
    return redirect("/dashboard")

# Admin: List active sessions
@app.route("/admin/sso/sessions")
def sso_sessions():
    sessions = client.sso.list_sessions()
    return {"sessions": [s.__dict__ for s in sessions.sessions]}

Legacy Single-Config Methods

Note: The following methods manage a single OIDC configuration per organization. They are retained for backward compatibility. For new integrations, use the enterprise connection methods above which support multiple IdPs, SAML, and domain-based routing.

Create Config

Create or update the OIDC SSO configuration for your developer organization:

from grantex import Grantex, CreateSsoConfigParams

with Grantex(api_key="gx_live_...") as client:
    config = client.sso.create_config(CreateSsoConfigParams(
        issuer_url="https://accounts.google.com",
        client_id="your-oidc-client-id",
        client_secret="your-oidc-client-secret",
        redirect_uri="https://myapp.com/sso/callback",
    ))

    print(f"Issuer: {config.issuer_url}")
    print(f"Client ID: {config.client_id}")
    print(f"Redirect URI: {config.redirect_uri}")
    print(f"Created at: {config.created_at}")

CreateSsoConfigParams

Field	Type	Required	Description
`issuer_url`	`str`	Yes	The OIDC issuer URL (e.g. `https://accounts.google.com`).
`client_id`	`str`	Yes	The OIDC client ID from your IdP.
`client_secret`	`str`	Yes	The OIDC client secret from your IdP.
`redirect_uri`	`str`	Yes	The redirect URI registered with your IdP.

Get Config

Retrieve the current SSO configuration. The client secret is not included in the response:

config = client.sso.get_config()

print(f"Issuer: {config.issuer_url}")
print(f"Client ID: {config.client_id}")
print(f"Redirect URI: {config.redirect_uri}")
print(f"Updated at: {config.updated_at}")

SsoConfig

Field	Type	Description
`issuer_url`	`str`	The OIDC issuer URL.
`client_id`	`str`	The OIDC client ID.
`redirect_uri`	`str`	The registered redirect URI.
`created_at`	`str`	ISO 8601 creation timestamp.
`updated_at`	`str`	ISO 8601 last-updated timestamp.

Delete Config

Remove the SSO configuration:

client.sso.delete_config()
# Returns None on success

Generate the OIDC authorization URL to redirect a user to for SSO login:

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    login = client.sso.get_login_url("my-organization")

    print(f"Redirect to: {login.authorize_url}")

Parameters

Parameter	Type	Required	Description
`org`	`str`	Yes	The organization identifier for SSO lookup.

SsoLoginResponse (legacy)

Field	Type	Description
`authorize_url`	`str`	The OIDC authorization URL to redirect the user to.

Handle Callback

Exchange the OIDC authorization code for user information after the IdP redirects back to your application:

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    result = client.sso.handle_callback(
        code="oidc_auth_code",
        state="csrf_state_value",
    )

    print(f"Developer ID: {result.developer_id}")
    print(f"Email: {result.email}")
    print(f"Name: {result.name}")
    print(f"Subject: {result.sub}")

Parameters

Parameter	Type	Required	Description
`code`	`str`	Yes	The authorization code from the OIDC callback.
`state`	`str`	Yes	The state parameter for CSRF verification.

SsoCallbackResponse (legacy)

Field	Type	Description
`developer_id`	`str`	The Grantex developer ID for the authenticated user.
`email`	`str \| None`	The user’s email address (if provided by IdP).
`name`	`str \| None`	The user’s display name (if provided by IdP).
`sub`	`str \| None`	The OIDC subject identifier.

Legacy SSO Flow Example

from grantex import Grantex, CreateSsoConfigParams

with Grantex(api_key="gx_live_...") as client:
    # 1. Configure SSO (one-time setup)
    client.sso.create_config(CreateSsoConfigParams(
        issuer_url="https://accounts.google.com",
        client_id="your-client-id",
        client_secret="your-client-secret",
        redirect_uri="https://myapp.com/sso/callback",
    ))

    # 2. Generate login URL for a user
    login = client.sso.get_login_url("my-organization")
    # Redirect the user's browser to login.authorize_url

    # 3. Handle the callback (in your /sso/callback route)
    result = client.sso.handle_callback(
        code="code_from_idp",
        state="state_from_idp",
    )
    print(f"Logged in as: {result.email} (developer: {result.developer_id})")

    # 4. Verify or clean up configuration
    config = client.sso.get_config()
    print(f"SSO configured with: {config.issuer_url}")

    # To remove SSO:
    # client.sso.delete_config()

​Overview

​Enterprise SSO Connections

​Create Connection

​SAML example

​CreateSsoConnectionParams

​SsoConnection

​List Connections

​SsoConnectionList

​Get Connection

​Parameters

​Update Connection

​UpdateSsoConnectionParams

​Delete Connection

​Parameters

​Test Connection

​Parameters

​SsoTestResult

​Enforcement

​Set Enforcement

​SsoEnforcementParams

​SsoEnforcement

​Session Management

​List Sessions

​SsoSessionList

​SsoSession

​Revoke Session

​Parameters

​Enterprise Login Flow

​Get Login URL (enterprise)

​SsoLoginParams

​SsoLoginResponse

​Handle OIDC Callback

​SsoOidcCallbackParams

​SsoCallbackResponse

​Handle SAML Callback

​SsoSamlCallbackParams

​Response

​Handle LDAP Callback

​SsoLdapCallbackParams

​Response

​Full Enterprise SSO Flow Example

​Legacy Single-Config Methods

​Create Config

​CreateSsoConfigParams

​Get Config

​SsoConfig

​Delete Config

​Get Login URL (legacy)

​Parameters

​SsoLoginResponse (legacy)

​Handle Callback

​Parameters

​SsoCallbackResponse (legacy)

​Legacy SSO Flow Example

Overview

Enterprise SSO Connections

Create Connection

SAML example

CreateSsoConnectionParams

SsoConnection

List Connections

SsoConnectionList

Get Connection

Parameters

Update Connection

UpdateSsoConnectionParams

Delete Connection

Parameters

Test Connection

Parameters

SsoTestResult

Enforcement

Set Enforcement

SsoEnforcementParams

SsoEnforcement

Session Management

List Sessions

SsoSessionList

SsoSession

Revoke Session

Parameters

Enterprise Login Flow

Get Login URL (enterprise)

SsoLoginParams

SsoLoginResponse

Handle OIDC Callback

SsoOidcCallbackParams

SsoCallbackResponse

Handle SAML Callback

SsoSamlCallbackParams

Response

Handle LDAP Callback

SsoLdapCallbackParams

Response

Full Enterprise SSO Flow Example

Legacy Single-Config Methods

Create Config

CreateSsoConfigParams

Get Config

SsoConfig

Delete Config

Get Login URL (legacy)

Parameters

SsoLoginResponse (legacy)

Handle Callback

Parameters

SsoCallbackResponse (legacy)

Legacy SSO Flow Example