This page explains how NBG implements the OAuth specification.

Every call of your client’s application to an NBG API requires an access token, which is included in an Authorization header as a Bearer token.

OAuth 2.0 lets you securely authorize your client application to access the data that the NBG APIs provide. OAuth provides authorization without your client needing to access customer sign in information.

OAuth2 and OpenID Connect

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 supersedes the work done on the original OAuth protocol created in 2006. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and smart home devices. This specification is developed within the IETF OAuth WG.

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It allows clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

OpenID Connect allows clients of all types, including Web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users. The specification suite is extensible, by allowing participants to use optional features such as encryption of identity data, discovery of OpenID Providers, and session management, when it makes sense for them.

See http://openid.net/connect/faq/ for a set of answers to Frequently Asked Questions about OpenID Connect.

OAuth Access Token Glossary

OAuth2 Interactive Flows

In the following scenarios, human interaction is required, in order to delegate access for the client to the protected resource. The following type of flow is also known as three-legged authorization. For those flows, end users (Resource Owners) must be redirected to the NBG Authorization server. The URL must include the application’s clientId and redirect URI. The NBG authorization server authenticates the end users and authorizes the client application to access their NBG Data or Profile.

NBG supports the Authorization Code flow as defined in RFC 6749. The authorization code grant consists of two requests and two responses in total, plus the final request – response to the API.

Once the user authentication part ends, the application receives a short-lived authorization code, which has to be exchanged for an access token.

OAuth2 Non-interactive Flows

In the following flow, there is no separate authentication step, in the sense that no human interaction in the form of consent is required, in order for resource access to be given.

NBG supports the Client Credential flow for client to service communication (machine to machine) so there is no resource owner involved at all. The client typically has to authenticate at the token endpoint using its client ID and secret.

An example POST request looks like the following:

  https://my.nbg.gr/identity/connect/token \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials&scope=nbgAPI1%20nbgAPI2'

 The access token is returned as part of a JSON object.

OAuth and NBG API Products

NBG implements OAuth in the following ways:

• Some APIs require the client credentials flow, also known as two-legged OAuth.

• Some APIs require the authorization code flow, also known as three-legged OAuth.

When you register your client application on the developer portal, you receive a client ID and a client secret. You also provide the following information:

• An app title and an app description.

• A redirect URI, which is required for the APIs that require the authorization code flow (if needed).

Make sure to keep your client secret outside of your client code, in a secure place on your server.

OAuth Request Client Parameters Glossary

An Authorization Code Flow example

In the following section, we will demonstrate how to use a common http client such as Postman to access NBG APIs by using the authorization code flow and user interaction. The authorization code flow requires two requests to get an access token, plus one request to the NBG API.

The first step is to create the authorization code URL in order to get an authorization code from the authorization endpoint. The received authorization code, enables you to exchange the code for an access token by using the token endpoint. Based on your needs, you can change the response mode of your request by setting the parameter Response Mode in the request URL.

Authorization Code URL

First, you must create and call an authorization code URL like the following example: 

curl -X GET \ 
  'https://my.nbg.gr/identity/connect/authorize?client_id=YOUR_CLIENT_ID&scope=openid%20profile%20email%20offline_access&state=10748102&redirect_uri=YOUR_APP_PAGE
&response_mode=query&response_type=code' 

Once the request is validated by NBG authorization server, the NBG login screen will appear. You may use your own NBG username and password to complete the user login process.

After the user authentication completes, the response mode may differ depending on the value of the request parameter response_mode (query or form_post).

A successful response when response_mode is set to query looks like this:

http://myApp/Callback?code=07cf0c94fbb3cd7f4ecfe58e6ba071b8fd91be6816027922932ccdadd52a1a22&scope=openid%20profile%20email%20offline_access&
state=10748102&session_state=-T-0xpxyoN5vS9As7bE8UIeNeHKm63mXEQesYmni40I.57ad3b7bec88edfa46f5ae5962d7a991d3b7bec88edfa46f5ae5962d7a991

 A successful response when response_mode is set to form_post looks like this:

