Skip to main content

SDK OAuth Helper

Is this the right authentication method for you?

Before starting to read this page, we invite you to check if this is the best authentication method for you. Please check the flowchart you can find on the Authentication page before proceeding.

The OAuth 2.0 Authentication Code Flow is the recommended method to retrieve an Access Token for applications that have access to secure, private storage such as web applications deployed on a server; if your use case isn't compatible with this requirement, we suggest checking the Authentication page to check the other methods supported by our app.

This is not a general explanation

This guide describes our implementation of the OAuth 2.0 Authentication Code flow. If you are interested in a more general explanation of this concept, please refer to the dedicated page.

To interact with our API on behalf of the user using this flow, it is necessary to implement the steps explained below.

Code Examples

This guide makes extensive use of our SDKs. Our OAuth2 helpers are built to take care of the authentication steps for you, hiding the implementation details and simplifying the development; since it could be confusing to read information about the steps made transparent by our SDK, this guide omits a lot of details, such as the performed REST calls. If you are interested in deep diving into our authentication flow, or if you prefer to avoid importing our SDK and use vanilla code instead, you could prefer to read this page.

🔑  Token types​

Here's a quick reminder of the three tokens that we'll obtain in the following steps. All of the three tokens are pseudo casual strings with a specific prefix that can be used to discern each one of the tokens; each one of the tokens has a specific purpose and a lifespan (e.g. an expiration time) that define their validity.

Token NameDescriptionPrefixLifespan
Authorization CodeThis is the token you will exchange to get an Access Token. It is valid only one time and has a very short lifespan.c/60 seconds (from its emission)
Access TokenThis is the token you will use to make requests.a/24 hours (from its emission)
Refresh TokenThis is the token you will use only to make refresh requests to obtain a new Access Token when the old one expires, without having to ask the user to give a new explicit authorization. When it expires it is necessary to perform this flow again from step 1.r/1 year (from the last refresh request)

0️⃣  Prerequisites: Create an app and retrieve the credentials​

The Authentication Code flow requires specific credentials, that are specific to a single application. You can create an app following this guide: Create an app.

While creating the app, you need to select the OAuth 2.0 authentication and authorization method and retrieve the Client ID and Client Secret credentials: you will need them in the following steps.

Never share the Client Secret!!!

The Client Secret, used in the OAuth 2.0 flow, is a piece of sensible information so it must NEVER be shared with third-party actors, and it must always be kept safe (for example in an environment variable used by your backend). Never share it with other people, or publish it on your frontend! If it happened, then we suggest you to delete your application on the Fatture in Cloud page.

On the same page, you need to define a Redirect URL: it is an endpoint that must be exposed by your application to be able to receive the Authorization Code.

For this chapter, we will use the https://www.yourapplication.com/redirect URL, but you are free to specify one that best fits your needs.

note

The Redirect URI must be formally valid, and it will be checked while creating the application. For local development purposes, also the localhost URI is enabled (for example, you can declare "http://localhost:8080" to reach your backend running locally).

1️⃣  Initialize the OAuth2AuthorizationCodeManager object​

The first fundamental step is to initialize the OAuth2AuthorizationCodeManager object, you will need it in all the following steps.

using It.FattureInCloud.Sdk.OauthHelper;

var redirectUri = "http://localhost:3000/oauth";
OAuth2AuthorizationCodeManager oauth = new OAuth2AuthorizationCodeManager("CLIENT_ID", "CLIENT_SECRET", redirectUri);
Keep it secret!

It is important to keep the Client Secret a secret. So it must be stored carefully and it should be used only in backend applications. Don't commit it to public repositories and don't use it where the users could obtain it (for example in frontend applications).

Check the Redirect URI!!!

We perform a String Equals to compare the Redirect URI the SDK will send in the following requests and the one you inserted in the Application page, so they must be exactly the same. This means that if the two paths are equivalent but the strings are different (for example, because you added a "/" at the end of only one of the two strings) you will still obtain an error.

Also, if you use different applications for your different environments (for example, DEV and PROD), please use the correct Redirect URI for the environment you're currently in: if the two redirect URIs are different and you're using the DEV redirect URI while running in PROD env, you'll obtain an error.

2️⃣  Redirect the user to the Fatture in Cloud authorization page​

