# Class yii\authclient\clients\Facebook

Inheritance | yii\authclient\clients\Facebook » yii\authclient\OAuth2 » yii\authclient\BaseOAuth » yii\authclient\BaseClient » yii\base\Component » yii\base\BaseObject
Implements | yii\authclient\ClientInterface, yii\base\Configurable
Available since version | 2.0
Source Code | https://github.com/yiisoft/yii2-authclient/blob/master/clients/Facebook.php

Facebook allows authentication via Facebook OAuth.

In order to use Facebook OAuth you must register your application at https://developers.facebook.com/apps. Add an app. In "Settings" -> "Basic" specify "App Domains". There you can obtain ID and Secret values to put into config. In "Products" press "+" and add "Facebook Login". In its settings make sure you enabled "Web OAuth Login" and specify "Valid OAuth Redirect URIs" as "https://example.com/auth?authclient=facebook".

Example application configuration:

    'components' => [
        'authClientCollection' => [
            'class' => 'yii\authclient\Collection',
            'clients' => [
                'facebook' => [
                    'class' => 'yii\authclient\clients\Facebook',
                    'clientId' => 'facebook_client_id',
                    'clientSecret' => 'facebook_client_secret',
                ],
            ],
        ]
        // ...
    ]

See also:

- https://developers.facebook.com/apps
- http://developers.facebook.com/docs/reference/api

## Public Properties

Hide inherited properties

Property | Type | Description | Defined By
--- | --- | --- | ---
$accessToken | yii\authclient\OAuthToken | Auth token instance. Note that the type of this property differs in getter and setter. See getAccessToken() and setAccessToken() for details. | yii\authclient\BaseOAuth
$apiBaseUrl | string | API base URL. | yii\authclient\clients\Facebook
$attributeNames | array | List of attribute names, which should be requested from API to initialize user attributes. | yii\authclient\clients\Facebook
$authUrl | string | Authorize URL. | yii\authclient\clients\Facebook
$autoExchangeAccessToken | boolean | Whether to automatically upgrade short-live (2 hours) access token to long-live (60 days) one, after fetching it. | yii\authclient\clients\Facebook
$autoRefreshAccessToken | boolean | Whether to automatically perform 'refresh access token' request on expired access token. | yii\authclient\clients\Facebook
$behaviors | yii\base\Behavior[] | List of behaviors attached to this component. This property is read-only. | yii\base\Component
$clientAuthCodeUrl | string | URL endpoint for the client auth code generation. | yii\authclient\clients\Facebook
$clientId | string | OAuth client ID. | yii\authclient\OAuth2
$clientSecret | string | OAuth client secret. | yii\authclient\OAuth2
$httpClient | yii\httpclient\Client | Internal HTTP client. Note that the type of this property differs in getter and setter. See getHttpClient() and setHttpClient() for details. | yii\authclient\BaseClient
$id | string | Service id. | yii\authclient\BaseClient
$name | string | Service name. | yii\authclient\BaseClient
$normalizeUserAttributeMap | array | Normalize user attribute map. | yii\authclient\BaseClient
$parametersToKeepInReturnUrl | array | List of the parameters to keep in default return url. | yii\authclient\BaseOAuth
$requestOptions | array | HTTP request options. This property is read-only. | yii\authclient\BaseClient
$returnUrl | string | Return URL. | yii\authclient\BaseOAuth
$scope | string | Auth request scope. | yii\authclient\clients\Facebook
$signatureMethod | yii\authclient\signature\BaseMethod | Signature method instance. Note that the type of this property differs in getter and setter. See getSignatureMethod() and setSignatureMethod() for details. | yii\authclient\BaseOAuth
$stateStorage | yii\authclient\StateStorageInterface | Stage storage. Note that the type of this property differs in getter and setter. See getStateStorage() and setStateStorage() for details. | yii\authclient\BaseClient
$title | string | Service title. | yii\authclient\BaseClient
$tokenUrl | string | Token request URL endpoint. | yii\authclient\clients\Facebook
$userAttributes | array | List of user attributes. | yii\authclient\BaseClient
$validateAuthState | boolean | Whether to use and validate auth 'state' parameter in authentication flow. | yii\authclient\OAuth2
$version | string | Protocol version. | yii\authclient\BaseOAuth
$viewOptions | array | View options in format: optionName => optionValue. | yii\authclient\BaseClient