<form method='post' action='http://myApp/Callback'>
<input type='hidden' name='code' value='d8cdb1ef37784c4162c18969e450025916dea9ad7b00c71be13d44e93fc780a6' />
<input type='hidden' name='id_token' value='213pZC819_awRywnT5EXkkLt144iaA-WJ1_UW-XRw_zfAljmiuxqwK4Xjr5D3eTOj1DmZ4HsxkdIIjPG9hDe9zWsRMJSMQCk4V84Hg3929a3cHYy6uxdKxNcvZAeXnHt1T4tTov2j25Fm7zos
Fr0YZV6zEqsAX6Qh15sCOJUL0yj_FSEd8hraWKMMtjFA' />
<input type='hidden' name='scope' value='openid profile email offline_access/>
<input type='hidden' name='state' value='OpenIdConnect.AuthenticationProperties=p-iCv0TFlDc1M8LbGP2rW4mKO0agNo32HIkWkbgC5kPCXd-rZmLKp3l2Y15ndaxV_jtUGfhG_M6JuAgBKcJvKQLIQCb20ZJGRaHNm44GBcIFFTnQ7K6WJ3Ue4jcT7Yh91geKU37LJ4OjV-955z6Wkkn5FaDVTlYbPiso_l90QcYTG6B0Br4qzCKYTPVgKcK1SOLeOgMgJAsOHLKRbyJ5YQ' />
<input type='hidden' name='session_state' value='AeCL7PbyBDFvMmaebibhU9eWIGcAyGwVGPobkPrcze8.c748cd86da6f3ac774d480b933f30b3d' />
</form><script>(function(){document.forms[0].submit();})();</script>

At this point, the form will auto submit the form values to the redirect_uri you specified in you request. The authorization code is included in the form data you will receive after the form is posted.

Exchange the Authorization Code for an Access Token

Once you get the authorization code, it can be exchanged for an identity token and/or an access token. You can use any HTTP client in your application. The HTTP method must be POST.

curl -X POST \
 https://my.nbg.gr/identity/connect/token \
 -H 'cache-control: no-cache' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET
&code=d8cdb1ef37784c4162c18969e450025916dea9ad7b00c71be13d44e93fc780a6&redirect_uri=http://myApp/Callback 

After the code exchange completes , a successful response could look like this:

 Note that the refresh_token will only be present in the response if you included the offline_access in the scope list during the authorization code request. Check the Refreshing access tokens section for more information about offline_access and refresh tokens.

Authorization Code Flow using PostMan

Setup your application

Edit your application settings and add postman’s OAuth Redirect URL

https://www.getpostman.com/oauth2/callback

Request token

In the Postman Authorization tab, select the OAuth 2.0 authorization protocol from the Type list and then select the “Get New Access Token” button.

Fill in the values of the following parameters:

Each nbgAPIScope is found within the corresponding API’s documentation

Click the “Request Token” button.

Authenticate the user

Once the request is validated by the NBG authorization server, the NBG login screen will appear. You may use your own NBG username and password to complete the user login process.

Authorization and user consent

Following a successful login, the user consent screen will be prompted to the user. The consent screen has three sections:

The access token is returned as part of a JSON object.

Access an NBG API

Once your application has an access token, it may use the token to access an NBG API, until the token expires or is revoked.

curl -X POST \  
 http://Https://NBG/API/ApiMethod \
 -H 'authorization: Bearer    3d84656b8de7d2a1fb61b27e2ea3b0c27440a8ef1664cf735e43ccb75fe6556c' \
 -H 'cache-control: no-cache' \
 -H 'content-type: application/json' \
 -d '{“Parameter1” : “Value1”} 

Access Personal User Information

After the user authentication is completed, you can use the UserInfo endpoint in order to get additional information for the user.

Here is an example of a UserInfo Endpoint request, using cURL. Note that it includes the access token:

curl -X GET \
 https://my.nbg.gr/identity/connect/userinfo \
 -H 'authorization: Bearer bce0b5aa32e4d0874e960e18021c9ac043005af25dae11e16724bf20ea45da24' \
 -H 'cache-control: no-cache' \
 -H 'postman-token: b1df096b-de6e-d061-a930-6ec0afd1cecc' 

A successful response could look like this:

Token Expiration

When your application receives an access token response from the Token Endpoint, the expires_in property indicates the token’s time to expire in seconds. There are several reasons that a token might stop working:

• The user has revoked the token

• The user has changed his password

• The user account has exceeded a certain number of token requests per client.

Using refresh tokens allows you to request new access tokens without any user interaction (consent). For instructions of requesting and using refresh tokens, take a look at the following  section.

Refreshing access tokens

Refresh tokens allow the application to request new access tokens (renew expired access tokens) without any user interaction. In order to get a refresh token, you must include in your request scope the "offline_access" scope.

curl -X POST \  
 https://my.nbg.gr/identity/connect/token \
 -H 'cache-control: no-cache' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&refresh_token=13656402d4f5681a7952d
0b000423a8d05ab98ce86837b24cbbbf66554f0f659&scope=openid%20profile'

A successful response could look like this:

After receiving your new access token and refresh token, you can start using them for your calls

Mobile Authorization

You can use the Authorization code flow to create your mobile application. Your application must be capable to display the NBG authentication/authorization web page (usually via a browser control), send HTTP requests/responses and handle the redirections that occur at the various steps of the flow.