Okta API Bearer प्रमाणीकरण

Okta द्वारा जारी किए गए OAuth 2.0 Bearer tokens का उपयोग करके Halo API तक प्रोग्रामेटिक एक्सेस को प्रमाणित करें।

अवलोकन​

Halo, API-Access सेवा के माध्यम से एक REST API उपलब्ध कराता है। सभी API अनुरोधों में Authorization header में एक वैध Bearer token शामिल होना चाहिए। Tokens, OAuth 2.0 Client Credentials flow (machine-to-machine) का उपयोग करके Okta से प्राप्त किए जाते हैं।

यह गाइड Halo API-Access सेवा के लिए Okta को Identity Provider के रूप में कॉन्फ़िगर करने और फिर Bearer token authentication के साथ integration का परीक्षण करने की प्रक्रिया बताती है।

पूर्वापेक्षाएँ​

• API-Access सेवा कॉन्फ़िगर की हुई एक चालू Halo deployment
• admin access के साथ एक Okta organization
• Halo के लिए कॉन्फ़िगर किया गया Okta authorization server (देखें Okta Authorization Server)
• API client से Okta और Halo API endpoint दोनों तक नेटवर्क एक्सेस

सेटअप​

Okta में एक API client रजिस्टर करें​

एक machine-to-machine application बनाएं​

1. Okta Admin Console में लॉगिन करें।
2. Applications -> Applications -> Create App Integration -> API Services पर जाएं।

3. उपयुक्त App integration नाम दें: उदाहरण के लिए Glasswall Halo API

DPoP (proof of possession) अक्षम करें​

4. application के General tab -> General Settings section पर जाएं -> Edit पर क्लिक करें।
5. Proof of possession के अंतर्गत, Require Demonstrating Proof of Possession (DPoP) header in token requests को अनचेक करें।
6. सेव करें।

Note: Okta, API Services applications के लिए डिफ़ॉल्ट रूप से DPoP सक्षम करता है। DPoP tokens को client की cryptographic key से बाँधता है, जिससे token replay attacks रोके जाते हैं। हालांकि, Halo API-Access service वर्तमान में DPoP token validation को support नहीं करती, इसलिए Bearer token authentication के काम करने के लिए इसे अक्षम करना आवश्यक है।

client credentials कॉन्फ़िगर करें​

7. Client ID नोट करें और एक Client Secret जनरेट करें।

   export CLIENT_ID="<your-client-id>"
   export CLIENT_SECRET="<your-client-secret>"
   

Security Note: client secrets को secrets manager (उदाहरण के लिए, Azure KeyVault) का उपयोग करके सुरक्षित रूप से स्टोर करें। secrets को कभी भी source control में commit न करें।

roles कॉन्फ़िगर करें (वैकल्पिक)​

8. यदि आपके API client को license management endpoints पर write access चाहिए, तो सुनिश्चित करें कि authorization server पर role claim कॉन्फ़िगर किया गया है और Admin value आपके client से mapped है (देखें API Roles)।

नोट: role claim के बिना, API डिफ़ॉल्ट रूप से User role का उपयोग करता है। प्रत्येक role क्या access कर सकता है, इसकी जानकारी के लिए API Roles to Action Mapping देखें।

issuer URI और audience नोट करें​

9. पूर्वापेक्षा चरण में कॉन्फ़िगर किए गए authorization server से:

   export OKTA_ISSUER_URI="https://<your-okta-domain>/oauth2/<authorization-server-id>"
   export VALID_AUDIENCE="api://halo"
   

API client के लिए access policy जोड़ें​

10. authorization server के Access Policies टैब पर जाएँ (Security -> API -> अपना authorization server चुनें -> Access Policies)।
11. Add a new access policy:
    • नाम: उदाहरण के लिए API Client Access
    • विवरण: उदाहरण के लिए Access policy for Halo API clients
    • Assign to: ऊपर बनाया गया API Services client (step 2 से application name glasswall-halo-api द्वारा खोजें)
