Troubleshooting V‑Spark SSO

Configuring V‑Spark SSO for use with certain IDPs may lead to special configuration requirements as described in the following sections.

Global IDP Logout with Okta

When V‑Spark is configured for use with Okta, users may be logged out of the entire Okta system when they log out of V‑Spark. In this case, the global logout may be avoided by specifying an incorrect URL for the end session endpoint. This requires the discovery endpoint to be disabled and for individual endpoints to be specified manually. To implement this workaround, use the following procedure:

  1. Click Settings > Accounts.
  2. Click Edit next to the company to be modified. The Update Company dialog displays.
  3. Click Next until the dialog page with SSO options appears.
  4. Copy the discovery endpoint and open it in a separate browser tab. The data returned from the discovery endpoint displays. For easier reading, copy and paste this data into a JSON viewer.
  5. The discovery endpoint's output includes, among other data fields, seven fields with endpoint URLs used for V‑Spark company SSO configuration. The field names for endpoint URLs required by V‑Spark are:

    • issuer

    • introspection_endpoint

    • jwks_uri

    • authorization_endpoint

    • token_endpoint

    • userinfo_endpoint

    • end_session_endpoint

    Important: Although it is required by V‑Spark under normal circumstances, the end_session_endpoint URL provided by the IDP must not be used for this workaround.
  6. In V‑Spark, disable the Use Discovery Endpoint option. Seven text fields for required IDP endpoints appear, as in the following example:advanced update company dialog
  7. Enter the issuer , introspection_endpoint , jwks_uri , authorization_endpoint , token_endpoint , and userinfo_endpoint URLs in the corresponding text fields.
  8. Enter an invalid URL in the End Session Endpoint field. For this workaround, the value for End Session Endpoint must not be equal to the value supplied by the discovery endpoint. For simplicity, using the URL for the V‑Spark login page is recommended.
  9. Click Update.

Okta's discovery endpoint lacks userinfo data

When adding manual endpoints as described in Global IDP Logout with Okta, data obtained from Okta's discovery endpoint may lack information about the userinfo endpoint. The following endpoint URLs function correctly for a V‑Spark-Okta SSO implementation as of November 2023.

Field name

Endpoint URL example

issuer

https://{variable}.okta.com

introspection_endpoint

https://{variable}.okta.com/oauth2/v1/introspect

jwks_uri

https://{variable}.okta.com/oauth2/v1/keys

authorization_endpoint

https://{variable}.okta.com/oauth2/v1/authorize

token_endpoint

https://{variable}.okta.com/oauth2/v1/token

userinfo_endpoint

https://{variable}.okta.com/oauth2/v1/userinfo

end_session_endpoint

https://{V‑Spark}.{company}.com/login

For the latest information on Okta's endpoint configuration, refer to Okta's OIDC documentation.

Missing Email Address Error with Azure Active Directory

Users may encounter a V‑Spark error that says SSO verification failed because the email address is missing from the credentials returned from the IDP, even though the email field has been configured for the IDP client application scope. This error happens because some IDPs such as Azure Active Directory may not include the email field as a supported claim by default. For more information, refer to the external Active Directory documentation.

In this case, the email field must be added manually to the claims_supported list in the IDP's client application configuration. Otherwise, SSO authentication fails and V‑Spark logs an event in /var/log/vspark/server.log .

When configuring the IDP to communicate with V‑Spark, the openid , profile , and email fields must be included in the IDP's scopes_supported list.

The email field must also be included in the claims_supported list. In addition, the sub , iss , aud , exp , iat , and at_hash claims must be included in the claims_supported list.

To confirm that the lists contain the required elements, use the following procedure:

  1. Click Settings > Accounts.
  2. Click Edit next to the company to be modified. The Update Company dialog displays.
  3. Click Next until the dialog page with SSO options appears.
  4. Copy the discovery endpoint and open it in a separate browser tab. The data returned from the discovery endpoint displays. For easier reading, copy and paste this data into a JSON viewer.
  5. Confirm the scopes_supported list includes openid , profile , and email .
  6. Confirm the claims_supported list includes email , sub , iss , aud , exp , iat , and at_hash .
  7. Add any missing fields using your IDP's client application configuration.
    Note: Your IDP configuration may contain additional scopes and claims not documented here, but these fields are not related to V‑Spark.