feat: add SSO, SCIM and Magic Link documentation

administration/authentication/magic_link.md

@@ -0,0 +1,31 @@
+---
+title: Magic Link
+description: "Learn about signing in to Kosli with Magic Link."
+icon: "wand-magic-sparkles"
+---
+
+Magic Link is a way of signing into Kosli without needing to set up [single sign-on](/administration/authentication/single_sign_on). When you want to sign in, Kosli emails you a link, and clicking that link signs you in.
+
+## Enabling Magic Link
+
+To use Magic Link with your company email, email [support@kosli.com](mailto:support@kosli.com) and we'll enable it for your email domain.
+
+## Using Magic Link
+
+<Steps>
+  <Step title="Enter your email address">
+    Once Magic Link is enabled for your domain, enter your email address on the Kosli sign-in page and select **Continue with SSO** — the same button is used for Magic Link sign-in.
+
+    <Frame><img src="/images/administration/magic-link-enter-email.png" alt="Kosli sign-in page with an email address entered and the Continue with SSO button" /></Frame>
+  </Step>
+  <Step title="Check your inbox">
+    Kosli then sends you an email containing the link and asks you to check your inbox.
+
+    <Frame><img src="/images/administration/magic-link-check-email.png" alt="Kosli prompt telling you to check your inbox for the sign-in link" /></Frame>
+  </Step>
+  <Step title="Click to sign in">
+    The email contains a button to click; clicking this will sign you in to your Kosli account.
+
+    <Frame><img src="/images/administration/magic-link-email.png" alt="Magic Link email from Kosli with a button to sign in" /></Frame>
+  </Step>
+</Steps>

administration/authentication/single_sign_on.md

@@ -0,0 +1,44 @@
+---
+title: Single sign-on
+description: "Learn about configuring single sign-on with Kosli"
+icon: "key"
+---
+
+Kosli supports signing in using your identity provider, via single sign-on (SSO). If you don't use an identity provider, [Magic Link](/administration/authentication/magic_link) is an alternative way to sign in.
+
+## Enabling single sign-on
+
+When you are ready for your organization to access Kosli using single sign-on, your IT team will need to configure a new SSO connection. It's done through a self-service setup wizard to make this as straightforward as possible.
+
+Your Kosli Customer Success representative will provide you with a custom direct link to your personalized SSO setup wizard.
+
+## Step by step
+
+Before you begin, you will need access to your Identity Provider (IdP) — such as Azure Entra ID, Okta, or Google Workspace — with permissions to create or modify application registrations and SSO configurations.
+
+<Steps>
+  <Step title="Review current status">
+    Open the link provided by Kosli. The wizard will display the current state of your SSO connection. If no connection exists yet, you'll see an option to add one.
+
+    <Frame>
+      <img src="/images/administration/add-sso.png" alt="The SSO setup wizard welcome screen, showing an SSO Configuration card with an Add button, and grayed-out SSO Mapping and SSO Testing options under Advanced." />
+    </Frame>
+  </Step>
+  <Step title="Select your identity provider">
+    Click **+ Add**, then select your IdP from the list (for example, Okta, Azure Entra ID, Keycloak, or Auth0). Select **OIDC** if there is a choice. The exception is Okta: its SCIM integration only works with a SAML connection, so select **SAML** if you use Okta and expect to add [SCIM provisioning](/administration/managing_users/automated_user_provisioning) — choosing OIDC now means recreating the connection later.
+
+    <Frame>
+      <img src="/images/administration/select-idp.png" alt="The Identity Provider (IdP) Selection step of the wizard, with a search box and cards for OKTA, Azure Entra ID, Keycloak, and Auth0." />
+    </Frame>
+  </Step>
+  <Step title="Configure the connection">
+    The wizard will guide you through the setup process with screenshots specific to your IdP. You'll be asked to copy and paste values between your IdP and the wizard.  For an OIDC connection these are the Client ID and Client Secret from your IdP's application registration; for a SAML connection the wizard asks for your IdP's metadata instead.
+
+    <Frame>
+      <img src="/images/administration/sso-setup-suite.png" alt="Step 2 of 6 of the wizard, Identity Provider Information and User Attribute Mapping, with Client ID and Client Secret fields and a screenshot showing where to find those values in Okta." />
+    </Frame>
+  </Step>
+  <Step title="Notify Kosli">
+    Once you have completed the SSO configuration in the wizard, please let your Kosli Customer Success representative know. We will then switch your email domain to use SSO and confirm when the migration is complete.
+  </Step>
+</Steps>