An external application can consume our API resources only if the owner permits it to do it. The permissions can be obtained on a dedicated page published by Fatture in Cloud.

To perform this step, you just need to redirect the user to a specific URL; this URL will contain some specific information that must be collected beforehand:

Parameter nameDescription
scopeA space-separated list of permissions you are asking for your app. See the Scopes page for further information.
stateA custom, request-specific string parameter generated by your application, that can be double-checked in the next step (see the following note).
The state parameter

The state parameter is intended to preserve some state object set by the client in the Authorization request, and make it available to the client in the response. The main security reason for this is to stop Cross Site Request Forgery (XSRF). XSRF attacks are not new or specific to OAuth, and the way to prevent them is to include something in the request that the client can verify in the response but that an attacker could not know. An example of this would be a hash of the session cookie or a random value stored in the server linked to the session. If the client can’t verify the value returned, then it must reject authentication responses that could be generated as the result of requests by third-party attackers. Also, if you need to keep any other pieces of information you can encode it in the state parameter as well since it is just a string.

Below you can find some code examples that will help you build the URL for the redirect.

using It.FattureInCloud.Sdk.OauthHelper;

// the oauth object is defined at the step 1

var scopes = new List<Scope> {
    Scope.SETTINGS_ALL,
    Scope.ISSUED_DOCUMENTS_INVOICES_READ
};
var url = oauth.GetAuthorizationUrl(scopes, "EXAMPLE_STATE");

The generated URL, with URL-encoded params, will look like this:

https://api-v2.fattureincloud.it/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fwww.yourapplication.com%2Fredirect&scope=scope%3Ar%20scope%3Aa&state=EXAMPLE_STATE
You must redirect!

This is not a simple HTTP GET request, you need to be able to open a browser page to complete this step.

Once the URL is generated, you must use it to redirect the user. Once landed on the Fatture in Cloud page, the user will be required to:

  • Login to Fatture in Cloud using his account credentials;
  • Give explicit consent to the permissions requested by the application. These operations will be performed automatically by our page, so you don't need to worry about them.
Scopes and permissions

Please note that the permissions requested to the user on our page will be strictly related to the scopes you picked and inserted in the query string.

It is important to select the minimum set of scopes required by your application to fulfill your use case: if you select too few, you may obtain some 403 Forbidden errors while performing operations out of the scope set, while if you select too many the user could feel overwhelmed and reject your permissions request entirely.

3️⃣  Obtain the Authorization Code​

