Single Sign-On (SSO)

vScope offers full support for both SAML 2.0 and OpenID Connect (OIDC), giving organizations flexibility to integrate with their preferred identity provider. Whether you rely on SAML for established compatibility or OIDC for modern token-based authentication, vScope ensures secure, centralized access control.

SAML 2.0

vScope supports Single Sign-On (SSO) using any SAML 2.0–capable IdP. This allows enhanced security features such as Multi-factor Authentication (MFA). By letting your IdP handle authentication and permissions, you centralize access control and user management. This guide outlines the configuration steps.

Note

If you want to use Microsoft Entra ID as IdP, you can find the full step-by-step guide on: Configuring Single Sign-On for Microsoft Entra ID using SAML 2.0

SAML2.0 requires configuration in both the Identity Provider (IdP) and the Service Provider (vScope).

vScope SSO settings

Settings in vScope for Single Sign-On.

• Configuration name
  • The name of the SAML configuration in vScope.
  • E.g. Entra.
• Callback URL
  • The URL (on vScope) to which the IdP will redirect successful authentications.
  • Automatically generated by vScope.
    • The Callback URL will be generated by combining:
      • Settings > Network > Web Application Address > Base URL
      • Settings > Single Sign-On (SSO) > Configuration name
      • E.g. https://vscope.mycompany.com/rest/usermanager/sso/authenticate/Entra.
• Identifier (Entity ID)
  • The unique identifier that vScope uses when interacting with the IdP (must match the Identifier/Entity ID registered for the app in the IdP).
  • E.g. vScope.
• App Federation Metadata Url
  • The URL to the Identity Provider metadata XML which contains configuration details of the IdP along with certificates for signing SAML assertions.
  • Often called App Federation Metadata URL, IdP Metadata URL or SAML Metadata URL in the IdP
  • E.g. (ADFS) https://<adfs-server>/FederationMetadata/2007-06/FederationMetadata.xml
  • E.g. (Entra ID) https://login.microsoftonline.com/mytenant/federationmetadata/2007-06/federationmetadata.xml?appid=myapp
  • E.g. (Okta) https://mycompany.okta.com/app/myapp/sso/saml/metadata

Signing & Certificates

Signing is used to verify the validity of SAML messages and assertions. Most IdPs sign assertions by default but do not require the SP to do the same for authentication requests or metadata.

In vScope SSO settings there are four settings that control different aspects of signing:

• Sign Metadata (default false)
  • Signs the vScope SP metadata XML file. If you configure the IdP with the SP metadata from vScope and the IdP expects it to be signed, enable this setting.
• Sign Authentication Requests (default false)
  • Signs the AuthnRequest from vScope to the IdP.
• Request Signed Assertions (default false)
  • Requests the IdP to sign assertions sent to vScope. Unsigned assertions will be ignored by vScope if enabled. Make sure to configure the IdP to sign assertions.
• Request Signed Responses (default false)
  • Requests the IdP to sign entire SAML responses sent to vScope. Unsigned responses will be ignored by vScope if enabled. Make sure to configure the IdP to sign responses.

Important

If you enable Sign Metadata or Sign Authentication Requests, the IdP must have access to vScope’s signing certificate.
Make sure to upload the vScope signing certificate to the IdP; otherwise, authentication requests from vScope to the IdP will fail.

vScope automatically retrieves the IdP’s signing certificate from the App Federation Metadata URL setting, so you do not need to download or import the IdP certificate manually.

Keystore options

vScope generates its signing keystore automatically the first time you configure SAML. The default keystore is recommended and normally should be left untouched.
If you need full control over the certificate that vScope presents to the IdP—for example to align with an internal PKI policy—you can upload your own keystore instead. Ensure the private key and certificate chain match the IdP requirements and plan to replace the file before it expires.

IdP SSO settings

These are settings in the IdP. The exact names of the settings may vary.

• Identifier (Entity ID) (Entra), Relying Party Identifier (ADFS), Application label (Okta)
  • Must match Identifier (Entity ID) in vScope SSO settings.
• ACS (Assertion Consumer Service URL) (Entra), Callback URL, Reply URL or Single sign-on URL (Okta)
  • Must match Callback URL in vScope SSO settings.

Attributes & Claims

To enable authentication and authorization, both vScope (the Service Provider) and the IdP (Identity Provider) must agree on which attributes (user data stored in the IdP) are sent, and how these are represented as claims inside a SAML assertion.

