audit-trail(add): iam authentication methods (#5589)

Author: nerda-codes

menu/navigation.json

@@ -3763,6 +3763,10 @@
                     "label": "Audit Trail product integration",
                     "slug": "resource-integration-with-adt"
                   },
+                  {
+                    "label": "IAM authentication events in Audit Trail",
+                    "slug": "iam-authentication-events"
+                  },
                   {
                     "label": "Supported endpoints for Audit Trail",
                     "slug": "adt-supported-endpoints"

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

@@ -0,0 +1,91 @@
+---
+title: IAM authentication events in Audit Trail
+description: Discover which IAM events are logged in Audit Trail and what they mean.
+tags: audit-trail iam-authentication iam-logs authentication-logs
+dates:
+  validation: 2025-10-01
+  posted: 2025-10-01
+---
+
+This page explains how to differentiate IAM members authentication methods and understand and how they appear in Audit Trail.
+
+This page only covers **Unauthenticated API** methods that actually perform and/or complete an authentication step.
+
+## 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 code received.
+
+If multifactor authentication (MFA) is required, the flow proceeds to `CheckLoginMFAOTP`. Otherwise, the flow redirects to `CommitLogin`.
+
+
+## Password login
+
+This method allows you to authenticate 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`.
+
+
+
+## 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`.
+
+
+## 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 accounts via an Identity Provider (IdP).
+
+- `InitiateSamlLogin`
+  Starts the SAML login and redirects the user to the IdP.
+
+- `CreateSamlLogin`
+  Finalizes authentication once the SAML response is received and validated.
+
+As with the other methods, if MFA is required, `CheckLoginMFAOTP` is triggered before committing the login. Otherwise, the flow continues to `CommitLogin`.
+
+## 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).
+
+- `RenewJWT`
+  Exchanges a valid login session/refresh context for a new JWT without re-authenticating credentials. JWTs are valid for 1 hour. If a member refreshes the Scaleway console or performs actions more than 1 hour after the last creation or update of a JWT, the JWT will be renewed.
+
+
+## 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**      | Redirects the user to the SAML IdP.                              | SAML login               |
+| **CreateSamlLogin**        | Finalizes login after SAML response validation.                  | SAML login               |
+| **CheckLoginMFAOTP**       | Validates MFA OTP when required.                                 | All flows (if MFA)       |
+| **CommitLogin**            | Commits login and issues the JWT.                                | All flows                |
+| **RenewJWT**               | Renews the JWT without full re-authentication.                   | Session maintenance      |
+
+