</details>

<details>
<summary><strong>कस्टम SSH कुंजी जोड़ी</strong></summary>

डिफ़ॉल्ट रूप से Bastillion पहली बार शुरू होने पर अपनी खुद की Ed25519 कुंजी जोड़ी उत्पन्न करता है। अपनी खुद की कुंजी उपयोग करने के लिए,
सबसे आसान तरीका UI के माध्यम से है: **Settings → Replace Application SSH Key**
(केवल प्रबंधक खाते) — एक निजी कुंजी, सार्वजनिक कुंजी, और पासफ़्रेज़ (यदि है) पेस्ट करें,
और यह तुरंत प्रभावी हो जाता है, किसी पुनःआरंभ की आवश्यकता नहीं है।

⚠️ यह उस *एक* कुंजी को बदलता है जिस पर हर पंजीकृत सिस्टम भरोसा करता है। यह एक बार का कदम है
जब पहली बार Bastillion सेट कर रहे हों, **इससे पहले** कि आपने कोई सिस्टम पंजीकृत किया हो — यदि आपके पास
पहले से सिस्टम पंजीकृत हैं, तो कुंजी बदलते ही Bastillion उन सभी तक SSH पहुंच खो देता है,
जब तक कि यह सटीक कुंजी पहले से ही उन सभी के `authorized_keys` में मौजूद न हो।
एक बार सिस्टम पंजीकृत होने के बाद Settings पृष्ठ पर एक अतिरिक्त पुष्टिकरण चेकबॉक्स की आवश्यकता होती है,
ठीक इसी कारण से।

**क्या आपके पास पहले से सिस्टम पंजीकृत हैं और फिर भी कुंजी घुमाने की आवश्यकता है?** नई कुंजी को
हर जगह `authorized_keys` को हाथ से संपादित करने के बजाय Bastillion के माध्यम से ही पहले से तैयार करें:

1. `FORCE_USER_KEY_GENERATION=false` सेट करें ताकि **Manage SSH Keys → Add SSH Key** आपको
   केवल नई कुंजी उत्पन्न करने के बजाय मौजूदा सार्वजनिक कुंजी पेस्ट करने दे।
2. वहां आपके सभी सिस्टम को कवर करने वाले प्रोफ़ाइल के विरुद्ध नई कुंजी जोड़ें, और पुष्टि करें (Manage SSH Keys के अंतर्गत,
   या प्रत्येक सिस्टम की स्थिति में) कि यह वास्तव में हर जगह पहुंच गई है — `AUTH_KEYS_REFRESH_INTERVAL` को ध्यान में रखें,
   क्योंकि यही इसे बाहर भेजता है।
3. केवल जब आप सुनिश्चित हों कि यह हर सिस्टम पर है, तब Settings में एप्लिकेशन कुंजी बदलें।
4. `FORCE_USER_KEY_GENERATION` को उसके पिछले मान पर वापस सेट करें, फिर एक बार आपने पुष्टि कर ली
   कि नई एप्लिकेशन कुंजी हर सिस्टम पर प्रसारित हो गई है (फिर से, `AUTH_KEYS_REFRESH_INTERVAL` का ध्यान रखें),
   तो चरण 2 में जोड़ी गई कुंजी को Manage SSH Keys से हटा दें — यह केवल `authorized_keys` को पहले से भरने के लिए
   वहां रखी गई थी और आगे के लिए आवश्यक नहीं है।

स्क्रिप्टेड/हेडलेस सेटअप के लिए, वही काम पर्यावरण चर और एक पुनःआरंभ के माध्यम से किया जा सकता है:```bash
# Regenerate and import SSH keys
export RESET_APPLICATION_SSH_KEY=true

# Private key
export PRIVATE_KEY=/Users/you/.ssh/id_rsa

# Public key
export PUBLIC_KEY=/Users/you/.ssh/id_rsa.pub

# Passphrase (leave blank if none)
export DEFAULT_SSH_PASSPHRASE=myPa$$w0rd

</details>

<details>
<summary><strong>डेटाबेस सेटिंग्स</strong></summary>

एम्बेडेड H2 उदाहरण:```bash
export DB_USER=bastillion
export DB_PASSWORD=p@$$w0rd!!
export DB_DRIVER=org.h2.Driver
export DB_CONNECTION_URL=jdbc:h2:file:keydb/bastillion;CIPHER=AES;

</details>

<details>
<summary><strong>बाह्य प्रमाणीकरण (LDAP / JAAS)</strong></summary>

