SSD Nodes Learn Hosting plans →
নির্দেশিকা Matt Connorদ্বারা Matt Connor · আপডেট করা হয়েছে 2026-11-06

oauth2-proxy ব্যবহার করে যেকোনো অ্যাপে SSO যুক্ত করার নিয়ম

oauth2-proxy এবং forward auth ব্যবহার করে লগইনহীন অ্যাপে SSO যুক্ত করুন। Nginx বা Traefik-এর মাধ্যমে OIDC ইন্টিগ্রেশন করার সময় cookie ও redirect সংক্রান্ত জটিলতা এড়ানোর উপায় জানুন।

Forward auth: login ছাড়া কোনো অ্যাপে SSO কীভাবে কাজ করে

oauth2-proxy এমন একটি অ্যাপ্লিকেশনে single sign-on দেয়, যার নিজস্ব login ব্যবস্থা নেই। এটি কাজ করে কারণ অ্যাপ্লিকেশনের সামনে থাকা reverse proxy প্রতিটি request থামায়, request-এ বৈধ session আছে কি না তা oauth2-proxy-কে জিজ্ঞেস করে, এবং উত্তর হ্যাঁ হলেই request upstream-এ পাঠায়। অ্যাপ্লিকেশনের code পরিবর্তন করতে হয় না, কারণ অ্যাপ্লিকেশনটি কখনো এই check দেখতে পায় না।

এই check-এর জন্য আরও একটি HTTP request লাগে। proxy incoming request-এর header-এর একটি অনুলিপি /oauth2/auth-এ পাঠায় এবং status code পড়ে। 202 হলে check সফল হয়েছে, তাই proxy মূল request-টি app-এ পাঠায়। 401 হলে বৈধ session নেই, তাই proxy browser-কে /oauth2/sign_in-এ পাঠায়; এটি defaultভাবে একটি login page দেখায়। /oauth2/start আপনার identity provider-এ OpenID Connect (OIDC) login শুরু করে; skip_provider_button = true ব্যবহার করলে /oauth2/sign_in এটি স্বয়ংক্রিয়ভাবে শুরু করে। OIDC হলো OAuth 2.0-এর ওপর নির্মিত identity layer, আর provider হলো login-এর জন্য আপনি আগে থেকেই যে service চালান।

প্রতিটি reverse proxy-তে এই pattern-এর একটি নির্দিষ্ট নাম আছে। Nginx-এ directive-টির নাম auth_request। Traefik-এ middleware-টির নাম forwardAuth। Caddy-তে এটি forward_auth নামে লেখা হয়। Sub-request-এর উত্তর দেওয়া service-টিও পরিবর্তন করা যায়। oauth2-proxy সাধারণ পছন্দ, কারণ এটি সরাসরি OIDC সমর্থন করে এবং নিজস্ব কোনো database প্রয়োজন হয় না।

কোনো configuration লেখার আগে trust boundary নির্ধারণ করুন

সফল check-এর পরে oauth2-proxy response header হিসেবে identity ফেরত দেয়, এবং reverse proxy সেই header-গুলো upstream request-এ কপি করে। set_xauthrequest enabled থাকলে আপনি X-Auth-Request-User এবং X-Auth-Request-Email পান। application এই header-গুলো পড়ে এবং সেগুলোকে বিশ্বাস করে।

এটাই সম্পূর্ণ security model। তাই এর পরিণতি স্পষ্টভাবে বুঝুন। যে কোনো client application port-এ TCP connection খুলতে পারলে নিজেই এই header-গুলো সেট করে যেকোনো user হিসেবে পরিচয় দিতে পারে। application-এ সরাসরি পৌঁছাতে পারলে একটি মাত্র curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/-ই সম্পূর্ণ bypass ঘটাতে যথেষ্ট।

তাই proxy ছাড়া application-এ পৌঁছানো যাবে না। Docker Compose-এ app service থেকে ports: mapping মুছে দিন এবং service-টিকে internal network-এ রাখুন, যাতে শুধু proxy container-ই সেটিতে connection করতে পারে। bare host-এ app-কে 0.0.0.0:3000-এর পরিবর্তে 127.0.0.1:3000-এ bind করুন। এরপর বাস্তবে কী expose করেছেন তা পরীক্ষা করুন:

sudo ss -tlnp | grep 3000

0.0.0.0:3000 লেখা একটি line-এর অর্থ হলো app public IP-তে request গ্রহণ করছে এবং আপনার gate কেবল আনুষ্ঠানিক ব্যবস্থা। 127.0.0.1:3000-ই প্রত্যাশিত ফল। Firewall rule একটি কার্যকর দ্বিতীয় স্তর, কিন্তু bind address-ই এমন নিয়ন্ত্রণ যা অন্য কোনো tool ruleset flush করলেও বহাল থাকে।

oauth2-proxy ইনস্টল করুন

October 2026 অনুযায়ী বর্তমান release হলো v7.15.5, যা 1 October 2026-এ প্রকাশিত হয়েছে। এটি দুটি critical security advisory-এর সমাধান করে। এর একটি হলো skip_auth_routes-এর bypass, যা v7.5.0-এর পরের প্রতিটি release-কে প্রভাবিত করে। তাই এর চেয়ে পুরোনো কোনো release ইনস্টল করবেন না। binary ইনস্টল করে download যাচাই করুন:

