OIDC / Single Sign-On

SnapOtter single sign-on के लिए OpenID Connect (OIDC) का समर्थन करता है। Users स्थानीय username/password authentication के बजाय (या उसके साथ-साथ) Keycloak, Authentik, Google, या Microsoft Entra ID जैसे किसी बाहरी identity provider से login कर सकते हैं।

यह भी देखें

SAML SSO | SCIM Provisioning | Users, Roles और Permissions

Quick start

अपने docker-compose.yml में ये environment variables जोड़ें:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

आपके provider के लिए redirect URI हमेशा यही होता है:

${EXTERNAL_URL}/api/auth/oidc/callback

उदाहरण के लिए, यदि EXTERNAL_URL https://photos.example.com है, तो अपने provider का redirect URI https://photos.example.com/api/auth/oidc/callback के रूप में configure करें।

Configuration reference

Variable	Default	Description
OIDC_ENABLED	false	OIDC login सक्षम करें। login page पर एक "Sign in with SSO" बटन दिखाई देता है।
OIDC_ISSUER_URL		Provider का issuer URL। OIDC Discovery (/.well-known/openid-configuration) का समर्थन करना चाहिए।
OIDC_CLIENT_ID		आपके provider के साथ पंजीकृत OAuth client ID।
OIDC_CLIENT_SECRET		OAuth client secret।
OIDC_SCOPES	openid profile email	अनुरोध करने के लिए scopes की space-separated सूची।
OIDC_AUTO_CREATE_USERS	true	पहली OIDC login पर स्वतः एक स्थानीय user account बनाएँ।
OIDC_DEFAULT_ROLE	user	स्वतः बनाए गए OIDC users को सौंपी गई role। admin, editor, या user में से एक।
OIDC_AUTO_LINK_USERS	false	यदि email पता मेल खाता है तो किसी OIDC पहचान को मौजूदा स्थानीय user से जोड़ें।
OIDC_PROVIDER_NAME		login बटन पर दिखाया गया display नाम (उदा. "Keycloak", "Google")। यदि खाली हो, तो बटन "SSO" कहता है।
OIDC_CLOCK_TOLERANCE	30	token validation के लिए सेकंड में clock skew सहनशीलता।
OIDC_USERNAME_CLAIM	preferred_username	नए accounts के लिए username के रूप में उपयोग किया जाने वाला ID token claim।
EXTERNAL_URL		वह सार्वजनिक URL जहाँ SnapOtter पहुँच योग्य है। सही redirect URI बनाने के लिए OIDC के लिए आवश्यक।
COOKIE_SECRET	स्वतः-जनरेटेड	session cookies पर हस्ताक्षर करने के लिए secret। अनेक replicas चलाते समय इसे स्पष्ट रूप से सेट करें।

Provider guides

Keycloak

1. एक नया realm बनाएँ (या किसी मौजूदा का उपयोग करें)।
2. Clients पर जाएँ और एक नया client बनाएँ:
   • Client ID: snapotter
   • Client authentication: On (confidential)
   • Authentication flow: Standard flow (Authorization Code)
