Create README.md

README.md

@@ -1,11 +1,106 @@
+# How to Configure SAML 2.0 for Hugging Face Enterprise Hub
+
+![Hugging Face logo](https://huggingface.co/front/assets/huggingface_logo-noborder.svg)
+
+---
+
+## Prerequisites
+
+Before you begin, make sure the following conditions are met:
+
+- Your Hugging Face organization must be on an **Enterprise** or **Enterprise Plus** plan to enable SAML-based Single Sign-On (SSO).  
+- You must have **administrator privileges** in both your **Okta** organization and your **Hugging Face Enterprise Hub** organization.  
+- Your Hugging Face organization must have a unique **Organization Name** and **Organization ID**.  
+  - These can be found in **Organization Settings → SSO → SAML** in Hugging Face.  
+- You need your **Okta Identity Provider (IdP) metadata**, including:
+  - **Identity Provider Single Sign-On URL**
+  - **X.509 Certificate** (full text including `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`)
+- For more information about Hugging Face’s Enterprise SSO, visit the [Hugging Face Enterprise SSO Documentation](https://huggingface.co/docs/hub/en/enterprise-sso).
+
+---
+
+## Supported Features
+
+The Okta / Hugging Face Enterprise Hub SAML integration supports the following features:
+
+| Feature | Supported | Description |
+|----------|------------|-------------|
+| **IdP-initiated SSO** | ✅ | Users can sign in directly from the Okta dashboard. |
+| **SP-initiated SSO** | ✅ | Users accessing Hugging Face are redirected to Okta for authentication. |
+| **JIT (Just-In-Time) Provisioning** | ✅ | Accounts are created automatically on first login via SSO. |
+| **Single Logout (SLO)** | ❌ | Not currently supported. |
+
 ---
-title: Okta Saml Integration Guide
-emoji: 🚀
-colorFrom: purple
-colorTo: indigo
-sdk: static
-pinned: false
-short_description: Official SAML integration guide for Okta x Hugging Face
+
+## Configuration Steps
+
+### Step 1 — Add the Hugging Face App from Okta Integration Network (OIN)
+
+1. Sign in to your **Okta Admin Console**.  
+2. Navigate to **Applications → Browse App Catalog**.  
+3. Search for **Hugging Face** and click **Add Integration**.
+
+### Step 2 — Configure the Hugging Face App in Okta
+
+4. On the **General Settings** page, specify:
+   - **Application label:** `Hugging Face`
+   - **Organization Name:** Your Hugging Face organization name
+   - **Organization ID:** Your Hugging Face organization ID  
+   *(These values are visible under **Organization Settings → SSO → SAML** in Hugging Face.)*
+
+   ![Screenshot: Hugging Face SSO settings](/static/images/hf-sso-saml-screenshot.png)
+
+5. Click **Next**, verify the sign-on options (username format should be **Email**), and then click **Done**.  
+6. Ensure the administrator performing these steps is **assigned** to the Hugging Face app under the **Assignments** tab.
+
+### Step 3 — Copy SAML Configuration from Okta
+
+7. In the Hugging Face app in Okta, open the **Sign On** tab.  
+8. Locate the **SAML 2.0** section and click **View SAML Setup Instructions**.  
+9. Copy the following values:
+   - **Identity Provider Single Sign-On URL**
+   - **X.509 Certificate** — full text including `BEGIN` and `END` certificate markers.
+
+### Step 4 — Configure SAML in Hugging Face
+
+10. In Hugging Face, go to **Organization Settings → SSO → SAML**.  
+11. Enter the values copied from Okta:
+    - **Sign On URL:** Paste the Identity Provider Single Sign-On URL.  
+    - **X.509 Certificate:** Paste the full certificate text.  
+12. Click **Update and Test SAML Configuration**.  
+13. If the test succeeds, toggle **Enable SAML SSO** to activate SSO for your organization.
+
+---
+
+## SP-Initiated SSO
+
+Hugging Face supports SP-initiated Single Sign-On. To start the login flow directly from Hugging Face:
+
+1. Go to [https://huggingface.co/login](https://huggingface.co/login).  
+2. Select **Sign in with your Enterprise SSO**.  
+3. Enter your **organization name** and click **Continue**.  
+4. You’ll be redirected to Okta for authentication, then returned to your Hugging Face workspace.
+
+Users can also trigger this flow automatically when trying to access organization content — they’ll see a banner prompting **“Login with SSO”** that redirects them to Okta.
+
+---
+
+## Notes
+
+- This configuration covers **Standard SSO**.  
+  For **Advanced SSO** (with SCIM user provisioning and advanced network security), see the [Hugging Face Advanced SSO Documentation](https://huggingface.co/docs/hub/en/enterprise-hub-advanced-sso).  
+- Make sure that the **Organization Name** and **Organization ID** used in Okta **exactly match** the values in your Hugging Face settings.  
+- Once SAML is enabled, access to organization content requires Okta authentication.
+
+---
+
+## Customer Support Contact
+
+If you need help with setup or troubleshooting, contact Hugging Face Enterprise Support:
+
+- **Email:** [enterprise-support@huggingface.co](mailto:enterprise-support@huggingface.co)  
+- **Documentation:** [https://huggingface.co/docs/hub/en/enterprise-sso](https://huggingface.co/docs/hub/en/enterprise-sso)
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+© Hugging Face, Inc. All rights reserved.