Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

SSO Integration Documentation (en)

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 via 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.
- Reject requests with old timestamps outright. In the context of SSO, this window can be relatively short (e.g., 15 seconds).
 
What We Provide
- A test environment for validating the SSO integration.
- Documentation and integration support.

2. Request Details

Request Body
The body includes event metadata at root, and SSO event specific data under the `data` object.
 
{
  "eventId": "123e4567-e89b-12d3-a456-426614174000",
  "eventType": "Vinst_SSO",
  "eventTimestamp": "2025-05-13T14:30:00Z",
  "data": {
    "email": "turid@jensen.com",
    "firstName": "Turid",
    "lastName": "Jensen",
    "orgNo": "123456789"
  }
}
 
Field Type Description
email string User's email address.
firstName string User's first name.
lastName string User's last name.
orgNo string Organization number associated with user.

 


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.
 
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).

 

Error Response
For invalid requests, return an appropriate HTTP status code (e.g., 400 Bad Request) with an error message.
 
{
  "error": "Invalid signature"
}
 

4. Security Considerations

Refer to the Webhook Integration documentation for details on:
- HMAC signature validation.
- Timestamp-based replay protection.
- HTTPS requirements.

5. Example Integration


Request from Our Portal
POST /your-endpoint HTTP/1.1
Content-Type: application/json
Vinst-Signature: <computed-signature>
Vinst-Timestamp: 2025-05-12T10:00:00Z
{
  "eventId": "123e4567-e89b-12d3-a456-426614174000",
  "eventType": "Vinst_SSO",
  "eventTimestamp": "2025-05-13T14:30:00Z",
  "data": {
    "email": "turid@jensen.com",
    "firstName": "Turid",
    "lastName": "Jensen",
    "orgNo": "123456789"
  }
}
 

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"
}

6. 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 `Vinst-Signature` is validated.
- Replay attack prevention is not necessary for SSO

7. Contact Information

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