All the data is managed through a series of Yaml files so it may be useful to read up on the Yaml syntax.
To add or edit site, go to the data files and get familiar with how it is setup. There is a section and corresponding file for each Category. Site icons are stored in folders corresponding to each of those categories in their own folder.
- Don't break the build: We have a simple continuous integration system setup with Travis. If your pull request doesn't pass, it won't be merged. Travis will only check your changes after you submit a pull request. If you want to test locally, instructions are listed below. Keep reading!
- Use a Nice Icon: The icon must have a resolution of 32x32. PNG is the preferred format. If possible, please also run the image through an optimizing utility such as OptiPNG before committing it to the repo and keep the file to be under 2.5 kB.
- HTTPS links: All sites that support HTTPS should also be linked with an HTTPS address.
- Alexa top 200k: A new site, that is not already listed, has to be within the Alexa top 200k ranking. You can check the ranking of a site here.
- No 2FA providers: We do not list 2FA providers, such as Authy, Duo or Google Authenticator.
- Be Awesome: You need to be awesome. That is all.
It's easy to run everything locally to test it out. Either you can have plain Jekyll installed or you can use Bundler to manage everything for you.
- To install Bundler, just run
gem install bundler
. - Install dependencies in the Gemfile,
bundle install
. - Run Jekyll:
bundle exec jekyll serve --watch
. The--watch
is optional and makes Jekyll watch for file changes.
To verify that your additions are fine, you can run the entire set of tests locally which will check all links and images with:
$ bundle exec rake
However, this can take a while as there are roughly 900 links that it checks. If you just wish to test your YAML changes, you can run:
$ bundle exec rake verify
- Install Jekyll if you don't already have it:
gem install jekyll
. - Run Jekyll:
jekyll serve --watch
. The--watch
is again optional.
The following section contains rough criteria and explanations regarding what websites should be listed on dongleauth.com. If one of the following criteria is met, it belongs on dongleauth.com:
- Personal Info/Image: Any site that deals with personal info or a person's image. An example of a site with Personal Info would be their Amazon account and a site regarding Personal Image would be one like Twitter.
- Data: This criteria relates to data that is either important or sensitive. Websites detailed in criteria 1 also fit this criteria.
- Money: Any site that deals with money.
- Control: This criteria is more general, in that it includes sites that give access to things that may infringe upon criteria 1, 2, or 3. An example of this is a website that allows remote access to a device.
If you have any questions regarding whether or not a site matches one of the criteria, simply open an issue and we'll take a look.
A list for excluded sites has also been created to ensure sites that have been removed are not added in the future. The list also contains the reason for its removal.
View the complete list in the EXCLUSION.md file.
To add a new category, modify the sections
value in sections.yml
and follow the template below:
- id: category-id
title: Category Name
icon: icon-class
Then create a new file in the _data
directory with the same name as your section's
id, using the .yml
extension.
First and foremost, make sure the new site meets our definition requirements of DongleAuth.
If you are adding multiple sites to the TwoFactorAuth list, please create a new git branch for each website, and submit a separate pull request for each branch. More information regarding how to create new git branches can be found on GitHub's Help Page or DigitalOcean's Tutorial.
Adding a new website should be pretty straight-forward. The websites
array should
already be defined; simply add a new website to it as shown in the following example:
websites:
- name: Site Name
url: https://www.site.com/
img: site.png
tfa: Yes
hardware: Yes
otp: Yes
u2f: Yes
doc: <link to site TFA documentation>
The fields name:
, url:
, img:
, tfa:
are required for all entries.
Note that the original repo may use fields that we do not use.
The fields we do NOT use are: SMS
, Phone Call
, Email
, Hardware Token
, Software Token
.
Make sure to double-check that you use our required fields before you make a pull request, otherwise changes won't be displayed correctly on the site when merging a pull request. See commented out fields here..
Don't delete the fields of the original repo, though, as this makes comparisons easier.
If a site does provide TFA, it is strongly recommended that you add the doc:
field where public documentation is available. Other fields should be included
if the website supports them. Any services that are not supported can be excluded.
Sites supporting TFA should not have a twitter
, facebook
or email_address
field.
The following is an example of a website that supports TFA but not multiple dongles:
- name: YouTube
url: https://www.youtube.com/
img: youtube.png
tfa: Yes
hardware: Yes
otp: Yes
u2f: Yes
doc: http://www.google.com/intl/en-US/landing/2step/features.html
The following is an example of a website that additionally supports adding multiple dongles and passwordless authentication with FIDO2 devices:
- name: Windows Hello
url: https://www.microsoft.com/
img: windows-hello.png
tfa: Yes
hardware: Yes
otp: Yes
u2f: Yes
multipleu2f: Yes
passwordless: Yes
doc: http://www.google.com/intl/en-US/landing/2step/features.html
If a site does not provide TFA, the twitter:
field should be included if the site uses
Twitter. Facebook can also be included using the facebook
field, as well as Email using
the email_address
field. If the website does not use the English language, the lang:
field should also be included. The fields sms:
, email:
, phone:
, software:
and
hardware:
can be completely removed.
The following is an example of a website that does not support TFA:
- name: Netflix
url: https://www.netflix.com/us/
twitter: Netflixhelps
facebook: netflix
email_address: [email protected] (Only if available and monitored)
img: netflix.png
tfa: No
lang: <ISO 639-1 language code> (Only for non-English websites)
The lang:
field is only used for non-English websites. The language codes should be lowercase ISO 639-1 codes.
If a site doesn't support TFA in certain countries, you can note this on the website. There are 4 ways to customize how it is displayed:
-
A default message acknowledging restrictions will be used with the following config:
- name: Site Name url: https://www.site.com/ img: site.png tfa: Yes hardware: Yes exceptions: Yes doc: <link to site TFA documentation>
-
The message can be replaced with a custom set of words:
- name: Site Name url: https://www.site.com/ img: site.png tfa: Yes hardware: Yes exceptions: text: "Specific text goes here." doc: <link to site TFA documentation>
-
The icon can be made into a link in which more details can be revealed such as country specific info and anything else.
- name: Site Name url: https://www.site.com/ img: site.png tfa: Yes hardware: Yes exceptions: link: Yes doc: <link to site TFA documentation>
-
2 and 3 can be combined into:
- name: Site Name url: https://www.site.com/ img: site.png tfa: Yes hardware: Yes exceptions: link: Yes text: "Specific text can go here as well." doc: <link to site TFA documentation>
-
See Guideline #2 about icons. The png file should go in the corresponding
img/section
folder. -
For the sake of organization and readability, it is appreciated if you insert new sites alphabetically and that your site chunk follows the same order as the example above.
-
If a site supports TFA, their Twitter and Facebook handles as well as their email address are not needed and can be left out for cleanliness.
-
If a site does not have TFA but there is documentation that they are adding it, then use:
tfa: No status: <url to documentation>
There are many forms of Two Factor Auth, but DongleAuth.com is only interested in
listing sites that support Two Factor Authentication using USB dongles. Currently
that means the site must support either One Time Passwords (HOTP / RFC 4226 or TOTP / RFC 6238)
or FIDO Universal 2nd Factor (U2F). If a site supports multiple U2F dongles (e.g. as a backup),
multipleu2f
may be set to Yes
.
A lot of people have different ideas of what constitutes Two Factor Auth and what doesn't, so it stands to reason that we should clarify a bit. For the purposes of this site, Two Factor Auth is defined as any service provided as a redundant layer for account authentication. Services that provide authorization redundancy are certainly appreciated, but should not be considered Two Factor Authentication.
As an example, a site that prompts you for an authentication token following user login would be considered Two Factor Auth. A site that does not prompt you for a token upon login, but prompts you for a token when you try to perform a sensitive action would not be considered Two Factor Authentication.
For context, check out the discussion in issue #242.