स्थानीय पासवर्ड के बजाय (या उनके साथ) किसी मौजूदा LDAP/Active Directory सर्वर के विरुद्ध प्रमाणीकरण करें। इसे सक्षम करें:```bash
export JAAS_MODULE=ldap-ol

LDAP भूमिकाओं को Bastillion प्रोफाइल से मैप करने के लिए:```
ldap-ol-with-roles {
    org.eclipse.jetty.security.jaas.spi.LdapLoginModule required
    debug="false"
    useLdaps="false"
    contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
    hostname="<SERVER>"
    port="389"
    bindDn="<BIND-DN>"
    bindPassword="<BIND-DN PASSWORD>"
    authenticationMethod="simple"
    forceBindingLogin="true"
    userBaseDn="ou=users,dc=bastillion,dc=com"
    userRdnAttribute="uid"
    userIdAttribute="uid"
    userPasswordAttribute="userPassword"
    userObjectClass="inetOrgPerson"
    roleBaseDn="ou=groups,dc=bastillion,dc=com"
    roleNameAttribute="cn"
    roleMemberAttribute="member"
    roleObjectClass="groupOfNames";
};

</details>

<details>
<summary><strong>सिंगल साइन-ऑन (SAML 2.0)</strong></summary>

किसी एंटरप्राइज़ आइडेंटिटी प्रोवाइडर - Microsoft Entra ID, Okta, ADFS, या किसी भी
SAML 2.0 IdP - के विरुद्ध प्रमाणीकरण करें, स्थानीय पासवर्ड या LDAP के बजाय (या उनके साथ)। कॉन्फ़िगर होने के बाद लॉगिन पेज पर एक **Sign in with SSO**
बटन दिखाई देता है। इसे सक्षम करें:```bash
export SAML_BASE_URL=https://bastillion.example.com
export SAML_IDP_METADATA_URL=https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app-id>

केवल तभी आवश्यक है जब IdP पक्ष पर पंजीकृत Entity ID `SAML_BASE_URL` से बिल्कुल मेल नहीं खा सकती:```bash
export SAML_SP_ENTITY_ID=https://bastillion.example.com

पहले SSO लॉगिन पर एडमिन जोड़े जाते हैं और उन्हें सिस्टम प्रोफाइल असाइन की जा सकती हैं।

**Bastillion में दिखाया गया उपयोगकर्ता नाम:** SAML NameID उपयोगकर्ता नाम बन जाता है। Entra डिफ़ॉल्ट रूप से
`user.userprincipalname` भेजता है, जो नियमित टेनेंट सदस्यों के लिए ठीक है, लेकिन B2B मेहमानों (वे सभी जो
व्यक्तिगत या बाहरी ईमेल से साइन इन करते हैं और मेहमान के रूप में जोड़े गए हैं) के लिए एक बदसूरत
गेस्ट UPN उत्पन्न करता है जैसे `alice_gmail.com#EXT#@yourtenant.onmicrosoft.com`। एक साफ-सुथरे उपयोगकर्ता नाम के लिए,
Enterprise Application के *Single sign-on* → SAML → *Attributes & Claims* पर जाएं, **Unique
User Identifier (Name ID)** को संपादित करें, और इसका *Source attribute* `user.userprincipalname`
से बदलकर `user.mail` कर दें।

**भूमिका मैपिंग वास्तव में कैसे काम करती है - ऊपर LDAP के समान तंत्र:** `SAML_ROLE_ATTRIBUTE`
यह निर्दिष्ट करता है कि *कौन सा* assertion विशेषता उपयोगकर्ता के समूहों/भूमिकाओं को ले जाती है; किसी दिए गए लॉगिन पर
उस विशेषता में जो भी *मान* होते हैं, उनकी तुलना **सटीक टेक्स्ट मिलान द्वारा**, आपके द्वारा **Manage → Profiles** के तहत
बनाई गई Profiles के नामों से की जाती है। एक मान जो किसी प्रोफाइल नाम से मेल खाता है, उपयोगकर्ता को उसे
असाइन कर देता है; दावे के बारे में और कुछ भी मायने नहीं रखता। इसलिए एक Bastillion प्रोफाइल का नाम
बिल्कुल उसी स्ट्रिंग के समान होना चाहिए जो assertion भेजता है - कोई अलग मैपिंग चरण
या UI नहीं है, नामों को बस एक-दूसरे से मेल खाना होता है।

