Skip to content

Commit 31c1162

Browse files
dangrondahldangrondahl
authored
docs: add okta to sso configuration (#623)
* docs: add Okta to SSO configuration * fix: don't use the whole height on pages with little content
1 parent 2851f43 commit 31c1162

5 files changed

Lines changed: 143 additions & 27 deletions

File tree

‎docs.kosli.com/assets/_custom.scss‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ aside.book-toc .book-toc-content {
4444
.markdown {
4545
display: flex;
4646
flex-direction: column;
47-
justify-content: space-between;
47+
justify-content: flex-start;
4848
flex-grow: 1;
4949
}
5050

@@ -98,10 +98,10 @@ aside.book-toc .book-toc-content {
9898
color: $neutral-100;
9999

100100
.container {
101-
.docs-logo {
101+
.docs-logo {
102102
width: 16rem;
103-
104-
103+
104+
105105
a {
106106
margin: 1rem 0;
107107
padding: 0 1rem;
@@ -160,12 +160,12 @@ aside.book-toc .book-toc-content {
160160
width: 24px;
161161
background-image: url("/images/icons/kosli-icon-copy.svg");
162162
background-repeat: no-repeat;
163-
}
163+
}
164164
&:hover::after {
165-
background-image: url("/images/icons/kosli-icon-copy-hover.svg");
165+
background-image: url("/images/icons/kosli-icon-copy-hover.svg");
166166
}
167167
&:active::after {
168-
background-image: url("/images/icons/kosli-icon-copy-clicked.svg");
168+
background-image: url("/images/icons/kosli-icon-copy-clicked.svg");
169169
}
170170
&:hover code {
171171
opacity: 0.7;
@@ -197,3 +197,9 @@ aside.book-toc .book-toc-content {
197197
.footer-logo {
198198
height: 40px;
199199
}
200+
201+
.markdown h2 {
202+
margin-top: 0.5em;
203+
margin-bottom: 0.5em;
204+
}
205+

‎docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/_index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: "SSO Configuration"
3+
bookCollapseSection: true
4+
weight: 100
5+
summary: "Configure Single Sign-On (SSO) for your Kosli organization."
6+
---
7+
8+
# SSO Configuration
9+
10+
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.
11+
12+
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.
13+
14+
## Subpages

docs.kosli.com/content/implementation_guide/phase_2/sso_configuration.md renamed to docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/entra_id_setup.md

Lines changed: 6 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: "SSO Configuration"
2+
title: "Microsoft Entra ID Setup"
33
bookCollapseSection: false
44
weight: 200
55
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
5555
{{% /hint %}}
5656

5757
### 3. Share details with Kosli Securely
58+
5859
Please share details below securely in order for Kosli to complete SSO setup.<br>
5960

6061
```
@@ -63,7 +64,7 @@ Directory (tenant) ID: 11111111-2222-3333-4444-555555555555
6364
Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
6465
Client Secret Expiration Date: 1999-12-31 (format: yyyy-mm-dd)
6566
```
66-
See [Securely share secrets with Kosli](#securely-share-secrets-with-kosli).
67+
See [Sharing Secrets Securely with Kosli]({{< relref "sharing_secrets_securely" >}}).
6768

6869
## Update or Rotate the Client Secret
6970

@@ -92,22 +93,7 @@ Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
9293
Client Secret Expiration Date: 1999-12-31 (format: yyyy-mm-dd)
9394
```
9495

95-
See [Securely share secrets with Kosli]({{< ref "#securely-share-secrets-with-kosli" >}}).
96-
97-
## Securely share secrets with Kosli
98-
99-
For securely sharing your secrets with Kosli, we recommend using one of the following services:
100-
101-
* **Onetime Secret:** https://eu.onetimesecret.com
102-
* **Yopass:** https://yopass.se
103-
104-
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.
105-
106-
{{% hint warning %}}
107-
**Important:**
108-
The expiration for this must be set to a minimum of 7 days to allow Kosli to process it correctly.
109-
{{% /hint %}}
110-
96+
See [Sharing Secrets Securely with Kosli]({{< relref "sharing_secrets_securely" >}}).
11197

11298
## Troubleshooting
11399

@@ -136,8 +122,8 @@ Check the following common issues:
136122
- **Invalid Application ID, Directory ID, or Client Secret**
137123
- Verify that the values provided to Kosli are correct and correspond to those in your Microsoft Entra ID app registration.
138124
- **Expired Client Secret**
139-
- Ensure that the Client Secret provided to Kosli is still valid and has not expired
140-
- 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
125+
- Ensure that the Client Secret provided to Kosli is still valid and has not expired.
126+
- 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.
141127
- **User and Group Assignments**
142128
- 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.
143129

‎docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/okta_setup.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: "Okta Setup"
3+
bookCollapseSection: false
4+
weight: 300
5+
summary: "Step-by-step guide for configuring Single Sign-On (SSO) with Okta for your Kosli organization."
6+
---
7+
8+
# Okta Setup for SSO
9+
10+
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:
11+
12+
- [Create a new App integration](#create-a-new-app-integration)
13+
- [Update or Rotate the Client Secret](#update-or-rotate-the-client-secret)
14+
15+
## Prerequisites
16+
17+
To begin the setup process, ensure that you:
18+
19+
- Are logged into the Okta Admin Console at https://admin.okta.com/
20+
- Possess the necessary permissions to create a new application within Okta.
21+
22+
## Create a new App integration
23+
24+
### 1. Create the App Integration
25+
Follow the official Okta documentation to create a new OIDC app integration, with the following settings:
26+
27+
- **Application type:** Web Application
28+
- **Sign-in redirect URIs:** https://api.userfront.com/v0/auth/okta/login
29+
30+
### 2. Create a Client Secret
31+
32+
Follow the official Okta documentation to create a Client Secret for your newly created app integration.
33+
34+
## 3. Share details with Kosli Securely
35+
Please share details below securely in order for Kosli to complete SSO setup.<br>
36+
37+
```
38+
Okta client ID: abcdefghijklmnopqrst
39+
Okta domain: mycompany.okta.com
40+
Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
41+
Client Secret Expiration Date: 1999-12-31 (format: yyyy-mm-dd)
42+
```
43+
See [Sharing Secrets Securely with Kosli]({{< relref "sharing_secrets_securely" >}}).
44+
45+
## Update or Rotate the Client Secret
46+
47+
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.
48+
49+
### 1. Create a New Client Secret
50+
51+
Follow the official Okta documentation to create a new Client Secret for your existing app integration.
52+
53+
### 2. Share new Client Secret with Kosli Securely
54+
Please share the new Client Secret securely with Kosli.
55+
56+
```
57+
Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
58+
Client Secret Expiration Date: 1999-12-31 (format: yyyy-mm-dd)
59+
```
60+
61+
See [Sharing Secrets Securely with Kosli]({{< relref "sharing_secrets_securely" >}}).
62+
63+
## Troubleshooting
64+
65+
Once Kosli have confirmed the SSO setup, once you log in to Kosli, you should be redirected to the Okta login page.
66+
67+
### Common Issues
68+
69+
#### Problem: Unable to log in via SSO
70+
71+
Check the following common issues:
72+
73+
- **Wrong Redirect URI**
74+
- Ensure that the Redirect URI in your Okta app integration matches `https://api.userfront.com/v0/auth/okta/login`.
75+
- **Invalid Client ID or Client Secret**
76+
- Verify that the values provided to Kosli are correct and correspond to those in your Okta app integration.
77+
- **Expired Client Secret**
78+
- Ensure that the Client Secret provided to Kosli is still valid and has not expired.
79+
- 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.
80+
81+
## References
82+
83+
### Okta Documentation
84+
85+
- [Create OpenID Connect app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm)
86+
- [Manage secrets and keys for OIDC app client authentication](https://help.okta.com/oie/en-us/content/topics/apps/oauth-client-cred-mgmt.htm)

‎docs.kosli.com/content/implementation_guide/phase_2/sso_configuration/sharing_secrets_securely.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: "Sharing Secrets Securely"
3+
bookCollapseSection: false
4+
weight: 400
5+
summary: "How to securely share secrets with Kosli during Single Sign-On (SSO) configuration."
6+
---
7+
8+
# Sharing Secrets Securely
9+
10+
For securely sharing your secrets with Kosli, we recommend using one of the following services:
11+
12+
- **Onetime Secret:** https://eu.onetimesecret.com
13+
- **Yopass:** https://yopass.se
14+
15+
If your organization uses a different secret management tool that allows you to generate an access link, you can use that as well.
16+
17+
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.
18+
19+
{{% hint warning %}}
20+
**Important:**
21+
- Please ensure that the expiration for this must be set to a **minimum of 7 days** to allow Kosli to process it correctly.
22+
- Please allow **multiple access attempts**, as Kosli may need to access the secret more than once during the setup process.
23+
- 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.
24+
{{% /hint %}}

0 commit comments

Comments
 (0)