Skip to content

Commit c669001

Browse files
boojackclaudeCopilot
authored
docs: add IdP-initiated flow documentation (#922)
* docs: add IdP-initiated flow documentation Add comprehensive documentation for IdP-initiated SSO flow feature based on PR #17927. This feature allows users to access Bytebase directly from their identity provider's dashboard without needing to click a login button. Changes: - Add new idp-initiated.mdx documentation page - Include Okta setup guide using Initiate Login URI - Add security considerations and troubleshooting sections - Update SSO overview to reference the new feature - Add navigation entry in docs.json - Include Okta admin interface screenshot Co-Authored-By: Claude <[email protected]> * Update mintlify/administration/sso/idp-initiated.mdx Co-authored-by: Copilot <[email protected]> --------- Co-authored-by: Claude <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent e3b9701 commit c669001

File tree

4 files changed

+199
-1
lines changed

4 files changed

+199
-1
lines changed

‎mintlify/administration/sso/idp-initiated.mdx‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
title: IdP-Initiated Flow
3+
---
4+
5+
Identity Provider-initiated (IdP-initiated) flow allows users to access Bytebase directly from their identity provider's dashboard or portal, without needing to first visit Bytebase and click a "Sign in with..." button.
6+
7+
## Overview
8+
9+
In a traditional Service Provider-initiated (SP-initiated) flow, the authentication process starts when a user tries to access Bytebase and clicks the SSO login button. With IdP-initiated flow, the process begins at the identity provider's side—for example, when a user clicks the Bytebase tile in their Okta dashboard.
10+
11+
### IdP-Initiated vs SP-Initiated
12+
13+
**SP-Initiated (Traditional Flow)**:
14+
15+
1. User visits Bytebase
16+
2. User clicks "Sign in with Okta" button
17+
3. User is redirected to Okta for authentication
18+
4. After authentication, user is redirected back to Bytebase
19+
20+
**IdP-Initiated Flow**:
21+
22+
1. User is already logged into their IdP (e.g., Okta)
23+
2. User clicks Bytebase tile/bookmark in their IdP dashboard
24+
3. User is directly authenticated and redirected to Bytebase
25+
26+
### Benefits
27+
28+
- **Streamlined user experience**: Users can access Bytebase with a single click from their IdP dashboard
29+
- **Centralized access**: All applications are accessible from one place (the IdP portal)
30+
- **Reduced friction**: Eliminates the extra step of clicking the SSO button in Bytebase
31+
32+
## Prerequisites
33+
34+
1. Configure [External URL](/get-started/self-host/external-url) for your Bytebase instance
35+
2. Set up an [OAuth 2.0](/administration/sso/oauth2) or [OIDC](/administration/sso/oidc) SSO provider in Bytebase
36+
37+
<Info>
38+
39+
IdP-initiated flow in Bytebase works with OAuth 2.0 and OpenID Connect (OIDC) protocols. This feature uses a specialized endpoint to initiate the authentication flow from the identity provider's side.
40+
41+
</Info>
42+
43+
## Configuration
44+
45+
### Step 1: Configure SSO Provider in Bytebase
46+
47+
First, ensure you have already configured your SSO provider (OAuth 2.0 or OIDC) in Bytebase following the respective documentation:
48+
49+
- [OAuth 2.0 Configuration](/administration/sso/oauth2)
50+
- [OIDC Configuration](/administration/sso/oidc)
51+
52+
### Step 2: Get Your IdP-Initiated URL
53+
54+
Once your SSO provider is configured, the IdP-initiated flow URL follows this format:
55+
56+
```
57+
{EXTERNAL_URL}/auth/idp-init?idp={IDENTITY_PROVIDER_ID}
58+
```
59+
60+
Where:
61+
62+
- `{EXTERNAL_URL}` is your Bytebase external URL (e.g., `https://bytebase.example.com`)
63+
- `{IDENTITY_PROVIDER_ID}` is the Identity Provider ID you specified when creating the SSO provider in Bytebase
64+
65+
**Example**:
66+
If your external URL is `https://bytebase.example.com` and your Identity Provider ID is `okta-company`, the IdP-initiated URL would be:
67+
68+
```
69+
https://bytebase.example.com/auth/idp-init?idp=okta-company
70+
```
71+
72+
### Step 3: Add Deep Linking (Optional)
73+
74+
You can optionally specify where users should land after authentication by adding a `relay_state` parameter. If not provided, users will be directed to the Bytebase homepage after successful authentication.
75+
76+
```
77+
{EXTERNAL_URL}/auth/idp-init?idp={IDENTITY_PROVIDER_ID}&relay_state={PATH}
78+
```
79+
80+
**Example**:
81+
To redirect users to a specific project after login:
82+
83+
```
84+
https://bytebase.example.com/auth/idp-init?idp=okta-company&relay_state=/projects/123
85+
```
86+
87+
<Note>
88+
89+
The `relay_state` parameter is optional. When used, it must be a relative path (starting with `/`). External URLs are not permitted for security reasons.
90+
91+
</Note>
92+
93+
## Okta Configuration
94+
95+
After setting up your [OIDC SSO provider](/administration/sso/oidc) in Bytebase, configure the Initiate Login URL in your Okta application to enable IdP-initiated flow.
96+
97+
1. In your Okta Admin Console, go to **Applications** > **Applications**.
98+
99+
2. Select your existing Bytebase OIDC application (the one you created when setting up OIDC SSO).
100+
101+
3. Go to the **General** tab and click **Edit** in the **General Settings** section.
102+
103+
4. Set the **Initiate login URI** to your Bytebase IdP-initiated URL:
104+
105+
```
106+
https://bytebase.example.com/auth/idp-init?idp=okta-company
107+
```
108+
109+
Where `okta-company` is the Identity Provider ID you configured in Bytebase.
110+
111+
![okta-initiate-login-uri](/content/docs/administration/sso/okta-initiate-login-uri.webp)
112+
113+
5. Click **Save** to apply the changes.
114+
115+
6. Now when users click the Bytebase tile in their Okta End-User Dashboard, they will be automatically authenticated and redirected to Bytebase without needing to click any additional login buttons.
116+
117+
<Tip>
118+
119+
To direct users to a specific page after login, add the `relay_state` parameter to your Initiate Login URI:
120+
121+
```
122+
https://bytebase.example.com/auth/idp-init?idp=okta-company&relay_state=/projects/123
123+
```
124+
125+
</Tip>
126+
127+
## Other Identity Providers
128+
129+
For other identity providers (GitLab, Keycloak, Casdoor, etc.), the configuration typically involves:
130+
131+
1. Creating a bookmark/shortcut application in your IdP
132+
2. Setting the target URL to your Bytebase IdP-initiated URL
133+
3. Assigning the bookmark to appropriate users or groups
134+
135+
Consult your identity provider's documentation for creating bookmark or web link applications.
136+
137+
## Security Considerations
138+
139+
IdP-initiated flow in Bytebase includes several security measures:
140+
141+
### CSRF Protection
142+
143+
The IdP-initiated flow uses the same state parameter mechanism as SP-initiated SSO to prevent Cross-Site Request Forgery (CSRF) attacks. Each authentication request generates a unique, single-use state token.
144+
145+
### Token Expiration
146+
147+
State tokens expire after 10 minutes, limiting the window for potential replay attacks.
148+
149+
### Relay State Validation
150+
151+
The `relay_state` parameter is validated to ensure it's a relative path, preventing open redirect vulnerabilities. External URLs are rejected.
152+
153+
### Existing Session Handling
154+
155+
If a user already has an active Bytebase session when using IdP-initiated flow, the system will respect the existing session state.
156+
157+
<Warning>
158+
159+
While IdP-initiated flow provides a better user experience, SP-initiated flows offer slightly stronger security guarantees because the authentication request originates from and is controlled by the service provider. For high-security environments, consider whether the convenience of IdP-initiated flow is appropriate for your security requirements.
160+
161+
</Warning>
162+
163+
## Troubleshooting
164+
165+
### Users redirected to homepage instead of intended destination
166+
167+
If you're using the `relay_state` parameter but users are landing on the homepage:
168+
169+
1. Verify that the `relay_state` value is URL-encoded if it contains special characters
170+
2. Ensure the path starts with `/` (e.g., `/projects/123`, not `projects/123`)
171+
3. Check that the path exists and is accessible to the authenticated user
172+
173+
### IdP-initiated flow not working
174+
175+
If clicking the application tile in your IdP dashboard doesn't authenticate users:
176+
177+
1. Verify your External URL is configured correctly in Bytebase
178+
2. Check that the Identity Provider ID in the Initiate Login URI matches exactly what you configured in Bytebase (case-sensitive)
179+
3. Ensure the OIDC SSO provider is properly configured and tested using SP-initiated flow first
180+
4. Verify the Initiate Login URI is correctly set in your Okta application's General Settings
181+
182+
### Authentication succeeds but shows an error
183+
184+
This may indicate an issue with token exchange or user provisioning:
185+
186+
1. Verify the OAuth/OIDC configuration in Bytebase has correct client ID and secret
187+
2. Check the user information field mapping in your SSO configuration
188+
3. Review Bytebase server logs for detailed error messages
189+
4. Ensure the user's email in the IdP matches a valid email format
190+
191+
## Learn More
192+
193+
- [OAuth 2.0 Configuration](/administration/sso/oauth2)
194+
- [OIDC Configuration](/administration/sso/oidc)
195+
- [External URL Configuration](/get-started/self-host/external-url)
196+
- [SSO Overview](/administration/sso/overview)

‎mintlify/administration/sso/overview.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Bytebase supports the following standard protocols that provide SSO:
1010
- [OpenID Connect (OIDC)](/administration/sso/oidc)
1111
- [Microsoft Entra ID (Azure AD) OIDC](/administration/sso/oidc-entra-id)
1212
- [Lightweight Directory Access Protocol (LDAP)](/administration/sso/ldap)
13+
- [IdP-Initiated Flow](/administration/sso/idp-initiated) - Access Bytebase directly from your identity provider's dashboard
1314

1415
## Prerequisites
1516

‎mintlify/content/docs/administration/sso/okta-initiate-login-uri.webp‎

57.2 KB
Loading

‎mintlify/docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -200,7 +200,8 @@
200200
"administration/sso/oauth2",
201201
"administration/sso/oidc",
202202
"administration/sso/oidc-entra-id",
203-
"administration/sso/ldap"
203+
"administration/sso/ldap",
204+
"administration/sso/idp-initiated"
204205
]
205206
},
206207
"administration/user-groups",

0 commit comments

Comments
 (0)