back to developers

Login with FIB

First Iraqi Bank is a fully digital bank launched in Iraq in 2020. We offer services to our customers following international security and compliance standards as it is our ambition to change banking in Iraq.

For our partners, we offer services whenever trust is needed. The first online use cases are our payments SDK and our single-sign-on method. With these two packages, you can make use of First Iraqi Banks infrastructure to offer a convenient login and payment method to your customers.

With our FIB SSO customers can easily authenticate themself and you can benefit that we prove who our customers are during our onboarding process following international standards. By that, you also know that you can trust your customers that they are not any suspicious persons or parts of terror networks.

We would like to preserve user data as much as possible and hence we would provide access to the following data after user confirmation:

  1. Phone number
  2. First Name in arabic
  3. Last Name in arabic

Environments

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

EnvironmentURL
Sandboxhttps://fib.sandbox.azure.lawrence-spring.com/
ProductionTBD

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 dev@firstiraqibank.co 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.

fib authorization flow

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.

Code Example

GET /auth/realms/fib-personal-application/protocol/openid-connect/auth?response_type=code&client_id={client_id}&scope=openid&redirect_uri={redirect_uri}

  • 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.

fib login page

User can click on the Back to Partner button. Then it will be redirected back to the your website. If user click on the Login button, then two different scenarios are possible:

  1. If that is a first login, then the consent page will be displayed to the user.fib consent page

    The user may or maynot decide to grant access to his personal data.

    If the user grant access, then authorization_code will be sent to redirect_uri. Please refer to the next steps → Step 2.

    If user does not grant access, then the response will be sent to redirect_uri with error message as a parameter.

    Code Example

    [your_redirect_uri]/redirect?error=access_denied

  2. In case of repetition of the Login process, the consent screen would no longer be shown and the authorization_code will be sent to redirect_uri right after login. Please refer to the next steps → Step 2.

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.

Code Example

[your_redirect_uri]/?code=8b874631-335c-4ea1-ab0f-16f09b6d30bb.c5969e06-35c2-407a-b14c-27ed110fe1a2.4c39f090-0257-41c2-ab53-4227a8a3deac

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.

Code Example

POST /auth/realms/fib-personal-application/protocol/openid-connect/token

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

client_id=[your_client_id]

&client_secret=[your_client_secret]

&grant_type=authorization_code

&code=[authorization_code]

&redirect_uri=[redirect_uri]

  • 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.

Code Example

