#ACL अनुमति नियंत्रण

ACL (एक्सेस कंट्रोल लिस्ट) का उपयोग संसाधन संचालन अनुमतियों को नियंत्रित करने के लिए किया जाता है। आप भूमिकाओं को अनुमतियाँ दे सकते हैं, या भूमिका प्रतिबंधों को छोड़कर सीधे अनुमतियों को नियंत्रित कर सकते हैं। ACL सिस्टम एक लचीला अनुमति प्रबंधन तंत्र प्रदान करता है, जो अनुमति स्निपेट, मिडलवेयर, शर्त-आधारित निर्णय और अन्य कई तरीकों का समर्थन करता है।

#अनुमति स्निपेट (Snippet) रजिस्टर करें

अनुमति स्निपेट (Snippet) आमतौर पर उपयोग किए जाने वाले अनुमति संयोजनों को पुन: प्रयोज्य अनुमति इकाइयों के रूप में रजिस्टर कर सकते हैं। किसी भूमिका को स्निपेट से जोड़ने के बाद, उसे अनुमतियों का संबंधित सेट प्राप्त हो जाता है, जिससे दोहराव वाली कॉन्फ़िगरेशन कम होती है और अनुमति प्रबंधन की दक्षता बढ़ती है।

acl.registerSnippet({
  name: 'ui.customRequests', // ui.* उपसर्ग उन अनुमतियों को इंगित करता है जिन्हें इंटरफ़ेस पर कॉन्फ़िगर किया जा सकता है
  actions: ['customRequests:*'], // संबंधित संसाधन संचालन, वाइल्डकार्ड का समर्थन करता है
});

#भूमिका प्रतिबंधों को छोड़ने वाली अनुमतियाँ (allow)

acl.allow() का उपयोग कुछ परिचालनों को भूमिका प्रतिबंधों को बाईपास करने की अनुमति देने के लिए किया जाता है। यह सार्वजनिक API, गतिशील अनुमति मूल्यांकन की आवश्यकता वाले परिदृश्यों, या उन मामलों के लिए उपयुक्त है जहाँ अनुमति का निर्णय अनुरोध संदर्भ के आधार पर करने की आवश्यकता होती है।

// सार्वजनिक पहुँच, लॉगिन की आवश्यकता नहीं
acl.allow('app', 'getLang', 'public');

// लॉग-इन किए गए उपयोगकर्ता पहुँच सकते हैं
acl.allow('app', 'getInfo', 'loggedIn');

// एक कस्टम शर्त के आधार पर
acl.allow('orders', ['create', 'update'], (ctx) => {
  return ctx.auth.user?.isAdmin ?? false;
});

condition पैरामीटर का विवरण:

• 'public' : कोई भी उपयोगकर्ता (लॉग-इन न किए गए उपयोगकर्ताओं सहित) बिना किसी प्रमाणीकरण के पहुँच सकता है।
• 'loggedIn' : केवल लॉग-इन किए गए उपयोगकर्ता ही पहुँच सकते हैं, इसके लिए वैध उपयोगकर्ता पहचान की आवश्यकता होती है।
• (ctx) => Promise<boolean> या (ctx) => boolean : कस्टम फ़ंक्शन जो अनुरोध संदर्भ के आधार पर गतिशील रूप से निर्धारित करता है कि पहुँच की अनुमति है या नहीं, यह जटिल अनुमति तर्क को लागू कर सकता है।

#अनुमति मिडलवेयर (use) रजिस्टर करें

acl.use() का उपयोग कस्टम अनुमति मिडलवेयर रजिस्टर करने के लिए किया जाता है, जिससे अनुमति जाँच प्रक्रिया में कस्टम तर्क डाला जा सके। यह आमतौर पर ctx.permission के साथ मिलकर कस्टम अनुमति नियमों के लिए उपयोग किया जाता है। यह उन परिदृश्यों के लिए उपयुक्त है जहाँ अपरंपरागत अनुमति नियंत्रण की आवश्यकता होती है, जैसे सार्वजनिक फ़ॉर्म को कस्टम पासवर्ड सत्यापन की आवश्यकता होती है, या अनुरोध पैरामीटर के आधार पर गतिशील अनुमति निर्णय।

