Authenticating users / authorizing operations

End users should prove their identity to execute authentication / signature operations, by one or two factors of authentication (also called IdP: identity providers). Third-party applications are allowed to provide restrictions to this behaviour (which ones / how many of them will be used).

These factors of authentication are classified in three categories:

• Based in Knowledge (Something I Know)
• Based in Possession (Something I have)
• Based in Inherence (Something I am)

When two factors of authentication are used, factors of different categories should be used (for instance, first a knowledge factor and later a possession one).

Request authorization

During the authorization phase, end user will be redirected to a Viafirma Fortress user interface, where the user ID has to be entered, and later user should provide valid responses to one or two factors of authentication. For instance, a user can be asked a PIN and then a One-Time-Password sent to the user's mobile phone in an SMS message.

Viafirma Fortress provide a web interface for this purpose, located in the following URL:

{viafirma_fortress_url}/oauth2/v1/auth

({viafirma_fortress_url}: URL of the Fortress implementation, for example https://sandbox.viafirma.com/fortress or https://fortress.viafirma.com/fortress)

The web interface will provide authentication screens for the user, using the factors of authentication recorded in the system for the specified user. This auth URL can receive some parameters which are used to prepare the authentication / authorization request:

{viafirma_fortress_url}/oauth2/v1/auth?
scope=profile|certificate|certificates&
state=&
redirect_uri={authorized_url_callback}&
response_type=code&
client_id={systemcode}&
user_code={usercode}

Param	Value	Desc
scope	profile / certificate / certificates	profile: used to request the authorization to access to user profile information, like name, email, etc. The following message will be shown on screen: certificate: used to request authorization to access to a specific digital certificate belonging to the end user. The following message will be printed on screen: certificates: used to request authorization to access to any of the digital certificates belonging to the end user. The following message will be printed on screen:
state	[string]	OPTIONAL; any value can be sent by third-party application, which will be sent back by Viafirma Fortress to the redirect_uri
redirect_uri	URL	Must be included in system_client Viafirma Fortress configuration
response_type	code	It should be code for webapps
client_id	[string]	third-party application code, which has been recorded in Viafirma Fortress
user_code	[string]	user code as recorded in Viafirma Fortress, for example, citizen-id, passport-id, etc.

Identity providers (IDPs)

An identity provider is a factor of authentication that protects user profile and certificates information. These IDPs are enabled or disabled in Viafirma Fortress setup, and can be later associated with users. These IDPs are used by Viafirma Fortress to make end users prove their identity (for instance: entering a PIN, or password, entering an OTP code sent to an email address or a mobile phone via SMS, etc.).

In order to verify if an IDP is active, settings following this pattern: fortress.idp.{idp_code}.active can be checked (as included in the Installation Manual).

Once the user identification is successfully performed, according to the request settings (one / two factors, etc.), Viafirma Fortress considers the operation has been authorized by end user and redirects back to authorized_url_callback, returning control back to the third party application.

When the passed scope of authorization is certificate or certificates, after the successful identification, Viafirma Fortress will provide the end user a list of the active digital certificate/s available for selection, returning to the client application once a specific certificate has been selected by user.

Email IDP

Viafirma generates an OTP code (otp - one time password) which is sent to the user email address. User is requested to enter this code in the web interface.

OTP SMS IDP

Viafirma generates an OTP code (otp - one time password) which is sent to the user mobile phone number via SMS. User is requested to enter this code in the web interface.

OTP (soft token) IDP

In this case, the OTP code is generated by Google Authenticator or Viafirma OTP apps, available for iOS and Android mobile devices.

LDAP IDP

User is requested to provide LDAP credentials (user/password). LDAP settings must be configured during the installation and configuration phases.

PIN IDP

Users are requested to provide the PIN (personal identification number, a positive 4-digits integer number) which was registered by them in the platform.

Password IDP

Similar to the PIN IDP, Users are requested to provide the password registered by them in the platform.

Getting the authorization/authentication process response

As explained before, once the user authorizes the operation and the identification is successfully performed, according to the request settings (one / two factors, etc.), Viafirma Fortress redirects back to authorized_url_callback, returning control back to the client application, including the code param in the redirect URL querystring:

{authorized_url_callback}?state=&code={authorization_code}

Callback sample:

https://example.com/response?state=&code=9a3fff39-079c-45ec-b263-7d80afb18161

Denied response denied or response with errors

In case the user does not authorize the request or in the event of any kind of errors, Viafirma Fortress will redirect user to authorized_url_callback URL including the param error in the querystring:

{authorized_url_callback}?error={error_code}&state=

Error callback sample:

http://example.com/?error=access_denied&state=

Getting an access token

Once the client app has received a valid authorization-code (code), an access token should be obtained by redeeming the authorization code:

Method: POST
URL: {viafirma_fortress_url}/fortress/oauth2/v1/token

Params:

Responses are returned using application/json format:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "user_code": "11111111H"
}

When grant_type value is client_credentials, no user code is returned:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer"
}

Response description:

Accessing the APIs

Some API REST services related to user profile / certificates can be invoked using a valid access_token. Depending on the provided scope during the authorization phase, some API services can be called:

• SCOPE = profile
• SCOPE = certificate or certificates

for application / client methods:

• signing documents