Overview

To support federated sign in (SSO), a customer must have an identity provider capable of supporting OIDC (Open ID Connect). These are usually offered by a third-party service (Azure Active Directory, Okta, Auth0, etc.) and must be open to the internet (our servers and users must both be able to reach the addresses given).

Setup

To configure SSO, the following steps should be taken by the customer:

  • Create a new client for Enhanced Voting.

    • The exact terminology and usage here differ from provider to provider. Client is the word used in OIDC, but some providers may use words like 'App' or 'Application'.
    • If the provider asks, this is a "Web" application, not a "Single page application (SPA)" or "Mobile" or "Desktop".
    • If applicable, the "Authorization Code" grant must be enabled.
    • PKCE (Proof Key for Code Exchange) should be enabled if it's an option.
    • If available, scopes should include at least "openid", "profile" and "email". Often these are added by default or not directly exposed to the administrator.
    • We will provide a unique sign-in and sign-out URL for the client generated by our team that must be saved on the client. (These are often called redirect uri or Front-channel logout uri)

  • Create a secret for the newly created Enhanced Voting client.

    • In some systems, this is created automatically.
    • In many systems, secrets are only displayed once. Copy it now because we will need this value.
    • The secret should be considered sensitive and should be transferred and stored only via secure means.
  • Assign users to the newly created Enhanced Voting client as necessary. If using buttons/badges for users to access our application on a dashboard provided as part of the provider, "Identity provided initiated SSO" is not available and should be disabled. OIDC does not support this out of the box. Any button should link to https://login.enhancedvoting.com.

Once done, we will need the following information from the customer: 

  • The clientid of the client created in step 1 (sometimes called appid, applicationid, or other)
  • The discovery document URL
  • In some systems this is provided, in others it's not obvious where to get it from. It usually contains .well-known in the URL, for example, here is ours: https://login.microsoftonline.com/4446d167-62fc-4736-95a9-2227dbdbb13d/.well-known/openid-configuration
  • Often, this is just a base domain + .well-known/openid-configuration. If you can't find it, just provide us a link to your sign in page, and we can likely figure it out.
  • The list of email domains in use by all users who could use our system. Often these are separate domains for each county.
  • Secure Transfer - A member of our team will send you a link to securely upload the following.
  • The secret created in step 2.

Operating Modes

SSO has 3 primary modes of determining during login, whether a user should use SSO. This is configurable.

  • (Preferred) Email Domain Match

    • In this mode, any user that enters an email address containing a domain name in the list of domains provided by the jurisdiction will receive a "Sign in with SSO" button that replaces the normal sign in with password workflow.
    • This method is not suitable if publicly available domains are in use that could be used across multiple clients. @gmail.com @outlook.com @hotmail.com etc. are not supported in this mode.

  • User Lookup

    • In this mode, when an email address is typed in, we look-up to see if the user is assigned to a jurisdiction that uses SSO. If so, we replace their password sign in with "Sign in with SSO".
    • This method is only recommended when email addresses are part of the public record. Otherwise, it's possible to harvest usernames with this method to determine which users have accounts in the system and which do not.

  • Custom Domain

    • It is possible to set up our software so that it runs behind a custom domain. In this case, any visitors to the custom domain will automatically be assumed to be using SSO and sent to the identity provider automatically.
    • This mode requires additional extra configuration, and the customer must have the capability of changing DNS records within their requested custom domain and may take additional time to set up.

In both the 1st and 3rd modes, while it is possible to have users get accounts created automatically via SSO without first needing to be invited into our system, we must have distinct domain names for each jurisdiction without overlaps (each county must have a separate list of domain names, and the state must have its own list), and the provider must also have roles or claims assigned to each user that would allow us to set permissions automatically. Without this, users must first be invited to the system, even if they use SSO.