## Public Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
__call() | Calls the named method which is not a class method. | yii\base\Component
__clone() | This method is called after the object is created by cloning an existing one. | yii\base\Component
__construct() | Constructor. | yii\base\BaseObject
__get() | Returns the value of a component property. | yii\base\Component
__isset() | Checks if a property is set, i.e. defined and not null. | yii\base\Component
__set() | Sets the value of a component property. | yii\base\Component
__unset() | Sets a component property to be null. | yii\base\Component
api() | Performs request to the OAuth API returning response data. | yii\authclient\BaseOAuth
applyAccessTokenToRequest() | Applies access token to the HTTP request instance. | yii\authclient\clients\Facebook
attachBehavior() | Attaches a behavior to this component. | yii\base\Component
attachBehaviors() | Attaches a list of behaviors to the component. | yii\base\Component
authenticateClient() | Authenticate OAuth client directly at the provider without third party (user) involved, using 'client_credentials' grant type. | yii\authclient\OAuth2
authenticateUser() | Authenticates user directly by 'username/password' pair, using 'password' grant type. | yii\authclient\OAuth2
authenticateUserJwt() | Authenticates user directly using JSON Web Token (JWT). | yii\authclient\OAuth2
beforeApiRequestSend() | Handles yii\httpclient\Request::EVENT_BEFORE_SEND event. | yii\authclient\BaseOAuth
behaviors() | Returns a list of behaviors that this component should behave as. | yii\base\Component
buildAuthUrl() | Composes user authorization URL. | yii\authclient\OAuth2
canGetProperty() | Returns a value indicating whether a property can be read. | yii\base\Component
canSetProperty() | Returns a value indicating whether a property can be set. | yii\base\Component
className() | Returns the fully qualified name of this class. | yii\base\BaseObject
createApiRequest() | Creates an HTTP request for the API call. | yii\authclient\BaseOAuth
createRequest() | Creates HTTP request instance. | yii\authclient\BaseClient
detachBehavior() | Detaches a behavior from the component. | yii\base\Component
detachBehaviors() | Detaches all behaviors from the component. | yii\base\Component
ensureBehaviors() | Makes sure that the behaviors declared in behaviors() are attached to this component. | yii\base\Component
exchangeAccessToken() | Exchanges short-live (2 hours) access token to long-live (60 days) one. | yii\authclient\clients\Facebook
fetchAccessToken() | Fetches access token from authorization code. | yii\authclient\clients\Facebook
fetchClientAccessToken() | Fetches access token from client-specific authorization code. | yii\authclient\clients\Facebook
fetchClientAuthCode() | Requests the authorization code for the client-specific access token. | yii\authclient\clients\Facebook
getAccessToken() |  | yii\authclient\BaseOAuth
getBehavior() | Returns the named behavior object. | yii\base\Component
getBehaviors() | Returns all behaviors attached to this component. | yii\base\Component
getHttpClient() | Returns HTTP client. | yii\authclient\BaseClient
getId() |  | yii\authclient\ClientInterface
getName() |  | yii\authclient\ClientInterface
getNormalizeUserAttributeMap() |  | yii\authclient\BaseClient
getRequestOptions() |  | yii\authclient\BaseClient
getReturnUrl() |  | yii\authclient\BaseOAuth
getSignatureMethod() |  | yii\authclient\BaseOAuth
getStateStorage() |  | yii\authclient\BaseClient
getTitle() |  | yii\authclient\ClientInterface
getUserAttributes() |  | yii\authclient\ClientInterface
getViewOptions() |  | yii\authclient\ClientInterface
hasEventHandlers() | Returns a value indicating whether there is any handler attached to the named event. | yii\base\Component
hasMethod() | Returns a value indicating whether a method is defined. | yii\base\Component
hasProperty() | Returns a value indicating whether a property is defined for this component. | yii\base\Component
init() | Initializes the object. | yii\base\BaseObject
off() | Detaches an existing event handler from this component. | yii\base\Component
on() | Attaches an event handler to an event. | yii\base\Component
refreshAccessToken() | Gets new auth token to replace expired one. | yii\authclient\BaseOAuth
setAccessToken() | Sets access token to be used. | yii\authclient\BaseOAuth
setHttpClient() | Sets HTTP client to be used. | yii\authclient\BaseOAuth
setId() |  | yii\authclient\ClientInterface
setName() |  | yii\authclient\ClientInterface
setNormalizeUserAttributeMap() |  | yii\authclient\BaseClient
setRequestOptions() |  | yii\authclient\BaseClient
setReturnUrl() |  | yii\authclient\BaseOAuth
setSignatureMethod() | Set signature method to be used. | yii\authclient\BaseOAuth
setStateStorage() |  | yii\authclient\BaseClient
setTitle() |  | yii\authclient\ClientInterface
setUserAttributes() |  | yii\authclient\BaseClient
setViewOptions() |  | yii\authclient\BaseClient
trigger() | Triggers an event. | yii\base\Component

