Environments

FIB offers 2 environments: sandbox and production. Sandbox has the same settings as production environment, but it is dedicated for integration purposes.

Request Partner Registration

You need to have access to our environments to integrate with Login with FIB functionality for which you will need the following details :client_id, client_secret, SSL Certificate.

Notice

Currently Pay with FIB is offline payment type. In future releases it will be upgraded to online type with full options related with this type.

Partner Requirements

Partner must successfully complete registration form and comply with the response instructions

1. Partner must install provided SSL certificate
2. Partner must put Login with FIB button on their web page (HTML tag is provided by FIB after registration)
3. Partner must provide endpoint to receive authorization_code from FIB - according to OAuth2 specification

Getting Started

Firstly, please register your company as a partner.

Our environments are only accessible with a SSL certificate. We will prepare a dedicated SSL certificate for your company and we will provide it to you together with clientId and clientSecret after successful registration. Along with the environment access, you will get all FIB buttons and graphics.

Please install SSL certificate on your machines.

If you already have access to our environment, then please proceed further, following the steps below.

Please reach out to us at integration@fib.iq in case you need further details.

Login with FIB

To be able to access user’s data on behalf of him, you need to obtain a list of tokens (access_token and id_token). In this section we will describe how to do it.

We are fully compliant with OIDC.

OIDC defines multiple flows for obtaining valid access token. In FIB we use the Authorization Code flow.

The flow is presented at the diagram below.

Step 1 - Login

Prerequisite for this stage is the addition of Login with FIB button to your login page. That button should be sent to you after registration as a partner.

To start login process please send following request.

• response_type: Required. Must be sent to code.
• client_id: Required. The client_id should be provided to you after successful registration as a partner.
• scope: Optional. We only support openid scope. If you ask about different scope, then your request will be rejected.
• redirect_uri: Optional. Where the authorization_code will be sent. This value must match one of the values provided during your partner registration.
• state: Optional

If the request was correct, then the FIB login page will be displayed to a user. The user should enter proper credentials, i.e. phone number and password.

Step 2 - Exchange authorization code with Tokens

The authorization_code is sent to the URL which is provided in your first request as a redirect_uri parameter.

Please handle authorization_code properly. It will be sent to you in the following format.

As you can see, the authorization_code is a string. You can use it to exchange it with tokens. To do it, please send following request.

• client_id: Required. The client_id should be provided to you after successful registration as a partner.
• client_secret: Required. The client_secret should be provider to you after successful registration as a partner.
• grant_type: Required. Must be set to authorization_code.
• code: Required. The authorization_code received in the redirect above.
• redirect_uri: Required. This value must mach one of the values provided during your partner registration.

If you send proper request, the FIB SSO will send you a response with list of tokens. Please refer to the next steps → Step 3.

Step 3 - Decode id token

If you successfuly decode id_token, you should see its real structure.

{
  "exp": 1596529813,
  "iat": 1596529513,
  "auth_time": 1596529503,
  "jti": "465fb2cd-d04e-480e-a94e-974fc5c05a4e",
  "iss": "https://keycloak.stage.azure.lawrence-spring.com/auth/realms/fib-personal-application",
  "aud": "sso-client-mock",
  "sub": "6a0b445a-b42c-4739-a65c-d669332bc1a9",
  "typ": "ID",
  "azp": "sso-client-mock",
  "nonce": "Kqxg9IcNjjSjmKN1qmXB0t60rWPAtafnK8bvumzYpeY",
  "session_state": "e573d23c-7a2d-499f-a043-5a16468f06f6",
  "acr": "0",
  "phone_number": "+48666605805",
  "given_name": "Piotr",
  "family_name": "Jasiński"
}

Decoded ID token contains following information about user:

• unique identifier of the user - available under sub > field
• first name - available under given_name field
• last name - available under family_name field
• mobile number - available under phone_number field

Register with FIB

There is no difference between Login with FIB and Register with FIB from the FIB perspective. We will provide both buttons (login and register) after registration as a partner. Please decide how you want to implement it:

• use one button for login and for registration (the registration is done behind the scene)
• use two different buttons: one for login, second one for registration

Anyway, to register new user please use information from id_token. If you decodeid_token (as presented above), then you should find sub field. It is unique identifier of the user. Please notice that id_token will be returned only if you request about openid scope.

Use identifier from sub field to register user in your database. If user will try to register one more time, you can use that field to check if it already exists in your database. Accordingly, for login functionality, you can verify if user exists in you database, and if not you can register him or throw an error.

Unique identifier of the user (sub) never changes.

Tokens

FIB provides three types of tokens:

• access_token
• refresh_token
• id_token

Access Token

Access Token is a part of OAuth2.0 protocol flow.

In FIB it is JWS (JWT with signature) object.

An example access_token looks like the following.

Refresh Token

Refresh Token is a part of OAuth 2.0 protocol flow.

It is also the JWS object (the same as access_token).

Please use it to get a new access_token in case when the current one has expired. Please follow OAuth2.0 standard here.

An example refresh_token looks like the following.

ID Token

ID token is a part of OpenID Connect Core 1.0.

It is the JWS object.

Please use it to get information about user.

An example id_token looks like the following.

Useful Links

To logout you can use the following URL.

Design Guidelines

Following guidelines should be kept in mind when designing the login button on the partner screens

Download the guidelines using the following link