cd /tmp
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
sha256sum -c oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
tar -xzf oauth2-proxy-v7.15.5.linux-amd64.tar.gz
sudo install -m 755 oauth2-proxy-v7.15.5.linux-amd64/oauth2-proxy /usr/local/bin/oauth2-proxy
oauth2-proxy --version

sha256sum -c-এর output-এর একটি লাইন অবশ্যই OK দিয়ে শেষ হতে হবে। যদি FAILED দেখা যায়, binary চালানোর পরিবর্তে থামুন এবং আবার download করুন।

Docker-এ image হলো quay.io/oauth2-proxy/oauth2-proxy। Tag নির্দিষ্ট করে ব্যবহার করুন: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5। এটি latest-এ রেখে দিলে নিয়মিত docker compose pull করার সময় সার্ভারের প্রতিটি app-এর সুরক্ষা দেওয়া একমাত্র process-টি অনিচ্ছাকৃতভাবে upgrade হয়ে যেতে পারে।

কুকি secret তৈরি করুন

Session cookie এনক্রিপ্ট করা থাকে, এবং cookie_secret হলো সেই key। Encryption key-এর দৈর্ঘ্য অবশ্যই 16, 24 অথবা 32 bytes হতে হবে, কারণ এটি একটি AES (advanced encryption standard) key হিসেবে ব্যবহৃত হয়। oauth2-proxy এমন একটি URL-safe base64 value গ্রহণ করে, যা decode করলে এই দৈর্ঘ্যগুলোর একটিতে পরিণত হয়। এই দৈর্ঘ্যগুলোর একটির সমান raw secret-ও গ্রহণ করে। অন্যথায় এটি শুরু হতে অস্বীকার করে এবং startup error-এ cookie secret-এর কথা উল্লেখ করে। নিচের command-টি 32-byte key encode করে 44-character value তৈরি করে।

openssl rand -base64 32 | tr -- '+/' '-_'

tr cosmetic নয়। এটি standard base64-কে সেই URL-safe alphabet-এ রূপান্তর করে, যেটি oauth2-proxy secret decode করার সময় ব্যবহার করে।

এই value-এর ক্ষেত্রে দুটি নিয়ম মানুন। প্রতিটি deployment-এর জন্য আলাদা secret ব্যবহার করুন। একই domain-এর পেছনে একাধিক oauth2-proxy instance চালালে সব instance-এ একই secret দিন, কারণ একটি instance দ্বারা encrypted cookie অন্য instance-গুলোর পড়তে সক্ষম হওয়া দরকার।

oauth2-proxy-এর কনফিগারেশন লিখুন

দীর্ঘ command line-এর বদলে settings একটি ফাইলে রাখুন, যাতে client secret কখনো ps output-এ দেখা না যায়।

# /etc/oauth2-proxy/oauth2-proxy.cfg
http_address = "127.0.0.1:4180"
reverse_proxy = true

provider = "oidc"
oidc_issuer_url = "https://id.example.com/application/o/myapp/"
client_id = "REPLACE_ME"
client_secret = "REPLACE_ME"

redirect_url = "https://app.example.com/oauth2/callback"
cookie_secret = "REPLACE_ME"
cookie_secure = true
cookie_domains = [".example.com"]
whitelist_domains = [".example.com"]

email_domains = ["*"]
set_xauthrequest = true
upstreams = ["static://202"]

reverse_proxy = true oauth2-proxy-কে তার সামনে থাকা proxy থেকে আসা X-Forwarded-* header বিশ্বাস করতে বলে। এটি না থাকলে oauth2-proxy proxy-এর নিজস্ব address-কে client address ধরে নেয় এবং request-টি HTTPS-এর মাধ্যমে এসেছে কি না ভুলভাবে নির্ধারণ করতে পারে।

trusted_proxy_ips নির্ধারণ করে কোন peer ওই header সরবরাহ করতে পারবে। এর default সব source-কে trust করে। এখানে এটি নিরাপদ, কারণ http_address oauth2-proxy-কে 127.0.0.1-এ সীমাবদ্ধ রাখে। oauth2-proxy যদি Docker network-এ listen করে, তাহলে এর মান reverse proxy-এর address দিন।

upstreams = ["static://202"] oauth2-proxy-কে authenticated request-এর জন্য 202 response দিতে এবং কোনো কিছু proxy না করতে বলে। forward auth-এর জন্য এটিই প্রয়োজন, কারণ reverse proxy-ই proxying করে। অন্য deployment পদ্ধতিতে upstreams = ["http://127.0.0.1:3000"] ব্যবহার করে এবং কোনো auth_request ছাড়াই oauth2-proxy-কে সরাসরি request path-এ রাখা হয়। একটি app-এর জন্য এটি সহজ, কিন্তু দশটি app-এর ক্ষেত্রে এটি scale করে না।

email_domains = ["*"] provider যেসব address authenticate করবে, সেগুলো সব অনুমোদন করে। এটিকে নিজের domain-এ সীমাবদ্ধ করুন। আরও ভালো হয় provider-এ group binding ব্যবহার করে access সীমিত করলে, কারণ মানুষজনের access আপনি ইতিমধ্যেই provider-এ পরিচালনা করেন।

