Finvera offers authentication and authorization using the OAuth 2.0 protocol and it supports the authorization code flow which exchanges an authorization code for an access token. This document describes our OAuth 2.0 implementation for authentication, which conforms to the OpenID Connect specification.

Configure an OAuth app in Finvera

Your application must register in the Finvera UI to obtain the OAuth client ID and secret and here is how you navigate to the Developers module to create an application.

🚧

You must have an admin privilege to at least one organization to create an application and your identity must be verified.

You provide an app name and select the organization to create the application.

Application is created successfully after the "create" button is clicked.

You save an application once you provide all the mandatory fields.

The Discovery document

The OpenID Connect protocol requires the use of multiple endpoints for authenticating users, and for requesting resources including tokens, user information, and public keys.

To simplify implementations and increase flexibility, OpenID Connect allows the use of a "Discovery document," a JSON document found at a well-known location containing key-value pairs which provide details about the OpenID Connect provider's configuration, including the URIs of the authorization, token, revocation, userinfo, and public-keys endpoints. The Discovery document for Finvera's OpenID Connect service may be retrieved from:

https://i.finvera.com/.well-known/openid-configuration

To use Finvera's OpenID Connect services, you should hard-code the Discovery-document URI (https://i.finvera.com/.well-known/openid-configuration) into your application. Your application fetches the document, applies caching rules in the response, then retrieves endpoint URIs from it as needed. For example, to authenticate a user, your code would retrieve the authorization_endpoint metadata value (https://i.finvera.com/o/authorize in the example below) as the base URI for authentication requests that are sent to Finvera.

Here is an example of such a document; the field names are those specified in OpenID Connect Discovery 1.0 Please refer to that document for their meanings.

{
  "issuer": "https://i.finvera.com",
  "authorization_endpoint": "https://i.finvera.com/o/authorize",
  "token_endpoint": "https://i.finvera.com/o/token",
  "userinfo_endpoint": "https://i.finvera.com/o/userinfo",
  "end_session_endpoint": "https://i.finvera.com/o/end-session",
  "introspection_endpoint": "https://i.finvera.com/o/introspect",
  "response_types_supported": [
    "code",
    "id_token",
    "id_token token",
    "code token",
    "code id_token",
    "code id_token token"
  ],
  "jwks_uri": "https://i.finvera.com/o/jwks",
  "id_token_signing_alg_values_supported": [
    "HS256",
    "RS256"
  ],
  "subject_types_supported": [
    "public"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ]
}

Obtain an access token and an id token

To access the user data, your application must obtain an access token from the authorization server. The first step is to call the /o/authorize/ endpoint with client_id, redirect_url, response_type, and scope, and the Finvera OAuth offers two scopes with a mandatory third openid scope. The scope parameter must begin with the openid value and then include the profile value, the email value, or both.

OAuth Scopes

📘

To access a full report of a financial professional with license information, you may refer to the "Accessing Data" section.

Request URL: https://i.finvera.com/o/authorize/
?client_id=YOUR-CLIENT-ID
&redirect_uri=https://YOUR-APPLICAION.COM/login/callback/
&scope=openid profile email
&response_type=code

Request Method: GET

Status Code: 302 Found

Location: https://app.finvera.com/o/authorize/
?client_id=YOUR-CLIENT-ID
&redirect_uri=https://YOUR-APPLICAION.COM/login/callback/
&scope=openid profile email
&response_type=code

The user redirects and logs in to Finvera and the user also completes the Finvera verification process if he has not done it before. Refer to this link for verification flow details.

After the identification verification, the user consents to give your application permissions to access his data and the Finvera sends an authorization code to your callback URL, which is registered in the Finvera UI.

Request URL: https://YOUR-APPLICAION.COM/login/callback/
?code=x3xqddtZjAJk9FwuOKCqf1ymObdb0m

Request Method: GET

Your application exchanges the authorization code for an access token.

Request URL: https://i.finvera.com/o/token/

Request Method: POST

Content-Type: application/json

Request Payload:
{
	"client_id":"YOUR-CLIENT_ID",
	"client_secret":"YOUR-CLIENT-SECRET",
	"redirect_uri":"https://YOUR-APPLICAION.COM/login/callback/",
	"code":"x3xqddtZjAJk9FwuOKCqf1ymObdb0m",
	"scope":"openid profile email",
	"grant_type":"authorization_code",
	"response_type":"token"
}

A successful response to this request contains the following fields in a JSON array:

Response:
{
	"access_token": "YUmj1IRnDzJAuUt0Z4BXTcPGfwh7ZC",
    "id_token": "k9FwuOKCqf1ymObdb0RnDzJAuqf1ymObdbuOKCqf1..."
	"expires_in": 3600,
	"token_type": "Bearer",
	"scope": "openid profile email"
}

Accessing Data

You can access the data of financial professionals in two ways, depending on the level of information that you need.

1. Obtain user information from the ID token

An ID Token is a JWT (JSON Web Token), that is, a cryptographically signed Base64-encoded JSON object. Normally, it is critical that you validate an ID token before you use it, but since you are communicating directly with Finvera over an intermediary-free HTTPS channel and using your client secret to authenticate yourself to Finvera, you can be confident that the token you receive really comes from Finvera and is valid. If your server passes the ID token to other components of your app, it is extremely important that the other components validate the token before using it.

Since most API libraries combine the validation with the work of decoding the base64url-encoded values and parsing the JSON within, you will probably end up validating the token anyway as you access the claims in the ID token.

An ID token is a JSON object containing a set of name/value pairs. Here's an example, formatted for readability:

{
  "iss": "https://i.finvera.com",
  "sub": "10769150350006150715113082367",
  "email": "[email protected]",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
}

1.1 Authenticate the user

After obtaining user information from the ID token, you should query your app's user database. If the user already exists in your database, you should start an application session for that user if all login requirements are met by the Finvera API response.

If the user does not exist in your user database, you should redirect the user to your new-user sign-up flow. You may be able to auto-register the user based on the information you receive from Finvera, or at the very least you may be able to pre-populate many of the fields that you require on your registration form. In addition to the information in the ID token, you can get additional user profile information at our user profile endpoints.

2. OAuth Resource Server

Using the OAuth access token, you can access the user's profile information and email address if the user consent to give you permissions.

curl --location --request GET 'https://api.finvera.com/id/v1.0/user' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN'

{
    "first_name": "John",
    "last_name": "Smith",
    "finvera_id": "Q55C3B",
    "email": "[email protected]",
    "crd": "4077298",
    "npn": "16559706"
}

3. Finvera API

The response payload of the /id/v1.0/user endpoint above includes finvera_id, the unique identifier of the financial professional in the Finvera system. Using the ID, you can retrieve a full report including license information through the Finvera API product.

Please refer to the API documentation