विशिष्ट अनुप्रयोग परिदृश्य:

• सार्वजनिक फ़ॉर्म परिदृश्य: कोई उपयोगकर्ता नहीं, कोई भूमिका नहीं, लेकिन अनुमतियों को कस्टम पासवर्ड के माध्यम से नियंत्रित करने की आवश्यकता है।
• अनुरोध पैरामीटर, IP पते और अन्य शर्तों के आधार पर अनुमति नियंत्रण।
• कस्टम अनुमति नियम, डिफ़ॉल्ट अनुमति जाँच प्रक्रिया को छोड़ना या संशोधित करना।

ctx.permission के माध्यम से अनुमतियों को नियंत्रित करें:

acl.use(async (ctx, next) => {
  const { resourceName, actionName } = ctx.action;
  
  // उदाहरण: सार्वजनिक फ़ॉर्म को अनुमति जाँच छोड़ने के लिए पासवर्ड सत्यापन की आवश्यकता है
  if (resourceName === 'publicForms' && actionName === 'submit') {
    const password = ctx.request.body?.password;
    if (password === 'your-secret-password') {
      // सत्यापन सफल, अनुमति जाँच छोड़ें
      ctx.permission = {
        skip: true,
      };
    } else {
      ctx.throw(403, 'Invalid password');
    }
  }
  
  // अनुमति जाँच निष्पादित करें (ACL प्रक्रिया जारी रखें)
  await next();
});

ctx.permission प्रॉपर्टी का विवरण:

• skip: true : बाद की ACL अनुमति जाँचों को छोड़ें और सीधे पहुँच की अनुमति दें।
• इसे मिडलवेयर में कस्टम तर्क के आधार पर गतिशील रूप से सेट किया जा सकता है, जिससे लचीला अनुमति नियंत्रण प्राप्त होता है।

#विशिष्ट परिचालनों के लिए निश्चित डेटा बाधाएँ जोड़ें (addFixedParams)

addFixedParams कुछ संसाधन परिचालनों के लिए निश्चित डेटा स्कोप (फ़िल्टर) बाधाएँ जोड़ सकता है। ये बाधाएँ भूमिका प्रतिबंधों को बाईपास करती हैं और सीधे लागू होती हैं, आमतौर पर महत्वपूर्ण सिस्टम डेटा की सुरक्षा के लिए उपयोग की जाती हैं।

acl.addFixedParams('roles', 'destroy', () => {
  return {
    filter: {
      $and: [
        { 'name.$ne': 'root' },
        { 'name.$ne': 'admin' },
        { 'name.$ne': 'member' },
      ],
    },
  };
});

// भले ही किसी उपयोगकर्ता के पास भूमिकाओं को हटाने की अनुमति हो, वे root, admin, member जैसे सिस्टम भूमिकाओं को हटा नहीं सकते हैं

टिप: addFixedParams का उपयोग संवेदनशील डेटा को गलती से हटाने या संशोधित होने से रोकने के लिए किया जा सकता है, जैसे सिस्टम में निर्मित भूमिकाएँ, व्यवस्थापक खाते आदि। ये बाधाएँ भूमिका अनुमतियों के साथ मिलकर प्रभावी होती हैं, यह सुनिश्चित करती हैं कि अनुमतियाँ होने पर भी संरक्षित डेटा को हेरफेर नहीं किया जा सकता है।

#अनुमतियों की जाँच करें (can)

acl.can() का उपयोग यह जाँचने के लिए किया जाता है कि किसी भूमिका के पास निर्दिष्ट संचालन को निष्पादित करने की अनुमति है या नहीं, यह एक अनुमति परिणाम ऑब्जेक्ट या null लौटाता है। इसका उपयोग आमतौर पर व्यावसायिक तर्क में गतिशील रूप से अनुमतियों की जाँच करने के लिए किया जाता है, जैसे मिडलवेयर या संचालन के हैंडलर में भूमिकाओं के आधार पर यह तय करना कि कुछ परिचालनों को निष्पादित करने की अनुमति है या नहीं।

