Swagger UI - Comtrade OAuth Server APIs

Introduction

Purpose of this document is to provide general overview of Comtrade OAuth Server APIs and specification of endpoints.

Overview

Comtrade APIs use the OAuth 2.0 protocol for authentication and authorization. Comtrade OAuth Server supports common OAuth 2.0 scenarios such as those for web Server, installed, and client-side applications.

The OAuth 2.0 framework requires your application to obtain an Access Token when the user authorizes your app to access their data. The Access Token is used for making HTTP request to the Comtrade APIs.

Client registration

The Comtrade OAuth 2.0 supports dynamic client registration according to the standard RFC 7591. Comtrade strongly recommends that you review the specification and use an OAuth client library for your programming language.

Below are common parameters used in POST:

URI Parameter	Description
`client_name`	Human-readable string name of the client to be presented to the end-user during authorization. Type: string
`redirect_uris`	Array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows. Type: array of strings
`token_endpoint_auth_method`	String indicator of the requested authentication method for the token endpoint. Values defined by this specification are: none, client_secret_post, client_secret_basic. Type: string
`scope`	String containing a space-separated list of scope values (as described in Section 3.3 of OAuth 2.0 [RFC6749]) that the client can use when requesting access tokens. Type: string
`response_types`	Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint. Possible values: code, token. Type: array of strings
`jwks_uri`	URL string referencing the client's JSON Web Key (JWK) Set [RFC7517] document, which contains the client's public keys. Type: string

Client editing

The Comtrade OAuth 2.0 supports editing of client's registration information - specifically redirect_uri list. Syntax is the same as in the case of the client registration, but only redirect_uri list is currently supported and actually will be changed. This method uses the same url as the register method, but PUT instead of the POST http verb.

Authorization Server Metadata

The Comtrade OAuth 2.0 supports obtaining server metadata using GET metod as spefied in RFC 8414. Comtrade strongly recommends that you review the specification and use an OAuth client library for your programming language.

Response example

{
    "issuer": "http://example.com/OAuthServer",
    "authorization_endpoint": "https://example.com/OauthSrv/authorize",
    "token_endpoint": "https://example.com/OauthSrv/token",
    "token_endpoint_auth_methods_supported": [
        "client_secret_basic",
        "tls_client_auth"
    ],
    "token_endpoint_auth_signing_alg_values_supported": [
        "RS256"
    ],
    "jwks_uri": "https://oapideveloper.addiko.hr/OauthSrv/api/jwks",
    "registration_endpoint": "https://example.com/OauthSrv/api/register",
    "response_types_supported": [
        "code",
        "token"
    ],
    "code_challenge_methods_supported": [
        "S256",
        "plain"
    ]
}

Installed Applications scenario

The Comtrade OAuth 2.0 endpoint supports applications that are installed on devices such as computers, mobile devices, and tablets. For those applications depending on how users are authenticated we are supporting two flows: resource owner and implicit flow.

Important note: PSD2 OAuth implementation uses only Authorization Code Flow with PKCE, as specified below.

Resource Owner Flow

This flow supports only software token (OTP) for user authentication.
For other types of user authentication installed applications should use implicit flow.
In this flow application will obtain access token directly from the OAuth Server by sending client and user credentials.

Implicit Flow

This flow the applications can use for any other type of user authentication which OAuth Server is providing.
In this flow application must use local browser to obtain access token.
In order to obtain access token application have to use installed browser to redirect user to OAuth Server's login page, after user authenticate himslef and or grant required permissions access token will be delivered to the application by the redirecting browser to preconfigured URI.

Client-side Applications scenario

The Comtrade OAuth 2.0 endpoint supports JavaScript-centric applications. These applications may access a Comtrade Banking API while the user is present at the application, and this type of application cannot keep a secret. For this type of applications we are supporting only implicit flow.

Implicit Flow

This flow is used by JavaScript-centric applications in same maner like the installed applications and since JavaScript applications is already in the context of the browser there is no need for additional step of launching local browser. Since client-side application are not trusted means that refresh tokens can't be issued for this type of clients.

