OAuth 2.0 Flow


You can obtain the credentials to call the APIs in your private area. We implement two of the standard OAuth 2.0 flows: client credentials and authorization code.

How to choose the right flow for your needs?

  • you must choose authorization code when the user is into your application, and can insert his CheBanca! credentials
  • you must choose client credentials when the user is not logged into your application

WARNING: the flow to manage API calls without the user online is still in evaluation; the final decision will be made by September 2019. At the moment, we assume to use the OAuth client credentials flow

You can find more information about the OAuth2.0 standard here

Client credentials

If you need to call the APIs which don't need the presence of a user, you can use the client credentials flow to obtain an OAuth access token. The flow is described in the following diagram.

OAuth 2.0 Client Credentials Flow

What are the required steps to perform this type of authentication?

  • Register to the developer portal
  • Request a new application with grant type = client_credentials
  • You'll be given a credential couple (client_id + client_secret)
  • Call the /oauth/v2/token API with the given credentials, as written [here]
  • You'll receive the access token and the refresh token (if expected)
  • Now you can call CheBanca! APIs!

Client credentials steps

Here's and example of the needed requests to obtain an access token in curl format. You can invoke the /auth/oauth/v2/token API either with application/json or application/x-www-form-urlencoded content type.

Since the connection is secure, you have to add the external-api.chebanca.io certificates (in the following example, the certificate chain is in the external-api.chebanca.io.pem file).

Request
curl --cacert external-api.chebanca.io.pem \
  -X POST \
  https://external-api.chebanca.io/auth/oauth/v2/token \
  -H 'content-type: application/json' \
  -d '{
    "client_id":"<CLIENT_ID>",
    "client_secret":"<CLIENT_SECRET>",
    "grant_type":"client_credentials"
    }'
Response
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Connection: close
< Content-Type: application/json;charset=UTF-8
< Content-Length: 347
< Date: Tue, 12 Feb 2019 11:54:50 GMT
< Strict-Transport-Security: max-age=16070400; includeSubDomains
<
{
"result": {
            "messages":[

            ],
            "flushMessages":true,
            "outcome":"SUCCESS",
            "requestId": "<REQUEST_UNIQUE_ID>"
        },"data":{

  "access_token":"<ACCESS_TOKEN>",
  "token_type":"Bearer",
  "expires_in":<TIME>,
  "refresh_token":"<REFRESH_TOKEN>",
  "rt_expires_in":<TIME>,
  "scope":"<SCOPE>"

}

Authorization code

If you need to call an API which requires the authorization of the user, you must choose the authorization code flow to obtain an access token. The flow is described in the following diagram.

OAuth 2.0 Authorization Code Flow

What are the required steps to perform this type of authentication?

  • Register to the developer portal
  • Request a new application with grant type = client_credentials
  • You'll be given a credential couple (client_id + client_secret)
  • Follow the flow as written here
  • You'll receive the access token and the refresh token (if expected)
  • Now you can call CheBanca! APIs!

Authorization code steps

Here's and example of the needed requests to obtain an access token in curl format. You can invoke the /auth/oauth/v2/authorize and /auth/oauth/v2/token API either with application/json or application/x-www-form-urlencoded content type.

Since the connection is secure, you have to add the external-api.chebanca.io certificates (in the following example, the certificate chain is in the external-api.chebanca.io.pem file).

Please notice that the /login API is executed directly on CheBanca! website: in fact, you, as a third party provider, should only propagate the redirect returned by the /authorize API to the browser, and the actual login (and the consent phase) will be executed on a page on chebanca.it domain. At the end of the login verification, the CheBanca! login page will redirect to your callback URL (configured when you requested your client_id). Then, the service exposed on your callback URL will have to call the /token API.

We show here the Login request only as an example to better understand the complete process.

Authorize request
curl --cacert external-api.chebanca.io.pem \
  -X GET \
  'https://external-api.chebanca.io/auth/oauth/v2/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<URLENCODED_CALLBACK_URL>'

Pay attention to the URLENCODED_CALLBACK_URL parameter: it should be in urlencoded format (e.g. https%3A%2F%2Fwww.yourdomain.com%2Foauth2%2Fcallback).

Authorize response
< HTTP/1.1 302 Found
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS,HEAD
< Access-Control-Allow-Headers: Content-Type
< Strict-Transport-Security: max-age=16070400; includeSubDomains
< X-Frame-Options: Deny
< Location: https://clienti.chebanca.it/auth/oauth/v2/authorize/login?action=display&sessionID=<SESSION_ID>&sessionData=<SESSION_DATA>
< cb-apitrack-id: 5478152593
< Content-Type: text/plain;charset=UTF-8
< Content-Length: 0
< Date: Tue, 12 Feb 2019 14:53:35 GMT
Login request
curl --cacert clienti.chebanca.it.pem \
      -X POST \
      https://clienti.chebanca.it/auth/oauth/v2/authorize/login \
      -H 'content-type: application/x-www-form-urlencoded' \
      -d 'user=<USER_ID>&pin=<USER_PIN>&action=login&sessionID=<SESSION_ID>&sessionData=<SESSION_DATA>&extLoginAndConsent=on'
Login response
< HTTP/1.1 302 Found
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS,HEAD
< Access-Control-Allow-Headers: Content-Type
< Strict-Transport-Security: max-age=16070400; includeSubDomains
< X-Frame-Options: Deny
< location: https://clienti.chebanca.it/oauth/consent/?sessionID=<SESSION_ID>&sessionData=<SESSION_DATA>
< cb-apitrack-id: 5504891511
< Content-Type: text/xml
< Content-Length: 0
< Date: Tue, 12 Feb 2019 15:13:48 GMT
Consent request
curl --cacert clienti.chebanca.it.pem \
      -X POST \
      https://clienti.chebanca.it/auth/oauth/v2/authorize/consent \
      -H 'content-type: application/x-www-form-urlencoded' \
      -d 'action=consent&sessionData=<SESSION_DATA>&sessionID=<SESSION_ID>'
Consent response
< HTTP/1.1 302 Found
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS,HEAD
< Access-Control-Allow-Headers: Content-Type
< Strict-Transport-Security: max-age=16070400; includeSubDomains
< X-Frame-Options: Deny
< location: https://<YOURDOMAIN>/path/to/your/callback?code=<AUTHORIZATION_CODE>&state=chebanca
< cb-apitrack-id: 5504891511
< Content-Type: text/xml
< Content-Length: 0
< Date: Tue, 12 Feb 2019 15:13:48 GMT
Get token request
curl --cacert external-api.chebanca.io.pem \
  -X POST \
  https://external-api.chebanca.io/auth/oauth/v2/token \
  -H 'content-type: application/json' \
  -d '{
    "code":"<AUTHORIZATION_CODE>",
    "client_id":"<CLIENT_ID>",
    "client_secret":"<CLIENT_SECRET>",
    "grant_type":"authorization_code"
    }'
