From b5680e860abff08889a9a0f79c9a839cd58ec0f5 Mon Sep 17 00:00:00 2001 From: Graham Savage Date: Tue, 15 Sep 2026 09:25:59 +0100 Subject: [PATCH 1/2] docs: add a GitHub sign-in page with the IP allow list addresses GitHub was the only sign-in method with no page of its own; the single FAQ entry covered just the verified-email requirement. A customer whose GitHub organization enforces an IP allow list could not sign in, because Descope, Kosli's identity provider, completes the OAuth exchange with GitHub from a fixed set of IP addresses that GitHub rejected. Add administration/authentication/github_login under Authentication & access, alongside single sign-on and Magic Link. It covers the verified-email requirement, the sign-in steps, and the Descope Project Static IPs to allow, split by Kosli instance: app.kosli.com uses the EU set and app.us.kosli.com uses the US set. The FAQ entry and the getting-started authentication page now link to it. Co-Authored-By: Claude Fable 5.1 --- administration/authentication/github_login.md | 62 +++++++++++++++++++ config/navigation.json | 1 + faq/faq.md | 2 + getting_started/authenticating_to_kosli.md | 3 +- 4 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 administration/authentication/github_login.md diff --git a/administration/authentication/github_login.md b/administration/authentication/github_login.md new file mode 100644 index 00000000..d27682f2 --- /dev/null +++ b/administration/authentication/github_login.md @@ -0,0 +1,62 @@ +--- +title: GitHub sign-in +description: "Sign in to Kosli with a GitHub account, and allow Kosli's sign-in traffic through a GitHub IP allow list." +icon: "github" +--- + +Kosli supports signing in with a GitHub account. If your organization uses an identity provider, +[single sign-on](/administration/authentication/single_sign_on) is the alternative, and +[Magic Link](/administration/authentication/magic_link) works without one. + +## Before you begin + +Your GitHub account must have a verified email address, otherwise sign-in fails. Check the status of +your email addresses at [github.com/settings/emails](https://github.com/settings/emails). + +## Sign in with GitHub + + + + Open the Kosli web app for your region: + + - EU: [app.kosli.com](https://app.kosli.com) + - US: [app.us.kosli.com](https://app.us.kosli.com) + + + Select the GitHub option on the sign-in page. GitHub asks you to authorize Kosli the first time + you sign in. + + + Once GitHub confirms the authorization, you are signed in to Kosli. + + + +## GitHub IP allow lists + +If your GitHub organization or enterprise restricts access with an +[IP allow list](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization), +GitHub sign-in to Kosli fails until Kosli's sign-in traffic is allowed. + +Kosli uses [Descope](https://www.descope.com/) as its identity provider. After you authorize Kosli in +GitHub, Descope calls GitHub from a fixed set of IP addresses to complete the sign-in. GitHub rejects +those calls unless the addresses are on your allow list. + +Add the addresses for the Kosli instance you sign in to. Only one set is needed. + +### app.kosli.com (EU) + +- `3.72.207.40` +- `3.74.59.88` +- `3.121.31.67` + +### app.us.kosli.com (US) + +- `35.170.24.133` +- `3.212.215.29` +- `52.44.167.251` + + +These are Descope's **Project Static IPs**. Descope publishes the current list at +[Public static IPs](https://docs.descope.com/how-to-deploy-to-production/public-static-ips). If sign-in +stops working after you have added the addresses above, check that page for changes. + diff --git a/config/navigation.json b/config/navigation.json index a536cb54..321e2c47 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -47,6 +47,7 @@ "pages": [ "administration/authentication/single_sign_on", "administration/authentication/magic_link", + "administration/authentication/github_login", "administration/authentication/api_authentication_methods", "administration/authentication/service_accounts", "administration/authentication/api_key_rotation" diff --git a/faq/faq.md b/faq/faq.md index 2ad79cfa..3b8c9754 100644 --- a/faq/faq.md +++ b/faq/faq.md @@ -86,6 +86,8 @@ kosli report evidence artifact generic server:1.0 \ If you sign in to Kosli with GitHub, you must have a verified email address on your GitHub account — otherwise login will fail. You can check the status of your email addresses at [github.com/settings/emails](https://github.com/settings/emails). + +If your GitHub organization uses an IP allow list, you also need to allow Kosli's sign-in traffic. See [GitHub sign-in](/administration/authentication/github_login#github-ip-allow-lists) for the addresses to add. diff --git a/getting_started/authenticating_to_kosli.md b/getting_started/authenticating_to_kosli.md index 3bccb1f7..4a2977c3 100644 --- a/getting_started/authenticating_to_kosli.md +++ b/getting_started/authenticating_to_kosli.md @@ -26,7 +26,7 @@ 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. + Depending on how your organization is set up, you'll sign in with single sign-on, [Magic Link](/administration/authentication/magic_link) or [GitHub](/administration/authentication/github_login). - **For CI/CD**, follow [Service accounts](/administration/authentication/service_accounts) to create a service account and generate its first API key. @@ -52,6 +52,7 @@ For CLI usage, basic auth, and full examples, see [API authentication methods](/ - [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. +- [GitHub sign-in](/administration/authentication/github_login) — sign in with a GitHub account, including GitHub IP allow lists. - [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. From 8c82eb4b2376c43e8809fc739542eb4ba6422011 Mon Sep 17 00:00:00 2001 From: Graham Savage Date: Tue, 15 Sep 2026 09:42:57 +0100 Subject: [PATCH 2/2] docs: fix name of GitHub signin button Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> --- administration/authentication/github_login.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/administration/authentication/github_login.md b/administration/authentication/github_login.md index d27682f2..54402684 100644 --- a/administration/authentication/github_login.md +++ b/administration/authentication/github_login.md @@ -23,8 +23,8 @@ your email addresses at [github.com/settings/emails](https://github.com/settings - US: [app.us.kosli.com](https://app.us.kosli.com) - Select the GitHub option on the sign-in page. GitHub asks you to authorize Kosli the first time - you sign in. + Select **Continue with GitHub** on the sign-in page. GitHub asks you to authorize Kosli the + first time you sign in. Once GitHub confirms the authorization, you are signed in to Kosli.