Skip to content
Dashboard
Theme
Theme

Import CSV and SAML metadata

Import a bounded archive of home-grown SAML connections through the migration engine.

View Markdown

Use the csv_saml backend source when your configuration is a CSV plus SAML metadata files. This imports configuration through the existing engine; it does not import passwords or establish users’ subjects. Application callback forwarding remains a separate migration lever.

Create a ZIP containing connections.csv and flat named metadata XML files. Use an upload with purpose: csv_saml and its exact size_bytes, then send POST /v1/imports with source: csv_saml and bundle_upload_id. The upload must belong to the same environment, be unexpired and unconsumed. Upload consumption and import-plan creation are atomic; the worker uses the frozen bytes.

The ZIP upload is at most 16 MiB. The CSV is UTF-8 and RFC 4180, at most 5 MiB and 10,000 rows. Nested paths and arbitrary archive entries are refused; metadata filenames must be flat XML names. Do not include secrets or unrelated files.

Required CSV column Meaning
organization_external_id Stable external organization identifier.
organization_name Organization display name.
domains Semicolon-separated routing domains; verification is still required.
name_id_format Supported SAML NameID format.
attribute_email Email attribute selector.
attribute_first_name First-name attribute selector.
attribute_last_name Last-name attribute selector.
attribute_groups Group attribute selector.

Include metadata_file or metadata_url in the header. Each row must select exactly one source: an XML file from the archive or a public HTTPS metadata URL. Unknown or duplicate headers are refused. Metadata uses the hardened SAML parser; DTDs, entities, malformed and oversized documents are refused. URL fetching uses checked public addresses and no redirects. An archive names at most 100 distinct metadata URLs, each fetched once; the 101st distinct URL refuses the archive before it is fetched. The whole CSV read is bounded to 50 seconds.

Diagnostics identify physical CSV line numbers and finite fields/reasons without echoing cell values. Resolve refused rows and plan blockers before running. Formula-like values are never evaluated; do not treat a CSV export as executable spreadsheet content.

Imported connections are inactive and untested. Domain verification, a fresh successful test and activation remain required. Standard attribute selectors read only the verified assertion. Unsupported binding or NameID settings remain draft blockers, rather than producing a working sign-in by guessing.

Only one Auth0 or CSV SAML import can be planned or running per environment, adapter imports are limited to 20 per hour, and an inline bundle is refused: see limits on adapter imports.

Follow cutover and rollback and imported-profile limits. The CLI source interface is separate work; this page documents only the merged backend contract.