Get token response
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS,HEAD
< Access-Control-Allow-Headers: Content-Type
< cb-apitrack-id: 4067327926
< Cache-Control: no-store
< Pragma: no-cache
< Content-Type: application/json
< Content-Length: 366
< Date: Tue, 12 Feb 2019 16:06:27 GMT
< Connection: close
< Strict-Transport-Security: max-age=16070400; includeSubDomains
<
{
    "result": {
        "messages": [],
        "flushMessages": true,
        "outcome": "SUCCESS",
        "requestId": "<REQUEST_UNIQUE_ID>"
    },
    "data": {
        "access_token": "<ACCESS_TOKEN>",
        "token_type": "Bearer",
        "expires_in": <TIME>,
        "refresh_token": "<REFRESH_TOKEN>",
        "rt_expires_in": <TIME>,
        "scope": "<SCOPE>"
    }
}

Refresh token

Request
curl --cacert external-api.chebanca.io.pem \
  -X POST \
  https://external-api.chebanca.io/auth/oauth/v2/token \
  -H 'content-type: application/json' \
  -d '{
    "code":"<AUTHORIZATION_CODE>",
    "client_id":"<CLIENT_ID>",
    "client_secret":"<CLIENT_SECRET>",
    "refresh_token":"<REFRESH_TOKEN>",
    "grant_type":"refresh_token"
    }'
Response
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS,HEAD
< Access-Control-Allow-Headers: Content-Type
< cb-apitrack-id: 4067327926
< Cache-Control: no-store
< Pragma: no-cache
< Content-Type: application/json
< Content-Length: 366
< Date: Tue, 12 Feb 2019 16:06:27 GMT
< Connection: close
< Strict-Transport-Security: max-age=16070400; includeSubDomains
<
{
    "result": {
        "messages": [],
        "flushMessages": true,
        "outcome": "SUCCESS",
        "requestId": "<REQUEST_ID>"
    },
    "data": {
        "access_token": "<ACCESS_TOKEN>",
        "token_type": "Bearer",
        "expires_in": <TIME>,
        "refresh_token":"<REFRESH_TOKEN>",
        "rt_expires_in":<TIME>,
        "scope": "<SCOPE>"
    }
}

Revoke a token

Request
curl --cacert external-api.chebanca.io.pem \
  -X POST \
  https://external-api.chebanca.io/auth/oauth/v2/revoke \
  -H 'content-type: application/json' \
  -d '{
    "client_id":"<CLIENT_ID>",
    "client_secret":"<CLIENT_SECRET>",
    "token":"<ACCESS_TOKEN|REFRESH_TOKEN>",
    "token_type_hint":"<access_token|refresh_token>"
    }'
Response
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS,HEAD
< Access-Control-Allow-Headers: Content-Type
< cb-apitrack-id: 4067327926
< Cache-Control: no-store
< Pragma: no-cache
< Content-Type: application/json
< Content-Length: 366
< Date: Tue, 12 Feb 2019 16:06:27 GMT
< Connection: close
< Strict-Transport-Security: max-age=16070400; includeSubDomains
<
{
    "result": {
        "messages": [],
        "flushMessages": true,
        "outcome": "SUCCESS",
        "requestId": "<REQUEST_ID>"
    },
    "data": {
        "tokenType": "access_token|refresh_token",
        "operationOutcome": "revoked"
    }
}