Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #29 from poprazvan17/2.0
Documentation v2 dot-authentication
- Loading branch information
Showing
19 changed files
with
313 additions
and
146 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
name: "Continuous Integration" | ||
|
||
on: | ||
pull_request: | ||
push: | ||
branches: | ||
tags: | ||
|
||
jobs: | ||
ci: | ||
uses: laminas/workflow-continuous-integration/.github/workflows/continuous-integration.yml@1.x |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
name: docs-build | ||
|
||
on: | ||
release: | ||
types: [published] | ||
workflow_dispatch: | ||
|
||
jobs: | ||
build-deploy: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- name: Build Docs | ||
uses: dotkernel/documentation-theme/github-actions/docs@main | ||
env: | ||
DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
# Security Policy | ||
|
||
## Supported Versions | ||
|
||
|
||
| Version | Supported | PHP Version | | ||
|---------|--------------------|--------------------------------------------------------------------------------------------------------------------| | ||
| 2.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-authentication/2.3.4) | | ||
| <= 1.x | :x: | | | ||
|
||
## Reporting Potential Security Issues | ||
|
||
If you have encountered a potential security vulnerability in this project, | ||
please report it to us at <security@dotkernel.com>. We will work with you to | ||
verify the vulnerability and patch it. | ||
|
||
When reporting issues, please provide the following information: | ||
|
||
- Component(s) affected | ||
- A description indicating how to reproduce the issue | ||
- A summary of the security vulnerability and impact | ||
|
||
We request that you contact us via the email address above and give the | ||
project contributors a chance to resolve the vulnerability and issue a new | ||
release prior to any public exposure; this helps protect the project's | ||
users, and provides them with a chance to upgrade and/or update in order to | ||
protect their applications. | ||
|
||
|
||
## Policy | ||
|
||
If we verify a reported security vulnerability, our policy is: | ||
|
||
- We will patch the current release branch, as well as the immediate prior minor | ||
release branch. | ||
|
||
- After patching the release branches, we will immediately issue new security | ||
fix releases for each patched release branch. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
../../README.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# Configuration | ||
|
||
Please note that usually this package will be installed as a dependency to a concrete implementation, so usually you won't need to add this to you project manually. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
# Installation | ||
|
||
Install `dot-authentication` by executing the following Composer command: | ||
|
||
composer require dotkernel/dot-authentication |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# Overview | ||
|
||
`dot-authentication` is DotKernel's authentication base package which define interfaces for authentication services to be used with DotKernel applications. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,42 @@ | ||
# Usage | ||
|
||
## AuthenticationInterface | ||
|
||
Defines the interface that should be implemented by any authentication service, in order to work with DotKernel applications. This is a result of the fact that the default packages used by DotKernel applications, that need access to the authentication service are type-hinted against this interface. | ||
|
||
Also, concrete implementations should be registered in the service manager using this interface's FQN. | ||
|
||
### Methods | ||
|
||
```php | ||
public function authenticate(ServerRequestInterface $request): AuthenticationResult; | ||
``` | ||
|
||
* method to implement the actual authentication process. It should extract credentials from the `$request` object(Authorization header, custom request attributes etc.). It should return an `AuthenticationResult` object, defined in this package, which carry the authentication status and identity on success. | ||
|
||
```php | ||
public function challenge(ServerRequestInterface $request): ResponseInterface; | ||
``` | ||
|
||
* this method should return a valid PSR-7 `ResponseInterface` used to notify the client or browser that it needs to authenticate first(usually using the `WWW-Authenticate` header - usefull for HTTP basic and digest authentication) | ||
|
||
```php | ||
public function hasIdentity(): bool; | ||
public function getIdentity(): ?IdentityInterface; | ||
public function setIdentity(IdentityInterface $identity); | ||
public function clearIdentity(); | ||
``` | ||
|
||
* these methods are used to check if authenticated, get the authenticated identity object, force set an identity(maybe useful for auto-login) or clear an identity(logout) | ||
|
||
## IdentityInterface | ||
|
||
You can use any object to represent an authenticated identity(user) as long as it implements this interface. It requires 2 methods, `getId()` which should return the unique identifier of the identity, and `getName(): string` which should return a string representation of the identity(for display purposes, usually the email or username) | ||
|
||
## AuthenticationResult | ||
|
||
Returned by the authentication service, on authentication success or failure. It composes one of the predefined authentication codes, which describes the authentication status, an error message in case the authentication has failed, and the identity object on success. | ||
|
||
## UnauthorizedException | ||
|
||
Exception to be thrown when accessing content that need authentication first. This can be used within an application to trigger an error and do a custom action(like redirecting to a login page). There is not a predefined way to handle this, DotKernel packages use this exception paired with a custom error handler to handle unauthorized errors. When using the frontend or admin applications, this is already setup among the authentication/authorization packages, and throwing an UnauthorizedException from anywhere your application, it will redirect to the login page by default. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
docs_dir: docs/book | ||
site_dir: docs/html | ||
extra: | ||
project: Packages | ||
current_version: v2 | ||
versions: | ||
- v2 | ||
nav: | ||
- Home: index.md | ||
- v2: | ||
- Overview: v2/overview.md | ||
- Installation: v2/installation.md | ||
- Configuration: v2/configuration.md | ||
- Usage: v2/usage.md | ||
site_name: dot-authentication | ||
site_description: "Core interfaces for authentication implementations" | ||
repo_url: "https://github.com/dotkernel/dot-authentication" | ||
plugins: | ||
- search |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
<?php | ||
|
||
declare(strict_types=1); | ||
|
||
namespace DotTest\Authentication; | ||
|
||
use Dot\Authentication\AuthenticationInterface; | ||
use Dot\Authentication\Identity\IdentityInterface; | ||
use PHPUnit\Framework\MockObject\Exception; | ||
use PHPUnit\Framework\MockObject\MockObject; | ||
use PHPUnit\Framework\TestCase; | ||
|
||
class AuthenticationInterfaceTest extends TestCase | ||
{ | ||
protected AuthenticationInterface|MockObject $mockAuthenticationInterface; | ||
|
||
protected IdentityInterface|MockObject $identityInterfaceMock; | ||
|
||
/** | ||
* @throws Exception | ||
*/ | ||
public function setUp(): void | ||
{ | ||
$this->mockAuthenticationInterface = $this->createMock(AuthenticationInterface::class); | ||
$this->identityInterfaceMock = $this->createMock(IdentityInterface::class); | ||
$this->identityInterfaceMock->method('getId')->will($this->returnValue(10)); | ||
$this->identityInterfaceMock->method('getName')->willReturn('username'); | ||
$this->mockAuthenticationInterface->method('hasIdentity')->willReturn(true); | ||
$this->mockAuthenticationInterface->method('getIdentity')->willReturn($this->identityInterfaceMock); | ||
} | ||
|
||
public function testCreate(): void | ||
{ | ||
$this->assertInstanceOf(AuthenticationInterface::class, $this->mockAuthenticationInterface); | ||
$this->assertInstanceOf(IdentityInterface::class, $this->identityInterfaceMock); | ||
} | ||
|
||
public function testFunction(): void | ||
{ | ||
$this->assertTrue($this->mockAuthenticationInterface->hasIdentity()); | ||
$this->assertSame('username', $this->mockAuthenticationInterface->getIdentity()->getName()); | ||
$this->assertSame(10, $this->mockAuthenticationInterface->getIdentity()->getId()); | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.