docs: explain how to import organization users and SAML (#2079)

* docs: explain how to import organization users and SAML

* chore: apply suggestions from code review

* chore: format

---------

Co-authored-by: Vincent <[email protected]>

Author: aeneasr

docs/kratos/manage-identities/25_import-user-accounts-identities.mdx

@@ -634,6 +634,81 @@ Connect ID Token provider such as Google.
 }
 ```
 
+### SAML connections
+
+When importing SAML connections, the `provider` field is the SAML provider ID you set in your SAML configuration. The `subject` ID
+must be the ID of the user on the given platform. The subject should not be an email, but a fixed user ID that never changes.
+
+```json {7-20}
+{
+  "schema_id": "preset://email",
+  "traits": {
+    "email": "[email protected]"
+  },
+  "credentials": {
+    "saml": {
+      "config": {
+        "providers": [
+          {
+            "provider": "okta",
+            "subject": "12345"
+          },
+          {
+            "provider": "one-login",
+            "subject": "12345"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Organization-specific SAML and OIDC connections
+
+When importing SAML or OIDC connections that are only available for certain [organizations](../organizations/organizations.mdx)
+(for example `[email protected]`), you can use the `organization` field to specify the organization that the user belongs to.
+
+```json
+{
+  "schema_id": "preset://email",
+  "traits": {
+    "email": "[email protected]"
+  },
+  // highlight-start
+  "organization": "9ed50339-d6b9-47ef-9610-194773f3bfbf",
+  // highlight-end
+  "credentials": {
+    "saml": {
+      "config": {
+        "providers": [
+          {
+            "provider": "okta",
+            "subject": "12345",
+            // highlight-start
+            "organization": "9ed50339-d6b9-47ef-9610-194773f3bfbf"
+            // highlight-end
+          }
+        ]
+      }
+    },
+    "oidc": {
+      "config": {
+        "providers": [
+          {
+            "provider": "github",
+            "subject": "12345",
+            // highlight-start
+            "organization": "9ed50339-d6b9-47ef-9610-194773f3bfbf"
+            // highlight-end
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
 ## Bulk import identities from other providers
 
 To import multiple identities into Ory Identities, use the