diff --git a/docs.kosli.com/assets/_custom.scss b/docs.kosli.com/assets/_custom.scss index 7b91068d3..f92c61429 100644 --- a/docs.kosli.com/assets/_custom.scss +++ b/docs.kosli.com/assets/_custom.scss @@ -44,7 +44,7 @@ aside.book-toc .book-toc-content { .markdown { display: flex; flex-direction: column; - justify-content: space-between; + justify-content: flex-start; flex-grow: 1; } @@ -98,10 +98,10 @@ aside.book-toc .book-toc-content { color: $neutral-100; .container { - .docs-logo { + .docs-logo { width: 16rem; - - + + a { margin: 1rem 0; padding: 0 1rem; @@ -160,12 +160,12 @@ aside.book-toc .book-toc-content { width: 24px; background-image: url("/images/icons/kosli-icon-copy.svg"); background-repeat: no-repeat; - } + } &:hover::after { - background-image: url("/images/icons/kosli-icon-copy-hover.svg"); + background-image: url("/images/icons/kosli-icon-copy-hover.svg"); } &:active::after { - background-image: url("/images/icons/kosli-icon-copy-clicked.svg"); + background-image: url("/images/icons/kosli-icon-copy-clicked.svg"); } &:hover code { opacity: 0.7; @@ -197,3 +197,9 @@ aside.book-toc .book-toc-content { .footer-logo { height: 40px; } + +.markdown h2 { + margin-top: 0.5em; + margin-bottom: 0.5em; +} + diff --git a/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/_index.md b/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/_index.md new file mode 100644 index 000000000..ced07e394 --- /dev/null +++ b/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/_index.md @@ -0,0 +1,14 @@ +--- +title: "SSO Configuration" +bookCollapseSection: true +weight: 100 +summary: "Configure Single Sign-On (SSO) for your Kosli organization." +--- + +# SSO Configuration + +Kosli supports Single Sign-On (SSO) integration with popular identity providers (IdPs) such as Microsoft Entra ID and Okta. This allows users to authenticate using their existing organizational credentials, enhancing security and simplifying access management. + +Secrets such as Client Secrets must be shared securely with Kosli to complete the SSO setup. See [Sharing Secrets Securely]({{< relref "sharing_secrets_securely" >}}) for recommended methods. + +## Subpages \ No newline at end of file diff --git a/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration.md b/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/entra_id_setup.md similarity index 87% rename from docs.kosli.com/content/implementation_guide/phase_2/sso_configuration.md rename to docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/entra_id_setup.md index a55ec3ddc..2d4a8fcb4 100644 --- a/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration.md +++ b/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/entra_id_setup.md @@ -1,5 +1,5 @@ --- -title: "SSO Configuration" +title: "Microsoft Entra ID Setup" bookCollapseSection: false weight: 200 summary: "Step-by-step guide for configuring Single Sign-On (SSO) with Microsoft Entra ID for your Kosli organization." @@ -55,6 +55,7 @@ Make sure to assign the necessary user and group assignments to the application {{% /hint %}} ### 3. Share details with Kosli Securely + Please share details below securely in order for Kosli to complete SSO setup.
``` @@ -63,7 +64,7 @@ Directory (tenant) ID: 11111111-2222-3333-4444-555555555555 Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Client Secret Expiration Date: 1999-12-31 (format: yyyy-mm-dd) ``` -See [Securely share secrets with Kosli](#securely-share-secrets-with-kosli). +See [Sharing Secrets Securely with Kosli]({{< relref "sharing_secrets_securely" >}}). ## Update or Rotate the Client Secret @@ -92,22 +93,7 @@ Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Client Secret Expiration Date: 1999-12-31 (format: yyyy-mm-dd) ``` -See [Securely share secrets with Kosli]({{< ref "#securely-share-secrets-with-kosli" >}}). - -## Securely share secrets with Kosli - -For securely sharing your secrets with Kosli, we recommend using one of the following services: - -* **Onetime Secret:** https://eu.onetimesecret.com -* **Yopass:** https://yopass.se - -After encrypting the secret and generating the link, please email the link to support@kosli.com or your Kosli contact, so we can finalize the SSO registration process. - -{{% hint warning %}} -**Important:** -The expiration for this must be set to a minimum of 7 days to allow Kosli to process it correctly. -{{% /hint %}} - +See [Sharing Secrets Securely with Kosli]({{< relref "sharing_secrets_securely" >}}). ## Troubleshooting @@ -136,8 +122,8 @@ Check the following common issues: - **Invalid Application ID, Directory ID, or Client Secret** - Verify that the values provided to Kosli are correct and correspond to those in your Microsoft Entra ID app registration. - **Expired Client Secret** - - Ensure that the Client Secret provided to Kosli is still valid and has not expired - - If it has expired, follow the [Update or Rotate the Client Secret]({{< ref "#update-or-rotate-the-client-secret" >}}) steps to create a new client + - Ensure that the Client Secret provided to Kosli is still valid and has not expired. + - If it has expired, follow the [Update or Rotate the Client Secret]({{< ref "#update-or-rotate-the-client-secret" >}}) steps to create a new client. - **User and Group Assignments** - Ensure that the necessary user and group assignments have been made to the application in Microsoft Entra ID so that users can access Kosli via SSO. diff --git a/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/okta_setup.md b/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/okta_setup.md new file mode 100644 index 000000000..f796e7695 --- /dev/null +++ b/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/okta_setup.md @@ -0,0 +1,86 @@ +--- +title: "Okta Setup" +bookCollapseSection: false +weight: 300 +summary: "Step-by-step guide for configuring Single Sign-On (SSO) with Okta for your Kosli organization." +--- + +# Okta Setup for SSO + +For Single Sign-On (SSO) integration between Okta and Kosli, you can choose and follow the steps outlined in one of the two methods provided below: + +- [Create a new App integration](#create-a-new-app-integration) +- [Update or Rotate the Client Secret](#update-or-rotate-the-client-secret) + +## Prerequisites + +To begin the setup process, ensure that you: + +- Are logged into the Okta Admin Console at https://admin.okta.com/ +- Possess the necessary permissions to create a new application within Okta. + +## Create a new App integration + +### 1. Create the App Integration +Follow the official Okta documentation to create a new OIDC app integration, with the following settings: + +- **Application type:** Web Application +- **Sign-in redirect URIs:** https://api.userfront.com/v0/auth/okta/login + +### 2. Create a Client Secret + +Follow the official Okta documentation to create a Client Secret for your newly created app integration. + +## 3. Share details with Kosli Securely +Please share details below securely in order for Kosli to complete SSO setup.
+ +``` +Okta client ID: abcdefghijklmnopqrst +Okta domain: mycompany.okta.com +Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +Client Secret Expiration Date: 1999-12-31 (format: yyyy-mm-dd) +``` +See [Sharing Secrets Securely with Kosli]({{< relref "sharing_secrets_securely" >}}). + +## Update or Rotate the Client Secret + +To prevent downtime, we advise rotating your secrets safely and well in advance of their expiration date. This allows us to manage the update process smoothly. + +### 1. Create a New Client Secret + +Follow the official Okta documentation to create a new Client Secret for your existing app integration. + +### 2. Share new Client Secret with Kosli Securely +Please share the new Client Secret securely with Kosli. + +``` +Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +Client Secret Expiration Date: 1999-12-31 (format: yyyy-mm-dd) +``` + +See [Sharing Secrets Securely with Kosli]({{< relref "sharing_secrets_securely" >}}). + +## Troubleshooting + +Once Kosli have confirmed the SSO setup, once you log in to Kosli, you should be redirected to the Okta login page. + +### Common Issues + +#### Problem: Unable to log in via SSO + +Check the following common issues: + +- **Wrong Redirect URI** + - Ensure that the Redirect URI in your Okta app integration matches `https://api.userfront.com/v0/auth/okta/login`. +- **Invalid Client ID or Client Secret** + - Verify that the values provided to Kosli are correct and correspond to those in your Okta app integration. +- **Expired Client Secret** + - Ensure that the Client Secret provided to Kosli is still valid and has not expired. + - If it has expired, follow the [Update or Rotate the Client Secret]({{< ref "#update-or-rotate-the-client-secret" >}}) steps to create a new client. + +## References + +### Okta Documentation + +- [Create OpenID Connect app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) +- [Manage secrets and keys for OIDC app client authentication](https://help.okta.com/oie/en-us/content/topics/apps/oauth-client-cred-mgmt.htm) \ No newline at end of file diff --git a/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/sharing_secrets_securely.md b/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/sharing_secrets_securely.md new file mode 100644 index 000000000..f3319a31c --- /dev/null +++ b/docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/sharing_secrets_securely.md @@ -0,0 +1,24 @@ +--- +title: "Sharing Secrets Securely" +bookCollapseSection: false +weight: 400 +summary: "How to securely share secrets with Kosli during Single Sign-On (SSO) configuration." +--- + +# Sharing Secrets Securely + +For securely sharing your secrets with Kosli, we recommend using one of the following services: + +- **Onetime Secret:** https://eu.onetimesecret.com +- **Yopass:** https://yopass.se + +If your organization uses a different secret management tool that allows you to generate an access link, you can use that as well. + +After encrypting the secret and generating the link, please email the link to support@kosli.com or your Kosli contact, so we can finalize the SSO registration process. + +{{% hint warning %}} +**Important:** +- Please ensure that the expiration for this must be set to a **minimum of 7 days** to allow Kosli to process it correctly. +- Please allow **multiple access attempts**, as Kosli may need to access the secret more than once during the setup process. +- Kosli will only access the secret for the purpose of completing the SSO setup and will not store or share it beyond this use case. +{{% /hint %}}