Supported Remote Authentication Methods

Simply Voting supports Remote Authentication of electors via the following protocols:

• Security Access Markup Language (SAML)
• OpenID Connect (OIDC)
• Lightweight Directory Access Protocol (LDAP)
• Central Authentication Service (CAS)
• HTTP(S) Authentication
• External Website Login
• Proprietary SSO

Security Access Markup Language (SAML)

The Voting System can authenticate against a Security Assertion Markup Language (SAML) Identity Provider such as Shibboleth, ADFS, Azure AD, Keycloak, or Okta. Electors click a Login button on the Voting Website and enter their credentials on the organization's system, after which they are redirected back to the Voting System upon successful authentication. Passwords are not seen by the Voting System.

Requirements

• Step 1: You must first exchange metadata with Simply Voting. Simply Voting's Service Provider metadata is located here.

https://shibboleth.simplyvoting.com/shibboleth-sp

• Step 2: You must install Simply Voting's metadata (or entityID) as an approved Service Provider in your organization's Identity Provider.
  
  
• Step 3: You must release a single attribute, a unique identifier, which can be anything as long as it matches the Elector ID that will be used in the stored list of eligible electors in the Voting System. For example, if "email" is being used as the Elector ID, then "email" must be released as an attribute.
  
  
• Step 4: The SAML name of the chosen attribute must be communicated to Simply Voting staff. You may also communicate to Simply Voting staff any single Logout URL that you would like the Voting System to redirect electors to upon logout.
  
  
• Step 5: To test the integration, our preference is for your organization to provide Simply Voting with a set of test login credentials. Otherwise we can coordinate testing with your IT staff.

OpenID Connect (OIDC)

The Voting System can authenticate against an OpenID Connect provider such as Okta or Keycloak. Electors click a Login button on the Voting Website and enter their credentials on the organization's system, after which they are redirected back to the Voting System upon successful authentication. Passwords are not seen by the Voting System.

Implementation of this authentication method does not require Simply Voting staff involvement, and can be configured self-service by client organizations inside the Election Manager tool by navigating to the Settings page and then to the Authentication Details section.

Requirements

