Authentication

Glossary

OAuth2 is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords.

OAuth 2.0 is the industry-standard protocol for authorization and focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

We use 2 authentication flows:

• ROPC flow (Resource Owner Password Credentials) allows an application to sign in the user by directly handling their password.
• Basic client credential flow: With machine-to-machine (M2M) applications, the system authenticates and authorizes the app rather than a user. M2M apps use the Client Credentials Flow (RFC 6749) in which they pass along their Client ID and Client Secret to authenticate themselves and get a token.

MFA: Multi-factor authentication is an authentication method in which a computer user is granted access only after successfully presenting two or more pieces of evidence to an authentication mechanism

The process

The access token

• You obtain an access token from the Linxo Connect Authorization Server

  A single access token can grant varying degrees of access to multiple resources. A variable parameter called scope controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.

  There are several ways to make this request, and they vary based on the type of application you are building. For example, a JavaScript application might request an access token using a browser redirect to Linxo Connect, while an application installed on a device which doesn't have a browser could use web service requests.

• You send the access token to the API

  After an application obtains an access token, it sends the token to the API in an HTTP authorization header.

  Access tokens are valid only for the set of operations and resources described in the scope of the token request. For example, if an access token is issued for the bank account resource only, it does not grant access to the transaction resource. You can, however, send that access token to the API multiple times for similar operations.

  See below for a description of the scope values.

The API

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Property
Security scheme type	OAuth2
OAuth2 Flow	Client credentials & ROPC
Token URL	{anvilUrl}/token

The scopes list

The scopes list represents the list of permissions you can request from a user. Each scope is associated with endpoints in our API v2.

Scope
accounts_read	Allows you to retrieve the user's bank account information: bank name, account name, balance...
accounts_manage	accounts_read permissions + update, create and delete bank accounts
connections_manage	update connections credentials, add connections, generate keys for encrypt datas, subscribe to synchronization events queue
connections_sync	Allows you to trigger a synchronization.
transactions_read	Allows you to retrieve the user's bank account information, connections information and transactions information.
profile	Allows you to retrieve information of the user's profile.
profile_edit	profile permissions + update and delete informations
users_create	ability to create users

The complete authentication flow

## The client credentials flow

This flow is meant to be used from a service on the server side (it needs the client secret) in order to access resources which do not belong to a specific user. This flow also allows the API to be used in admin mode. To use this flow, you will have to perform a POST request on the /token endpoint of Linxo Connect authentication server with a HTTP basic authentication and some parameters documented below.

HTTP basic authentication is made by setting a HTTP header Authorization with the value of: Basic clientid:clientsecret Note that this value must be base64-encoded in the request.

HTTP params	Description
grant_type	The value must be client_credentials in order to use the Client Credentials flow.
scope	The scopes requested by your application. It must be separated with spaces (%20 according to URL encoding).

The response will be a JSON object containing:

HTTP params	Description
access_token	The JWT token you will need to authorize your requests to the API in order to access the current user data.
token_type	This will be the word “Bearer” (to indicate a bearer token).
expires_in	Integer representing the TTL of the access token (i.e. when the token will expire).

Example:

# Get access_token
response=$(curl -s -u "${client_id}:${client_secret}"-X POST {anvilUrl}/token \
        -d grant_type=client_credentials \
        -d scope=users_create

# Print human readable response
echo $response | sed -r 's/.?"([^"]+)":"?([^",]+)"?.?/\1: \2\n\n/g'

This command outputs:

access_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
token_type: Bearer
expires_in: 3600

## The resource owner password credentials flow

In the shared Linxo Connect environment, you own your users. You can therefore use the ROPC authentication flow allowing you to obtain an access token against your user credentials.

Widgets services are relying on Accounts API endpoints and therefore you need to ask for the accurate list of scopes when negociating a User Access Token and depending on the widget action you want to deal with for your Linxo Connect user, this list may vary. Refer to the See dedicated chapter for the detailed list of scopes.

HTTP params	Description
grant_type	The value must be password in order to use the ROPC flow.
scope	The scopes requested by your application. It must be separated with spaces (%20 according to URL encoding).
username	The user login
password	The user password
client_id	Your application identifier on Linxo Connect authorization server
client_secret	Your application secret on Linxo Connect authorization server
provider	The method to identify user. Has to be connect

The response will be a JSON object containing:

HTTP params	Description
access_token	The JWT token you will need to authorize your requests to the API in order to access the current user data.
token_type	This will be the word “Bearer” (to indicate a bearer token).
expires_in	Integer representing the TTL of the access token (i.e. when the token will expire).

ROPC example:

# Get access_token
response=$(curl -sk -X POST {anvilUrl}/token \
    -d username=${username} \
    -d password=${password} \
    -d grant_type=password \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d scope=openid%20profile%20accounts_read \
    -d provider=connect)

# Print human readable response
echo $response | sed -r 's/.?"([^"]+)":"?([^",]+)"?.?/\1: \2\n\n/g'

# Get token
token=$(echo $response | sed -r 's/.?"([^"]+)":"?([^",]+)"?.?/\1: \2\n\n/g' | grep access_token | cut -d' ' -f2)

# Use token on a private resource
curl -sk ${api_baseurl}/accounts -H "authorization: Bearer $token" | jq .