ClientID’s

What you need to know

Client applications need a JWT bearer token to identify themselves when they are calling an api on OneGround. The ZGW standard does not define a function for retrieving such a token. Although there is a service in the VNG reference implementation, that service is meant for testing purposes and cannot be used as an example. Contrary to the expectation of many developers, JWT bearer tokens need to be generated by the client application itself, using a given ClientID and secret. Also contary to expectations: there is no authentication or authorisation on user level in the Api’s. Only applications can be authenticated and authorized. These limitations are a feature of the ZGW standard itself.

How to get a ClientID and secret

You can create a ClientID and secret using the configuration tool. We advise to create one ClientID per application so that you can give suitable permissions per application, and identify the application in the logging.

How to generate a JWT token

As stated above, your Client application has to generate the token. Here is an example code snippet for generating a token in Postman:

     
    function base64url(source) {
        // Encode in classical base64
        encodedSource = CryptoJS.enc.Base64.stringify(source);
    
        // Remove padding equal characters
        encodedSource = encodedSource.replace(/=+$/, '');
    
        // Replace characters according to base64url specifications
        encodedSource = encodedSource.replace(/\+/g, '-');
        encodedSource = encodedSource.replace(/\//g, '_');
    
        return encodedSource;
    }
    
    function addIAT(request) {
        var iat = Math.floor(Date.now() / 1000) + 257;
        data.iat = iat;
        data.exp = iat + 10000000;
        return data;
    }
    
    var header = {
        "typ": "JWT",
        "alg": "HS256"
    };
    
    var data = {
        "iss": "client-123456789",
        "client_id": "client-123456789",
        "user_id": "user",
        "user_representation": "client-123456789",
        "jti": "35b9d0e0-8c80-4aef-9c9c-55d6e34eff40"
    };
    data = addIAT(data);
    
    var secret = "<secret>";
    
    // encode header
    var stringifiedHeader = CryptoJS.enc.Utf8.parse(JSON.stringify(header));
    var encodedHeader = base64url(stringifiedHeader);
    
    // encode data
    var stringifiedData = CryptoJS.enc.Utf8.parse(JSON.stringify(data));
    var encodedData = base64url(stringifiedData);
    
    // build token
    var token = encodedHeader + "." + encodedData;
    
    var signature = CryptoJS.HmacSHA256(token, secret);
    signature = base64url(signature);
    
    var signedToken = token + "." + signature;