const result = acl.can({
  roles: ['admin', 'manager'], // एक एकल भूमिका या भूमिकाओं की एक सरणी (array) पास कर सकते हैं
  resource: 'orders',
  action: 'delete',
});

if (result) {
  console.log(`भूमिका ${result.role} ${result.action} संचालन निष्पादित कर सकती है`);
  // result.params में addFixedParams के माध्यम से सेट किए गए निश्चित पैरामीटर शामिल हैं
  console.log('निश्चित पैरामीटर:', result.params);
} else {
  console.log('इस संचालन को निष्पादित करने की कोई अनुमति नहीं');
}

टिप: यदि कई भूमिकाएँ पास की जाती हैं, तो प्रत्येक भूमिका को क्रमिक रूप से जाँच की जाएगी, और अनुमति वाली पहली भूमिका का परिणाम लौटाया जाएगा।

प्रकार परिभाषाएँ:

interface CanArgs {
  role?: string;      // एकल भूमिका
  roles?: string[];   // कई भूमिकाएँ (क्रमिक रूप से जाँच की जाती हैं, अनुमति वाली पहली भूमिका लौटाता है)
  resource: string;   // संसाधन का नाम
  action: string;    // संचालन का नाम
}

interface CanResult {
  role: string;       // अनुमति वाली भूमिका
  resource: string;   // संसाधन का नाम
  action: string;    // संचालन का नाम
  params?: any;       // निश्चित पैरामीटर जानकारी (यदि addFixedParams के माध्यम से सेट की गई हो)
}

#कॉन्फ़िगर करने योग्य संचालन रजिस्टर करें (setAvailableAction)

यदि आप चाहते हैं कि कस्टम संचालन को इंटरफ़ेस पर अनुमतियाँ कॉन्फ़िगर करने योग्य बनाया जा सके (जैसे भूमिका प्रबंधन पृष्ठ में प्रदर्शित करना), तो आपको उन्हें setAvailableAction का उपयोग करके रजिस्टर करना होगा। पंजीकृत संचालन अनुमति कॉन्फ़िगरेशन इंटरफ़ेस में दिखाई देंगे, जहाँ व्यवस्थापक विभिन्न भूमिकाओं के लिए संचालन अनुमतियाँ कॉन्फ़िगर कर सकते हैं।

acl.setAvailableAction('importXlsx', {
  displayName: '{{t("Import")}}', // इंटरफ़ेस प्रदर्शन नाम, अंतर्राष्ट्रीयकरण का समर्थन करता है
  type: 'new-data',               // संचालन का प्रकार
  onNewRecord: true,              // क्या नई रिकॉर्ड बनाते समय प्रभावी होगा
});

पैरामीटर का विवरण:

• displayName : अनुमति कॉन्फ़िगरेशन इंटरफ़ेस में प्रदर्शित नाम, अंतर्राष्ट्रीयकरण का समर्थन करता है ( {{t("key")}} प्रारूप का उपयोग करके)।
• type : संचालन का प्रकार, जो अनुमति कॉन्फ़िगरेशन में इस संचालन के वर्गीकरण को निर्धारित करता है।
  • 'new-data' : नया डेटा बनाने वाले संचालन (जैसे आयात, जोड़ना आदि)।
  • 'existing-data' : मौजूदा डेटा को संशोधित करने वाले संचालन (जैसे अपडेट, हटाना आदि)।
• onNewRecord : क्या नई रिकॉर्ड बनाते समय प्रभावी होगा, यह केवल 'new-data' प्रकार के लिए वैध है।

पंजीकरण के बाद, यह संचालन अनुमति कॉन्फ़िगरेशन इंटरफ़ेस में दिखाई देगा, जहाँ व्यवस्थापक भूमिका प्रबंधन पृष्ठ में इस संचालन की अनुमतियाँ कॉन्फ़िगर कर सकते हैं।