A SAML assertion is a digitally signed, trusted XML message issued by the IdP and consumed by vScope. It communicates proof of authentication, user attributes (such as email or group membership), and authorization details each time a user logs in to vScope.

There are four claims that vScope expects to be present in the SAML assertion. Ensure that your IdP is configured to include the corresponding attributes as claims.

• Email (user email)
• Given name (first name)
• Surname (last name or family name)
• Groups (the user’s group memberships)

These claims are configured as Attribute assignments in vScope SSO settings:

For each of the claims the following values must be set.

• Name
  • The name of the claim. E.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
• Friendly name (optional)
  • The friendly name of the claim. E.g. emailaddress.
• Name format
  • The format of Name. E.g. URI.

Verify the exact names in the IdP.

As vScope receives a SAML assertion it will attempt to map claims by their Name or Friendly name. So for email in the example above, vScope will look for the user email in http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress and emailaddress in the SAML assertion.

Note

Make sure there are no conditional access policies, role restrictions, or resource scope settings in the IdP that block the user from authenticating or being redirected to vScope. This may cause 403 error. Common causes include policies that:

• Restrict sign-ins based on network location or group membership
• Deny token issuance for the vScope application or scope

Groups claim

The groups claim is not required but recommended. It can be used by vScope Group Mapping to map the user by the groups in the SAML assertion to groups in vScope.

Important

If you encounter issues with group claims, check the format of the groups attribute in your SAML response. In some cases, the groups claim may appear as a single string containing comma-separated entries. Our library interprets this entire string as one value, rather than multiple individual group entries. Make sure the claim format matches what the library expects.

Troubleshooting SAML 2.0

The most common errors when setting up SAML 2.0 involve mismatched callback URLs, incorrect or inconsistent entity IDs, and missing or mismatched claims or attributes. The troubleshooting guide below will help you identify and resolve these issues.

A reliable way to detect such problems is to inspect the SAMLRequest (AuthnRequest) sent to the Identity Provider (IdP) and the SAMLResponse returned from it. Comparing the decoded XML contents with your configuration often reveals discrepancies in entity IDs, redirect URLs, or missing attributes.

Capture and decode the SAMLRequest

1. Initiate a SSO login in vScope and open your browser’s developer tools (Network tab). Find the first redirect that targets the IdP, then inspect the Payload or Headers panel to locate the SAMLRequest parameter. If you are using Chrome, make sure Preserve log is checked, otherwise the request log might be incomplete. In the image below the request is targeting https://login.microsoftonline.com since we are using Azure Entra.

   

2. Copy the entire SAMLRequest value. It is URL-encoded, Base64-encoded, and deflated.

3. Go to samltool.com, paste the value into the Deflated and Encoded XML field and click Decode. The tool automatically inflates, Base64-decodes, and URL-decodes the payload so you can review the XML AuthnRequest.

Confirm the AssertionConsumerServiceURL, Issuer, and requested NameID formats match your IdP configuration.

Example AuthnRequest (from Azure Entra) decoded from the SAMLRequest value:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" AssertionConsumerServiceURL="https://myvscope.acme.org/rest/usermanager/sso/authenticate/Azure" Destination="https://login.microsoftonline.com/12345678-cd35-4c08-9299-a9eb162f38e8/saml2" ForceAuthn="false" ID="_e5ad770568044a929ba64e0ad969b32f55b9b5e" IsPassive="false" IssueInstant="2025-11-11T12:05:04.172Z" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Version="2.0">
  <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://myvscope.acme.org</saml2:Issuer>
  <saml2p:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"/>
</saml2p:AuthnRequest>

Capture and decode the SAMLResponse

1. Let the IdP finish authentication. Back in developer tools, look for the POST request that targets .../rest/usermanager/sso/authenticate/<configuration>. It is usually the next request after the request to the IdP. In the image below our configuration is named Azure. The form data of this request includes the SAMLResponse parameter.

   

2. Copy the SAMLResponse value. Unlike the request, it is only Base64-encoded (no deflate).

3. In samltool.com, paste the value into the Deflated and Encoded XML field and click Decode to view the XML response.

Review the <StatusCode> for errors, verify the <Audience> equals your vScope Entity ID, and check that the expected claims (givenName, surName, email, name and groups) are present under <Assertion><AttributeStatement><Attribute Name="..."><AttributeValue>...</AttributeValue></Attribute></AttributeStatement>.