यह वह हिस्सा है जो विशेष रूप से Entra ID के साथ लोगों को सबसे अधिक परेशान करता है: डिफ़ॉल्ट रूप से,
Entra का समूह दावा प्रत्येक समूह को उसके **Object ID** (एक GUID) के रूप में उत्सर्जित कर सकता है, न कि उसके प्रदर्शन
नाम के रूप में, जब तक कि Enterprise Application का टोकन कॉन्फ़िगरेशन स्पष्ट रूप से समूह **नाम** उत्सर्जित करने के लिए सेट न हो।
यदि आपकी Bastillion प्रोफाइल के नाम `admins`/`everyone` जैसे हैं, लेकिन Entra
GUID भेज रहा है, तो कभी कुछ मेल नहीं खाएगा। यह मानने से पहले कि मैपिंग टूटी हुई है, वास्तविक assertion (या
ऐप के लिए Entra का टोकन कॉन्फ़िगरेशन) में वास्तविक दावा मान जांचें - यह आमतौर पर
यही होता है, Bastillion-पक्ष की समस्या नहीं। इसे ठीक करने के तीन तरीके, हमारी अनुशंसा के क्रम में:

1. **समूह दावों के बजाय Entra App Roles का उपयोग करें (सबसे साफ)।** ऐप के पंजीकरण →
   App roles के तहत, बिल्कुल उन मानों के साथ भूमिकाएँ परिभाषित करें जो आप चाहते हैं (`admins`, `everyone`, ...), फिर
   Enterprise Application के *Users and groups* के तहत उन भूमिकाओं को उपयोगकर्ताओं/समूहों को असाइन करें।
   SAML टोकन को `roles` दावा उत्सर्जित करने के लिए कॉन्फ़िगर करें, और `SAML_ROLE_ATTRIBUTE` को उस
   दावे के URI पर इंगित करें, न कि समूह दावे पर। आप वह सटीक स्ट्रिंग चुनते हैं जो Entra भेजता है - कोई GUID
   समस्या नहीं, और यह वैसे भी AD समूहों को पुनः उपयोग करने की तुलना में एक साफ अधिकृतकरण मॉडल है।
2. **समूह दावे की स्रोत विशेषता बदलें।** Enterprise Application → Single sign-on →
   SAML → *Attributes & Claims* → Groups दावे को संपादित करें → एक *Source attribute*
   ड्रॉपडाउन है, जो सामान्यतः Group ID पर डिफ़ॉल्ट होता है। आपके टेनेंट और समूह क्लाउड-केवल हैं या
   ऑन-प्रिम AD से सिंक किए गए हैं, इस पर निर्भर करते हुए, आप इसे `sAMAccountName`
   या एक प्रदर्शन-नाम विकल्प पर स्विच करने में सक्षम हो सकते हैं - सटीक विकल्प टेनेंट और Entra पोर्टल संस्करण के अनुसार भिन्न होते हैं, इसलिए
   एक विशिष्ट लेबल मानने के बजाय जांचें कि वास्तव में क्या पेश किया गया है।
3. **या इससे न लड़ें - Bastillion प्रोफाइल का नाम उसी के अनुसार रखें जो Entra वास्तव में भेजता है।** यदि
   Entra GUID भेजने पर जोर देता है, तो एक Bastillion प्रोफाइल बनाएं जिसका नाम सचमुच वह GUID हो।
   बदसूरत, लेकिन Entra-पक्ष के पुनर्संरचना की शून्य आवश्यकता।

जिस उपयोगकर्ता के दावे किसी Bastillion प्रोफाइल से मेल नहीं खाते, उसे लॉगिन पर अस्वीकार कर दिया जाता है (**Manager** खाते
एकमात्र अपवाद हैं; वे प्रोफाइल-स्कोप्ड नहीं हैं) - बिल्कुल LDAP की तरह, इसलिए
ऊपर `DEFAULT_PROFILE_FOR_SAML` सेट करना उसी कारण से उचित है जिस कारण
`DEFAULT_PROFILE_FOR_LDAP` है: एक सुरक्षा जाल जबकि आप अभी भी प्रोफाइल नामों को
अपने IdP के दावा मानों के साथ संरेखित कर रहे हैं।

Bastillion की अपनी एक-बार-पासकोड जांच SSO लॉगिन के लिए छोड़ दी जाती है - IdP से अपेक्षा की जाती है कि
वह अपनी स्वयं की MFA/Conditional Access नीति लागू करे। पहली बार OTP नामांकन अभी भी
पेश किया जाता है ताकि SAML उपयोगकर्ताओं के पास एक स्थानीय फ़ॉलबैक क्रेडेंशियल उपलब्ध हो यदि SSO कभी अक्षम हो।