## Protected Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
applyClientCredentialsToRequest() | Applies client credentials (e.g. $clientId and $clientSecret) to the HTTP request instance. | yii\authclient\OAuth2
composeUrl() | Composes URL from base URL and GET params. | yii\authclient\BaseOAuth
createHttpClient() | Creates HTTP client instance from reference or configuration. | yii\authclient\BaseOAuth
createSignatureMethod() | Creates signature method instance from its configuration. | yii\authclient\BaseOAuth
createToken() | Creates token from its configuration. | yii\authclient\BaseOAuth
defaultName() | Generates service name. | yii\authclient\clients\Facebook
defaultNormalizeUserAttributeMap() | Returns the default $normalizeUserAttributeMap value. | yii\authclient\BaseClient
defaultRequestOptions() | Returns default HTTP request options. | yii\authclient\BaseOAuth
defaultReturnUrl() | Composes default $returnUrl value. | yii\authclient\BaseOAuth
defaultTitle() | Generates service title. | yii\authclient\clients\Facebook
defaultViewOptions() | Returns the default $viewOptions value. | yii\authclient\clients\Facebook
generateAuthState() | Generates the auth state value. | yii\authclient\OAuth2
getState() | Returns persistent state value. | yii\authclient\BaseClient
getStateKeyPrefix() | Returns session key prefix, which is used to store internal states. | yii\authclient\BaseClient
initUserAttributes() | Initializes authenticated user attributes. | yii\authclient\clients\Facebook
normalizeUserAttributes() | Normalize given user attributes according to $normalizeUserAttributeMap. | yii\authclient\BaseClient
removeState() | Removes persistent state value. | yii\authclient\BaseClient
restoreAccessToken() | Restores access token. | yii\authclient\BaseOAuth
saveAccessToken() | Saves token as persistent state. | yii\authclient\BaseOAuth
sendRequest() | Sends the given HTTP request, returning response data. | yii\authclient\BaseOAuth
setState() | Sets persistent state. | yii\authclient\BaseClient

## Property Details

$apiBaseUrl public property

API base URL. This field will be used as yii\httpclient\Client::$baseUrl value of $httpClient. Note: changing this property will take no effect after $httpClient is instantiated.

public string $apiBaseUrl = 'https://graph.facebook.com'
$attributeNames public property (available since version 2.0.5)

List of attribute names, which should be requested from API to initialize user attributes.

public array $attributeNames = ['name', 'email']
$authUrl public property

Authorize URL.

public string $authUrl = 'https://www.facebook.com/dialog/oauth'
$autoExchangeAccessToken public property (available since version 2.1.3)

