Gå til innhold
Norsk
Kontakt oss
  • Det finnes ingen forslag fordi søkefeltet er tomt.

SSO Integration Documentation

This document outlines how to integrate Single Sign-On (SSO) with our portal using a api-based approach to authenticate users and redirect them to your system.

1. Overview


How It Works
1. A user attempts to access your domain through our portal.
2. We send a POST request with user details to your HTTPS endpoint.
3. You process the user data and return a redirect URL (e.g. for direct session, login or registration).
4. Our portal redirects the user to the provided URL.

What You Need to Do
- Implement webhook integration with Vinst to receive user data. (see webhook integration documentation) 
 
What We Provide
- A test environment for validating the SSO integration and overview of the JSON payload.
- Integration support.

2. Request Details

Request Body
The body includes event metadata at root, and SSO event specific data under the `data` object. The oversight over data types in the JSON of the data field will be provided through a swagger, where you'll also be able to test the integration by sending dummy events.
 
 

3. Response Details


Success Response
Return a 200 OK status with a JSON object containing the `redirectUrl`. This gives you the possibility to redirect to a user creation page, if you wish to create an external user from our system, session redirect with a token, or what fits your company's system.

We of course recommend implementing a direct session for the user experience to be as smooth as possible. 
 
Session Example:
{
  "redirectUrl": "https://your-system.com/dashboard?token=abc123"
}
 

Registration Example:
{
  "redirectUrl": "https://your-system.com/register"
}
 
Field Type Description
redirectUrl string URL to redirect the user (e.g., login or registration page).
 

4. Example Integration


Request from Our Portal
POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Vinst-Signature: <computed-signature>
X-Vinst-Timestamp: 2025-05-12T10:00:00
{
   "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventType": "SSO",
  "eventTimestamp": "2025-11-10T12:34:56.789Z",
  "data": " {\"firstName\":\"John\",\"lastName\":\"Doe\",\"orgNo\":\"123456789\",\"email\":\"john.doe@example.com\",\"companyName\":\"Example Company\",\"addresses\":[{\"type\":\"invoice\",\"address1\":\"123 Main Street\",\"address2\":null,\"postalCode\":\"12345\",\"city\":\"Example City\"},{\"type\":\"visiting\",\"address1\":\"456 Elm Street\",\"address2\":\"Apt 7\",\"postalCode\":\"67890\",\"city\":\"Sample Town\"}]}"
}
}
 

Supplier Response

Success:
HTTP/1.1 200 OK
Content-Type: application/json
{
  "redirectUrl": "https://your-system.com/login?token=abc123"
}
 

Error:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "Invalid HMAC signature"
}

5. Testing and Validation

Test Environment
Provide a test endpoint that mimics the production environment for SSO validation.

Validation Checklist
- Verify user data processing and `redirectUrl` generation.
- Ensure `X-Vinst-Signature` is validated.
 

6. Contact Information

For assistance, contact our support team at `va@visma.com`.