12. Add a rule:
    • नाम: उदाहरण के लिए Allow API Clients
    • Grant type: Client Credentials
    • अन्य settings को डिफ़ॉल्ट रहने दें या आवश्यकता अनुसार token lifetime समायोजित करें।

नोट: Client Credentials grant के लिए access policies यह नियंत्रित करती हैं कि कौन से clients (client_id के आधार पर) tokens का अनुरोध कर सकते हैं। Group membership लागू नहीं होती क्योंकि इस flow में कोई user context नहीं होता। API तक सुरक्षित access सुनिश्चित करने के लिए, अपने secrets manager के माध्यम से यह सीमित करें कि किसके पास client_id और client_secret है।

Okta के लिए API-Access service कॉन्फ़िगर करें​

cdrplatform-api-access Helm chart को आपके Okta authorization server द्वारा जारी किए गए Bearer tokens को validate करने के लिए कॉन्फ़िगर किया जाना चाहिए। chart, authentication settings को configuration values key के अंतर्गत expose करता है।

कॉन्फ़िगरेशन परिनियोजित करें​

Note: The Authority and ValidIssuer must both be set to the Okta issuer URI. The API-Access service uses Authority to discover the JWKS (JSON Web Key Set) for token signature validation, and ValidIssuer to verify the iss claim in the token.

export HALO_DOMAIN=<your-halo-domain>
helm upgrade --install cdrplatform-api-access cdrplatform-api-access --reuse-values \
  --set configuration.AuthenticationScheme="Bearer" \
  --set configuration.Authentication__Schemes__Bearer__Authority="${OKTA_ISSUER_URI:?}" \
  --set configuration.Authentication__Schemes__Bearer__ValidIssuer="${OKTA_ISSUER_URI:?}" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="${VALID_AUDIENCE:?}" \
  --set strategy.type="Recreate" \
  --set ingress.enabled=true \
  --set ingress.tls.enabled=true \
  --set ingress.tls.domain="${HALO_DOMAIN:?}" \
  --atomic

एकाधिक audiences (वैकल्पिक)​

यदि कई API clients या applications को अलग-अलग audiences के साथ Halo API तक पहुँच की आवश्यकता है, तो अतिरिक्त ValidAudiences entries जोड़ें:

  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="api://halo-api" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__1="<second-client-id>" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__2="<third-client-id>"

Halo API का उपयोग​

Bearer token प्राप्त करें​

Client Credentials flow (machine-to-machine)​

इस flow का उपयोग automated systems, CI/CD pipelines, और service-to-service integrations के लिए करें, जहाँ किसी user interaction की आवश्यकता नहीं होती।

export TOKEN_ENDPOINT="${OKTA_ISSUER_URI}/v1/token"

एक token का अनुरोध करें:

curl -s -X POST "${TOKEN_ENDPOINT}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=halo.api"

उदाहरण response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "halo.api"
}

token निकालें:

export ACCESS_TOKEN=$(curl -s -X POST "${TOKEN_ENDPOINT}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=halo.api" | jq -r '.access_token')

API अनुरोधों का प्रमाणीकरण करें​

हर API अनुरोध के Authorization header में Bearer token शामिल करें:

export HALO_API_URL="https://<your-halo-domain>"

प्रमाणीकरण सत्यापित करें​

एक सुरक्षित endpoint के साथ परीक्षण करें। token के बिना अनुरोध 401 लौटाना चाहिए, और वैध token के साथ अनुरोध 200 लौटाना चाहिए:

# Without token - expect 401
curl -s -o /dev/null -w "%{http_code}" \
  "${HALO_API_URL}/api/v1/policies"

# With token - expect 200
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  "${HALO_API_URL}/api/v1/policies"

उदाहरण: प्रोसेसिंग के लिए एक फ़ाइल सबमिट करें​

curl -s -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F "file=@/path/to/document.pdf" \
  "${HALO_API_URL}/api/v1/rebuild/file" \
  --output rebuilt_document.pdf

समस्या निवारण​