The Name value (for example http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname) must also match the Attribute name configured in vScope for that attribute. If the names differ, vScope cannot map the attribute.

This XML also confirms whether the IdP signed the response and/or assertion per your configuration.

Example decoded SAMLResponse (from Azure Entra):

<?xml version="1.0"?>
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_7b104111-c8d9-4bfe-9abf-dc215d097de5" Version="2.0" IssueInstant="2025-11-11T12:06:29.767Z" Destination="https://myvscope.acme.org/rest/usermanager/sso/authenticate/Azure" InResponseTo="_7f11edf346f04b57a2ecd804c0a80ab7c096446">
  <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://sts.windows.net/12345678-cd35-4c08-9299-a9eb162f38e8/</Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </samlp:Status>
  <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="_4bbe4980-e873-4eb5-bf5a-d0f2edab3f00" IssueInstant="2025-11-11T12:06:29.763Z" Version="2.0">
    <Issuer>https://sts.windows.net/12345678-cd35-4c08-9299-a9eb162f38e8/</Issuer>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
      <SignedInfo>
        <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
        <Reference URI="#_4bbe4980-e873-4eb5-bf5a-d0f2edab3f00">
          <Transforms>
            <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
            <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          </Transforms>
          <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
          <DigestValue>DbgbMN4Holh7O6fQyajNbindIQdkiqW+Zb+m0y+mh5M=</DigestValue>
        </Reference>
      </SignedInfo>
      <SignatureValue>UpcoGceU0qZvz5lgHaV0qG3JssHOzC/Tq4b9Sd2mbVlxVOaqm6e+PRag26cLyfIjVZr</SignatureValue>
      <KeyInfo>
        <X509Data>
          <X509Certificate>MIIC8DCCAdigAwIBAgIQSksKe1WjbKJF0MaOOaN0mjANBgkqhkiG9w0BAQsFAD</X509Certificate>
        </X509Data>
      </KeyInfo>
    </Signature>
    <Subject>
      <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">john.doe@acme.org</NameID>
      <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <SubjectConfirmationData InResponseTo="_7f11edf346f04b57a2ecd804c0a80ab7c096446" NotOnOrAfter="2025-11-11T13:06:29.644Z" Recipient="https://myvscope.acme.org/rest/usermanager/sso/authenticate/Azure"/>
      </SubjectConfirmation>
    </Subject>
    <Conditions NotBefore="2025-11-11T12:01:29.644Z" NotOnOrAfter="2025-11-11T13:06:29.644Z">
      <AudienceRestriction>
        <Audience>http://myvscope.acme.org</Audience>
      </AudienceRestriction>
    </Conditions>
    <AttributeStatement>
      <Attribute Name="http://schemas.microsoft.com/identity/claims/tenantid">
        <AttributeValue>12345678-cd35-1234-9299-a9eb162f38e8</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
        <AttributeValue>98765432-b89c-1234-b3ef-e7afaa3b02cc</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.microsoft.com/identity/claims/displayname">
        <AttributeValue>John Doe</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups">
        <AttributeValue>98765432-d218-1234-a3ab-285d36e125fc</AttributeValue>
        <AttributeValue>98765432-5d68-1234-88a5-92d8a53e07b3</AttributeValue>
        <AttributeValue>98765432-df98-1234-b666-e4297d273695</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.microsoft.com/identity/claims/identityprovider">
        <AttributeValue>https://sts.windows.net/12345678-cd35-4c08-9299-a9eb162f38e8/</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.microsoft.com/claims/authnmethodsreferences">
        <AttributeValue>http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
        <AttributeValue>John</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
        <AttributeValue>Doe</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
        <AttributeValue>john.doe@acme.org</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
        <AttributeValue>john.doe@acme.org</AttributeValue>
      </Attribute>
    </AttributeStatement>
    <AuthnStatement AuthnInstant="2025-11-11T06:52:24.123Z" SessionIndex="_4bbe4980-e873-4eb5-bf5a-d0f2edab3f00">
      <AuthnContext>
        <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
      </AuthnContext>
    </AuthnStatement>
  </Assertion>
</samlp:Response>

OpenID Connect

Note

Currently, only Microsoft Entra ID is available as IdP using OpenID Connect. Configuring Single Sign-On for Microsoft Entra ID using OpenID Connect