• Client ID
• Client Secret Value
• Issuer (provider) URL (e.g. https://idp.domain.com). The voting system will look for a discovery document with your OpenID metadata under https://idp.domain.com/.well-known/openid-configuration.
• You must configure https://customer.simplyvoting.com/auth.php as the Login Callback in your identity provider (where customer.simplyvoting.com is your voting website).
• You must configure https://customer.simplyvoting.com as the Logout Callback in your identity provider (where customer.simplyvoting.com is your voting website).

Optional Parameters

• Custom Logout URL: This is typically only needed for OIDC providers that don't publish an end_session_endpoint directive in their well-known configuration (e.g. Auth0).
• Claim: The claim name returned by the identity provider that will be used to match the Elector ID in the voting system. The value will default to sub if not provided. If you wish to use a different claim, please ensure that the issued Client ID and Client Secret Value are authorized to access the OpenID scope to which it belongs.
• Scopes: A semicolon-separated list of scopes that will be requested from the IdP. The scopes will default to openid if not provided.

Testing

• You can test your OIDC configuration using the Test these Settings button in the Authentication Details form. To test properly, you must add https://www1.simplyvoting.com/manage/authtest.php as one of your Login Callbacks.

Lightweight Directory Access Protocol (LDAP)

The Voting System can authenticate against directory technologies over the Lightweight Directory Access Protocol (LDAP). Electors enter their credentials on the Voting Website, which are passed along to your LDAP server. Upon successful authentication, the elector is logged into the Voting System. Passwords are never stored in the Voting System.

You may need to whitelist the Voting System's IP addresses in your firewall to allow external access to your LDAP directory. If so, please contact support to request the required information.

Implementation of this authentication method does not require Simply Voting staff involvement, and can be configured self-service by client organizations inside the Election Manager tool by navigating to the Settings page and then to the Authentication Details section.

Depending on how your organization's directory is set up, the Voting System can either:

• bind directly using the elector's Elector ID, or
• use Elector ID to search for DN (Distinguished Name), then bind using DN

Requirements for LDAP (bind using Elector ID)

• LDAP Server URL (e.g. ldap(s)://hostname:port/ )

Requirements for LDAP (use Elector ID to search for DN, then bind using DN)

• LDAP Server URL (e.g. ldap(s)://hostname:port/ )
• LDAP Base DN (e.g. o=AcmeWidgets,c=US)
• LDAP Search Key (e.g. uid, sn, etc.)
• LDAP Search Filter (e.g. objectCategory=person), an optional filtering condition which is combined with LDAP Search Key into a logical AND.

Anonymous binding can be used for search, or you may optionally provide:

• LDAP User DN (e.g. uid=Username,ou=MyUnit,o=AcmeWidgets,c=US)
• LDAP User Password

Central Authentication Service (CAS)

The Voting System can authenticate against a Central Authentication Service (CAS) protocol. Electors click a Login button on the Voting Website and enter their credentials on the organization's system, after which they are redirected back to the Voting System upon successful authentication. Passwords are not seen by the Voting System.

Implementation of this authentication method does not require Simply Voting staff involvement, and can be configured self-service by client organizations inside the Election Manager tool by navigating to the Settings page and then to the Authentication Details section.

Requirements

• Server Hostname (e.g. www.example.com)
• Server Base URI (e.g. /cas)
• Server Port (usually 443)
• CAS Logout can also be optionally configured to logout the elector from CAS upon logout from the Voting System.

HTTP(S) Authentication

The Voting System can authenticate against a URL protected by the HTTP Basic Authentication schema. Electors enter their credentials on the Voting Website, which are passed along to your system. Upon successful authentication, the elector is logged into the Voting System. Passwords are never stored on the Voting System.

Implementation of this authentication method does not require Simply Voting staff involvement, and can be configured self-service by client organizations inside the Election Manager tool by navigating to the Settings page and then to the Authentication Details section.

Requirements

• HTTP(S) Auth URL (e.g. https://example.com/members-only)

External Website Login

The Voting System can authenticate against an external website login, such as the login form of a members-only portal. Electors enter their credentials on the Voting Website, which are passed along to your system. Upon successful authentication the elector is logged into the Voting System. Passwords are never seen by the Voting System.

If your organization does not have an external website login, your IT staff could instead create a web service API for the Voting System to call.

Implementation of this authentication method does not require Simply Voting staff involvement, and can be configured self-service by client organizations inside the Election Manager tool by navigating to the Settings page and then to the Authentication Details section.

Requirements

• Login URL (e.g. https://www.example.com/login.php). This is the URL that the external website's login form will submit to.
• HTTP Method (GET or POST)
• Elector ID Parameter (e.g. username)
• Password Parameter (e.g. password)
• Static Parameters (e.g. foo=value1&bar=value2): specify any additional parameters that must be supplied along with Elector ID and Password.
• Success String (e.g. "OK"): a word or phrase that will appear on the external website after successfully logging in.

Proprietary SSO

The Voting System can authenticate against Simply Voting's proprietary Single Sign-On authentication. Electors enter their credentials through the organization's secure website login form and then click a specially programmed link displayed in the organization's secure website. When an elector clicks this link, the elector is redirected to the Voting System and automatically logged in. Passwords are never seen by the Voting System.

Implementation of this authentication method does not require Simply Voting staff involvement, and can be configured self-service by client organizations inside the Election Manager tool by navigating to the Settings page and then to the Authentication Details section, and by following the below steps in your own system.

Requirements

• Secret Text, a mutually shared secret.
• Optionally, a Sign-on URL of the login page or landing page of your secure website can be provided. This redirects unauthenticated visitors to your secure website.
• Optionally, Restricted Referrers can be provided. You may restrict SSO according to the HTTP referrer. Supply the host and as much of the path as desired to match. For example, www.example.com/members-only/ could restrict SSO to visitors following the SSO link on any page in the members-only section of a website. To allow several referrers, separate them with a semi-colon.

Single Sign-On links must be programmed by your organization. Each link contains a unique hash that corresponds to a specific elector in the Voting System.

The format of the link is as follows:

Where:

• yourvotingwebsite.simplyvoting.com is your voting website address.
• {id} is the Elector ID, both in your organization's system and in Simply Voting (e.g. jsmith, 73649, etc). This parameter must be URL encoded. To have an elector presented with a ballot, there must be an eligible elector present in the Voting System under an Active or Waiting election, and whose Elector ID matches this exact one.
• {hash} is a unique hash that represents the specific elector (see hash recipe below).

The hash generation recipe is as follows:

SHA1(Secret Text + ElectorID + Secret Text)

Where:

• SHA1 is the hashing function,
• Secret Text is a password of your choosing, and
• + means concatenate.

Example

Given the following parameters:

• Voting Website: nova.simplyvoting.com
• Secret Text: abc123
• Member ID: MTom

The elector's {hash} is generated as:

SHA1(abc123MTomabc123)

Which returns:

38c2c62f118208f2c5741014a221dde8721964a6

The resulting single sign-on URL for this elector is therefore:

https://nova.simplyvoting.com/auth.php?e=MTom&mac=38c2c62f118208f2c5741014a221dde8721964a6

Sample Implementation in PHP

<?php

$secretKey = "abc123"; 
$memberId = "MTom"; 
$hash = sha1($secretKey . $memberId . $secretKey); 
$memberIdEncoded = urlencode($memberId); // important if member IDs contain characters that are unsafe in URLs (“/,?+[]” etc.) 

echo "<a href=\"https://nova.simplyvoting.com/auth.php?e={$memberIdEncoded}&mac={$hash}\">click here to authenticate</a>"; 

?>