feat: add FGA mappings support to SSO tenant settings

[dorsha]

Summary

• Adds FGAGroupMapping and FGAGroupMappingRelation types to the public API
• Wires fgaMappings (plus configFGATenantIDResourcePrefix / configFGATenantIDResourceSuffix for SAML variants) into configure_oidc_settings, configure_saml_settings, and configure_saml_settings_by_metadata, matching the management.proto contract and the Go SDK shape
• Brings the Python SDK to parity with the backend / Go SDK so consumers can configure FGA-based group→relation mappings for SSO tenants

Closes descope/etc#15652

Test plan

• python -m pytest tests/management/test_sso_settings.py -v — 16 passed (4 new FGA-specific tests)
• python -m pytest tests/ — 470 passed
• Manual smoke against staging once merged

🤖 Generated with Claude Code

[shuni-bot-dev]

🐕 Review complete — View session on Shuni Portal 🐾

[Copilot]

Pull request overview

Adds first-class support in the Python SDK for configuring FGA group→relation mappings in SSO tenant settings (OIDC + SAML), aligning the SDK request payload shape with the backend / Go SDK.

Changes:

• Introduces public FGAGroupMapping and FGAGroupMappingRelation types.
• Wires fgaMappings into OIDC/SAML SSO settings request bodies, plus SAML-specific configFGATenantIDResourcePrefix/Suffix.
• Expands SSO settings tests to cover FGA serialization and request payloads.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
descope/management/sso_settings.py	Adds FGA mapping types + serialization and includes them in SSO configure request bodies.
descope/__init__.py	Exposes the new FGA mapping types in the public package exports.
tests/management/test_sso_settings.py	Adds/updates tests validating FGA mapping serialization and request JSON payloads.

Comments suppressed due to low confidence (2)

descope/management/sso_settings.py:154

• SSOSAMLSettings.__init__ adds new optional parameters before the existing migration override parameters (sp_acs_url, sp_entity_id). This changes the positional-argument order and can break existing callers that instantiate SSOSAMLSettings positionally (their old sp_acs_url value would be interpreted as fga_mappings, etc.). To preserve backward compatibility, append the new parameters after the existing ones (or otherwise keep the original positional ordering).

    def __init__(
        self,
        idp_url: str,
        idp_entity_id: str,
        idp_cert: str,
        attribute_mapping: Optional[AttributeMapping] = None,
        role_mappings: Optional[List[RoleMapping]] = None,
        default_sso_roles: Optional[List[str]] = None,
        idp_additional_certs: Optional[List[str]] = None,
        groups_priority: Optional[List[str]] = None,  # list of group names in priority order (first = highest priority)
        fga_mappings: Optional[Dict[str, FGAGroupMapping]] = None,  # map of IDP group name -> FGA relations
        config_fga_tenant_id_resource_prefix: Optional[str] = None,
        config_fga_tenant_id_resource_suffix: Optional[str] = None,
        # NOTICE - the following fields should be overridden only in case of SSO migration, otherwise, do not modify these fields
        sp_acs_url: Optional[str] = None,
        sp_entity_id: Optional[str] = None,
    ):

descope/management/sso_settings.py:188

• SSOSAMLSettingsByMetadata.__init__ inserts new optional parameters before the migration override parameters (sp_acs_url, sp_entity_id), which changes positional-argument ordering and can break existing code that uses positional construction. Consider moving fga_mappings / config_fga_tenant_id_resource_prefix / config_fga_tenant_id_resource_suffix after the existing parameters to keep positional compatibility.

    def __init__(
        self,
        idp_metadata_url: str,
        attribute_mapping: Optional[AttributeMapping] = None,
        role_mappings: Optional[List[RoleMapping]] = None,
        default_sso_roles: Optional[List[str]] = None,
        groups_priority: Optional[List[str]] = None,  # list of group names in priority order (first = highest priority)
        fga_mappings: Optional[Dict[str, FGAGroupMapping]] = None,  # map of IDP group name -> FGA relations
        config_fga_tenant_id_resource_prefix: Optional[str] = None,
        config_fga_tenant_id_resource_suffix: Optional[str] = None,
        # NOTICE - the following fields should be overridden only in case of SSO migration, otherwise, do not modify these fields
        sp_acs_url: Optional[str] = None,
        sp_entity_id: Optional[str] = None,
    ):

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[shuni-bot-dev]

🐕 Shuni's Review

Adds FGAGroupMapping/FGAGroupMappingRelation types and wires fgaMappings (plus FGA tenant prefix/suffix for SAML) into the OIDC and SAML configure flows, with matching test updates.

No issues found — good bones! Wire format follows the existing camelCase pattern, edge cases (None map, empty/None relations, omitted mapping value) are handled in _fga_mappings_to_dict, and all three compose bodies + tests are kept in sync. Woof!

[github-actions]

Coverage report

The coverage rate went from 98.29% to 98.31% ⬆️

100% of new lines are covered.

Diff Coverage details (click to unfold)

descope/management/sso_settings.py

100% of new lines are covered (100% of the complete file).