3. client के Settings टैब के अंतर्गत, Valid redirect URIs को अपने callback URL पर सेट करें (उदा. https://photos.example.com/api/auth/oidc/callback)।
4. Credentials टैब से Client secret कॉपी करें।
5. OIDC_ISSUER_URL को https://keycloak.example.com/realms/your-realm पर सेट करें।

Authentik

1. admin interface में, Applications > Providers पर जाएँ और एक नया OAuth2/OpenID Provider बनाएँ।
   • Client type: Confidential
   • Redirect URIs: आपका callback URL
   • Signing key: कोई मौजूदा key चुनें या एक बनाएँ
2. एक Application बनाएँ और उसे provider से लिंक करें।
3. provider settings से Client ID और Client Secret कॉपी करें।
4. OIDC_ISSUER_URL को https://authentik.example.com/application/o/snapotter/ पर सेट करें (अंत का slash मायने रखता है)।

Google

1. Google Cloud Console पर जाएँ।
2. एक project बनाएँ (या किसी मौजूदा को चुनें)।
3. APIs & Services > OAuth consent screen पर जाएँ और उसे configure करें।
4. APIs & Services > Credentials पर जाएँ और एक OAuth 2.0 Client ID बनाएँ:
   • Application type: Web application
   • Authorized redirect URIs: आपका callback URL
5. Client ID और Client secret कॉपी करें।
6. OIDC_ISSUER_URL को https://accounts.google.com पर सेट करें।
7. OIDC_USERNAME_CLAIM को email पर सेट करें (Google preferred_username प्रदान नहीं करता)।

Azure AD / Entra ID

1. Azure portal में, Microsoft Entra ID > App registrations > New registration पर जाएँ।
2. app का नाम "SnapOtter" रखें। Redirect URI के अंतर्गत, Web platform चुनें और अपना callback URL दर्ज करें (उदा. https://photos.example.com/api/auth/oidc/callback)। Single-page application न चुनें: SnapOtter एक client secret से authenticate करता है, जिसे Entra ID SPA registrations पर अस्वीकार कर देता है।
3. Overview पृष्ठ से Application (client) ID और Directory (tenant) ID कॉपी करें।
4. Certificates & secrets > New client secret पर जाएँ और secret की Value तुरंत कॉपी करें। यह केवल एक बार दिखाई जाती है, और उसके बगल वाला Secret ID secret नहीं है।
5. चरण 3 की Directory (tenant) ID का उपयोग करते हुए, OIDC_ISSUER_URL को https://login.microsoftonline.com/<tenant-id>/v2.0 पर सेट करें।
6. OIDC_USERNAME_CLAIM को उसके डिफ़ॉल्ट पर ही रहने दें। Entra ID preferred_username प्रदान करता है, इसलिए Google गाइड वाले email override की यहाँ आवश्यकता नहीं है।

issuer URL में हमेशा अपनी tenant ID का उपयोग करें, common या organizations का नहीं। वे multi-tenant endpoints अपने issuer के रूप में शाब्दिक template {tenantid} घोषित करते हैं, जो OIDC discovery validation में विफल हो जाता है।

WARNING

Entra ID का preferred_username user principal name को दर्शाता है, जो user का नाम बदलने या उसे किसी दूसरे tenant में ले जाने पर बदल जाता है। SnapOtter इस claim को केवल एक बार, पहली login पर पढ़ता है, इसलिए उसके बाद account का मूल username बना रहता है। दोनों ही स्थितियों में logins काम करते रहते हैं: लौटने वाले users का मिलान username से नहीं, बल्कि token के स्थिर subject से किया जाता है।

Entra ID पर switch करने से password login बंद नहीं होता। स्थानीय login को अक्षम करना देखें।

Okta और अन्य providers

OIDC Discovery का समर्थन करने वाला कोई भी provider इसी तरह काम करता है: अपने callback URL के साथ एक confidential web client बनाएँ, फिर OIDC_ISSUER_URL को issuer पर इंगित करें। Okta के लिए, OIDC - OpenID Connect sign-in method और Web Application type के साथ एक app बनाएँ, फिर अपने Okta domain को issuer के रूप में उपयोग करें (उदा. https://your-company.okta.com)।

SnapOtter identity provider groups को roles से map नहीं करता। नए SSO users को OIDC_DEFAULT_ROLE मिलती है, admins Settings > Users के अंतर्गत roles बदलते हैं, और OIDC_SCOPES के माध्यम से group claims का अनुरोध करने का कोई प्रभाव नहीं होता।

User provisioning

Auto-create

जब OIDC_AUTO_CREATE_USERS true हो (डिफ़ॉल्ट), तो जब कोई पहली बार OIDC के माध्यम से login करता है तब एक स्थानीय user account बनाया जाता है। username OIDC_USERNAME_CLAIM द्वारा निर्दिष्ट claim से लिया जाता है, और role OIDC_DEFAULT_ROLE पर सेट होती है।

यदि username टकराव होता है, तो एक संख्यात्मक suffix जोड़ा जाता है (उदा. jane jane_2 बन जाता है)।

Auto-link

जब OIDC_AUTO_LINK_USERS true हो, तो यदि email पते मेल खाते हैं तो SnapOtter किसी OIDC पहचान को मौजूदा स्थानीय account से जोड़ देता है। यह तब उपयोगी है जब आपके पास पहले से बनाए गए user accounts हैं और आप चाहते हैं कि वे अपना data खोए बिना SSO का उपयोग शुरू करें।

WARNING

auto-link केवल तभी सक्षम करें जब आप अपने OIDC provider पर email पतों को सत्यापित करने के लिए भरोसा करते हों। एक असत्यापित email किसी को दूसरे user के account पर कब्ज़ा करने की अनुमति दे सकता है।

स्थानीय login को अक्षम करना

OIDC स्थानीय username/password login को अक्षम नहीं करता। दोनों विधियाँ उपलब्ध रहती हैं। यदि OIDC provider पहुँच से बाहर हो तो Admins अब भी स्थानीय credentials से login कर सकते हैं।

Self-signed certificates

यदि आपका OIDC provider एक self-signed या निजी CA certificate का उपयोग करता है, तो CA bundle को container में mount करें और NODE_EXTRA_CA_CERTS को उस पर इंगित करें:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    volumes:
      - ./my-ca.pem:/etc/ssl/certs/custom-ca.pem:ro
    environment:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/custom-ca.pem
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.internal.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

DANGER

NODE_TLS_REJECT_UNAUTHORIZED=0 सेट न करें। यह सभी TLS verification को अक्षम कर देता है और एक सुरक्षा जोखिम है।

सादे http वाले issuer

SnapOtter http:// issuer URL तभी स्वीकार करता है जब EXTERNAL_URL भी सादा http हो, जो लोकल या LAN टेस्ट सेटअप के लिए ठीक है। ऐसे में discovery, लॉगिन कोड का आदान-प्रदान और टोकन नेटवर्क पर बिना एन्क्रिप्शन के जाते हैं, इसलिए SnapOtter स्टार्टअप पर issuer होस्ट के नाम के साथ एक चेतावनी लॉग करता है। https:// वाले EXTERNAL_URL के साथ, http issuer को साइन-इन के समय अस्वीकार कर दिया जाता है और स्टार्टअप चेतावनी यह बताती है। दोनों ही स्थितियों में समाधान है अपने identity provider को https पर चलाना।

Troubleshooting

Redirect URI mismatch

सबसे आम त्रुटि। आपका provider जो अपेक्षा करता है और SnapOtter जो भेजता है, उनके बीच इन अंतरों की जाँच करें:

• http बनाम https - scheme बिल्कुल मेल खाना चाहिए
• अंत का slash - कुछ providers इस बारे में सख्त होते हैं
• Port number - यदि यह non-standard हो तो port शामिल करें
• Path - /api/auth/oidc/callback होना चाहिए

EXTERNAL_URL को दोबारा जाँचें। यह उस URL से मेल खाना चाहिए जो users अपने browser में टाइप करते हैं।

UNABLE_TO_VERIFY_LEAF_SIGNATURE

OIDC provider एक ऐसे certificate का उपयोग कर रहा है जिस पर Node.js भरोसा नहीं करता। ऊपर Self-signed certificates देखें।

Clock skew त्रुटियाँ

यदि आपके server की घड़ी और OIDC provider की घड़ी असंगत हैं, तो token validation विफल हो सकती है। OIDC_CLOCK_TOLERANCE बढ़ाएँ (डिफ़ॉल्ट 30 सेकंड है)। एक बेहतर समाधान दोनों मशीनों पर NTP चलाना है।

"OIDC provider unreachable"

SnapOtter startup पर और login के दौरान provider का discovery document लाता है। जाँचें:

• Docker container के भीतर से DNS resolution (docker exec snapotter nslookup auth.example.com)
• container और provider के बीच Firewall नियम
• OIDC_ISSUER_URL मान - यह server से पहुँच योग्य होना चाहिए, केवल आपके browser से नहीं

Missing claims

यदि login के बाद usernames या emails खाली हैं, तो हो सकता है आपका provider अपेक्षित claims न लौटा रहा हो। सत्यापित करें:

• OIDC_SCOPES में configure किए गए scopes में profile और email शामिल हैं
• provider को ID token में OIDC_USERNAME_CLAIM द्वारा निर्दिष्ट claim शामिल करने के लिए configure किया गया है
• कुछ providers को claims जारी करने के लिए स्पष्ट mapper/scope configuration की आवश्यकता होती है