{
  "exp": 1596529813,
  "iat": 1596529513,
  "auth_time": 1596529503,
  "jti": "465fb2cd-d04e-480e-a94e-974fc5c05a4e",
  "iss": "https://keycloak.dev.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.

Code Example

{

"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJPdjBsNEJGOVRmVDlWNTEtVjZBeTRmYlVoQ0dMbTZXUVpxcXQ4S3lLOGhnIn0.eyJleHAiOjE1OTY1Mjk4MTMsImlhdCI6MTU5NjUyOTUxMywiYXV0aF90aW1lIjoxNTk2NTI5NTAzLCJqdGkiOiI3YTU2MWUzNC1jNjk4LTRhYzMtYmQyYS05ODQyMTA0NmM3NjIiLCJpc3MiOiJodHRwczovL2tleWNsb2FrLmRldi5henVyZS5sYXdyZW5jZS1zcHJpbmcuY29tL2F1dGgvcmVhbG1zL2ZpYi1wZXJzb25hbC1hcHBsaWNhdGlvbiIsInN1YiI6IjZhMGI0NDVhLWI0MmMtNDczOS1hNjVjLWQ2NjkzMzJiYzFhOSIsInR5cCI6IkJlYXJlciIsImF6cCI6InNzby1jbGllbnQtbW9jayIsIm5vbmNlIjoiS3F4ZzlJY05qalNqbUtOMXFtWEIwdDYwcldQQXRhZm5LOGJ2dW16WXBlWSIsInNlc3Npb25fc3RhdGUiOiJlNTczZDIzYy03YTJkLTQ5OWYtYTA0My01YTE2NDY4ZjA2ZjYiLCJhY3IiOiIwIiwic2NvcGUiOiJvcGVuaWQifQ.Ds_k_CTm9jNm2jc7khADyBWzaj0HvX8_ieefl6p_9lzFuRdKhC8SSLNxde_JHoHX9AG9VHylVHM0MtoRDTiv2J0uEd8LQOZ4EuPCb6SVm4oah3bjZtL8D5gdhiL0fP114MY5oTKFFW_Mv-681Vd6acyUVYqBKG_vrsSYkkX_NNmj-_Gq6WM5AKS4PdqHvrPdZcn5KAoq0Y7WvhOseM2hq11KE8NUBpkRQRdc3rIYRfeRjDulKSswOozg7-e9FmT9rBw2Cb65Hx3kYl-SDROaTWZjYfiHLaiVTU7luxPy4Et-fd6_axrutp139yoq1dR3kzF-q-y1-AX0HSziDUekig"

}

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.

Code Example

{

"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJPdjBsNEJGOVRmVDlWNTEtVjZBeTRmYlVoQ0dMbTZXUVpxcXQ4S3lLOGhnIn0.eyJleHAiOjE1OTY1Mjk4MTMsImlhdCI6MTU5NjUyOTUxMywiYXV0aF90aW1lIjoxNTk2NTI5NTAzLCJqdGkiOiI3YTU2MWUzNC1jNjk4LTRhYzMtYmQyYS05ODQyMTA0NmM3NjIiLCJpc3MiOiJodHRwczovL2tleWNsb2FrLmRldi5henVyZS5sYXdyZW5jZS1zcHJpbmcuY29tL2F1dGgvcmVhbG1zL2ZpYi1wZXJzb25hbC1hcHBsaWNhdGlvbiIsInN1YiI6IjZhMGI0NDVhLWI0MmMtNDczOS1hNjVjLWQ2NjkzMzJiYzFhOSIsInR5cCI6IkJlYXJlciIsImF6cCI6InNzby1jbGllbnQtbW9jayIsIm5vbmNlIjoiS3F4ZzlJY05qalNqbUtOMXFtWEIwdDYwcldQQXRhZm5LOGJ2dW16WXBlWSIsInNlc3Npb25fc3RhdGUiOiJlNTczZDIzYy03YTJkLTQ5OWYtYTA0My01YTE2NDY4ZjA2ZjYiLCJhY3IiOiIwIiwic2NvcGUiOiJvcGVuaWQifQ.Ds_k_CTm9jNm2jc7khADyBWzaj0HvX8_ieefl6p_9lzFuRdKhC8SSLNxde_JHoHX9AG9VHylVHM0MtoRDTiv2J0uEd8LQOZ4EuPCb6SVm4oah3bjZtL8D5gdhiL0fP114MY5oTKFFW_Mv-681Vd6acyUVYqBKG_vrsSYkkX_NNmj-_Gq6WM5AKS4PdqHvrPdZcn5KAoq0Y7WvhOseM2hq11KE8NUBpkRQRdc3rIYRfeRjDulKSswOozg7-e9FmT9rBw2Cb65Hx3kYl-SDROaTWZjYfiHLaiVTU7luxPy4Et-fd6_axrutp139yoq1dR3kzF-q-y1-AX0HSziDUekig"

}

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.

Code Example

{

"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJPdjBsNEJGOVRmVDlWNTEtVjZBeTRmYlVoQ0dMbTZXUVpxcXQ4S3lLOGhnIn0.eyJleHAiOjE1OTY1Mjk4MTMsImlhdCI6MTU5NjUyOTUxMywiYXV0aF90aW1lIjoxNTk2NTI5NTAzLCJqdGkiOiI3YTU2MWUzNC1jNjk4LTRhYzMtYmQyYS05ODQyMTA0NmM3NjIiLCJpc3MiOiJodHRwczovL2tleWNsb2FrLmRldi5henVyZS5sYXdyZW5jZS1zcHJpbmcuY29tL2F1dGgvcmVhbG1zL2ZpYi1wZXJzb25hbC1hcHBsaWNhdGlvbiIsInN1YiI6IjZhMGI0NDVhLWI0MmMtNDczOS1hNjVjLWQ2NjkzMzJiYzFhOSIsInR5cCI6IkJlYXJlciIsImF6cCI6InNzby1jbGllbnQtbW9jayIsIm5vbmNlIjoiS3F4ZzlJY05qalNqbUtOMXFtWEIwdDYwcldQQXRhZm5LOGJ2dW16WXBlWSIsInNlc3Npb25fc3RhdGUiOiJlNTczZDIzYy03YTJkLTQ5OWYtYTA0My01YTE2NDY4ZjA2ZjYiLCJhY3IiOiIwIiwic2NvcGUiOiJvcGVuaWQifQ.Ds_k_CTm9jNm2jc7khADyBWzaj0HvX8_ieefl6p_9lzFuRdKhC8SSLNxde_JHoHX9AG9VHylVHM0MtoRDTiv2J0uEd8LQOZ4EuPCb6SVm4oah3bjZtL8D5gdhiL0fP114MY5oTKFFW_Mv-681Vd6acyUVYqBKG_vrsSYkkX_NNmj-_Gq6WM5AKS4PdqHvrPdZcn5KAoq0Y7WvhOseM2hq11KE8NUBpkRQRdc3rIYRfeRjDulKSswOozg7-e9FmT9rBw2Cb65Hx3kYl-SDROaTWZjYfiHLaiVTU7luxPy4Et-fd6_axrutp139yoq1dR3kzF-q-y1-AX0HSziDUekig"

}

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