# Import CSV and SAML metadata

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](/migrate/from-home-grown-saml/) remains a separate migration lever.

## Prepare a closed archive

Create a ZIP containing `connections.csv` and flat named metadata XML files. Use an [upload](/reference/api/management/) 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.

## Inspect before running

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](/migrate/from-auth0/#limits-on-adapter-imports).

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