Skip to content
  • Documentation >
  • Guide >
  • Users >
  • User authentication >
  • OAuth authentication

OAuth authentication

You can use OAuth2 authentication to securely connect to external services.

Ibexa DXP uses an integration with knpuniversity/oauth2-client-bundle to provide OAuth2 authentication.

To enable OAuth2, you need to:

OAuth2 provider configuration

To configure the OAuth2 provider, add it under the oauth2 key in SiteAccess-aware configuration, for example:

1
2
3
4
5
6
ezplatform:
    system:
        admin:
            oauth2:
                enabled: true
                clients: ['google']

Details of the configuration depend on the OAuth2 provider that you want to use. For sample configurations for different providers, see knpuniversity/oauth2-client-bundle configuration.

Firewall configuration

Firewall configuration is located in config/packages/security.yaml under security.firewalls. The guard.authenticators setting specifies the Guard authenticators to use.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
        oauth2_connect:
            pattern: /oauth2/connect/*
            security: false

        ezpublish_front:
            pattern: ^/
            user_checker: eZ\Publish\Core\MVC\Symfony\Security\UserChecker
            anonymous: ~
            ezpublish_rest_session: ~
            guard:
                authenticators:
                    - 'Ibexa\Platform\Bundle\OAuth2Client\Security\Authenticator\OAuth2Authenticator'
            form_login:
                require_previous_session: false
                csrf_token_generator: security.csrf.token_manager
            logout: ~

Resource owner mappers

Resource owner mappers map the data received from the OAuth2 provider to user information in the Repository.

Resource owner mappers must implement the Ibexa\Platform\Contracts\OAuth2Client\ResourceOwner\ResourceOwnerMapper interface. There are four existing implementations of ResourceOwnerMapper:

  • ResourceOwnerToExistingUserMapper is the base class that is extended by the following mappers:
    • ResourceOwnerIdToUserMapper does not create a new user, but loads a user (resource owner) based on their identifier.
    • ResourceOwnerEmailToUserMapper does not create a new user, but loads a user (resource owner) based on their email.
  • ResourceOwnerToExistingOrNewUserMapper checks if the user exists and loads them if they do. If they do not, the mapper creates a new user in the Repository.

To use ResourceOwnerToExistingOrNewUserMapper you need to extend it in your custom mapper.

See Adding login through external service for an example of creating a mapper that extends ResourceOwnerToExistingOrNewUserMapper.

OAuth User Content Type

When you implement your own mapper for external login, it is good practice to create a special User Content Type for users registered in this way.

This is because users who register through an external service do not have a separate password in the system. Instead, they log in by their external service's password.

To avoid issues with password restrictions in the built-in User Content Type, create a special Content Type (for example, "OAuth User"), without restrictions on the password.

This new Content Type must also contain the User (ezuser) Field.