Working with Visma Connect OAuth 2.0
Alright lets get rocking - if you are unfamiliar, I will quickly try to summarize how OAuth 2.0 works through Visma Connect. After that you should jump into Postman with our collection and try it out yourself.
Do note that steps 1-3 only happen ONCE if you have offline_access turned on. With that you will get refresh tokens, so your users won't have to authorize you every single hour.
First
We need to generate a link for our users to click. This link needs to contain:
- client_id - the isv_companyname.
- scopes - the ones you applied for, for instance dineropublicapi:read, dineropublicapi:write and/or offline_access.
- redirect_uri - which needs to match the one we have in our Visma Connect settings.
- A response_type of code.
- We might also include a nonce or state value, so we can identify the user, once they return and prevent replay attacks.
It could look something like this:
https://connect.visma.com/connect/authorize?client_id=isv_{INSERT_YOUR_CLIENT_ID}&response_mode=form_post&response_type=code&scope=dineropublicapi:read+dineropublicapi:write+offline_access&redirect_uri={INSERT_YOUR_REDIRECT_URI}&ui_locales=da-DK
Do note that this is a link we create for our user to interact with. So it is neither a POST nor GET request. We do recommend avoiding openid connect, unless you are very comfortable with it. This should also be reflected in your Visma Connect Application settings.
Second
We wait for the users to hit either accept or cancel in the window they get. All we do here is wait for the user. Further down this tutorial you can see this in practice.
Third
If the user accepts, we'll get a POST request send to our application through our redirect_uri. This POST request will contain everything we need to get an access_token. Simple enough.
We will get a code, id_token, a confirmation of scopes and so on to validate the request. The most important part, that we will continue to interact with, is the code.
Forth
We exchange the code for a token, that we can use to interact with the API. This happens through a regular old POST request to https://connect.visma.com/connect/token. Here we send:
- grant_type of authorization_code
- our redirect_uri from our visma connect application settings
- the code we got in step 3
- client_id
- client_secret
We send this as content-type: application/x-www-form-urlencoded. Make sure to send it as a url-encoded string. If the body is formatted as a json, the request will fail.
In return we'll get our access_token, id_token, expires_in, token_type and scopes.
We're ready to interact with Dineros API.
Just to reiterate, if we have offline_access turned on here, we'll also get a refresh_token that we can exchange for a new token, so the user doesn't have to go through this once an hour, and we can continue to interact with the API without user involvement.
Once you need to apply this to your own code, you can find all the information in the Visma Connect Documentation. Just make sure to use the right scopes, and remember you're creating a link for user interaction in step 1.