Web Server Applications scenario

The Comtrade OAuth 2.0 endpoint supports Web Server applications. For this type of applications we are recommending of using authorization code flow as the most secure way to obtain access token.

Authorization Code Flow

This flow is similar to the Implict flow but instead of OAauth Server returning access token it returns code which Web Application can use to obtain access token via back-channel.

Comtrade OAuth Server

Comtrade OAuth Server fully implements OAuth 2.0 protocol by RFC 6749 specification with all of the standard flows like: resource owner, client credentials, implicit and authorization code flow. Oauth Server also supports multiple authentication types: username and password, software tokens, hardware tokens and client certificates. In order to use any of the OAuth flows client application must be registered on the server.

Client Credentials Flow

Comtrade OAuth Server follows the OAuth 2.0 Client Credentials Grant as specified in RFC 6749. Comtrade strongly recommends that you review the specification and use an OAuth 2 client library for your programming language.

The Client Credentials Grant flow has the following steps:

1.	The client authenticates with the OAuth Server and requests an access token from the token endpoint.

2.	The OAuth Server authenticates the client, and if valid, issues an access token and refresh token. See Access Token Request below.

Resource Owner Flow

Comtrade OAuth Server follows the OAuth 2.0 Resource Owner Password Credentials Grant as specified in RFC 6749. Comtrade strongly recommends that you review the specification and use an OAuth 2 client library for your programming language.

The Resource Owner Password Credentials Grant flow has the following steps:

1.	The resource owner provides the client with its username, then client using software token generates OTP (one time password).

2.	The client requests an access token from the OAuth Server's token endpoint by including the credentials received from the resource owner. See Access Token Request below.

3.	The OAuth Server authenticates the client and validates the resource owner credentials, and if valid, issues an access token and refresh token.

Implicit Flow

Comtrade OAuth Server follows the OAuth 2.0 Implicit Code Grant as specified in RFC 6749. Comtrade strongly recommends that you review the specification and use an OAuth client library for your programming language.

The Implicit Code Grant Flow has the following steps:

1.	Your application redirects the user to OAuth Server's authorization page. See Authorization Page below.

2.	Upon user consent, OAuth Server redirects the user back to your application's callback URL with an access token as a URL fragment.

3.	Your application stores the access token. It will use the access token to make requests to the Comtrade APIs.

Authorization Code Flow

Comtrade OAuth Server follows the OAuth 2.0 Authorization Code Grant as specified in RFC 6749. Comtrade strongly recommends that you review the specification and use an OAuth 2 client library for your programming language.

The Authorization Code Grant Flow has the following steps:

1.	Your application redirects the user to OAuth Server's authorization page. See Authorization Page below.

2.	Upon user consent, OAuth Server redirects the user back to your application's callback URL with an authorization code as a URL parameter.

3.	Your application exchanges the authorization code for an access token and refresh token. See Access Token Request below.

4.	Your application stores the access token. It will use the access token to make requests to the Comtrade APIs.

Authorization Page

Redirect the user to the Comtrade OAuth 2.0 authorization page with the following parameters:

URI Parameter	Description
`client_id`	Your application id from server Type: string
`redirect_uri`	URI where Comtrade OAuth Server will redirect the user after the user grants or denies consent. Type: string
`state`	This parameter will be added to the redirect URI exactly as your application specifies. Comtrade strongly recommend including an anti-forgery token in this parameter and confirming its value in the redirect to mitigate against cross-site request forgery (CSRF). Type: string
`scope`	A space-separated list of scopes. Scopes represent permissions for resources that client is intending to access or modify. Type: string
`response_type`	code for Authorization Code Grant Flow token for Implicit Grant Flow. Type: string
`login_hint`	Hint to the OAuth Server on how to authentication the user (username_password, hard_token, client_certificate). Type: string

All parameter values must be URI encoded.

Examples

Authorization Code Flow

https://domainname/oauth/authorize?client_id=5555&redirect_uri=https%3A%2F%2Flocalhost%3A38500%2F&state=3UPWZKRQ7REkcDT3SZxI8A&scope=eBanking%20eTrading&response_type=code&login_hint=username_password

Implicit Flow

https://domainname/oauth/authorize?client_id=12345687&redirect_uri=https%3A%2F%2Flocalhost%3A38515%2FHome%2FSignIn&state=my-nonce&scope=eBanking%20eTrading&login_hint=hard_token&response_type=token

Access Token Request

In order to obtain access token application must initiate access token request on token endpoint (domainname/oauth/token). This is true for all of the OAuth flows with the exception of Implicit flow which gets token directly from callback as URL fragment.

Authorization header

The Authorization header must be set to Basic followed by a space, then the Base64 encoded string of your application's client id and secret concatenated with a colon. For example, the Base64 encoded string, Y2xpZW50X2lkOmNsaWVudCBzZWNyZXQ=, is decoded as "client_id:client secret".

Body Parameters

Parameters for Client Credentials Flow

URI Parameter	Description
`grant_type`	client_credentials Type: string
`scope`	A space-separated list of scopes. Scopes represent permissions for resources that client is intending to access or modify. Type: string

Parameters for Resource Owner Flow

URI Parameter	Description
`username`	The username obtained from the resource owner. Type: string
`password`	The password generated by software token. Type: string
`grant_type`	password Type: string
`scope`	A space-separated list of scopes. Scopes represent permissions for resources that client is intending to access or modify. Type: string
`client_id`	Required if the client is not authenticating with the Comtrade OAuth Server. Type: string

Parameters for Authorization Code Flow

URI Parameter	Description
`code`	The authorization code received in the callback as a URI parameter. Type: string
`grant_type`	authorization_code Type: string
`redirect_uri`	Required if specified in the redirect to the authorization page. Must be exact match. Type: URI
`client_id`	Required if the client is not authenticating with the Comtrade OAuth Server. Type: string

Post examples

Client Credentials Flow post example

                POST https://domainname/oauth/token  
Authorization: Basic Y2xpZW50X2lkOmNsaWVudCBzZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
scope=eBanking&grant_type=client_credentials

Resource Owner Flow post example

            POST https://domainname/oauth/token  
Authorization: Basic Y2xpZW50X2lkOmNsaWVudCBzZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
username=user&password=pass&scope=eBanking&grant_type=password

Authorization Code Flow post example

                POST https://domainname/oauth/token  
Authorization: Basic NTU1NTpTRUNSRVQ=
Content-Type: application/x-www-form-urlencoded
code=79ac0cb6&redirect_uri=https%3A%2F%2Flocalhost%3A38500%2F&grant_type=authorization_code

Access Token Response example

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik91cThXS2dpS1M5cjYzUXF3UElXVDFpbU42VSJ9.
eyJ1bmlxdWVfbmFtZSI6IjExMTEiLCJhenAiOiIxMTExIiwic2NvcGUiOlsiYmFua2luZyIsInRyYWRpbmciXSwic3ViIjoiMTExMSIsI
nJvbGUiOlsiVmlld2VyIiwiU2lnbmVyIl0sImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3QvT0F1dGhTZXJ2ZXIiLCJhdWQiOiJPQXV0aFNlcn
ZlciIsImV4cCI6MTQ1MDU0NDM4MywibmJmIjoxNDUwNTQ0MDgzfQ.sEbFBG__8Nobs5i3bsLfTpdrb1VcVGcaHjT-3FTdyg6Bw8EhlIJI
PXrQILYoDqSJVaMArmIISUEid0BXeMz3Y2JCg-yVhbzwYLVXrW-HwiYzRzlI8gB>mcXIdt869bWBEDvkm6fjAQFJJvQmLU6MxCZSmcLsY
OKGf33WvRyK2i73Rp1VTq6VJeOi6ovgh0oxYslgXDw3Ew_Do_XfwBLeQtyYi6fMlazyFEAHxJWxxVzoN1oj7rmINhswM3202QVyNEnUsBz
eBzymPD4WSV-jexW0ajKZGjHxTKlZCwcXR1YnM8hFoasWFgUwOvMesD-1TvcERPDRuWA_h3Khi-dV1aQ",
    "token_type": "bearer",
    "expires_in": 1199,
    "refresh_token": "ec37a580-30ca-4008-b749-3213b98d5afb"
}

