Authenticating with OAuth 2.0

Onvio BR Accounting API

OVERVIEW

Purpose

As Thomson Reuters pushes more-and-more APIs into the 3rd-party marketplace, we MUST use standards-based approaches for API access management; in short, this means using OAuth2 and for the partner's Company access Onvio users data and act in his behalf they will need to authenticate through the OAuth 2 pattern.

Establish OAuth roles

To get started with OAuth, it helps to first figure out who is playing what role, from an OAuth perspective:

Actor	OAuth role
Accountant	No role in this OAuth flow
Accountant's client (i.e. a person)	Resource owner
3rd-party / Partner application	Client (as in an application)
Auth0	Authorization Server
Onvio BR API	Resource Server
OIDC	Open Id connection

With the actors mapped to OAuth roles, then there are a certain amount of definitions that come along and that need to be clearly defined and communicated to all that need to interact with us.

Authorization code

The authorization code is the code that you are going to use to exchange for an access token.

Access token

The first thing a client must do in order to access protected resources is to obtain an access token.

Access tokens are the thing that applications use to make API requests on behalf of a user. The access token represents the authorization of a specific application to access specific parts of a user’s data.

Access tokens must be kept confidential in transit and in storage. The only parties that should ever see the access token are the application itself, the authorization server, and resource server. The application should ensure the storage of the access token is not accessible to other applications on the same device. The access token can only be used over an https connection, since passing it over a non-encrypted channel would make it trivial for third parties to intercept.

Refresh token

Based on OAuth 2.0 Refresh Token definition:
"The Refresh Token grant type is used by clients to exchange a refresh token for an access token when the access token has expired.

This allows clients to continue to have a valid access token without further interaction with the user."

OpenId Connect Protocol

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 framework. It allows third-party applications to verify the identity of the end-user and to obtain basic user profile information. OIDC uses JSON web tokens (JWTs),

While OAuth 2.0 is about resource access and sharing, OIDC is about user authentication. Its purpose is to give you one login for multiple sites. Each time you need to log in to a website using OIDC, you are redirected to your OpenID site where you log in, and then taken back to the website. For example, if you chose to sign in to Auth0 using your Google account then you used OIDC. Once you successfully authenticate with Google and authorize Auth0 to access your information, Google sends information back to Auth0 about the user and the authentication performed. This information is returned in a JWT. You'll receive an access token and if requested, an ID token.

Enabling your company to integrate with Onvio APIs

In order to be able to integrate with Onvio and Domínio Contábil you have to go through the below steps:

Step 1 - Credentials

To receive OAuth credentials send an email to Onvio BR API team with Company's name, the main person of contact, phone contact, email, and callback URL.

We are going to email you back with client_id and cliente_secret. The below steps are going to explain where and how you are going to use client_id and client_secret.

Step 2 - Authorization Code

Using client_id received and callback URL provided, in order to get the authorization code, you will need to access the Thomson Reuters authentication service calling the below URL:

https://auth.thomsonreuters.com/authorize?client_id={client_id}&response_type=code&audience=409f91f6-dc17-44c8-a5d8-e0a1bafd8b67&redirect_uri={callback url}&scope=openid+profile+email+offline_access

{cliente_id} and {callback url} on the above URL are required variables that you have to replace those for the appropriate values.

The parameters:

audience: default value for the onvio audience '409f91f6-dc17-44c8-a5d8-e0a1bafd8b67'

response_type: default value 'code'

scope: openId for OIDC.
profile and email for the api requirements.
offline_access to receive the refresh_token.

state: optional parameter. understand the state parameter

Once the below web page is opened the user has to enter his Onvio Client credentials. If the user does not have Onvio Client credentials, the user has to request the credentials to the Accountant.

After the user hits the "Sign In" button and if the credentials are validated, Thomson Reuters authentication service will make a redirect to the callback URL informed in the redirect_uri and it will have the query parameter called "code" that will be the authorization code:

Once you have a valid code you are going to exchange your code(Authorization code) for access and refresh token.

Step 3 - Exchange Authorization code for Access/Refresh Token

Now to start making requests to our API's you will need the access token and it can be generated using the authorization code and making the below request:

HTTP POST to:

https://auth.thomsonreuters.com/oauth/token

Headers:

Authorization: Basic hash_base64(client_id:client_secret)

Content-Type: application/x-www-form-urlencoded

Body:

grant_type: Always "authorization_code"

redirect_uri: Redirect url(your callback URL)

code: Authorization code

The response will be a JSON with the following properties:

"access_token": access token as a JWT to be used in the API calls in the authorization header.

"refresh_token": refresh token to be used when the access token expires.

"scope": the resources that were granted access.

" id_token":id_token is a JSON Web Token (JWT)

"token_type": the type of the token to be put as pre in the authorization header.

"expires_in": when the token expires in secondes.

Step 4 - Exchange a Refresh Token for a new Access/Refresh Token

Once the access token gets expired, you must use the refresh token in order to receive new access and refresh token. You need to make the below request: