Authentication and authorization with OAuth 2.0

Here you can find documentation and examples for end user authentication and authorization.

OAuth specification 2.0

This page is currently in development so some changes are expected.

Introduction

Authentication to our APIs is done via OAuth. OAuth is an authorization framework that enables applications to get limited access to end user's resources without giving them user passwords.

OAuth provides to clients a "secure delegated access" to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.

OAuth provides different authentication and authorization flows based on the use case and the type of client application. When developing your application you should be aware the differences between OAuth Grants and select suitable flow based on your application design.

Based on the API security level different grant types are required when accessing our APIs. Read from API documentation which grant is required when accessing the API.

Allways store your api keys and secrets in secure way!

Roles

OAuth defines four roles:

Resource Owner

The resource owner is the user who authorizes an application to access their resources. The application's access to the user's resource is limited to the "scope" of the authorization granted (e.g. read or write access).

Client

The client is the application that wants to access the user's resources. Before it may do so, it must be authorized by the user, and the authorization must be validated by the API.

Resource Server

The resource server (Service API) hosts the protected user resources.

Authorization Server

The authorization server (Authorization API) verifies the identity of the user then issues access tokens to the application.

Tokens

Depending on a grant type and the position of access flow, authorization endpoints respond with slightly different tokens.

A typical token response contains these fields.

  • token_type - Type of the token (bearer, refresh, etc)
  • access_token - Requested access token
  • scope - Defines the amount of access granted to this access token
  • status - Status of the token (approved, rejected, pending etc)
  • refresh_token - Token for refreshing access token
  • refresh_token_expires_in - Validity period for refresh token (in seconds)
  • refresh_token_issued_at - Issue time (in seconds since epoch)
  • expires_in - Validity period for access token (in seconds)
  • refresh_count - Number of times access token has been refreshed

Grants

The OAuth 2.0 framework specifies several grant types for different use cases. Here you can find explanations and examples for different grants that are used with OP APIs.

Authorization Code Grant

Coming soon.

Implicit Grant

Coming soon.

Resource owner credentials Grant

Coming soon.

Client credentials Grant

The OAuth Client Credentials grant is used when an application wants to access resources it owns, and which do not require acting on behalf of a user.

In our context, the Client Credentials grant is used as a means of identifying third parties in cases where strong end user identification is not required, and/or where end user consent is handled separately from the actual API interaction.

In practice, the client credentials grant is implemented by a token endpoint which returns an access token corresponding to the supplied API key and secret. Some APIs require extra attributes during token requests. For more information see corresponding API documentation.

Below is a sample request with client_id and client_secret payload:

  1. Client authenticates.
POST /auth/v2/accesstoken?grant_type=client_credentials HTTP/1.1
Host: sandbox.apis.op-palvelut.fi
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
 
client_id=*********&client_secret=*******

In the above request, client_id is your APP API KEY and client_secret is your APP API SECRET. The differences in naming stem from the OAuth 2.0 standard.

  1. Authorization server generates and returns access token. The response will contain the access token and associated data in JSON format, as per the sample below:
{
  "token_type" : "BearerToken",
  "access_token" : "Axqx362CnSmLABgzqcBasG0pxBj9",
  "scope" : "",
  "status" : "approved",
  "refresh_token" : "U71FUIsqADNqpaqhh4pNsqE2YYfPwbUV",
  "refresh_token_expires_in" : "1799",
  "refresh_token_issued_at" : "1521035756257",
  "expires_in" : "86399",
  "refresh_count" : "0"
}
  1. Client calls protected resource using access token.
curl -v "https://sandbox.apis.op-palvelut.fi/loans/oneoffs/v1/creditterms" -H "Authorization: Bearer Axqx362CnSmLABgzqcBasG0pxBj9"