Authentication and authorization

All endpoints are authorization protected, per the upstream Standard.

Open Zaak uses the described authentication and authorization mechanism based on JSON Web Tokens (JWT in short).

To connect to Open Zaak, you have received a Client ID and a Secret, which you must use to build a JWT. You can read more about JWT’s on https://jwt.io

The payload of the JWT is:

{
    "iss": "<value of Client ID>",
    "iat": 1602857301,
    "client_id": "<value of Client ID>",
    "user_id": "<unique user ID of the actual end user>",
    "user_representation": "<e.g. the name of the actual end user>"
}

The JWT must be generated with the HS256 algorithm and signed with the secret you received. iat is the Unix timestamp when token-creation happened.

Next, for every API call you make, you must include this token in the appropriate header:

Authorization: Bearer <jwt>

An example:

Given a Client ID docs and secret example-secret, the header of the JWT is:

{
    "typ": "JWT",
    "alg": "HS256"
}

The payload is:

{
  "iss": "docs",
  "iat": 1602857301,
  "client_id": "docs",
  "user_id": "docs@example.com",
  "user_representation": "Documentation Example"
}

Which leads to the following JWT:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJkb2NzIiwiaWF0IjoxNjAyODU3MzAxLCJjbGllbnRfaWQiOiJkb2NzIiwidXNlcl9pZCI6ImRvY3NAZXhhbXBsZS5jb20iLCJ1c2VyX3JlcHJlc2VudGF0aW9uIjoiRG9jdW1lbnRhdGlvbiBFeGFtcGxlIn0.DZu7E780xG4zqRiT8ZhrBeMudz45301wNVDT0ra-Iyw

This would then be used in an API call like:

GET https://test.openzaak.nl/besluiten/api/v1/besuiten HTTP/1.1
Host: test.open-zaak.nl
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJkb2NzIiwiaWF0IjoxNjAyODU3MzAxLCJjbGllbnRfaWQiOiJkb2NzIiwidXNlcl9pZCI6ImRvY3NAZXhhbXBsZS5jb20iLCJ1c2VyX3JlcHJlc2VudGF0aW9uIjoiRG9jdW1lbnRhdGlvbiBFeGFtcGxlIn0.DZu7E780xG4zqRiT8ZhrBeMudz45301wNVDT0ra-Iyw

Warning

Note that you are expected to generate a JWT almost for every call! Open Zaak by default expires JWT’s one hour past the iat timestamp, and for audit-purposes, the user_id and user_representation claims should match the end-user of the application.

Generating JWT Examples:

Example of how to generate JWT tokens in Java, JavaScript, PHP and Python with example libraries. There is a link to a list of more libraries for these and other languages below.

Using the pyjwt for python.

import jwt
import requests
import time

CLIENT_ID = "example"
SECRET = "secret"

payload = {
    "iss": CLIENT_ID,
    "iat": int(time.time()),  # current time in seconds
    "client_id": CLIENT_ID,
    "user_id": "eample@example.com",
    "user_representation": "Example Name",
}
jwt_token = jwt.encode(payload, SECRET, algorithm="HS256")

# add token token to the authentication HTTP header of your request library
zaaktype_url = "https://openzaak.gemeente.local/catalogi/api/v1/zaaktypen/4acb5ab8-f189-4559-b18a-8a54553a74ff"
headers = {"Authorization": "Bearer {token}".format(token=jwt_token)}
response = requests.get(
    zaaktype_url,
    headers=headers,
)
print(response.json())

In JavaScript, most of the token can be generated with the jsonwebtoken package.

import jwt from 'jsonwebtoken';

const CLIENT_ID = 'example';
const SECRET = 'secret';

const getJWT = () => {
  return jwt.sign(
    {
        // iat: placed automatically
        client_id: CLIENT_ID,
        user_id: "eample@example.com",
        user_representation: "Example Name"
    },
    SECRET,
    {
      algorithm: 'HS256',
      issuer: CLIENT_ID, // iss in payload
    }
  );
};


var jwt_token = getJWT()

// add token token to the authentication HTTP header of fetch
const zaaktype_url = "https://openzaak.gemeente.local/catalogi/api/v1/zaaktypen/4acb5ab8-f189-4559-b18a-8a54553a74ff";
fetch(
  zaaktype_url,
  {
    method: 'get',
    headers: {
      'Authorization': `Bearer ${jwt_token}`,
      'Accept': 'application/json',
    },
  }
).then(response => {
  console.log(response);
});

The php-jwt package is available for PHP which can generate the JWT token for you.

use Firebase\JWT\JWT;

$CLIENT_ID = "example";
$SECRET = "secret";

$payload = [
    "iss" => $CLIENT_ID,
    "iat" => time(),
    "client_id" => $CLIENT_ID,
    "user_id" => "eample@example.com",
    "user_representation" => "Example Name",
];

$jwt_token = JWT::encode($payload, $SECRET, "HS256");
// add token token to the authentication HTTP header of your request library
$headers = [
    "Authorization" => "Bearer " . $jwt_token,
];
$zaaktype_url ="https://openzaak.gemeente.local/catalogi/api/v1/zaaktypen/4acb5ab8-f189-4559-b18a-8a54553a74ff";

$client = new \GuzzleHttp\Client();
$response = $client->request("GET", $zaaktype_url, [
    "headers" => $headers,
    'http_errors' => false
]);

echo $response->getBody();

The java-jwt package is available for java which can generate the JWT token for you.

final String CLIENT_ID = "example";
final String SECRET = "secret";

Algorithm algorithm = Algorithm.HMAC256(SECRET);

String jwt_token = JWT.create()
    .withIssuer(CLIENT_ID) // iss
    .withIssuedAt(new Date()) // iat
    .withClaim("client_id", CLIENT_ID)
    .withClaim("user_id", "eample@example.com")
    .withClaim("user_representation", "Example Name")
    .sign(algorithm);

// add token token to the authentication HTTP header of your request library
try {
    URL zaaktype_url = new URL("https://openzaak.gemeente.local/catalogi/api/v1/zaaktypen/4acb5ab8-f189-4559-b18a-8a54553a74ff");
    URLConnection zaaktype_connection = zaaktype_url.openConnection();

    zaaktype_connection.setRequestProperty ("Authorization", "Bearer "+jwt_token);
    zaaktype_connection.addRequestProperty("Accept", "application/json");

    BufferedReader in = new BufferedReader(
            new InputStreamReader(
                zaaktype_connection.getInputStream()));
    // do stuff with buffer

} catch (Exception exception){
    // exception code
}

Useful Links

More indepth JWT Explanation

JWT implementations for various languages