Skip to main content

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 Oxlin 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 Oxlin, 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 typeOAuth2
OAuth2 FlowClient credentials & ROPC
Token URLhttps://sandbox-auth.oxlin.io/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_readAllows you to retrieve the user's bank account information: bank name, account name, balance...
accounts_manageaccounts_read permissions + update, create and delete bank accounts
connections_manageupdate connections credentials, add connections, generate keys for encrypt datas, subscribe to synchronization events queue
connections_syncAllows you to trigger a synchronization.
transactions_readAllows you to retrieve the user's bank account information, connections information and transactions information.
profileAllows you to retrieve information of the user's profile.
profile_editprofile permissions + update and delete informations
users_createability to create users

The complete authentication flow#

Oxlin Signup Flow

## The client credentials flow

OAuth2 client credentials flow schema

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 Oxlin 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 paramsDescription
grant_typeThe value must be client_credentials in order to use the Client Credentials flow.
scopeThe 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 paramsDescription
access_tokenThe JWT token you will need to authorize your requests to the API in order to access the current user data.
token_typeThis will be the word “Bearer” (to indicate a bearer token).
expires_inInteger 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 https://sandbox-auth.oxlin.io/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 OXLIN environment, you own your users. You can therefore use the ROPC authentication flow allowing you to obtain an access token against your user credentials.

OAuth2 ropc flow schema

Widgets services are relying on Oxlin 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 Oxlin user, this list may vary. Refer to the See dedicated chapter for the detailed list of scopes.

 HTTP paramsDescription
grant_typeThe value must be password in order to use the ROPC flow.
scopeThe scopes requested by your application. It must be separated with spaces (%20 according to URL encoding).
usernameThe user login
passwordThe user password
client_idYour application identifier on Oxlin authorization server
client_secretYour application secret on Oxlin authorization server
providerThe method to identify user. Has to be connect

The response will be a JSON object containing:

 HTTP paramsDescription
access_tokenThe JWT token you will need to authorize your requests to the API in order to access the current user data.
token_typeThis will be the word “Bearer” (to indicate a bearer token).
expires_inInteger representing the TTL of the access token (i.e. when the token will expire).

ROPC example:

# Get access_token
response=$(curl -sk -X POST https://sandbox-auth.oxlin.io/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 .