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.

• 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) > Name
      • E.g. https://vscope.acme.org/rest/usermanager/sso/authenticate/Entra.
• 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. http://myvscope.acme.org.
• Metadata resource
  • 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://acme.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 service provider metadata (default false)
  • If enabled, vScope will sign its Service Provider (SP) metadata (default: false). Enable this only if the IdP requires signed metadata. The IdP must have vScope’s signing certificate to verify the signature.
• Sign service provider authentication requests (default false)
  • If enabled, vScope will sign its SAML AuthnRequests (default: false). The IdP must have vScope’s signing certificate to validate the signed requests.
• Want Assertions signed (default false)
  • If enabled, vScope requires the IdP to sign all SAML Assertions (default: false). Unsigned assertions will be rejected.
• Want Responses signed (default false)
  • If enabled, vScope requires the IdP to sign the entire SAML Response (default: false). Unsigned responses will be rejected.

ADFS: Enable Signatures

When integrating with ADFS, there is no UI setting to control SAML response signing mode for the relying party trust. Use PowerShell to set SamlResponseSignature to match the vScope signing requirements:

vScope SSO setting	ADFS SamlResponseSignature value
Enable Want Responses signed	MessageOnly
Enable Want Assertions signed	AssertionOnly
Enable both Want Responses signed and Want Assertions signed	MessageAndAssertion

Run the following command with your RPT (Relying Party Trust) name and SamlResponseSignature parameter value.

Set-AdfsRelyingPartyTrust -TargetName "<Your RPT Name>" -SamlResponseSignature <Value>

Important

If you enable Sign service provider metadata or Sign service provider authentication requests, the IdP must have access to vScope’s signing certificate. If the IdP cannot ingest the SP metadata referenced in Downloading vScope metadata, upload the vScope signing certificate manually; otherwise, authentication requests from vScope to the IdP will fail.

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

Downloading vScope metadata

Use the Download metadata button in vScope’s SAML 2.0 settings to open the generated Service Provider (SP) metadata in a browser. Copy the URL of that metadata page and register it in your IdP if it supports consuming SP metadata via URL. The metadata already contains vScope’s signing certificates, so the IdP can automatically trust future signing certificate rotations without you manually copying certificates. For IdPs that only accept file uploads, download the XML and upload it directly.

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.

NameID requirements

vScope expects the NameID in the SAML assertion to be in the emailAddress format (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress). Ensure your IdP emits the user’s email address as the NameID.

ADFS: Configure Name ID

For ADFS, emailAddress is not configured by default for Name ID. Add a claim rule to emit the email as NameID:

1. Right-click the Relying Party Trust for vScope and select Edit Claim Issuance Policy.
2. Click Add Rule….
3. Choose Transform an Incoming Claim and click Next.
4. Configure:
   • Claim rule name: Email As Name ID
   • Incoming claim type: E-Mail Address
   • Outgoing claim type: Name ID
   • Outgoing name ID format: Email
   • Check Pass through all claim values
5. Click OK and apply the changes.

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.

• Attribute 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 Attribute 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.

ADFS: Emit group SIDs

For ADFS, set the Groups attribute name in vScope SSO settings to http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid so it matches the Group SID claim emitted by the rule below.

To send group memberships from ADFS, add a transform rule that passes through group SIDs:

1. Right-click the Relying Party Trust for vScope and select Edit Claim Issuance Policy.
2. Click Add Rule….
3. Choose Transform an Incoming Claim and click Next.
4. Configure:
   • Claim rule name: Groups SIDs
   • Incoming claim type: Group SID
   • Outgoing claim type: Group SID
   • Check Pass through all claim values
5. Click OK and apply the changes.

If configured correctly, ADFS will now include Group SIDs in the assertion. When setting up group mapping you must set the mapping ID to the SID of the group you want to map.

ADFS emits group SIDs for every group the user belongs to (both direct and nested memberships).

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>

NameID must be persistent

Ensure the NameID your IdP emits is persistent and never changes for a given user. vScope uses the NameID as part of its user ID; if it changes (for example switching from email to UPN or by not using a persistent NameID), vScope will treat the user as new and lose the link to the previous account. For ADFS-specific steps, see ADFS: Configure Name ID.

The NameID is returned as part of the SAML Response under Response -> Assertion -> Subject:

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

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