administration/managing_users/automated_user_provisioning.md

@@ -0,0 +1,112 @@
+---
+title: Automated user provisioning
+description: "Learn about configuring automated user provisioning (SCIM) with Kosli."
+---
+
+Kosli supports SCIM provisioning and deprovisioning of users. This feature allows users to be added to Kosli by assigning them to the Kosli application within your Identity Provider (IdP). This page explains how to get started.
+
+## Benefits
+
+User provisioning within your IdP simplifies the process of granting access to Kosli; you no longer need to explicitly invite people one-by-one. Your existing processes and procedures for onboarding team members can now be leveraged to give access to Kosli.
+
+User deprovisioning within your IdP means that when your people no longer need access to Kosli, for example because they have changed roles or left your organization, their access to Kosli is revoked automatically.
+
+## Prerequisites
+
+Before configuring SCIM, make sure that:
+
+- **[Single sign-on](/administration/authentication/single_sign_on) is already configured.** SCIM builds on your
+  existing SSO connection, and IdP groups are mapped to Kosli roles in the SSO part of the same wizard.
+- **SCIM is enabled for your Kosli organizations.** Tell your Kosli Customer Success representative which
+  organizations you want SCIM for, so that the matching roles can be created — see
+  [Roles for new and existing users](#roles-for-new-and-existing-users) below.
+- **You have a link to the setup wizard.** Your Customer Success representative provides one with instructions
+  for your IdP, which you can pass on to the team that will do the work.
+- **That team can administer your IdP.** They need permissions to create or modify application registrations,
+  and to manage the groups you map to Kosli roles.
+
+## Setup
+
+The team that manages your IdP configures the connection between your IdP and Kosli's auth provider. Because
+different IdPs need different configuration, the wizard gives step-by-step instructions specific to yours.
+
+<Note>
+Adding SCIM does not normally require any change to your existing SSO connection. The exception is Okta over
+OIDC: Okta's SCIM integration only works with a SAML connection, so an Okta OIDC connection has to be recreated
+using SAML before SCIM can be enabled. If you are not sure which your IdP uses, ask your Kosli Customer Success
+representative.
+</Note>
+
+<Steps>
+  <Step title="Open the wizard and select SCIM Configuration">
+    Open the link from your Customer Success representative and select the **SCIM Configuration** box on the
+    first screen.
+
+    <Frame>
+      <img src="/images/administration/scim-setup-wizard.png" alt="Start page for the SSO and SCIM setup suite wizard" />
+    </Frame>
+  </Step>
+  <Step title="Follow the wizard">
+    The wizard then guides you through setting up and configuring the application, with screenshots at each
+    stage.
+  </Step>
+  <Step title="Create your IdP groups and add your users">
+    Create a group in your IdP for each Kosli organization and role you need, then add your users to them. See
+    [Roles for new and existing users](#roles-for-new-and-existing-users) for the group naming scheme, and for
+    how to map those groups to Kosli roles.
+  </Step>
+  <Step title="Trigger a provisioning cycle">
+    Once your users are in the right groups and you have triggered a provisioning cycle within your IdP,
+    changes to your users within the IdP are reflected in Kosli.
+  </Step>
+</Steps>
+
+## Timeliness
+
+How quickly a change reaches Kosli depends on your IdP's provisioning schedule, which you configure there — some IdPs sync on a fixed interval rather than immediately. Once your IdP has sent the change, it is typically reflected in Kosli within five minutes. To apply a change straight away, trigger a sync in your IdP.
+
+## Existing Kosli users
+
+People who already have access to Kosli via SSO keep that access. Enabling SCIM does not, by itself, change
+anyone's roles or organization memberships. Nothing in Kosli changes until your IdP sends a change. A user who
+is not assigned to any Kosli group is not provisioned or deprovisioned and their existing access is untouched
+until you add them to a group.
+
+Once SCIM has started sending changes, your IdP drives membership. Once a user has been provisioned through SCIM,
+the groups they belong to in your IdP determine their organizations and roles in Kosli, replacing whatever they had before.
+
+That makes the first sync worth planning. A full or forced sync in your IdP — however it is labeled there —
+provisions every assigned user at once, not only the ones you have just changed, so make sure your groups and
+[role mappings](#map-your-idp-groups-to-kosli-roles) are correct before you trigger one.
+
+## Roles for new and existing users
+
+Kosli supports role assignment through your IdP, so that users' [roles within Kosli](/administration/managing_users/roles_in_kosli) can be managed by your onboarding and IT teams, without requiring admin access to Kosli.
+
+You will need to tell us which of your Kosli organizations you wish to have SCIM enabled for; we will then create the necessary roles within our auth provider. Each organization will have four roles, with the names `kosli-<org-name>-<role>`, to correspond to the available roles in Kosli (admin, member, snapshotter, reader).
+
+Within your IdP you will need to create a group for each of these roles. You will then add your users to the groups corresponding to the organizations/roles you wish them to have in Kosli. If a member receives two different roles for the same organization, the highest-privilege role will be assigned.
+
+### Map your IdP groups to Kosli roles
+
+<Steps>
+  <Step title="Switch to the SSO Configuration wizard">
+    Group mapping is done in **SSO Configuration**, not in the SCIM configuration you used to set up
+    provisioning. Open **SSO Configuration** and go to the **Group Attribute Mapping** tab.
+  </Step>
+  <Step title="Map each group to its Kosli role">
+    Follow the instructions on the tab, mapping each of your IdP groups to the corresponding role.
+
+    <Frame>
+      <img src="/images/administration/scim-group-role-mapping.png" alt="Section in the SSO Setup Suite Wizard showing how to configure mapping of IdP groups to Kosli roles" />
+    </Frame>
+  </Step>
+  <Step title="Save the configuration">
+    Click through to the **Testing** page and save the configuration.
+  </Step>
+</Steps>
+
+<Note>
+Once a user has been provisioned through SCIM, your IdP is authoritative for that user: neither their roles nor
+their membership of your Kosli organizations can be changed in Kosli, so every later change has to be made through their IdP group membership.
+</Note>

administration/managing_users/roles_in_kosli.md

@@ -188,6 +188,10 @@ The following sections provide more details about each Kosli user role, includin
 
 ## Assigning roles
 
+<Note>
+This procedure does not apply to users provisioned through [automated user provisioning](/administration/managing_users/automated_user_provisioning) - their roles, and their membership of the organization, cannot be changed in Kosli. Manage those through your identity provider groups instead.
+</Note>
+
 To assign or change a user's role:
 
 1. Log in to Kosli as an Admin

config/navigation.json

@@ -45,6 +45,8 @@
             {
               "group": "Authentication & access",
               "pages": [
+                "administration/authentication/single_sign_on",
+                "administration/authentication/magic_link",
                 "administration/authentication/api_authentication_methods",
                 "administration/authentication/service_accounts",
                 "administration/authentication/api_key_rotation"
@@ -54,7 +56,8 @@
               "group": "Users & roles",
               "pages": [
                 "administration/managing_users/roles_in_kosli",
-                "administration/managing_users/mapping_users_to_roles"
+                "administration/managing_users/mapping_users_to_roles",
+                "administration/managing_users/automated_user_provisioning"
               ]
             },
             {

getting_started/authenticating_to_kosli.md

@@ -25,6 +25,8 @@ For anything automated, use a service account. Personal API keys inherit your us
 
     - EU: [app.kosli.com](https://app.kosli.com)
     - US: [app.us.kosli.com](https://app.us.kosli.com)
+
+    Depending on how your organization is set up, you'll sign in with single sign-on, [Magic Link](/administration/authentication/magic_link) or GitHub.
   </Step>
   <Step title="Create a key">
     - **For CI/CD**, follow [Service accounts](/administration/authentication/service_accounts) to create a service account and generate its first API key.
@@ -48,6 +50,8 @@ For CLI usage, basic auth, and full examples, see [API authentication methods](/
 
 ## See also
 
+- [Single sign-on](/administration/authentication/single_sign_on) — configure sign-in through your identity provider.
+- [Magic Link](/administration/authentication/magic_link) — sign in with an emailed link, without an identity provider.
 - [Service accounts](/administration/authentication/service_accounts) — admin lifecycle for machine credentials.
 - [API key rotation](/administration/authentication/api_key_rotation) — how rotation works, with a [step-by-step tutorial](/tutorials/rotating_api_keys).
 - [Roles in Kosli](/administration/managing_users/roles_in_kosli) — what users and service accounts can do at each role.