<commit_before>![](https://raw.githubusercontent.com/auth0/wp-auth0/master/banner-1544x500.png)

Wordpress Plugin for Auth0
====

Single Sign On for Enterprises + Social Login + User/Passwords. For all your WordPress instances. Powered by Auth0.

Demo: <http://auth0wp.azurewebsites.net>

Documentation: <https://auth0.com/docs/cms>

## Contributions

All PR should be done towards the `dev` branch.

## Installation

Before you start, **make sure the admin user has a valid email that you own**, read the Technical Notes for more information.

1. Install from the  **WordPress** Store or upload the entire wp-auth0 folder to the /wp-content/plugins/ directory.
2. Activate the plugin through the 'Plugins' menu in  **WordPress**.
3. Create an account in Auth0 (https://auth0.com) and add a new Application.
4. Copy the Client ID, Client Secret and Domain from the Settings of the Application.
5. On the Settings of the Auth0 application change the Callback URL to be: http://your-domain/index.php?auth0=1. Using TLS/SSL is recommended for production.
6. Go back to  **WordPress** Settings - Auth0 Settings edit the Domain, Client ID and Client Secret with the ones you copied from Auth0 Dashboard.

## Implicit Flow

There are cases where the server is behind a firewall and does not have access to internet (or at least, can't reach the Auth0 servers). In those cases, you can enable the Auth0 Implicit Flow in the advanced settings of the Auth0 Settings page.

When it is enabled, the token is returned in the login callback and then sent back to the WordPress server so it doesn't need to call the Auth0 webservices.

## Integrating with the plugin

### User login action

The plugin provides an action to get notified each time a user logs in or is created in WordPress. This action is called `auth0_user_login` and receives 5 params:
1. $user_id (int): the id of the user logged in
2. $user_profile (stdClass): the Auth0 profile of the user
3. $is_new (boolean): `true` if the user was created on WordPress, `false` if doesn't. Don't get confused with Auth0 registrations, this flag will tell you if a new user was created on the WordPress database.
4. $id_token (string): the user's JWT.
5. $access_token (string): the user's access token. It is not provided when using the **Implicit flow**.

To hook to this action, you will need to do the following:
```
    add_action( 'auth0_user_login', 'auth0UserLoginAction', 0,5 );

    function auth0UserLoginAction($user_id, $user_profile, $is_new, $id_token, $access_token) {
        ...
    }
```

### Render verify email page

This filter is called when a user with an unverified email logs in, and the `Requires verified email` setting is enabled.

To hook to this filter, you will need to do the following:
```
    add_filter( 'auth0_verify_email_page', 'render_verify_email_page', 1, 3 );
    function render_verify_email_page($html, $userinfo, $id_token) {
        return "You need to verify your email to log in.";
    }   
```
## API authentication

The last version of the plugin provides the ability integrate with **wp-jwt-auth** plugin to authenticate api calls via a HTTP Authorization Header.

This plugin will detect if you have wp-jwt-auth installed and active and will offer to configure it. Accepting this, will set up the client id, secret and the custom user repository.

After the user logs in via Auth0 in your Api client (ie: using Lock in a mobile app) you will get a JWT (JSON Web Token). Then you need to send this token in a HTTP header in the following way:<commit_msg>added info about new filter in the readme<commit_after>![](https://raw.githubusercontent.com/auth0/wp-auth0/master/banner-1544x500.png)

Wordpress Plugin for Auth0
====

Single Sign On for Enterprises + Social Login + User/Passwords. For all your WordPress instances. Powered by Auth0.

Demo: <http://auth0wp.azurewebsites.net>

Documentation: <https://auth0.com/docs/cms>

## Contributions

All PR should be done towards the `dev` branch.

## Installation

Before you start, **make sure the admin user has a valid email that you own**, read the Technical Notes for more information.

1. Install from the  **WordPress** Store or upload the entire wp-auth0 folder to the /wp-content/plugins/ directory.
2. Activate the plugin through the 'Plugins' menu in  **WordPress**.
3. Create an account in Auth0 (https://auth0.com) and add a new Application.
4. Copy the Client ID, Client Secret and Domain from the Settings of the Application.
5. On the Settings of the Auth0 application change the Callback URL to be: http://your-domain/index.php?auth0=1. Using TLS/SSL is recommended for production.
6. Go back to  **WordPress** Settings - Auth0 Settings edit the Domain, Client ID and Client Secret with the ones you copied from Auth0 Dashboard.

## Implicit Flow

There are cases where the server is behind a firewall and does not have access to internet (or at least, can't reach the Auth0 servers). In those cases, you can enable the Auth0 Implicit Flow in the advanced settings of the Auth0 Settings page.

When it is enabled, the token is returned in the login callback and then sent back to the WordPress server so it doesn't need to call the Auth0 webservices.

## Integrating with the plugin

### User login action

The plugin provides an action to get notified each time a user logs in or is created in WordPress. This action is called `auth0_user_login` and receives 5 params:
1. $user_id (int): the id of the user logged in
2. $user_profile (stdClass): the Auth0 profile of the user
3. $is_new (boolean): `true` if the user was created on WordPress, `false` if doesn't. Don't get confused with Auth0 registrations, this flag will tell you if a new user was created on the WordPress database.
4. $id_token (string): the user's JWT.
5. $access_token (string): the user's access token. It is not provided when using the **Implicit flow**.

To hook to this action, you will need to do the following:
```
    add_action( 'auth0_user_login', 'auth0UserLoginAction', 0,5 );

    function auth0UserLoginAction($user_id, $user_profile, $is_new, $id_token, $access_token) {
        ...
    }
```

### Render verify email page

This filter is called when a user with an unverified email logs in, and the `Requires verified email` setting is enabled.

To hook to this filter, you will need to do the following:
```
    add_filter( 'auth0_verify_email_page', 'render_verify_email_page', 1, 3 );
    function render_verify_email_page($html, $userinfo, $id_token) {
        return "You need to verify your email to log in.";
    }   
```

### Customize users matching

This filter is called after the plugin finds the related user to login (based on the auth0 `user_id`). It allows to override the default behaviour with custom matching rules(for example, always match by email).

If the filter returns null, it will lookup by email as stated in the [How doe it work?](https://auth0.com/docs/cms/wordpress/how-does-it-work) document.

```
    add_filter( 'auth0_get_wp_user', 'auth0_get_wp_user_handler', 1, 2 );
    function auth0_get_wp_user_handler($user, $userinfo) {
        $user = get_user_by( 'email', $userinfo->email );

        if ($joinUser instanceof WP_User) {
            return $user;
        }

        return null;
    }   
```

## API authentication

The last version of the plugin provides the ability integrate with **wp-jwt-auth** plugin to authenticate api calls via a HTTP Authorization Header.

This plugin will detect if you have wp-jwt-auth installed and active and will offer to configure it. Accepting this, will set up the client id, secret and the custom user repository.

After the user logs in via Auth0 in your Api client (ie: using Lock in a mobile app) you will get a JWT (JSON Web Token). Then you need to send this token in a HTTP header in the following way:
{'fraction_non_alphanumeric': 0.07836630504148054, 'fraction_numerical': 0.013401403956604978, 'mean_word_length': 4.062015503875969, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 8, 'https://': 7, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1286689', 'n_tokens_mistral': 2222, 'n_tokens_neox': 2151, 'n_words': 1114}