diff --git a/administration/authentication/magic_link.md b/administration/authentication/magic_link.md new file mode 100644 index 0000000..f6351a3 --- /dev/null +++ b/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 + + + + 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. + + Kosli sign-in page with an email address entered and the Continue with SSO button + + + Kosli then sends you an email containing the link and asks you to check your inbox. + + Kosli prompt telling you to check your inbox for the sign-in link + + + The email contains a button to click; clicking this will sign you in to your Kosli account. + + Magic Link email from Kosli with a button to sign in + + diff --git a/administration/authentication/single_sign_on.md b/administration/authentication/single_sign_on.md new file mode 100644 index 0000000..e58992b --- /dev/null +++ b/administration/authentication/single_sign_on.md @@ -0,0 +1,47 @@ +--- +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. + + + + 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. + + + 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. + + + + 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. + + + The Identity Provider (IdP) Selection step of the wizard, with a search box and cards for OKTA, Azure Entra ID, Keycloak, and Auth0. + + + + 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, including: + + - **Client ID** from your IdP's application registration + - **Client Secret** from your IdP's application registration + + + 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. + + + + 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. + + diff --git a/administration/managing_users/automated_user_provisioning.md b/administration/managing_users/automated_user_provisioning.md new file mode 100644 index 0000000..c42cc2f --- /dev/null +++ b/administration/managing_users/automated_user_provisioning.md @@ -0,0 +1,110 @@ +--- +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 the Kosli platform. + +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. + + +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. + + + + + Open the link from your Customer Success representative and select the **SCIM Configuration** box on the + first screen. + + + Start page for the SSO and SCIM setup suite wizard + + + + The wizard then guides you through setting up and configuring the application, with screenshots at each + stage. + + + 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. + + + Once your users are in the right groups and you have triggered a provisioning cycle, changes to your users + within the IdP are reflected in Kosli. + + + +## Timeliness + +Once changes within your IdP have been synced, they are typically reflected in Kosli within five minutes. + +## 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 moves until your IdP sends a change. + +From then on, 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--`, 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 + + + + 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. + + + Follow the instructions on the tab, mapping each of your IdP groups to the corresponding role. + + + Section in the SSO Setup Suite Wizard showing how to configure mapping of IdP groups to Kosli roles + + + + Click through to the **Testing** page and save the configuration. + + + + +Once a user has been provisioned through SCIM, your IdP is authoritative for that user: their roles can no +longer be changed in Kosli, so every later role change has to be made through their IdP group membership. + diff --git a/administration/managing_users/roles_in_kosli.md b/administration/managing_users/roles_in_kosli.md index cda1d22..f25230b 100644 --- a/administration/managing_users/roles_in_kosli.md +++ b/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 + +This procedure does not apply to users provisioned through [automated user provisioning](/administration/managing_users/automated_user_provisioning) — their roles cannot be changed in Kosli. Manage those roles through your identity provider groups instead. + + To assign or change a user's role: 1. Log in to Kosli as an Admin diff --git a/config/navigation.json b/config/navigation.json index e680d77..b2e7574 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -47,14 +47,17 @@ "pages": [ "administration/authentication/api_authentication_methods", "administration/authentication/service_accounts", - "administration/authentication/api_key_rotation" + "administration/authentication/api_key_rotation", + "administration/authentication/single_sign_on", + "administration/authentication/magic_link" ] }, { "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" ] }, { diff --git a/getting_started/authenticating_to_kosli.md b/getting_started/authenticating_to_kosli.md index 417e022..1bb1fc6 100644 --- a/getting_started/authenticating_to_kosli.md +++ b/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](/administration/authentication/single_sign_on) or [Magic Link](/administration/authentication/magic_link). - **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. diff --git a/images/administration/add-sso.png b/images/administration/add-sso.png new file mode 100644 index 0000000..264b85e Binary files /dev/null and b/images/administration/add-sso.png differ diff --git a/images/administration/magic-link-check-email.png b/images/administration/magic-link-check-email.png new file mode 100644 index 0000000..b541f31 Binary files /dev/null and b/images/administration/magic-link-check-email.png differ diff --git a/images/administration/magic-link-email.png b/images/administration/magic-link-email.png new file mode 100644 index 0000000..662dd15 Binary files /dev/null and b/images/administration/magic-link-email.png differ diff --git a/images/administration/magic-link-enter-email.png b/images/administration/magic-link-enter-email.png new file mode 100644 index 0000000..68d6657 Binary files /dev/null and b/images/administration/magic-link-enter-email.png differ diff --git a/images/administration/scim-group-role-mapping.png b/images/administration/scim-group-role-mapping.png new file mode 100644 index 0000000..bf7d587 Binary files /dev/null and b/images/administration/scim-group-role-mapping.png differ diff --git a/images/administration/scim-setup-wizard.png b/images/administration/scim-setup-wizard.png new file mode 100644 index 0000000..d43845a Binary files /dev/null and b/images/administration/scim-setup-wizard.png differ diff --git a/images/administration/select-idp.png b/images/administration/select-idp.png new file mode 100644 index 0000000..7970c69 Binary files /dev/null and b/images/administration/select-idp.png differ diff --git a/images/administration/sso-setup-suite.png b/images/administration/sso-setup-suite.png new file mode 100644 index 0000000..d02434a Binary files /dev/null and b/images/administration/sso-setup-suite.png differ