systemd-এর মাধ্যমে আলাদা user হিসেবে এটি চালান:

# /etc/systemd/system/oauth2-proxy.service
[Unit]
Description=oauth2-proxy
After=network-online.target
Wants=network-online.target

[Service]
User=oauth2-proxy
Group=oauth2-proxy
ExecStart=/usr/local/bin/oauth2-proxy --config=/etc/oauth2-proxy/oauth2-proxy.cfg
Restart=on-failure
ProtectSystem=strict
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
sudo useradd --system --no-create-home --shell /usr/sbin/nologin oauth2-proxy
sudo install -d -m 750 /etc/oauth2-proxy
sudo chown -R oauth2-proxy:oauth2-proxy /etc/oauth2-proxy
sudo chmod 600 /etc/oauth2-proxy/oauth2-proxy.cfg
sudo systemctl daemon-reload
sudo systemctl enable --now oauth2-proxy
curl -s http://127.0.0.1:4180/ping

/ping OK print করলে বোঝা যায় যে process শুরু হয়েছে এবং config load করেছে। এটি oauth2-proxy-এর নিজস্ব health endpoint এবং এখানে কখনো session প্রয়োজন হয় না। কোনো response না এলে journalctl -u oauth2-proxy -n 50 পরীক্ষা করুন, কারণ ভুল issuer URL এবং ভুল দৈর্ঘ্যের cookie secret—দুটিই startup-এ ব্যর্থ হয় এবং উভয় ক্ষেত্রেই কারণটি দেখায়।

আপনার provider-এ redirect URI নিবন্ধন করুন

আপনার provider-এ একটি OIDC application তৈরি করুন এবং এর redirect URI config-এর redirect_url-এর সঙ্গে হুবহু মিলিয়ে সেট করুন: https://app.example.com/oauth2/callback। হুবহু মিল বলতে scheme, host, port এবং path—সবকটি অক্ষর-অনুযায়ী একই হতে হবে। শেষে slash থাকলে সেটি ভিন্ন URI হিসেবে গণ্য হয়।

পুরো setup-এ এটিই সবচেয়ে সাধারণ ব্যর্থতা। oauth2-proxy কোনো ভূমিকা নেওয়ার আগেই এটি ব্যর্থ হয়। provider authorisation request প্রত্যাখ্যান করে এবং নিজের error page দেখায়। তাই oauth2-proxy log-এ কিছু দেখা যায় না। বিষয়টি বোঝার উপায় হলো address bar দেখা: browser তখনও আপনার provider-এর domain-এ থাকে, এবং query string-এ error=invalid_request থাকে অথবা page-এ সরাসরি redirect_uri লেখা থাকে। এমন হলে proxy config নয়, provider-এর application record ঠিক করুন।

Provider থেকে issuer URL কপি করুন; নিজে টাইপ করবেন না। oauth2-proxy oidc_issuer_url-এর সঙ্গে /.well-known/openid-configuration যোগ করে startup-এর সময় সেই discovery document সংগ্রহ করে। আগে নিজেই পরীক্ষা করুন:

curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400

authorization_endpoint key থাকা JSON হলো প্রাথমিক যাচাই। Document-এর issuer-কেও অবশ্যই oidc_issuer_url-এর সঙ্গে হুবহু মিলতে হবে। 404 বা HTML error page দেখা গেলে URL ভুল। একই 404-এ oauth2-proxy-ও start হতে ব্যর্থ হবে। এখনো provider নির্বাচন না করে থাকলে, Keycloak, Authentik এবং Zitadel-এর তুলনা-তে বিভিন্ন trade-off ব্যাখ্যা করা হয়েছে। আর নিজের SSO server হিসেবে Authentik চালানো-এ এই setup-এর provider অংশটি ধাপে ধাপে দেখানো হয়েছে।

Nginx: auth_request

Nginx `auth_request` ব্যবহার করে forward auth করে। এটি একটি internal sub-request পাঠায় এবং তার status code অনুযায়ী পরবর্তী ধাপ নির্ধারণ করে।

# in the http context, next to your other maps
map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

server {
  listen 443 ssl;
  server_name app.example.com;

  location /oauth2/ {
    proxy_pass       http://127.0.0.1:4180;
    proxy_set_header Host                    $host;
    proxy_set_header X-Real-IP               $remote_addr;
    proxy_set_header X-Auth-Request-Redirect $request_uri;
  }

  location = /oauth2/auth {
    proxy_pass       http://127.0.0.1:4180;
    proxy_set_header Host             $host;
    proxy_set_header X-Real-IP        $remote_addr;
    proxy_set_header X-Forwarded-Uri  $request_uri;
    proxy_set_header Content-Length   "";
    proxy_pass_request_body           off;
  }

  location / {
    auth_request /oauth2/auth;
    error_page 401 = @oauth2_signin;

    auth_request_set $user  $upstream_http_x_auth_request_user;
    auth_request_set $email $upstream_http_x_auth_request_email;
    proxy_set_header X-User  $user;
    proxy_set_header X-Email $email;

    auth_request_set $auth_cookie $upstream_http_set_cookie;
    add_header Set-Cookie $auth_cookie;

    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host       $host;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
  }

  location @oauth2_signin {
    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
  }
}

