A server-side web application must implement the authorization_code OAuth 2.0 grant type. For compliance with OAuth 2.1 specifications, a web application can also be configured to use Proof Key for Code Exchange extension. This can be enabled or disabled in the application's details page.

In order to authenticate users in a server-side web application, follow the steps described below.

Step 1: Authorization request

Before starting the authorization process, applications with PKCE enabled create what is known as the  code verifier. This is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.

Once the app has generated the code verifier it uses that to create a  code challenge. The code challenge is a BASE64-URL-encoded string of the SHA256 hash of the code verifier.

Initiate the authorization process by redirecting the user to Visma Connect authorization endpoint. This endpoint is accessible over https; plain http connections are refused. Ensure query parameter values are always URL encoded. The set of query parameters supported by the Visma Connect Authorization Server include:

Example:

GET https://connect.visma.com/connect/authorize?client_id=demoapp&response_type=code+id_token&response_mode=form_post&scope=openid+email+profile&redirect_uri=http://demoapp.example.com/oauthcallback&nonce=qksKW97hcv&state=CfDJ8NbGuiMeKnBKlosjbaGWcBzxsyHJjSmlXdcP5HT0Jp_qH...tE8u1Ws&ui_locales=nb-NO+sv-SE+en-GB

Step 2: User consent

In this step, the user decides whether to grant your application the requested access or not. At this stage, Visma Connect displays a consent window with the name of your application, seeking permission to access with the user’s authorization credentials. The user can then consent or refuse to grant access to your application.

Your application doesn’t need to do anything at this stage as it waits for the response from Visma Connect Authentication server indicating whether the access was granted or not.

Step 3: Authentication Response

Since we requested a form POST as response (response_mode=form_post used on the request), the authorization server sends the following response back to your application:

POST https://demoapp.example.com/oauthcallback Content-Type: application/x-www-form-urlencoded code: 94c99b73c13c1e39f7b0a7d259628338 &id_token:eyJhbGciOiJSUzI1NiIsImtpZCI6IjZCN0FDQzUyMDMwNUJGREI0R...ZBMEu6dA &scope:openid email profile &state:CfDJ8NbGuiMeKnBKlosjbaGWcBzxsyHJjSmlXdcP5HT0Jp_qH...tE8u1Ws &session_state:u9pDw26xhANhsj5vmg9aClWqWPRx8OdbyScowPzd8d0.4febcb64e04a793c4ab1aec3f1392257

curl --request POST --url https://connect.visma.com/connect/token --header 'content-type: application/x-www-form-urlencoded' --data 'grant_type=authorization_code&redirect_uri=https%3A%2F%2Fdemoapp.example.com/oauthcallback%2Fcallback&code=94c99b73c13c1e39f7b0a7d259628338&client_id=demoapp&client_secret=SECRET'

Parameters:

If successful, this call will return a neatly packaged token that will contain the following fields:

{
 "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjVENDc....7MTOBbdd5mgb2CHzxL0RFjs24pqC1pCeUqOjbg",
 "id_token": "eyJhbG....dsaeKOJdIHS988MLKJdsaCeUqOjbg",
 "expires_in": 3600, 
"token_type": "Bearer",
 "scope": "openid email profile" 
}

When Identity Scopes are used in the authentication request your application can retrieve additional information about the authenticated user from UserInfo Endpoint.

If offline_access scope is used in the authentication request, the response will also contain an refresh_token which can be used to refresh an expired access token.