As the extension allows 3rd party login providers to authenticate users, the first thing you need is to change the cookie security setting for the backend from sameSite to lax (if you are using providers hosted on another domain, for example Github or Google).
File: AdditionalConfiguration.php
(or adjust LocalConfiguration.php
):
$GLOBALS['TYPO3_CONF_VARS']['BE']['cookieSameSite'] = 'lax';
$GLOBALS['TYPO3_CONF_VARS']['FE']['cookieSameSite'] = 'lax';
To allow non-admin users to register OAuth2 providers, please allow them to access the module User Settings (user_setup).
To allow non-admin users to revoke OAuth2 provider registrations for frontend users, please allow them to modify the table tx_oauth2_feuser_provider_configuration
.
The extension is based on the OAuth2 client implementation from https://oauth2-client.thephpleague.com - by default, it comes with a generic provider you can configure for your use case.
The configuration is done in the file AdditionalConfiguration.php
or directly in LocalConfiguration.php in the section $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_client']
.
Note
If you are using composer, you can ease your configuration by requiring a pre-configured client package for the platform you want.
In the following section both the generic and some more specific examples are shown.
The generic provider can be used for basically any platform that supports OAuth2.
Gitlab minimal example:
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_client'] = [
'providers' => [
'gitlab' => [
'label' => 'Gitlab',
'scopes' => [
\Waldhacker\Oauth2Client\Service\Oauth2ProviderManager::SCOPE_BACKEND,
\Waldhacker\Oauth2Client\Service\Oauth2ProviderManager::SCOPE_FRONTEND,
],
'options' => [
'clientId' => '<your-gitlab-client-id>',
'clientSecret' => '<your-gitlab-client-secret',
'urlAuthorize' => 'https://<your-gitlab-installation.dev>/oauth/authorize',
'urlAccessToken' => 'https://<your-gitlab-installation.dev>/oauth/token',
'urlResourceOwnerDetails' => 'https://<your-gitlab-installation.dev>/api/v4/user',
'scopes' => ['openid', 'read_user'],
'scopeSeparator' => ' '
],
],
],
];
dl-parameters
- label
|
Condition:
required|
Type:
string|
Default:
''|
The label to show both in the login screen as well as in the configuration.
- description
|
Condition:
optional|
Type:
string|
Default:
''|
A description for the provider. The description is shown to the user when configuring the provider.
- iconIdentifier
|
Condition:
optional|
Type:
string|
Default:
'actions-key'|
A registered icon identifier. If you want to use custom icons, make sure to register them first.
- implementationClassName
|
Condition:
optional|
Type:
string|
Default:
'actions-key'|
The provider class name - the default is LeagueOAuth2ClientProviderGenericProvider::class - can be replaced for more specific providers, for example LeagueOAuth2ClientProviderGithub::class if the github provider has been installed.
- scopes
|
Condition:
optional|
Type:
array|
Default:
both backend and frontend are enabled|
The scopes where this provider can be used. Can be an array with either WaldhackerOauth2ClientServiceOauth2ProviderManager::SCOPE_BACKEND for backend only or WaldhackerOauth2ClientServiceOauth2ProviderManager::SCOPE_FRONTEND for frontend only or both.
Example:
'scopes' => [ \Waldhacker\Oauth2Client\Service\Oauth2ProviderManager::SCOPE_BACKEND, \Waldhacker\Oauth2Client\Service\Oauth2ProviderManager::SCOPE_FRONTEND, ],
- options.[...]
|
Condition:
required|
Type:
array|
Default:
|
The provider options - are given directly to the provider instance as constructor arguments. Please check your provider documentation for the concrete values (and see the examples section in this manual).
- options.clientId
|
Condition:
required|
Type:
string|
Default:
|
The OAuth2 client id.
- options.clientSecret
|
Condition:
required|
Type:
string|
Default:
|
The OAuth2 client secret.
- options.urlAuthorize
|
Condition:
required|
Type:
string|
Default:
|
The OAuth2 authorization URL.
- options.urlAccessToken
|
Condition:
required|
Type:
string|
Default:
|
The OAuth2 access token API URL.
- options.urlResourceOwnerDetails
|
Condition:
required|
Type:
string|
Default:
|
The OAuth2 REST API URL for getting the resource owner information (for example the user profile REST API route).
- options.scopes
|
Condition:
optional|
Type:
array of strings|
Default:
|
The scopes to request for the OAuth provider. May be required depending on the concrete provider (it is required in Gitlab for example).
- options.scopeSeparator
|
Condition:
optional|
Type:
string|
Default:
,|
The scope separator used to separate the different required scopes in the URL.
- options.proxy | options.verify
|
Condition:
optional|
Type:
string|
Default:
|
You can use a proxy to debug HTTP calls made to a provider. See https://oauth2-client.thephpleague.com/usage/#using-a-proxy
- collaborators
|
Condition:
optional|
Type:
array|
Default:
|
If you have advanced requirements, within this property you can change the default collaborators from the default implementation. See https://github.com/thephpleague/oauth2-client/blob/8c7498c14959b98d4143a8ef91e895f353381628/src/Provider/AbstractProvider.php#L107
Full example:
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_client'] = [
'providers' => [
'gitlab' => [
'label' => 'Gitlab',
'iconIdentifier' => 'oauth2-gitlab',
'description' => 'Login with Gitlab',
'implementationClassName' => \League\OAuth2\Client\Provider\GenericProvider::class,
'scopes' => [
\Waldhacker\Oauth2Client\Service\Oauth2ProviderManager::SCOPE_BACKEND,
\Waldhacker\Oauth2Client\Service\Oauth2ProviderManager::SCOPE_FRONTEND,
],
'options' => [
'clientId' => '<client-id>',
'clientSecret' => '<client-secret>',
'urlAuthorize' => 'https://<your-gitlab-url>/oauth/authorize',
'urlAccessToken' => 'https://<your-gitlab-url>/oauth/token',
'urlResourceOwnerDetails' => 'https://<your-gitlab-url>/api/v4/user',
'scopes' => ['openid', 'read_user'],
'scopeSeparator' => ' ',
'proxy' => '127.0.0.1:8080',
'verify' => false,
],
'collaborators' => [
'httpClient' => \My\Custom\HttpClient::class,
],
],
]
];
You must configure a frontend user storage folder within the site / site language settings. Only if frontend users are in this storage folder they can login with an OAuth2 provider or register an OAUth2 provider. Set Behaviour
-> Contains Plugin
to Website Users
to make a frontend user storage folder selectable in the site / site language settings.
Set user storage folder configuration
Now you can set this frontend user storage folder within the site / site language settings
Manage frontend user storage folder
Note
Currently no recursive lookup within this folder is implemented
The extension provides defined callback URLs to which the OAuth2 providers redirect in case of authorization requests. In the backend context these are fixed and in the frontend context they can be configured. For each context (frontend / backend) 2 callback URL's are needed which have to be configured in the OAuth2 providers.
Note
The OAuth2 providers behave differently in the way they validate the callback URLs. Some compare only the URL without query parameters and the query paramaters are not relevant and for some you have to configure the complete url including the query parameters.
In addition, the callback urls to be used for backend logins differ between TYPO3 v10 and TYPO3 v11!
To make OAuth2 backend login authorizations work, the following callback URL must be configured in the OAuth2 provider
TYPO3 v11: https://your-typo3-site.example.com/typo3/login?loginProvider=1616569531&oauth2-provider=<provider-identifier>&login_status=login&commandLI=attempt
TYPO3 v10: https://your-typo3-site.example.com/typo3/index.php?route=%2Flogin&loginProvider=1616569531&oauth2-provider=<provider-identifier>&login_status=login&commandLI=attempt
Note
Replace your-typo3-site.example.com with the domain of your project and <provider-identifier> with your OAuth2 provider configuration identifier ($GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_client']['providers'][<provider-identifier>]
).
For the registration of OAuth2 providers for backend users the following callback URL must be configured in the OAuth2 provider
TYPO3 v11: https://your-typo3-site.example.com/typo3/oauth2/callback/handle?oauth2-provider=<provider-identifier>&action=callback
TYPO3 v10: https://your-typo3-site.example.com/typo3/index.php?route=%2Foauth2%2Fcallback%2Fhandle&oauth2-provider=<provider-identifier>&action=callback
Note
Replace your-typo3-site.example.com with the domain of your project and <provider-identifier> with your OAuth2 provider configuration identifier ($GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_client']['providers'][<provider-identifier>]
).
In the fontend context the callback-slug can be configured within the site / site language settings. If this setting is empty, the default callback-slug _oauth2 is used. Make sure you use a callback-slug that does not match any slug of a TYPO3 page in your project.
Manage frontend OAuth2 callback-slug
To make OAuth2 frontend login authorizations work, the following callback URL must be configured in the OAuth2 provider
https://your-typo3-site.example.com/<callback-slug>?oauth2-provider=<provider-identifier>&logintype=login
Note
Replace your-typo3-site.example.com with the domain of your project and <provider-identifier> with your OAuth2 provider configuration identifier ($GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_client']['providers'][<provider-identifier>]
). Replace <callback-slug> with the configured callback-slug within your site / site language settings (or with _oauth2 if you have not configured anything).
For the registration of OAuth2 providers for frontend users the following callback URL must be configured in the OAuth2 provider
https://your-typo3-site.example.com/<callback-slug>?oauth2-provider=<provider-identifier>&tx_oauth2client%5Baction%5D=verify
Note
Replace your-typo3-site.example.com with the domain of your project and <provider-identifier> with your OAuth2 provider configuration identifier ($GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_client']['providers'][<provider-identifier>]
). Replace <callback-slug> with the configured callback-slug within your site / site language settings (or with _oauth2 if you have not configured anything).
By default, after an OAuth2 login or OAuth2 provider registration, the extension redirects to the page where the OAuth2 login or OAuth2 provider registration took place. But the page to which you are redirected after a login or registration can be specially defined if required.
Be aware that you have to create the links for an OAuth2 login or OAuth2 provider registration manually. If you append after-oauth2-redirect-uri=https://your-typo3-site.example.com/sales/
to the links, the extension will redirect to the URL https://your-typo3-site.example.com/sales/ after an OAuth2 login or OAuth2 provider registration.
Note
The custom redirect url must not be relative to the current page and must point to the same host on which the project is accessible. You cannot redirect to external pages or to pages of other page trees (sites).
An example of an Oauth2 login URL would look like this: https://your-typo3-site.example.com/some-site?oauth2-provider=<provider-identifier>&logintype=login&after-oauth2-redirect-uri=https://your-typo3-site.example.com/sales/
.
Note
You do not need to include the after-oauth2-redirect-uri=https://your-typo3-site.example.com/sales/
part in the callback URL configuration of your OAuth2 provider.
However, this feature is disabled by default for security reasons. If you want to use it you have to turn on the feature flag $GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['oauth2.frontend.login.afterOauth2RedirectUriFromQuery'] = true
; within the file AdditionalConfiguration.php
(or LocalConfiguration.php
):
Gitlab Github Google Keycloak Hydra
If you need to customize the login template Resources/Private/Templates/Backend/Oauth2LoginProvider.html
you can override it by adding your own fluid template search paths.
Example:
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['oauth2_client'] = [
'view' => [
// add some additional layout search paths:
'layoutRootPaths' => [
'EXT:site_package/Resources/Private/Layouts/Backend/',
],
// add some additional template search paths:
'templateRootPaths' => [
'EXT:site_package/Resources/Private/Templates/Backend/',
],
// add some additional partial search paths:
'partialRootPaths' => [
'EXT:site_package/Resources/Private/Partials/Backend/',
],
// you can override the template name too:
'template' => 'Oauth2LoginProvider',
],
];