এই configuration-এ তিনটি বিষয় গুরুত্বপূর্ণ। খালি `Content-Length সহ proxy_pass_request_body off` ব্যবহার করলে nginx authentication endpoint-এ request body পাঠায় না। ওই endpoint-এর শুধু headers প্রয়োজন।

`auth_request_set $auth_cookie এবং add_header Set-Cookie একসঙ্গে refreshed session cookie browser-এ ফেরত পাঠায়। এগুলো বাদ দিলে cookie_refresh নীরবে কোনো কাজ করে না। কারণ nginx sub-request-এর Set-Cookie` বাতিল করে দেয়। ফলে session মেয়াদ শেষ না হওয়া পর্যন্ত browser পুরোনো value ব্যবহার করে। এই জোড়া একটি cookie পরিচালনা করে। একাধিক অংশে বিভক্ত session cookie হলে অন্য অংশগুলোর জন্য অতিরিক্ত handling অথবা Redis session storage প্রয়োজন।

`error_page 401 = @oauth2_signin failed check-কে login flow-এ পরিণত করে। এটি না থাকলে unauthenticated visitor শুধু একটি ফাঁকা 401 Authorization Required` page পায় এবং এগোনোর কোনো উপায় থাকে না।

Reload করার আগে সব সময় test করুন:

sudo nginx -t && sudo systemctl reload nginx

চারপাশের directive-গুলো নতুন হলে nginx reverse proxy config-এর গঠন এই স্তরের নিচের layer ব্যাখ্যা করে।

Traefik: forwardAuth middleware

Traefik-এর একই কাজের জন্য দুটি middleware প্রয়োজন। একটি check চালায়। অন্যটি check ব্যর্থ হলে login page পরিবেশন করে।

# dynamic configuration
http:
  middlewares:
    oauth-auth:
      forwardAuth:
        address: https://oauth.example.com/oauth2/auth
        trustForwardHeader: true
    oauth-errors:
      errors:
        status:
          - "401-403"
        service: oauth-backend
        query: "/oauth2/sign_in?rd={url}"

আপনার app-এর সামনে থাকা router-এ দুটিকেই সংযুক্ত করুন। সেখানে oauth-errors-কে oauth-auth-এর আগে রাখুন। oauth2-proxy-কে oauth.example.com-এ নিজস্ব router-এ publish করুন, কারণ check ছাড়াই browser-কে /oauth2/sign_in এবং /oauth2/callback-এ পৌঁছাতে হবে। এই পৃথক login host-এর জন্য redirect_url-কে https://oauth.example.com/oauth2/callback সেট করুন এবং provider-এর কাছে সেই URI register করুন।

উপরের oauth2-proxy config ব্যবহার করলে /oauth2/sign_in একটি login page দেখায়। এর পরিবর্তে স্বয়ংক্রিয় redirect করতে চাইলে oauth2-proxy-তে skip_provider_button = true সেট করুন এবং Traefik-এর errors settings-এর অধীনে statusRewrites: {"401": 302} যোগ করুন। এই rewrite না থাকলে Traefik 401 status-সহ automatic redirect ফেরত দেয় এবং browser সেটি অনুসরণ করে না। শুধু rewrite যোগ করলে login flow শুরু হয় না।

trustForwardHeader: true incoming X-Forwarded-* header-কে trust করে; Traefik মূল host এবং URI oauth2-proxy-তে পাঠায়। বর্তমান Traefik documentation-এ এই option-টি deprecated। সেই host-টিকেও অন্তর্ভুক্ত করতে whitelist_domains সেট করুন। তা না হলে oauth2-proxy open-redirect ঝুঁকি হিসেবে rd parameter বাদ দেয় এবং login-এর পরে সবাই /-এ পৌঁছায়। একটি Traefik server সাধারণত একসঙ্গে একাধিক app-এর সামনে থাকে। একটি Traefik instance-এর মাধ্যমে একাধিক Docker Compose app route করা অংশে এই ব্যবস্থায় ব্যবহারযোগ্য router layout দেখানো হয়েছে।

Caddy: forward_auth