Whether to automatically upgrade short-live (2 hours) access token to long-live (60 days) one, after fetching it.

See also exchangeToken().

public boolean $autoExchangeAccessToken = false
$autoRefreshAccessToken public property (available since version 2.0.6)

Whether to automatically perform 'refresh access token' request on expired access token.

public boolean $autoRefreshAccessToken = false
$clientAuthCodeUrl public property (available since version 2.1.3)

URL endpoint for the client auth code generation.

See also:

- https://developers.facebook.com/docs/facebook-login/access-tokens/expiration-and-extension
- fetchClientAuthCode()
- fetchClientAccessToken()

public string $clientAuthCodeUrl = 'https://graph.facebook.com/oauth/client_code'
$scope public property

Auth request scope.

public string $scope = 'email'
$tokenUrl public property

Token request URL endpoint.

public string $tokenUrl = 'https://graph.facebook.com/oauth/access_token'

## Method Details

applyAccessTokenToRequest() public method (available since version 2.1)

Applies access token to the HTTP request instance.

public void applyAccessTokenToRequest ( $request, $accessToken )
$request | yii\httpclient\Request | HTTP request instance.
$accessToken | yii\authclient\OAuthToken | Access token instance.

defaultName() protected method

Generates service name.

protected string defaultName ( )
return | string | Service name.

defaultTitle() protected method

Generates service title.

protected string defaultTitle ( )
return | string | Service title.

defaultViewOptions() protected method

Returns the default $viewOptions value.

Particular client may override this method in order to provide specific default view options.

protected array defaultViewOptions ( )
return | array | List of default $viewOptions

exchangeAccessToken() public method (available since version 2.1.3)

Exchanges short-live (2 hours) access token to long-live (60 days) one.

Note that this method will success for already long-live token, but will not actually prolong it any further. Pay attention, that this method will fail on already expired access token.

See also https://developers.facebook.com/docs/facebook-login/access-tokens/expiration-and-extension.

public yii\authclient\OAuthToken exchangeAccessToken ( yii\authclient\OAuthToken $token )
$token | yii\authclient\OAuthToken | Short-live access token.
return | yii\authclient\OAuthToken | Long-live access token.

fetchAccessToken() public method

Fetches access token from authorization code.

public yii\authclient\OAuthToken fetchAccessToken ( $authCode, array $params = [] )
$authCode | string | Authorization code, usually comes at GET parameter 'code'.
$params | array | Additional request params.
return | yii\authclient\OAuthToken | Access token.
throws | yii\web\HttpException | on invalid auth state in case enableStateValidation is enabled.

fetchClientAccessToken() public method (available since version 2.1.3)

Fetches access token from client-specific authorization code.

This make sense for the distributed applications, which provides several Auth clients (web and mobile) to avoid triggering Facebook's automated spam systems.

See also:

- https://developers.facebook.com/docs/facebook-login/access-tokens/expiration-and-extension
- fetchClientAuthCode()

public yii\authclient\OAuthToken fetchClientAccessToken ( $authCode, array $params = [] )
$authCode | string | Client auth code.
$params | array |
return | yii\authclient\OAuthToken | Long-live client-specific access token.

fetchClientAuthCode() public method (available since version 2.1.3)

Requests the authorization code for the client-specific access token.

This make sense for the distributed applications, which provides several Auth clients (web and mobile) to avoid triggering Facebook's automated spam systems.

See also:

- https://developers.facebook.com/docs/facebook-login/access-tokens/expiration-and-extension
- fetchClientAccessToken()

public string fetchClientAuthCode ( yii\authclient\OAuthToken $token = null, $params = [] )
$token | yii\authclient\OAuthToken|null | Access token, if not set $accessToken will be used.
$params | array | Additional request params.
return | string | Client auth code.

initUserAttributes() protected method

Initializes authenticated user attributes.

protected array initUserAttributes ( )
return | array | Auth user attributes.