Authentication Service

By Bokbasen .
3 min

This is the new way of authentication when using Bokbasen's APIs

These services are using this new authentication:

  • Onix Export API

  • Object Export API

  • Onix Import API

  • Object Import API

  • Marc Export API

  • Description Export API

  • DDS API

  • Bokskya API

  • Order API

  • Innkjøpsposter API

  • Pliktavlevering API

  • Reporting API

All services requires the client to include a token, acquired from the authentication service. The token will be valid for a limited period of time, but valid for all requests during that time interval. So this is done in two steps:

  1. Authenticate to get a token

  2. Call resource with the token as a header (cache/re-use token as long at is is still valid)

The process uses the Client Credentials Flow (defined in OAuth 2.0), where clientId + clientSecret is used to get an access-token.

Client Credentials Flow

Login

URL

https://auth.bokbasen.io/oauth/token

Method

POST

Header

content-type

application/json
- or -
application/x-www-form-urlencoded

Request payload

client_id

<Your provided clientId>

client_secret

<Your provided clientSecret>

audience

<Your desired audience / dependent on API>

grant_type

client_credentials

Response (JSON)

access_token

Use this token in the header of API-calls

expires_in

Seconds until token will expire

token_type

Bearer

Returns

200

OK

401

Unauthorized (might be missing som attributes, or wrong clientId/Secret)

403

Forbidden (might not have access to the given audience)

Sample usage - Login

To get a token you have to indicate what audience (what service) you want a token for. See Use of Audience. Here is an example:

Example with json

curl -X POST https://auth.bokbasen.io/oauth/token \ -H 'content-type: application/json' \ -d '{ "client_id":"YOUR-CLIENT-ID", "client_secret":"YOUR-CLIENT-SECRET", "audience":"https://api.bokbasen.io/metadata/", "grant_type":"client_credentials" }'

Example with x-www-form-urlencoded

curl -X POST https://auth.bokbasen.io/oauth/token \ -H 'content-type: application/x-www-form-urlencoded' \ --data-urlencode client_id=YOUR-CLIENT-ID \ --data-urlencode client_secret=YOUR-CLIENT-SECRET \ --data-urlencode audience=https://api.bokbasen.io/metadata/ \ --data-urlencode grant_type=client_credentials

Example with x-www-form-urlencoded with Basic Auth

curl -X POST https://auth.bokbasen.io/oauth/token \ -H 'content-type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic BASE64-OF-CLIENT-ID-AND-CLIENT-SECRET' \ --data-urlencode audience=https://api.bokbasen.io/metadata/ \ --data-urlencode grant_type=client_credentials

A successful result will be something like this:

{ "access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ikd6Vk4wZ044S0pybDBKSWJqSHZhcSJ9.eyJodHRwczovL2Jva2Jhc2VuLmlvL21ldGFkYXRhIjp7fSwiaXNzIjoiaHR0cHM6Ly9sb2dpbi5kZXYuYm9rYmFzZW4uaW8vIiwic3ViIjoiYldReU1IbEJqTGI5TVFCaGVsUFo2emhtYWozdGV0UmJAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vYXBpLmRldi5ib2tiYXNlbi5pby9hcnRpY2xlLyIsImlhdCI6MTY4NDk5NDQ4OSwiZXhwIjoxNjg1MDgwODg5LCJhenAiOiJiV1F5TUhsQmpMYjlNUUJoZWxQWjZ6aG1hajN0ZXRSYiIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyIsInBlcm1pc3Npb25zIjpbXX0.TtqnUwmaaUIQ_qV4VPNobVc9vhbzmeKe_w3zOZtkTp1fgF3SXGsL9NMpTgF1CDpMsLVSA7liKSogwR3bsE_-AV7Dki4PK8upx_YKWvcHno6OzdBKErKGf2ftgeRrChUFcaMjkgOXf5BFAaHu5EyR3yZr1zYO0AV4eu4tTRznGBo9Bi-fTAlC95R0VqAOvZINMZbHbG7jQBvfyL9EvleoB1vN7bMjcNHXQ_SkEMU0q58N7CmGPbPuevE40KwXsxghgXiSzOeHO3rDdYzK04tXbmKwIYVgWHIb21KILZbQGoyxj7wkbXoFehcqtQWxn5j25BN5aKwXXzS6hNE54b062g", "expires_in":86400, "token_type":"Bearer" }

Sample usage - Calling other API

When access_token has been fetched, we can call other APIs (corresponding to the audience used):

curl -X POST https://api.bokbasen.io/foo/bar/book/123 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <access_token_here>'

Change to how Authorization-header is constructed

  • No longer use Authorization: Boknett TGT-...

  • Instead use: Authorization: Bearer <access_token_here>

Token expiration

We are optimizing when new tokens are generated and therefore you will see that expires_in will change dynamically through out the day. We are then serving you cached access_token while it is valid (we will not give you a token with less than 10 minutes left).

Caching token

If you want to reduce number of needed calls, we encourage you to cache it, just look at the expires_in (seconds) or look at exp in the payload-part of the JWT-token (right before you do the API-call).

Note that expires_in is dynamic and will just show number of seconds until the token is no longer valid.

Environments

Each environment has it’s own set of credentials

PROD

https://auth.bokbasen.io/oauth/token

TEST

https://auth.stage.bokbasen.io/oauth/token

Related content