joandysson/php-oidc-client

Local OIDC client helpers for scaffold-style PHP projects.

Maintainers

Package info

github.com/joandysson/php-oidc-client

pkg:composer/joandysson/php-oidc-client

Statistics

Installs: 18

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

1.1.0 2026-05-04 03:27 UTC

Requires

Requires (Dev)

MIT 604e52013abc7098e5f5c79617c67c56e29487aa

This package is auto-updated.

Last update: 2026-05-04 03:44:07 UTC

README

Mini lib para integrar login OIDC em projetos PHP no mesmo estilo de scaffold usado pelo devot-api.

Package Composer:

joandysson/php-oidc-client

Licenca:

MIT

O que a lib entrega

  • Joandysson\OidcClient\Service\OidcAuthService
  • Joandysson\OidcClient\Service\OidcUrlService
  • Joandysson\OidcClient\Service\OidcSessionService
  • Joandysson\OidcClient\Service\OidcHttpService
  • Joandysson\OidcClient\Config\OidcClientConfig
  • Joandysson\OidcClient\Middleware\StartSessionMiddleware
  • Joandysson\OidcClient\Middleware\RequireOidcAuthMiddleware
  • exceptions tipadas para configuracao, autenticacao e transporte

O que fica no app consumidor

  • controller de login, callback e logout
  • views de erro e logout
  • rotas do app
  • UI do sistema

Variaveis esperadas

APP_URL=http://localhost:8081
OIDC_ISSUER_URL=http://localhost
OIDC_HTTP_BASE_URL=http://host.docker.internal
OIDC_CLIENT_ID=toolz
OIDC_CLIENT_SECRET=toolz
OIDC_REDIRECT_URI=http://localhost:8081/auth/callback
OIDC_SCOPES="openid profile email"
SESSION_COOKIE_NAME=devot_session
OIDC_LOCAL_LOGIN_PATH=/auth/login
OIDC_REGISTER_PATH=/register
OIDC_FORGOT_PASSWORD_PATH=/forgot-password
OIDC_LOGOUT_PATH=/oauth/logout

Instalacao

Via Composer:

composer require joandysson/php-oidc-client

Se o projeto roda em Docker, execute o Composer dentro do container da aplicacao. Exemplo:

docker compose exec -T app composer require joandysson/php-oidc-client

Integracao minima

  1. Instale a lib via Composer.
  2. Registre Joandysson\\OidcClient\\Middleware\\StartSessionMiddleware no middleware global.
  3. Proteja web/admin e writes com Joandysson\\OidcClient\\Middleware\\RequireOidcAuthMiddleware.
  4. No seu controller, use Joandysson\\OidcClient\\Service\\OidcAuthService para:
    • gerar a URL de authorize
    • trocar code por token
    • carregar userinfo
    • manter a sessao local
    • renovar token com refresh_token quando necessario
    • limpar a sessao no logout
    • montar URLs auxiliares para cadastro, reset e logout no Auth Central

Refresh token

O OidcAuthService armazena expires_in, expires_at, access_token e refresh_token na sessao local apos o callback. Para renovar tokens:

  • refresh(): array forca grant_type=refresh_token, atualiza userinfo e substitui os tokens na sessao.
  • refreshIfNeeded(int $leewaySeconds = 60): ?array renova apenas quando o access token esta vencido, perto de vencer ou quando a sessao antiga nao possui expires_at.

O RequireOidcAuthMiddleware chama refreshIfNeeded() antes de liberar uma rota protegida. Se a renovacao falhar, ele limpa a sessao local e redireciona para o login ou retorna 401 em APIs.

Callback e URLs com retorno

Para manter compatibilidade, handleCallback() continua retornando apenas o return_to. Quando o app consumidor precisar do usuario e tokens no mesmo passo, use:

  • handleCallbackResult(?string $code, ?string $state): OidcCallbackResult
  • currentUserOrRefresh(int $leewaySeconds = 60): ?array

Para telas do Auth Central que precisam voltar ao sistema consumidor pelo fluxo OIDC, use:

  • registerUrlForReturnTo(string $returnTo, ?string $clientId = null): string
  • forgotPasswordUrlForReturnTo(string $returnTo): string
  • profileUrlForReturnTo(string $returnTo): string

Esses helpers usam authorizeUrl() internamente para criar state e PKCE reais antes de montar o return_to.

Helpers adicionais

O OidcAuthService tambem expoe:

  • registerUrl(?string $clientId = null): string
  • profileUrlForReturnTo(string $returnTo): string
  • forgotPasswordUrl(): string
  • providerLogoutUrl(?string $postLogoutRedirectUri = null): string

Esses helpers sao uteis quando o sistema consumidor quer manter uma tela propria de entrada, mas ainda encaminhar o usuario para as telas corretas do Auth Central.

Estrutura interna

  • Config/
  • Exception/
  • Middleware/
  • Service/
  • Support/

Documentacao complementar:

  • AGENTS.md
  • docs/AI_CONTEXT.md
  • docs/ARCHITECTURE.md

Assuncoes

  • o projeto consumidor fornece App\\Config\\Request\\Request
  • o projeto consumidor fornece App\\Config\\Response\\Response
  • o projeto consumidor usa sessao PHP padrao