Browse Source

Documentation updates

Adam Pippin 3 years ago
parent
commit
e1a5e92d7c
  1. 3
      TODO.md
  2. 69
      docs/INTERNALS.md

3
TODO.md

@ -1,10 +1,13 @@
# Fixes and Improvements
* Refresh callback only handles user tokens, not service tokens.
* Add logging to provide a better debugging experience.
* When anything goes wrong in communicating with the OpenID provider, trigger a
logout (at least) to prevent users ending up in an awkward or unrecoverable
situation of being logged in but not able to log out because the app is
broken due to the token being invalid.
* Split compatibility stuff out of Authkit2 class and into a separate compat
class.
# Features

69
docs/INTERNALS.md

@ -0,0 +1,69 @@
# 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.
Loading…
Cancel
Save