Authorization Code with PKCE flow (Proof Key for Code Exchange)

PKCE is an extension to the regular Authorization Code flow, so the flow is very similar, except that PKCE elements are included at various steps in the flow.
The Comtrade OAuth 2.0 supports PKCE flow as specified in RFC 7636.
Comtrade strongly recommends that you review the specification and use an OAuth client library for your programming language.

Below are additional parameters used in /authorize call:

URI Parameter	Description
`code_challenge`	BASE64URL-ENCODE(SHA256(ASCII(code_verifier_))) where code_verifier = high-entropy cryptographic random STRING Type: string
`code_challenge_method`	Transformation method - plain or S256 Type: string

Example of /authorize call


https://oauthexample.com/oauth2/default/v1/authorize?
  response_type=code
  &client_id=0oaln5pxp4o3BACXB0h7
  &redirect_uri=https://www.oauth.com/playground/authorization-code-with-pkce.html
  &scope=photo+offline_access
  &state=V4AiUZc1ED5hXD1B
  &code_challenge=QxugcyHp2rrC_MFIJAet-APOzEzoZRPmvOvJZSIWkQU
  &code_challenge_method=S256

Below are additional parameters used in POST /token call:

URI Parameter	Description
`code_verifier`	High-entropy cryptographic random string used as a base for code challenge creation in the authorize step. Type: string

Example of POST /token call

			
POST https://oauthexample.com/oauth2/default/v1/token
grant_type=authorization_code
&client_id=0oaln5pxp4o3BACXB0h7
&client_secret=ty3AVzB9LQiNo400QWjVoMgOQN7ctWJJfBd9jjVw
&redirect_uri=https://www.oauth.com/playground/authorization-code-with-pkce.html
&code=AB5l3GfyxLyiltuZTFet
&code_verifier=Qu_5V1PYpRBFr0XvFXGqfJX0L84Mshdwz2mwVI9PctOyJA5i

Refreshing Tokens

An access token intentionally is short lived. This is an important security mechanism of OAuth 2.0.

When an access token expires, an HTTP 401 error will be returned.Your application will need to refresh the access token.

Refreshing token example

POST https://domainname/oauth/token 
Authorization: Basic NTU1NTpTRUNSRVQ=
Content-Type: application/application/x-www-form-urlencoded
refresh_token=48e7ecd3&grant_type=refresh_token&client_id=2222

Alternatively for Authorization Code Flow, your application could redirect the user to the authentication flow. If the user is signed in and the scopes requested match the previously granted scopes, the user will be redirected to your callback URI with a new access token without being prompted.

Authorization Errors

Authorization request errors

200 OK

According to the OAuth 2.0 RFC 6749, if the redirect_uri is valid, the user is redirected to the app redirect_uri, and any errors are appended to the URI as a query string.

If client or redirect_uri is invalid then OAuth Server will not redirect to the invalid uri, instead it will show errors to the user.

Error response can contain three parameters:

URI Parameter	Description
`error (required)`	Required parameter representing error code.
`error_description (optional)`	Optional parameter representing human readable error description.
`error_uri (optional)`	Optional parameter representing web page with the error information.

Access Token Request Errors

400 Bad Request

If HTTP status of the token request is 400, then request errors are returned in JSON format in response body.

Error response can contain three parameters described in the table above.

Access token error response example:

400 Bad Request
{"error":"invalid_client","error_description":"Client is not registred to use refresh tokens."}