authkit2/docs/INTERNALS.md

authkit2 - Code Overview

A brief overview of the code layout and design decisions.

The bulk of the code provides the out-of-the-box Laravel integration, however all of that is just a wrapper around the core authkit2 library.

Core

The core of the library is the Authkit2 class and the objects and flows under src/Oidc/.

The Authkit2 class acts as both an entrypoint to the library as well as abstraction layer to allow the core of the library to function on both native PHP and within Laravel, while making the best use of the facilities available in Laravel when possible.

The code under src/Oidc/ implements a fairly minimal OIDC library. It manages tokens, encodes flows (e.g., three-legged oauth, service account), and provides an authentication system for PSR7 compatible HTTP client libraries (e.g., Guzzle) to authenticate outgoing requests.

• Client: Provides a minimal interface for working with an OIDC provider, implementing basic protocol operations, and encapsulating some of the logic around determining which endpoint to call and how to call it.
• Token: Provides an encapsulation for an access token or (access token, refresh token) tuple and an interface for validating, decoding and extracting data, from tokens. Creates authenticated clients for making requests with a given token.
• Authentication/: Primarily internal classes for authenticating outgoing HTTP requests using a given method.
• Flows/: Implementations of the discrete steps of various oauth flows (three-legged, service account) to ease integration.

Laravel Integration

The remainder of the code in the library is for Laravel integration. The library generally follows the layout of a typical Laravel project:

• config/: Configuration file
• database/: Database migrations
• routes/: Login routes
• src/Events/: Events published when a user is registered/logged in/logged out
• src/Http/: Basic controller for implementing the three-legged oauth flow
• src/Models/: Eloquent models
• src/Observers/: Observers for eloquent models
• src/Providers/: Service providers

When installed as a package, Laravel discovers the extra.laravel.providers section in composer.json, which tells it to register the Authkit2ServiceProvider class as a provider. Everything flows out of there.

The Authkit2ServiceProvider will, if enabled, register the AuthnServiceProvider (which provides authentication) and the AuthzServiceProvider (which provides authorization).

These register or make available several publishable resources:

• authkit2_config: The configuration file at config/authkit.php. Allows customizing the integration between authkit2 and Laravel.
• authkit2_migrate_new_project: A database migration to generate the tokens table, as well as one to remove the password and email_verified_at columns from the default Laravel users table.
• authkit2_migrate_existing_project: A database migration to generate the tokens table, as well as one to make the existing password column nullable so OIDC users can be created.

The providers handle registering the necessary routes (defined in the routes file) to act as an entrypoint for everything else.