**हस्ताक्षरित अनुरोध और एन्क्रिप्टेड assertions:** Bastillion अपना स्वयं का SAML हस्ताक्षर
प्रमाणपत्र स्वचालित रूप से उत्पन्न करता है (स्व-हस्ताक्षरित, उसी तरह जैसे यह अपना TLS प्रमाणपत्र उत्पन्न करता है)
पहली बार जब इसकी आवश्यकता होती है, और उसके बाद हर बाहरी AuthnRequest पर इसके साथ हस्ताक्षर करता है - कोई
सेटअप आवश्यक नहीं है, और हानिरहित भी है भले ही आपका IdP इसे जांचे नहीं। उस प्रमाणपत्र को मानक SP
मेटाडेटा रूप में प्राप्त करने के लिए `https://bastillion.example.com/saml/metadata` लाएं
और इसे अपने IdP एडमिन को सौंप दें यदि उन्हें Bastillion के हस्ताक्षरित
अनुरोधों को सत्यापित करना चाहिए, या Bastillion के लिए assertions एन्क्रिप्ट करनी चाहिए - अधिकांश IdP एक SP मेटाडेटा
URL को सीधे आयात कर सकते हैं, बजाय एक कच्चे प्रमाणपत्र को चिपकाने के। यदि आप स्वचालित रूप से उत्पन्न एक के बजाय एक वास्तविक (जैसे
CA-जारी) कुंजी जोड़ी का उपयोग करना पसंद करते हैं, तो `SAML_SP_KEYSTORE_PATH`/
`SAML_SP_KEYSTORE_PASSWORD` को उस युक्त PKCS12 कीस्टोर पर इंगित करें। एन्क्रिप्टेड assertions की *आवश्यकता* के लिए
(डिफ़ॉल्ट रूप से बंद - इसे केवल तभी चालू करें जब आपका IdP वास्तव में Bastillion के प्रमाणपत्र के लिए
एन्क्रिप्ट करने के लिए कॉन्फ़िगर किया गया हो, अन्यथा हर लॉगिन विफल होना शुरू हो जाएगा):```bash
export SAML_WANT_ENCRYPTED_ASSERTIONS=true

यहाँ एक फ़ाइल-आधारित ऑडिट लॉग भी है, जो डिफ़ॉल्ट रूप से अक्षम है। इसे **log4j2.xml** में निम्न को अनकमेंट करके सक्षम करें:
- `io.bastillion.manage.util.SystemAudit`
- `audit-appender`

> https://github.com/bastillion-io/Bastillion/blob/main/src/main/resources/log4j2.xml#L19-L22
</details>

<details>
<summary><strong>v4 से माइग्रेट करना</strong></summary>

पुराने Bastillion v4 इंस्टॉलेशन से अपग्रेड कर रहे हैं और अपने उपयोगकर्ताओं, सिस्टम, प्रोफाइल,
स्क्रिप्ट्स, और (सबसे महत्वपूर्ण) एप्लिकेशन की मौजूदा SSH कीपेयर को शुरू से शुरू करने के बजाय
बनाए रखना चाहते हैं? `tools/migrate/` में इसके लिए एक स्टैंडअलोन माइग्रेशन टूल है — यह पुराने
H2 डेटाबेस से हर टेबल को निर्यात करता है (पुराने इंस्टॉलेशन के कीस्टोर के साथ ऐप-स्तरीय
एन्क्रिप्टेड कॉलम को डिक्रिप्ट करके) एक JSON फ़ाइल में, फिर इसे एक नए v5 इंस्टॉलेशन में आयात
करता है (नए इंस्टॉलेशन के कीस्टोर के साथ पुनः-एन्क्रिप्ट करके)। मौजूदा उपयोगकर्ता तुरंत बाद
अपने वर्तमान पासवर्ड से लॉग इन कर सकते हैं — कोई जबरन रीसेट नहीं।```bash
cd tools/migrate

# 1. Export the old database
./migrate.sh export /opt/Bastillion-jetty/jetty/bastillion/WEB-INF/classes/ ~/bastillion-export.json

# 2. Start the new v5 instance once against the config dir you're migrating into, then
#    stop it (Ctrl+C) once it's finished booting - this creates the schema, jceks, and
#    default admin user.
cd ../..
java -DCONFIG_DIR=/data/bastillion/ -jar target/bastillion-5.0.0-SNAPSHOT.jar

# 3. Import into the new database (full replace of all 12 tables)
cd tools/migrate
./migrate.sh import /data/bastillion/ ~/bastillion-export.json --yes-replace-all-data

# 4. Delete the export file - it contains decrypted secrets
rm ~/bastillion-export.json