# Authentication Via Facebook

# Description

In this example, the TRIDENT authentication and authorization API is used to authenticate the users of a document signature portal (`https://docsign.safelayer.com`) using Facebook. This authentication allows users to log in to the website. It is triggered when the user clicks on the Login button associated to the Facebook authentication mechanism.

The website is registered as an OAuth 2.0 client application in a TRIDENT system (`txeidas.safelayer.com`) and `https://docsign.safelayer.com/oauth/callback` is the only redirect URL established. When registered, the website obtained an identifier (`docsign`) and a secret shared with TRIDENT (`demodemo`), and was associated to an authorization server called `main`, which has the following endpoints:

Endpoint | Value
Authorization Endpoint | `https://txeidas.safelayer.com/trustedx-authserver/oauth/main`
Access Token Endpoint | `https://txeidas.safelayer.com/trustedx-authserver/oauth/main/token`
UserInfo Endpoint | `https://txeidas.safelayer.com/trustedx-resources/openid/v1/users/me`

The authorization server delegates user authentication to an IdP of the platform called `eidas-provider` and intermediates between the portal and the users so that these users can authorize the portal for accessing their identity data and the details of their authentication process at the endpoint `https://txeidas.safelayer.com/trustedx-resources/openid/v1/users/me`. Furthermore, TRIDENT is configured so that the only authentication requirements for the users are those specified in the authorization requests (`acr_values` parameter).

# Obtaining Authorization

## Request

When the user clicks on the Login button in the browser's window, the website responds with the following HTTP redirect response (see the Obtain Authorization operation):

`HTTP/1.1 302 Found`
`Location: https://txeidas.safelayer.com/trustedx-authserver/oauth/main?response_type=code`
`&client_id=doc_sign`
`&redirect_uri=https://docsign.safelayer.com/oauth/callback`
`&scope=urn:safelayer:eidas:full_identity urn:safelayer:eidas:authn_details`
`&acr_values=urn:safelayer:tws:policies:authentication:flow:basic:facebook`
`&state=99de239bebd2fe9d93afcd9cff2a47b26a85c0a6015b317b08385e02cebd95bc`

Note that the website requests authorization for accessing the identity data of the user and the data on the authentication process carried out on them (`scope=urn:safelayer:eidas:full_identity urn:safelayer:eidas:authn_details)`. Note also that the website requests that the user is authenticated with a flow that delegates authentication to Facebook (`acr_values=urn:safelayer:tws:policies:authentication:flow:basic:facebook`).

When the browser receives this redirect response, it sends the following HTTP request to TRIDENT:

`GET /trustedx-authserver/oauth/main?response_type=code`
`&client_id=doc_sign`
`&redirect_uri=https://docsign.safelayer.com/oauth/callback`
`&scope=urn:safelayer:eidas:full_identity urn:safelayer:eidas:authn_details`
`&acr_values=urn:safelayer:tws:policies:authentication:flow:basic:facebook`
`&state=99de239bebd2fe9d93afcd9cff2a47b26a85c0a6015b317b08385e02cebd95bc HTTP/1.1`
`Host: txeidas.safelayer.com:443`

## Response

After authenticating the user and obtaining their authorization for the website to access their identity and authentication data, TRIDENT redirects the browser to the website's redirect URL, after including in it the authorization code granted (the code parameter of the query string). As a result of the redirect, the browser performs the following HTTP request to the signature site:

`GET /oauth/callback?code=87ad722b7705192382685091ae68aec0322cb1ca397c63ead348c3052865070d`
`&state=99de239bebd2fe9d93afcd9cff2a47b26a85c0a6015b317b08385e02cebd95bc HTTP/1.1`
`Host: docsign.safelayer.com:443`

As well as extracting the code for the authorization granted (`code`), the website must extract the `state` parameter and check that its value matches the value of the `state` parameter in the request.

# Obtaining the Access Token

## Request

After obtaining the authorization code, the signature website requests the access token it needs to access the user's data. To do this, it sends the following request to TRIDENT (see the Obtain a Token operation):

`POST /trustedx-authserver/oauth/main/token HTTP/1.1`
`Host: txeidas.safelayer.com:443`
`Authorization: Basic ZG9jc2lnbjpkZW1vZGVtbw==`
`Content-Type: application/x-www-form-urlencoded; charset=UTF-8`
``
`grant_type=authorization_code&code=87ad722b7705192382685091ae68aec0322cb1ca397c63ead348c3052865070d`

Note that the website must use its identifier and the secret it shares with TRIDENT to authenticate using the HTTP basic authentication scheme (RFC 2617). Also note that to obtain the access token, the website must include the authorization code in the request (`code`).

## Response

`HTTP/1.1 200 OK`
`Content-Type: application/json;charset=utf-8`
`Cache-Control: no-store, no-cache, must-revalidate`
`Pragma: no-cache`
``
`{`
`"access_token" : "c9597ed2551a764d72d687fb2ec511822ae224180376c7632e2515d038639920"`
`"token_type" : "bearer",`
`"expires_in" : 120`
`}`

# Obtaining the User Data

## Request

The website requests the identity data of the user and the information on their authentication process by sending the following request to TRIDENT (see the Obtain Information About the Authenticated User operation):

`GET /trustedx-resources/openid/v1/users/me HTTP/1.1`
`Host: txeidas.safelayer.com:443`
`Authorization: Bearer c9597ed2551a764d72d687fb2ec511822ae224180376c7632e2515d038639920`

Note that the website demonstrates its authorization for accessing the data requested by including the access token (`c959...9920`) in the `Authorization` header. Note also that the portal does not specify what specific information it wants to obtain as this information is determined by the scope of the access token included in the request.

## Response

The website receives an HTTP response with a JSON object containing the identity attributes of the user and information on their authentication process.

`HTTP/1.1 200 OK`
`Content-Type: application/json;charset=utf-8`
``
`{`
`"sub" : "john.doe",`
`"domain" : "eidas-provider",`
`"username" : "john.doe",`
`"email" : "john.doe@example.com",`
`"email_verified" : true,`
`"phone_number" : "00123456789",`
`"distinguished_name" : "CN=john.doe, O=Example",`
`"name" : "John Doe",`
`"updated_at" : 1405897200,`
`"groups" : [ "Marketing", "Sales" ],`
`"acr" : "urn:safelayer:tws:policies:authentication:flow:basic:facebook"`
`"authn_details" : {`
`"authnFlow" : "urn:safelayer:tws:policies:authentication:flow:basic:facebook",`
`"authnLevel" : "urn:safelayer:tws:policies:authentication:level:medium",`
`"directSso" : "false",`
`"targetAcr" : "urn:safelayer:tws:policies:authentication:flow:basic:facebook"`
`}`
`}`

For reasons of security, we recommend checking that the user was authenticated with the authentication flow requested. To do this, a check must be run that the flow specified in the `acr` property matches the flow in the `acr_values` parameter of the authorization request

Using the information in the response, the signature website creates a session for the user. Among the data stored in the session, the website includes the level of assurance of the user's identity (`authn_details.authnLevel` property). Thus, the portal can request the reauthentication of the user if the user makes a request that can only be attended if their identity is known with a higher level of assurance (step-up)

.