PHPackages                             joandysson/php-oidc-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. joandysson/php-oidc-client

ActiveLibrary[Authentication & Authorization](/categories/authentication)

joandysson/php-oidc-client
==========================

Local OIDC client helpers for scaffold-style PHP projects.

1.1.0(1mo ago)0172MITPHPPHP ^8.2

Since May 2Pushed 1mo agoCompare

[ Source](https://github.com/joandysson/php-oidc-client)[ Packagist](https://packagist.org/packages/joandysson/php-oidc-client)[ RSS](/packages/joandysson-php-oidc-client/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (2)Versions (3)Used By (0)

php-oidc-client
===============

[](#php-oidc-client)

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
-------------------

[](#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
----------------------------

[](#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
-------------------

[](#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
----------

[](#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
-----------------

[](#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
-------------

[](#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
---------------------------

[](#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
------------------

[](#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
-----------------

[](#estrutura-interna)

- `Config/`
- `Exception/`
- `Middleware/`
- `Service/`
- `Support/`

Documentacao complementar:

- `AGENTS.md`
- `docs/AI_CONTEXT.md`
- `docs/ARCHITECTURE.md`

Assuncoes
---------

[](#assuncoes)

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

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance92

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

2

Last Release

37d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f04a0ba04a855d4519d8642dc2eed9aafc38c73e950a0997c74740856f9ba818?d=identicon)[joandysson](/maintainers/joandysson)

---

Top Contributors

[![joandysson](https://avatars.githubusercontent.com/u/49295040?v=4)](https://github.com/joandysson "joandysson (5 commits)")

---

Tags

jwtoauth2oidcphp

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/joandysson-php-oidc-client/health.svg)

```
[![Health](https://phpackages.com/badges/joandysson-php-oidc-client/health.svg)](https://phpackages.com/packages/joandysson-php-oidc-client)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.3k532.1M2.5k](/packages/aws-aws-sdk-php)[overtrue/socialite

A collection of OAuth 2 packages.

1.4k5.6M90](/packages/overtrue-socialite)[neuron-core/neuron-ai

The PHP Agentic Framework.

1.9k496.1k32](/packages/neuron-core-neuron-ai)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3751.2M45](/packages/tencentcloud-tencentcloud-sdk-php)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k11](/packages/tempest-framework)[ellaisys/aws-cognito

AWS Cognito package that allows Auth and other related features using the AWS SDK for PHP

121242.9k1](/packages/ellaisys-aws-cognito)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)