app.example.com {
  handle /oauth2/* {
    reverse_proxy 127.0.0.1:4180 {
      header_up X-Real-IP {remote_host}
      header_up X-Forwarded-Uri {uri}
    }
  }
  handle {
    forward_auth 127.0.0.1:4180 {
      uri /oauth2/auth
      header_up X-Real-IP {remote_host}
      copy_headers X-Auth-Request-User X-Auth-Request-Email
      @error status 401
      handle_response @error {
        redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
      }
    }
    reverse_proxy 127.0.0.1:3000
  }
}

এখানে ক্রম গুরুত্বপূর্ণ। /oauth2/* block-টি প্রথমে আসে এবং এতে কোনো forward_auth নেই, কারণ লগ ইন না করা visitor-কে sign-in ও callback path-এ পৌঁছাতে হয়। এই path-গুলোর সামনে check বসালে browser হাল ছেড়ে দেওয়া পর্যন্ত login redirect নিজেকেই বারবার নির্দেশ করে।

copy_headers upstream request-এ identity পাঠায়, এবং oauth2-proxy set_xauthrequest = true নিয়ে চললে তবেই এটি মান তৈরি করে। কোন proxy ব্যবহার করবেন, তা আলাদা সিদ্ধান্তের বিষয়। nginx, Caddy ও Traefik-এর তুলনা এই বিষয়টি ব্যাখ্যা করে।

লগইন কেন আবার লগইন পেজে ফিরে যায়?

আপনি provider-এ sign in করেন, provider আপনাকে ফেরত পাঠায়, এরপর oauth2-proxy আপনাকে আবার login পেজে পাঠায়। এর অর্থ হলো, পরের request-এ oauth2-proxy কোনো বৈধ session গ্রহণ করছে না। Session cookie অনুপস্থিত হতে পারে। Cookie উপস্থিত থাকলেও validation ব্যর্থ হতে পারে, যেমন একাধিক instance ভিন্ন cookie secret ব্যবহার করলে। Browser-এর developer tools খুলুন। Provider থেকে redirect হয়ে ফেরার পর /oauth2/callback-এ পাঠানো request খুঁজুন এবং তার Set-Cookie response header দেখুন। সেখানে set করা cookie যদি পরের request-এ অনুপস্থিত থাকে, তাহলে browser ওই cookie প্রত্যাখ্যান করছে। Cookie উপস্থিত থাকলে validation error-এর জন্য server log পরীক্ষা করুন, যেমন cookie signature not valid, এবং নিশ্চিত করুন যে সব instance একই secret ব্যবহার করছে।

যে cookie অনুপস্থিত হচ্ছে সেটি যদি oauth2-proxy বাইরে যাওয়ার সময় set করা CSRF cookie হয়, তাহলে flow loop করে না। এটি callback-এ থেমে যায় এবং log-এ কারণটি দেখা যায়:

No cookies were found in OAuth callback.

অথবা অন্য কোনো cookie পৌঁছালেও সঠিক cookie না পৌঁছালে:

Cookies were found in OAuth callback, but none was a CSRF cookie.

CSRF-এর অর্থ cross-site request forgery। Login শুরু করা request-এর সঙ্গে callback যুক্ত করার জন্য এই cookie ব্যবহৃত হয়। Browser নিচের বার্তাসহ একটি 403 error page দেখায়:

Login Failed: Unable to find a valid CSRF token. Please try again.

নিচের প্রথম তিনটি কারণেই cookie অনুপস্থিত হতে পারে। Clock drift validation ব্যর্থতার আরেকটি কারণ। এই চারটি কারণ ক্রমানুসারে পরীক্ষা করুন।

  1. Browser plain HTTP-এর মাধ্যমে site-এ পৌঁছালেও cookie_secure = true সেট করা আছে। localhost ছাড়া অন্য ক্ষেত্রে browser Secure চিহ্নিত cookie কোনো http:// origin-এ সংরক্ষণ করবে না। তাই cookie-টি আর ফেরত পাঠানো হবে না। TLS (transport layer security) সঠিকভাবে terminate করুন। অথবা localhost-এ testing করার সময়ই শুধু cookie_secure = false সেট করুন।
  2. এমন একটি cookie_domains value ব্যবহার করা হয়েছে যা address bar-এর hostname-কে অন্তর্ভুক্ত করে না। .example.com, app.example.com-কে অন্তর্ভুক্ত করে, কিন্তু app.example.net-এর ক্ষেত্রে একেবারেই কার্যকর নয়।
  3. Browser cookie-টি বাদ দিচ্ছে। Strict privacy extension বা third-party cookie blocking outbound redirect এবং callback-এর মধ্যবর্তী সময়ে _oauth2_proxy_csrf সরিয়ে দিতে পারে। পরে session cookie-ও সরিয়ে দিতে পারে।
  4. Clock drift। Server clock provider-এর clock-এর তুলনায় অনেক এগিয়ে থাকলে ID token-কে expired মনে হতে পারে এবং validation ব্যর্থ হতে পারে। timedatectl-এ System clock synchronized: yes দেখানো উচিত।

আরেকটি কারণেও কোনো configuration ভুল না থাকলেও CSRF error হতে পারে। Default অবস্থায় oauth2-proxy একটি মাত্র CSRF cookie রাখে। তাই একই সময়ে দুটি tab login শুরু করলে তারা একে অন্যের cookie overwrite করে। cookie_csrf_per_request = true প্রতিটি login-এর জন্য আলাদা cookie দেয়।

অনুমান না করে server side থেকে ঘটনাটি পর্যবেক্ষণ করুন:

sudo journalctl -u oauth2-proxy -f

একটি private window-এ app খুলুন। প্রতিটি request-এর status log করা হবে। তাই callback-এর পরপরই login-এ আরেকটি redirect দেখা গেলে সেটিই loop। লগে এর প্রমাণ থাকবে।

লগইন এড়িয়ে চলা আবশ্যক এমন path: APIs, webhooks এবং websockets

Forward auth ধরে নেয় যে browser-এ একটি cookie আছে। Browser ছাড়া caller হলে এটি কাজ করে না।

Authorization: Bearer <token> পাঠানো API client-এর কোনো cookie থাকে না। তাই bearer-token authentication সক্রিয় না থাকলে উপরের proxy configuration-গুলো তাকে oauth2-proxy-এর login page-এ পাঠায়। এর দুটি পরিষ্কার সমাধান আছে। skip_jwt_bearer_tokens = true সেট করলে oauth2-proxy configured issuer থেকে আসা বৈধ JWT (JSON web token) bearer token গ্রহণ করে, যদি সেই token-এ এই client-এর জন্য গ্রহণযোগ্য audience থাকে। API client-গুলো provider থেকে ইতিমধ্যে উপযুক্ত token পেলে এটিই সঠিক পদ্ধতি। Token-এর aud-এর মান client_id অথবা extra_jwt_issuers-এর মাধ্যমে configured কোনো audience-এর সঙ্গে মিলতে হবে। অন্যথায় path-টি exempt করুন:

skip_auth_routes = [
  "^/api/",
  "POST=^/webhook/",
  "GET=^/healthz$"
]

প্রতিটি value একটি regular expression। এটি query parameter বাদ দিয়ে decoded path-এর সঙ্গে মেলানো হয়। এর আগে ঐচ্ছিকভাবে একটি HTTP method এবং = দেওয়া যায়। POST=^/webhook/ webhook receiver-এ POST-এর অনুমতি দেয়, কিন্তু একই path-এ browser দিয়ে আসা ব্যবহারকারী login-এ যায়, যদি authentication request মূল method সংরক্ষণ করে। Nginx-এর auth_request এবং Caddy-এর forward_auth GET check চালায়। তাই ওই setup-গুলোতে method-specific exemption-এর জন্য reverse proxy-তে আলাদা routing প্রয়োজন। প্রতিটি entry আপনার access control-এ একটি ফাঁক তৈরি করে। তাই ^ দিয়ে expression anchor করুন এবং caller যতটা অনুমতি দেয়, ততটাই সংকীর্ণ রাখুন।

এগুলোর ওপর নির্ভর করার আগে v7.15.5 বা পরবর্তী version চালান। v7.5.0-এর পরের আগের release-গুলোতে dot segment, শুরুতে একাধিক slash অথবা semicolon ব্যবহার করা request দিয়ে protected path ভুলভাবে exempt করানো যেত (advisory GHSA-63jm-59jj-478j)। Expression anchor করলেও এটি প্রতিরোধ করা যেত না। Fixed release-টি এ ধরনের অস্পষ্ট path exempt করতে অস্বীকার করে। তাই upgrade-এর পরে আপনার public route-গুলো এখনও সঠিকভাবে match করছে কি না পরীক্ষা করুন।

Websocket-এর ক্ষেত্রে মানুষ প্রায়ই ভুল করে। Upgrade request একটি সাধারণ HTTP GET, এবং এতে অন্য request-এর মতো একই cookie থাকে। তাই এটি সাধারণ check পার হয়ে যায় এবং exemption প্রয়োজন হয় না। সমস্যা হয় এর চারপাশের proxying-এ। Protected location-এ Upgrade এবং Connection header না থাকলে upgrade সম্পূর্ণ হয় না। ফলে app-এর client বারবার retry করে এবং browser console-এ WebSocket connection ... failed message দেখায়। সেখানে path exempt করলেও সমস্যার সমাধান হয় না, কারণ request-টি ইতিমধ্যে authorised ছিল।

একটি বাস্তব সীমাবদ্ধতা আছে। Upgrade-এর সময় check একবারই চলে। ঘণ্টার পর ঘণ্টা খোলা থাকা websocket আর পুনরায় check করা হয় না। তাই provider-এ কোনো user সরিয়ে দিলেও তার আগে থেকে খোলা socket বন্ধ হয় না। Live connection বিচ্ছিন্ন করতে app restart করুন।

ডিফল্টভাবে পুরো session cookie-এর ভেতরেই থাকে এবং আপনার cookie_secret দিয়ে encrypted থাকে। এতে oauth2-proxy stateless থাকে এবং অতিরিক্ত কোনো service প্রয়োজন হয় না। তবে এর একটি সীমা আছে, কারণ browser সাধারণত cookie-এর আকার প্রায় 4 KB-এ সীমাবদ্ধ রাখে। ID token-এ group claim-এর দীর্ঘ তালিকা থাকলে oauth2-proxy session-কে _oauth2_proxy_0, _oauth2_proxy_1 এবং পরবর্তী অংশগুলোতে ভাগ করে। কয়েকটি অংশের পর request header এত বড় হয়ে যায় যে app request পাওয়ার আগেই nginx 400 Request Header Or Cookie Too Large response দেয়।

এমন হলে session server-side-এ সরিয়ে নিন:

session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"

এরপর browser-এ একটি ছোট ticket থাকে এবং encrypted session Redis-এ সংরক্ষিত থাকে। এর বিনিময়ে একটি service সব সময় চালু রাখতে হয়। Redis বন্ধ হয়ে গেলে oauth2-proxy session load করতে পারে না। সংরক্ষিত session data হারালে সবাইকে আবার login করতে হয়। Cookie store-এরও নিজস্ব সীমাবদ্ধতা আছে। একই সময়ে একই session refresh করা দুটি request পরস্পরের সঙ্গে conflict করতে পারে এবং পুনরায় login করার প্রয়োজন হতে পারে।

আপনি forward auth থেকে যা পাবেন না

এটি দরজার সামনে থাকা একটি প্রবেশ-নিয়ন্ত্রণ স্তর। এটি অ্যাপ্লিকেশনের ভেতরের authorization নয়। আপনার ক্ষেত্রে এই পদ্ধতি উপযুক্ত কি না, তা এই পার্থক্যের ওপর নির্ভর করে।

কোনো user প্রবেশ করার পর অ্যাপ্লিকেশন আগে যা দেখত, তা-ই দেখে। অ্যাপের নিজস্ব role থাকলে forward auth সেগুলো পূরণ করে না। তবে অ্যাপটি header-based authentication সমর্থন করলে এবং কোনো header-কে একটি account-এর সঙ্গে map করলে ব্যতিক্রম হতে পারে। Grafana এটি সমর্থন করে, তার auth.proxy settings-এর মাধ্যমে। বেশিরভাগ self-hosted app এটি সমর্থন করে না। তাই gate পেরিয়ে আসা সবাই অ্যাপ্লিকেশনের কাছে একই একক identity হিসেবে দেখা যায়। সেই identity প্রায়ই admin হয়।

এটি অ্যাপ্লিকেশনের নিজস্ব API token-ও সুরক্ষিত করে না। অ্যাপের দেওয়া personal access token oauth2-proxy-তে নয়, সরাসরি অ্যাপ্লিকেশনে authentication করে। তাই gate-এর সামনে এটি বসালে token-টি কাজ করা বন্ধ করে দেয়। token আবার চালু করতে API path-টি exempt করলে ওই path রক্ষার একমাত্র উপায় হয়ে যায় token। তখন একটি service-এ দুটি authentication system চালাতে হয়, এবং SSO তাদের একটিকেই কভার করে।

Revocation হলো তৃতীয় সীমাবদ্ধতা। আপনার provider-এ কোনো user মুছে দিলে নতুন login বন্ধ হয়। কিন্তু oauth2-proxy বিদ্যমান session-এর ক্ষেত্রে provider-এর সঙ্গে পরীক্ষা করে না, যতক্ষণ না cookie_refresh-এর সময় আসে। Refresh বন্ধ থাকলে session cookie expiry না হওয়া পর্যন্ত বৈধ থাকে। cookie_expire-এর default মান 168 hours। ফলে সদ্য সরিয়ে দেওয়া কোনো user আরও এক সপ্তাহ access পেতে পারে। cookie_refresh-এর মান কম রাখুন, যেমন এক hour। User-এর refresh token আর বৈধ না থাকায় provider সেই refresh প্রত্যাখ্যান করলে oauth2-proxy session মুছে দেয় এবং refresh করার চেষ্টা করা পরবর্তী request-এ নতুন login বাধ্যতামূলক করে। সব provider refresh সমর্থন করে না। তাই আপনার provider-এর সঙ্গে এটি পরীক্ষা করুন।

Audit trail-ও gate-এ এসে থেমে যায়। oauth2-proxy কে এবং কখন প্রবেশ করেছে তা log করে। অ্যাপ্লিকেশন একটি নামহীন session log করে। কে কোনো setting পরিবর্তন করেছে, তা জানার প্রয়োজন হলে অ্যাপ্লিকেশনে header identity থাকা ন্যূনতম সমাধান। প্রকৃত per-user account ব্যবহার করাই সঠিক সমাধান।

SSO-এর খরচ দেওয়াই যখন ভালো সিদ্ধান্ত

কোনো অ্যাপে একেবারেই login ব্যবস্থা না থাকলে, অথবা একটি shared password ব্যবহার করলে, এবং আপনি এক জায়গা থেকে ব্যবহারকারী যোগ ও সরাতে চাইলে forward auth সঠিক উপায়। এটি সেটআপ করতে একটি বিকেল এবং আরও একটি process লাগে। HTTP সমর্থন করে এমন যেকোনো অ্যাপের সঙ্গে এটি কাজ করে।

একই অ্যাপের ভেতরে বিভিন্ন ব্যবহারকারীর আলাদা permission প্রয়োজন হলে এটি সঠিক উপায় নয়। একটি gate এই নিয়ম প্রকাশ করতে পারে না: "Ana dashboards সম্পাদনা করতে পারবে, আর Bo শুধু সেগুলো পড়তে পারবে।" vendor যদি SSO tier বিক্রি করে, group-to-role mapping সাধারণত সেটিই যা আপনি আসলে কিনছেন। headers এবং proxy rules দিয়ে এটি পুনর্নির্মাণ করা অর্থ প্রদানের চেয়ে বেশি ভঙ্গুর। সিদ্ধান্ত নেওয়ার আগে এই SSO tier-গুলোর পেছনের pricing pattern পড়ে দেখা উপযোগী।

যে কোনো mobile বা desktop client browser cookies বহন না করলে, প্রতিটি request-এ সেটি gate-এর সঙ্গে সমস্যায় পড়বে।

FAQ

Forward auth কী?

Forward auth এমন একটি পদ্ধতি, যেখানে reverse proxy upstream-এ অনুরোধ পাঠানোর আগে প্রতিটি incoming request সম্পর্কে একটি পৃথক authentication service-এর কাছে জানতে চায়। Proxy অনুরোধের header-গুলো /oauth2/auth-এর মতো একটি endpoint-এ পাঠায় এবং status code পরীক্ষা করে। 202 অর্থ অনুরোধ অনুমোদিত, তাই মূল অনুরোধটি application-এ পৌঁছে যায়। 401 অর্থ কোনো বৈধ session নেই, তাই proxy browser-কে login page-এ redirect করে। Nginx-এ এটি auth_request directive দিয়ে, Traefik-এ forwardAuth middleware দিয়ে এবং Caddy-তে forward_auth দিয়ে বাস্তবায়ন করা হয়।

oauth2-proxy কেন আমাকে বারবার login page-এ redirect করে?

Session cookie অনুপস্থিত অথবা validation ব্যর্থ হচ্ছে। তাই প্রতিটি check-এ কোনো বৈধ session পাওয়া যাচ্ছে না এবং আপনাকে আবার login page-এ পাঠানো হচ্ছে। ভিন্ন cookie secret ব্যবহার করা instance-গুলো একে অন্যের cookie প্রত্যাখ্যান করে। আরেকটি কারণ হলো plain HTTP-তে খোলা কোনো site-এ cookie_secure = true ব্যবহার করা। কারণ localhost ছাড়া browser কোনো Secure cookie http:// origin-এ সংরক্ষণ করে না। Address bar-এ থাকা hostname-কে অন্তর্ভুক্ত করে না এমন cookie_domains value আছে কি না, সেটিও পরীক্ষা করুন। কোন cookie অনুপস্থিত তা দেখতে browser-এর developer tools-এ /oauth2/callback response-এর Set-Cookie header পড়ুন। Cookie ফেরত পাঠানো হলে validation error-এর জন্য server log পরীক্ষা করুন। অনুপস্থিত cookie যদি CSRF cookie হয়, তাহলে loop-এর পরিবর্তে Login Failed: Unable to find a valid CSRF token. Please try again. লেখা একটি 403 page দেখবেন। কোনো cookie না এলে log-এ No cookies were found in OAuth callback. লেখা থাকবে।

কীভাবে oauth2-proxy-এর মাধ্যমে কোনো API client বা webhook-কে প্রবেশের অনুমতি দেব?

Anchored regular expression সহ skip_auth_routes ব্যবহার করুন। প্রয়োজনে এটি একটি HTTP method-এর মধ্যে সীমাবদ্ধ করুন, যেমন POST=^/webhook/। এছাড়া v7.15.5 বা পরবর্তী version চালান। এই version-এ এসব exemption-এর একটি critical bypass ঠিক করা হয়েছে। Method-specific exemption-এর ক্ষেত্রে authentication request-কে মূল method সংরক্ষণ করতে হবে। Nginx এবং Caddy-এর উদাহরণগুলো GET check করে। তাই reverse proxy-এর routing-এ এসব exemption পরিচালনা করুন। আপনার API client-গুলোর কাছে configured provider দ্বারা জারি করা এবং accepted audience-সম্বলিত বৈধ JWT থাকলে skip_jwt_bearer_tokens = true cookie-এর পরিবর্তে সেই token গ্রহণ করে এবং path-টি protected রাখে। Audience-টি client_id-এর সঙ্গে মেলাতে হবে অথবা extra_jwt_issuers-এর মাধ্যমে configured audience-এর সঙ্গে মিলতে হবে। skip_auth_routes-এ তালিকাভুক্ত যেকোনো কিছু সবার জন্য unauthenticated। তাই caller যতটা অনুমতি দেয়, প্রতিটি expression ততটাই সংকীর্ণ রাখুন।

oauth2-proxy কি application-কে per-user permission দেয়?

না। এটি একটি gate, authorisation system নয়। কে application-এ পৌঁছাতে পারবে তা এটি নির্ধারণ করে। Application identity header পড়ে account-এর সঙ্গে mapping না করলে gate পার হওয়া সবাই application-এর কাছে একই রকম দেখায়। Grafana-তে auth.proxy settings-এর মাধ্যমে এটি করা যায়। অধিকাংশ self-hosted app তা পারে না। তাই gate পার হওয়া প্রত্যেক ব্যক্তি app যে একক identity নিয়ে চলছে, সেই identity-ই ব্যবহার করে।

কেউ কি নিজে identity header সেট করে oauth2-proxy এড়িয়ে যেতে পারে?

হ্যাঁ, যদি তারা application-এ সরাসরি পৌঁছাতে পারে। Identity X-Auth-Request-Email-এর মতো একটি সাধারণ header হিসেবে আসে, এবং application যা পায়, সেটিই বিশ্বাস করে। Application port-এ connection খুলতে পারা যে কেউ সেই header পাঠিয়ে যেকোনো user-এর পরিচয় নিতে পারে। App-টিকে 127.0.0.1-এ bind করুন, অথবা published port ছাড়া একটি internal Docker network-এ রাখুন। এরপর sudo ss -tlnp দিয়ে তা নিশ্চিত করুন।

এই লেখাটি কি কাজে লেগেছে?

#oauth2-proxy#sso#oidc#reverse-proxy#forward-auth