https://github.com/flownative/flow-oauth2-client
A generic OAuth2 client base implementation for Flow Framework applications
https://github.com/flownative/flow-oauth2-client
flow flow-framework neoscms oauth2 oauth2-client php
Last synced: 2 months ago
JSON representation
A generic OAuth2 client base implementation for Flow Framework applications
- Host: GitHub
- URL: https://github.com/flownative/flow-oauth2-client
- Owner: flownative
- License: mit
- Created: 2017-11-20T17:10:02.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2025-03-05T17:04:17.000Z (3 months ago)
- Last Synced: 2025-03-05T18:22:28.069Z (3 months ago)
- Topics: flow, flow-framework, neoscms, oauth2, oauth2-client, php
- Language: PHP
- Size: 189 KB
- Stars: 5
- Watchers: 5
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](http://opensource.org/licenses/MIT)
[](https://packagist.org/packages/flownative/oauth2-client)
[](https://www.flownative.com/en/products/open-source.html)
# OAuth 2.0 Client for Flow Framework
This [Flow](https://flow.neos.io) package provides an OAuth 2.0 client
SDK. Even though it can be used as a generic OAuth2 client, it was
developed as a backing library for the
[OpenID Connect package](https://github.com/flownative/flow-openidconnect-client).
That's why documentation for this package is a bit sparse at the moment
and examples for generic use are missing.
## Authorizations
This package stores states and tokens as "authorizations" in a dedicated
database table.
For example, during the authorization code flow, this package needs to
keep track of a "state" in order to make sense of an incoming "finish
authorization" request. Another example is the client credentials flow,
where an access token is stored in the authorizations table which is
needed for executing authorized requests to the respective service.
### Token lifetime
New Authorization tokens are created with a lifetime of 600 seconds
(10 minutes) by default.
The expiration date is updated during authentication if a different
`expires` parameter is specified in the OAuth2 access token.
The default token lifetime and frequency of expired tokens to be removed
automatically can be configured:
```yaml
Flownative:
OAuth2:
Client:
garbageCollection:
# The probability in percent of a client shutdown triggering a garbage
# collection which removes expired tokens.
#
# Examples:
# 1 (would be a 1% chance to clean up)
# 20 (would be a 20% chance to clean up)
# 0.42 (would be a 0.42 % chance to clean up)
probability: 1
token:
# default lifetime of new tokens in seconds
defaultLifetime: 600
```
Note: By setting the `defaultLifetime` to `null`, new tokens won't expire
by default.
### Authorization metadata
Authorizations also may contain developer-provided metadata. For
example, you may attach an account identifier to an authorization when
an authorization process starts and use that information when
authorization finishes to make sure that the authorization is only used
for a specific account (or customer number, or participant id).
To set metadata, you need to know the authorization id when starting the
authorization code flow. This code could be used in an overloaded
`startAuthorizationAction()`:
```php
$authorizationId = $oAuthClient->generateAuthorizationIdForAuthorizationCodeGrant($this->appId);
$loginUri = $oAuthClient->startAuthorizationWithId(
$authorizationId,
$this->appId,
$this->appSecret,
$returnToUri,
$scope
);
$oAuthClient->setAuthorizationMetadata($authorizationId, json_encode($metadata));
```
And later, in `finishAuthorization()`, you may retrieve the metadata as
follows:
```php
$authorization = $this->getAuthorization($authorizationId);
$metadata = json_decode($authorization->getMetadata());
```
## Encryption
By default, access tokens are serialized and stored unencrypted in the
"authorizations" database table. You can improve the security of your
application by enabling the encrypted-at-rest feature of this package.
when active, it will encrypt tokens before storing them in the database
and decrypt them automatically when they are retrieved. The secret key
which is needed for encryption and decryption is not stored in the
database.
This package uses the "ChaCha20-Poly1305-IETF" construction for
authenticated encryption / decryption of serialized tokens. It uses the
["sodium" PHP extension](https://www.php.net/sodium) if installed, or
[a polyfill implementation](https://packagist.org/packages/paragonie/sodium_compat)
in pure PHP.
### Generating a Secret Key
The OAuth2 Flow package provides a CLI command for generating encryption
keys suitable for the currently supported encryption method:
```bash
$ ./flow oauth:generateencryptionkey
qpBzrH7icQqBKenvk8wTKROv4qcJNxslzdGo3IKXmws=
```
The key is base64-encoded in order to simplify handling and being able
to pass the key via Flow settings.
### Enabling Encryption
Set the encryption key via Flow settings (for example in your global
"Configuration/Settings.yaml"). Make sure to deploy this setting
securely, for example by creating the Settings file during deployment or
by using environment variables.
```yaml
Flownative:
OAuth2:
Client:
encryption:
base64EncodedKey: 'qpBzrH7icQqBKenvk8wTKROv4qcJNxslzdGo3IKXmws='
```
### Verifying Encryption Configuration
When you have set the encryption key, test that everything is working as
expected. Run your application so that a new authorization is created.
Check the database table `flownative_oauth2_client_authorization`: the
column `serializedaccesstoken` should be empty and the column
`encryptedserializedaccesstoken` should contain a long string similar to
his one:
```
ChaCha20-Poly1305-IETF$Mjdj4s9IFrPp6HFK$k9v3x…KQ==
```
There are three parts in this string, separated by two dollar signs:
1. the construction used for encryption ("ChaCha20-Poly1305-IETF")
2. the nonce used for this particular entry ("Mjdj4s9IFrPp6HFK")
3. the encrypted data ("k9v3x…KQ==")