Once the user gave explicit consent to your request, our page will redirect the user to the Redirect URL specified in the previous step (in the example, to https://www.yourapplication.com/redirect).

Our page will share two parameters with your application:

Parameter nameDescription
stateThe state string, as provided in the previous step.
codeThe Authorization Code token.

The two parameters will be sent to your application as URL-encoded query string parameters, so your application must be able to manage appropriately the following HTTP GET request (in this example, we use "EXAMPLE_CODE" as the value for the returned Authorization Code):

GET https://www.yourapplication.com/redirect?state=EXAMPLE_STATE&code=EXAMPLE_CODE

Most frameworks take care of extracting the query string params for you. In case you need to extract the params from the URL on your own, you can use the following code:

using It.FattureInCloud.Sdk.OauthHelper;

// the oauth object is defined at the step 1

var params = oauth.GetParamsFromUrl("http://localhost:3000/oauth?code=EXAMPLE_CODE&state=EXAMPLE_STATE");

var code = params.AuthorizationCode;
var state = params.State;

Once you extracted the two parameters, you must check the state parameter value; if it doesn’t match, then probably a third party created the request, and you should abort the process.

If the state is valid, then you can use the code parameter to perform the next step.

4️⃣  Obtain the Access Token​

The Authorization Code obtained above has only one purpose: to exchange it with an Access Token.

Once you checked that the state is valid, you can use it to retrieve the token using the related method as shown in the examples below.

The parameters required for the request are the following:

Parameter nameDescription
codeThe Authorization Code obtained in the previous step.

Here you can find some code examples to obtain the access token with our SDKs.

using It.FattureInCloud.Sdk.OauthHelper;

// the oauth object is defined at the step 1

var tokenObj = oauth.FetchToken("PREVIOUSLY_RETRIEVED_AUTHORIZATION_CODE");
var accessToken = tokenObj.AccessToken;
var refreshToken = tokenObj.RefreshToken;

The returned parameters are:

Parameter nameDescription
access_tokenThe Access Token.
refresh_tokenThe Refresh Token.
expires_inThe validity of the Access Token in seconds before its expiration.

As you can see, the REST call will return the Access Token and the Refresh Token. The Access Token can be used to perform multiple API requests, but it expires after a certain amount of time. The Refresh Token instead can be used to obtain a new Access Token once the previous one is expired; it also expires, but its lifespan is higher than the Access Token one.

We're done!

Now you can use the Access Token to interact with the Fatture in Cloud API. In the next sections, you'll see how to use it to perform a request.

Protect the tokens!!!

The Access Token (and by extension the Refresh Token) makes it possible to perform operations on the Fatture in Cloud API on behalf of the user, thus your application will be able to read and modify the user's resources. This means that the tokens are a precious resource that must be protected (avoid sending them to the frontend).

Also, your application will obtain a dedicated token set for each one of the users, so it will be necessary to correctly associate a single user with his tokens.

💼  Find your Company ID​

Even if this step is not strictly part of the Authentication process, it is required to be able to use the Company-scoped Methods. Once you obtain the Access Token, you can use the List User Companies method to retrieve the ID of the related Company; please check the Company-scoped Methods page for further info.

✅  Perform an API request​

A valid Access Token can be used to authorize requests included in the scopes authorized by the user at step one; to obtain a valid response it is necessary to include the Access Token in your request as an HTTP header.

In the following example, we'll simulate a Get Supplier call. We choose this method because it is relatively easy to understand and it requires the entity.suppliers:r scope to be authorized correctly.

Please, notice that for this example we will assume that we already know the parameters required by the request and that we have previously acquired a valid Access Token performing the steps above.

The corresponding code is the following:

using System.Collections.Generic;
using System.Diagnostics;
using It.FattureInCloud.Sdk.Api;
using It.FattureInCloud.Sdk.Client;
using It.FattureInCloud.Sdk.Model;

namespace Example
{
    public class GetIssuedDocumentExample
    {
        public static void Main()
        {
            Configuration config = new Configuration();
            config.AccessToken = "PREVIOUSLY_RETRIEVED_ACCESS_TOKEN";

            var apiInstance = new IssuedDocumentsApi(config);
            var companyId = 12345;
            var documentId = 17;

            try
            {
                GetIssuedDocumentResponse result = apiInstance.GetIssuedDocument(companyId, documentId);
                Console.WriteLine(result);
            }
            catch (ApiException  e)
            {
                Debug.Print("Exception when calling IssuedDocumentsApi.GetIssuedDocument: " + e.Message );
                Debug.Print("Status Code: "+ e.ErrorCode);
                Debug.Print(e.StackTrace);
            }
        }
    }
}

If the Access Token is valid and provided correctly in the header, the response will be a 200 OK. To check the possible error responses, please check the dedicated page.

♻️  Refreshing the token​

When the Access Token expires, you have two options to keep performing authenticated requests:

  • Obtain a new one performing steps 1-3
  • Obtain a new one using the Refresh Token

Please, note that the first option once again requires user interaction, so we suggest performing it again only when the Refresh Token is expired.

The parameters required for the request are the following:

Parameter nameDescription
refresh_tokenThe Refresh Token obtained previously.

Here you can find some code examples to refresh the token using our SDKs.

using It.FattureInCloud.Sdk.OauthHelper;

// the oauth object is defined at the step 1

var tokenObj = oauth.RefreshToken("PREVIOUSLY_RETRIEVED_REFRESH_TOKEN");
var accessToken = tokenObj.AccessToken;

The returned parameters are:

Parameter nameDescription
access_tokenThe Access Token.
refresh_tokenThe Refresh Token.
expires_inThe validity of the Access Token in seconds before its expiration.

The obtained token can be used exactly as explained in step 5 of this guide.

📝  Change Token permissions​

Unfortunately, if you need to change the set of permissions that you are currently requiring from your app users, you can't do it by preserving the old token: you must discard the old token on your code and replace it with a new one obtained after updating the scopes list at Step 2.