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.

OAuth Access Token Glossary

Property

Description

id_token

The ID token resembles the concept of an identity card, in a standard JWT format, signed by the NBG identity provider. You may use any Json Web Token decoder to extract claims from id_token (e.x. https://jwt.io/).

For security reasons, NBG authorization server does not allow self-contained access_token (JWT Token). The token is in reference token format and the actual data are stored in the authorization server. Once you include the reference token in your API call, the API receives this reference token.

expires_in

The expiration time of token (in seconds).

token_type

The token type and token usage.

refresh_token

Refresh tokens allow requesting new access tokens without any user interaction as described in RFC 6750. Refresh tokens are supported for the following flows: authorization code, hybrid and resource owner password flow.

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.

OAuth and NBG API Products

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

client_id

Your client id (required)

client_secret

Your client secret (required)

scope

Specify what access privileges are being requested for Access Tokens. This can be identity scopes such as profile and/or NBG API Scopes. (required)

state

A randomly generated unique value is typically used for preventing cross-site request forgery attacks. Before exchange authorization code, you should check if the state received matches with the state you send in the request. This parameter is optional and can only be used in the Authorization Code Flow.

redirect_uri

Your application page that will capture the NBG Authorization Code. This parameter is required only in the Authorization Code Flow.

response_mode

Specifies the method that should be used to send the resulting token back to your app. Can be set as query (Authorization Response parameters are encoded in the query string added to the redirect_uri when redirecting back to the Client) or form_post (Authorization Response parameters are encoded as HTML form values that are auto-submitted). This parameter is required only in the Authorization Code Flow.

response_type

The Response Type value that determines the authorization processing flow to be used.

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:

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.

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.

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:

Personal Information

Contains the user identity requested scopes (e.g. profile, email)

Application Access

Contains the API scopes that your client application will have access to on behalf of the signed user. Depending on the presence of the offline_access scope, your application can use the refresh token to update access without asking the user to consent again.

Do not ask me again

This choice allows the NBG authorization server to store the user’s decision. Note that if offline_access was requested the user will have to consent every time, even if he checks the “Do not ask me again checkbox”.

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.

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.

A plan is a collection of API resources or subsets of resources from one or more API. A plan can contain a mixture of HTTP GET, PUT, POST, and DELETE verbs from different APIs or it can contain all the GET verbs from various APIs. A plan can have a common rate limit for all the resources, or each resource can have a different rate limit. Rate limits specify how many requests an application is allowed to make during a specified time interval.

Use this Developer Portal to browse the different plans that are available to you and select a plan that is most suitable for your requirements.

When you add an application you are provided with a client ID and client secret for the application. You must supply the client ID when you call an API that requires you to identify your application by using a client ID, or a client ID and client secret.

To register an application click on Apps in the main menu and then click on the 'Register an application' link. Once you have provided an application name, description, etc you will see your application client ID and client secret.

Make a note of your client secret because it is only displayed once. You must supply the client secret when you call an API that requires you to identify your application by using a Client ID and Client Secret.

When looking at the details of an API you will see a table of the operations contained in the API. This will show what method they are (GET, POST, PUT, DELETE, PATCH, HEAD or OPTIONS) and what path the Resource uses.

If you click on the Resource you will see more information about it, what parameters it might take, what it returns, what possible return codes it might use and what they mean.

There is also a 'Try' button which enables you to try the Resource out directly from the Developer Portal.

If the API requires a client ID or a client secret for identification then you can specify these at the top of the 'Try' section.