OAuth2 Proxy
O OAuth2 Proxy é um proxy reverso que autentica usuários com um provedor OIDC antes que eles alcancem sua aplicação. Ele também pode atuar como endpoint forward-auth para Nginx, Caddy ou Traefik. Com o Casdoor como provedor, você pode permitir o acesso apenas aos membros de um grupo do Casdoor ou aos usuários que possuem uma função do Casdoor.
A configuração nesta página foi testada de ponta a ponta com OAuth2 Proxy v7.15 e Casdoor v4.17.
Se você precisa apenas do login do Casdoor na frente de uma aplicação e não precisa do OAuth2 Proxy em si, o casdoor-forward-auth faz o mesmo trabalho para Traefik, Caddy e Nginx, passando os grupos e funções do usuário nos cabeçalhos das requisições.
Etapa 1: Criar a aplicação no Casdoor
-
Na organização dos seus usuários, adicione uma aplicação (ou abra uma existente).
-
Adicione o callback do OAuth2 Proxy em Redirect URLs:
https://app.example.com/oauth2/callback -
Na aba OIDC/OAuth, configure:
- Token format:
JWT-Standard - Token group format:
Name (group), para que os grupos cheguem comodevsem vez demy-org/devs
- Token format:
-
Salve e anote o Client ID e o Client secret.
Por que usar JWT-Standard: com o formato padrão JWT, um usuário cujo e-mail não foi verificado não consegue fazer login (o OAuth2 Proxy rejeita email_verified: false, e usuários criados por um administrador geralmente têm e-mail não verificado), e a claim roles contém objetos de função completos em vez de nomes de funções. Veja O que o Casdoor envia.
Etapa 2: Configurar o OAuth2 Proxy
Crie o arquivo oauth2-proxy.cfg:
provider = "oidc"
oidc_issuer_url = "https://door.example.com"
client_id = "<client ID>"
client_secret = "<client secret>"
redirect_url = "https://app.example.com/oauth2/callback"
scope = "openid email profile"
email_domains = ["*"]
cookie_secret = "<random secret>"
http_address = "0.0.0.0:4180"
upstreams = ["http://127.0.0.1:8080"]
# Let in only members of the Casdoor group "devs"
oidc_groups_claim = "groups"
allowed_groups = ["devs"]
oidc_issuer_urlé a URL do Casdoor, sem barra final. Deve ser exatamente oissuerexibido emhttps://door.example.com/.well-known/openid-configuration. O Casdoor constrói o issuer a partir deoriginemconf/app.conf, ou do host da requisição quandooriginestá vazio; se os dois forem diferentes, o OAuth2 Proxy falha comissuer did not match.cookie_secretdeve ter 16, 24 ou 32 bytes, por exemplo, a saída deopenssl rand -base64 32 | tr -- '+/' '-_'.- Mantenha o escopo
profile: o Casdoor retorna grupos e funções do seu endpoint userinfo apenas quandoprofileé concedido. upstreamsé a sua aplicação.
Inicie-o:
oauth2-proxy --config oauth2-proxy.cfg
Abra https://app.example.com. Após fazer login no Casdoor, membros de devs acessam a aplicação e todos os outros recebem 403 Forbidden.
Restringir acesso por função em vez disso
Para verificar uma função do Casdoor em vez de um grupo, leia a claim roles:
oidc_groups_claim = "roles"
allowed_groups = ["admin"]
allowed_groups então conterá nomes de funções, sem a organização.
Verificar o que o OAuth2 Proxy recebeu
Após fazer login, abra https://app.example.com/oauth2/userinfo. Ele mostra os grupos que o OAuth2 Proxy extraiu:
{"user":"d1a5f427-...","email":"alice@example.com","groups":["devs"],"preferredUsername":"alice"}
Se groups estiver vazio, o usuário não possui nenhum grupo ou função no Casdoor, ou o nome da claim está incorreto. Se contiver longas strings JSON como {"owner":"my-org","name":"admin",...}, a aplicação ainda usa o formato padrão JWT com oidc_groups_claim = "roles"; altere o formato para JWT-Standard.
O que o Casdoor envia
Como os grupos e funções do usuário chegam ao OAuth2 Proxy depende do Token format da aplicação:
| Token format | groups | roles | Unverified email |
|---|---|---|---|
JWT-Standard | from userinfo, group names | from userinfo, role names | signs in |
JWT-Custom | in the token if Groups is in Token fields | in the token if you add a token attribute roles (see below) | signs in |
JWT (default) | in the token | role objects, not usable for allowed_groups | rejected |
JWT-Empty | in the token | from userinfo, role names | signs in |
Com JWT-Standard, o próprio token carrega apenas claims OIDC padrão. O OAuth2 Proxy consulta qualquer claim ausente no token no endpoint userinfo do Casdoor, então groups e roles ainda chegam, uma vez por login.
Token group format controla os valores dos grupos em todos os formatos: ID (padrão) fornece my-org/devs, Name fornece devs, e Path fornece my-org/parent/devs para grupos aninhados.
Para colocar nomes de funções no próprio token, use JWT-Custom e adicione uma linha em Token attributes:
| Name | Category | Value | Type |
|---|---|---|---|
roles | Existing Field | Roles | Array |
Se Token fields não estiver vazio, ele também limita o que o endpoint userinfo retorna (veja Token fields). Inclua Groups (e Roles quando você lê funções do userinfo), ou deixe-o vazio.
Se você precisar manter o formato padrão JWT, adicione insecure_oidc_allow_unverified_email = true para que usuários com e-mail não verificado possam fazer login, e restrinja apenas por groups.
Passar o usuário para a sua aplicação
O OAuth2 Proxy adiciona estes cabeçalhos às requisições que encaminha (pass_user_headers, ativado por padrão):
| Header | Value |
|---|---|
X-Forwarded-User | Casdoor user ID (the sub claim) |
X-Forwarded-Preferred-Username | Nome de usuário do Casdoor, ex.: alice |
X-Forwarded-Email | Email address |
X-Forwarded-Groups | Groups (or roles), comma separated |
Certifique-se de que sua aplicação seja acessível apenas através do OAuth2 Proxy, caso contrário, qualquer pessoa pode enviar esses cabeçalhos diretamente.
Para usar o OAuth2 Proxy como endpoint de autenticação direta do Nginx (auth_request), Caddy (forward_auth) ou Traefik (forwardAuth) em vez de como proxy reverso, aponte o proxy para o endpoint /oauth2/auth; veja Integrations na documentação do OAuth2 Proxy.
Solução de problemas
| Symptom | Cause and fix |
|---|---|
issuer did not match the issuer returned by provider at startup | oidc_issuer_url differs from the issuer in Casdoor's discovery document. Set origin in Casdoor's conf/app.conf to its public URL and use the same value here. |
500 after sign-in, log says email in id_token ... isn't verified | The application uses the default JWT format and the user's email is not verified. Switch to JWT-Standard, or set insecure_oidc_allow_unverified_email = true. |
403 Forbidden after sign-in | The user is not in allowed_groups. Open /oauth2/userinfo to see what OAuth2 Proxy received and compare it with Token group format. |
Casdoor shows Redirect URI: ... doesn't exist in the allowed Redirect URI list | Add https://app.example.com/oauth2/callback to the application's Redirect URLs. |