docs(add): saml and auth methods

Author: nerda-codes

pages/audit-trail/reference-content/iam-authentication-logs.mdx

@@ -7,5 +7,106 @@ dates:
   posted: 2025-09-30
 ---
 
-This page explains how to differentiate IAM member login methods and understand what is logged whenever you log in as an IAM member.
+This page explains how to differentiate IAM member authentication methods and understand and how they appear in Audit Trail.
+
+
+## 1. Authentication code login
+
+This flow allows a user to log in using an **authentication code** sent via email.
+
+- `InitiateMagicCodeLogin`
+  Sends the user an email containing a 6-digit authentication code.
+
+- `CreateMagicCodeLogin`
+  Authenticates the user based on their username and the 6-digit authentication codee received.
+
+If multifactor authentication (MFA) is required, the flow proceeds to `CheckLoginMFAOTP`. Otherwise, the flow redirects to `CommitLogin`.
+
+
+## 2. Password login
+
+This is the standard login method using a username and password.
+
+- `CreatePasswordLogin`
+  Authenticates the user with their username and password.
+
+If MFA is required, the system verifies it through `CheckLoginMFAOTP`. If not, the flow continues directly to `CommitLogin`.
+
+
+
+## 3. OAuth2 login
+
+This flow is based on external OAuth2 authentication providers.
+
+- `InitiateOAuth2Login`
+  Redirects the user to the external OAuth2 provider for authentication.
+
+- `CreateOAuth2Login`
+  Finalizes authentication once the OAuth2 provider confirms the user identity.
+
+As with the other methods, if MFA is required, `CheckLoginMFAOTP` is triggered before committing the login. Otherwise, the flow continues to `CommitLogin`.
+
+
+## 4. SAML login
+
+This flow integrates with **SAML (Security Assertion Markup Language)** for Single Sign-On (SSO).
+It allows you to set up identity federation on your Organization and provide your teams with secure access to their via an Identity Provider (IdP).
+
+- `InitiateSamlLogin`
+  Starts the SAML login process and redirects the user to the Identity Provider (IdP).
+
+- `CreateSamlLogin`
+  Finalizes authentication once the SAML response is received and validated.
+
+- `EnableOrganizationSaml`
+  Activates SAML authentication for the organization.
+
+- `AddSamlCertificate`
+  Adds a certificate used to validate SAML assertions.
+
+- `UpdateSaml`
+  Updates the SAML configuration for the organization.
+
+- `DeleteSaml`
+  Removes the SAML configuration for the organization.
+
+- `DeleteSamlCertificate`
+  Deletes an existing SAML certificate.
+
+- `CreateJWT`
+  Creates a JWT token after successful SAML authentication.
+
+- `DeleteJWT`
+  Deletes a previously issued JWT token.
+
+## Common steps
+
+- `CheckLoginMFAOTP`
+  Validates the Multi-Factor Authentication one-time password (OTP) if required.
+
+- `CommitLogin`
+  The final step of the login process. Transforms the authenticated session into a JWT (JSON Web Token).
+
+
+## Summary of authentication methods
+
+| Method name                | Description                                                        | Authentication flow      |
+|---------------------------|--------------------------------------------------------------------|--------------------------|
+| **InitiateMagicCodeLogin**| Sends the user an email containing a 6-digit authentication code.         | Authentication code login         |
+| **CreateMagicCodeLogin**  | Authenticates using username and the 6-digit authentication code.           | Authentication code login         |
+| **CreatePasswordLogin**   | Authenticates using username and password.                         | Password login           |
+| **InitiateOAuth2Login**   | Redirects the user to the OAuth2 provider for authentication.      | OAuth2 login             |
+| **CreateOAuth2Login**     | Finalizes authentication after OAuth2 provider confirmation.       | OAuth2 login             |
+| **InitiateSamlLogin**     | Starts the SAML login process and redirects to the IdP.            | SAML login              |
+| **CreateSamlLogin**       | Finalizes authentication after receiving SAML response.            | SAML login              |
+| **EnableOrganizationSaml**| Enables SAML authentication for the organization.                  | SAML login       |
+| **AddSamlCertificate**    | Adds a certificate to validate SAML assertions.                    | SAML login       |
+| **UpdateSaml**            | Updates SAML configuration.                                        | SAML login       |
+| **DeleteSaml**            | Deletes SAML configuration.                                        | SAML login       |
+| **DeleteSamlCertificate** | Removes a SAML certificate.                                        | SAML login      |
+| **CreateJWT**             | Issues a JWT token after successful SAML authentication.           | SAML login               |
+| **DeleteJWT**             | Deletes a previously issued JWT token.                             | SAML login               |
+| **CheckLoginMFAOTP**      | Validates the MFA one-time password if required.                   | All flows (if MFA)       |
+| **CommitLogin**           | Finalizes login and transforms the session into a JWT.             | All flows                |
+