# Documentation Homepage for [OTP Guard](https://otpguard.com) documentation. [🏁 Quickstart](/quickstart) [🎈Authenticator Types](/authenticator-types) [🖼️ Security Images](/security-images) [🎣 Phishing Resistance](/phishing-resistance) [🔐Github Security Best Practices](/github-security-best-practices) [👟Step-Up Authentication](/step-up-authentication) ### Frequently Asked Questions
What is OTP Guard? What does it do? OTP Guard is a step-up authentication system for pull requests that adds a second factor - a "step-up" - to ensure that PRs are approved only by authorized users. OTP Guard interoperates seamlessly within the Github branch protection system, ensuring that unauthorized PRs cannot be merged.
What does OTP Guard protect against if a user is already required to be logged into Github? OTP Guard is [step-up authentication](/step-up-authentication), meaning it requires a second factor at critical points in an organization's workflow - such as before merging a PR. Possessing Github session cookies alone does not imply that an authorized user is driving the action. For example, info-stealer malware can steal cookies, which would bypass any Github authentication check beyond the initial login.
Doesn't Github already have a 2FA requirement? Github does have a 2FA requirement, but it does not protect pull requests. Pull requests are the gateway to your company's codebase, and effective security requires a belt-and-suspenders approach. Moreover, Github organization admins currently cannot require a physical, phishing-resistant second factor such as a Yubikey to be associated with Github team members.
Git already has commit signing. How does OTP Guard differ? Git commit signing can be an important tool but OTP Guard covers different cases. Git commit signing is not always easy to [set up](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits), whereas getting started with OTP Guard takes only a few clicks. This makes OTP Guard suitable even for non-technical users such as content editors. OTP Guard also works well to ensure an authorized person-in-the-middle for automated PRs such as Dependabot, or open source projects where commit signatures would be impractical to enforce for all contributors.
What about Github web signatures for commits? The signing keys for these web signatures are held by Github and depend only on the presence of a logged-in user. As such, they are no more secure than Github's existing log-in security mechanisms. Github log-in security is good, but it does not cover the same areas that OTP Guard does.
If a developer is compromised enough to have their Github cookies stolen, isn't it already game over? Not with OTP Guard. A second factor, especially a physical one such as a Yubikey, can be used to authorize PRs and stop attackers in their tracks. They would not be able to approve and merge nefarious code without also accessing an OTP Guard authenticator. Malware can't push a button.
Can a hacked team member simply enroll a new authenticator with OTP Guard? The first authenticator is "free" but enrolling secondary authenticators requires a [step-up](/step-up-authentication) with an existing authenticator to unlock the enrollment. If a team member loses access to their existing authenticators, then an orgnization admin will need to remove the existing authenticators from their account in order to re-enroll. Admin-approved authenticators may also help with this. Contact us if this is a feature that you need.
What permissions does OTP Guard require? Why should I trust you with my code? Good news - you should not trust OTP Guard with your code. We don't need it, and can't see it. The Github API has a granular permissions model, and OTP Guard only requires minimal permissions. * **Read** access to [repository metadata](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-metadata). This permission is required by Github. * **Read** access to [pull requests](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-pull-requests). This includes the PR title, description, author, status, commit list and commit messages. However, this does not include the contents of the commits, or the contents of PR review messages. Your code stays with you. * **Read** access to [organization members](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#organization-permissions-for-members). This is so OTP Guard can determine which users should have what permissions, since permissions are inherited from the Github organization. * **Read and write** access to [checks](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-checks). This is how OTP Guard requires PRs to be authorized before merging.

Github check for OTP Guard

How much friction does OTP Guard introduce for developers? Validating a pull request in OTP Guard only takes seconds, and can easily be done alongside the existing PR process. The payoff is peace of mind: your developers are the ones pushing those buttons, not hackers.
*** Security requires a belt-and-suspenders approach; there is no magical wand to secure all the things. This includes best practices such as limiting access, keeping permissions up-to-date, and making sure secrets are not present in the code. See [Github Security Best Practices](/github-security-best-practices) for more tips on defense in depth. # Quickstart A step-by-step guide on how to quickly get started with OTP Guard. #### 1. [Install](https://github.com/apps/otp-guard/installations) the OTP Guard application for Github Use [this link](https://github.com/apps/otp-guard/installations/new) to install the OTP Guard application for Github. The screen should look similar to the following, but your account name and organization details may differ:
Screenshot of the OTP Guard application installer on Github, with a list of accounts to grant permissions to - either the `josh-transfix` user or the Transfix AI organization

OTP Guard installer on Github

#### 2. Grant OTP Guard access to organization repositories Access can be granted to only selected repositories, or all of them. This can be changed anytime.
Screenshot of the repository permission screen on Github for OTP Guard. This shows the permissions that OTP Guard requires (read access to organization members, PRs and repository metadata), and read/write access to PR checks.

Grant OTP Guard access to organization repositories

\ The permissions that OTP Guard requires are extremely limited**:** it can only **read** repository metadata (Github makes this permission mandatory), organizational members (so OTP Guard knows who can actually access the app), and pull requests. Note that OTP Guard can only read PR metadata (authors, PR descriptions, commit messages, etc) but not the actual code itself, nor can OTP Guard see the contents of PR reviews. OTP Guard also needs read-write access to [checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks) - the thing that gives a green and red checkmarks for PR status checks. #### 3. Make a pull request in a repository protected by OTP Guard A Github [check](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks) will be created for the PR. For the best security coverage, set up [branch protection rules](/github-security-best-practices) on Github so that the PR can't be merged until after someone review and approves it.
Screenshot of a Github status indicator for a PR in a repository which has OTP Guard installed on it.

Check request for OTP Guard

#### 4. Authorize the pull request with OTP Guard Click on the "Details" of the status check to drill down, and "Resolve" to authorize the PR on the OTP Guard website.
Drill-down on the status indicator showing how to click through to visit OTP Guard on the 'Resolve' button.

Click 'resolve' to authorize the PR with OTP Guard

#### 5. Register your first authenticator When authorizing a pull request for the first time, OTP Guard will prompt you to set up an authenticator. For more information on the types of authenticators OTP Guard support, please see [Authenticator Types](/authenticator-types) page.
Authenticator registration screen on OTP Guard. This lists the authenticators available to choose from - TOTP, platform (WebAuthN) or security key authenticators.

Registering an authenticator with OTP Guard for the first time

You will have a separate set of authenticators for every Github organization that you are a member of, so that authenticators can be managed independently by organization administrators. #### 6. Finish authorizing the pull request Once an authenticator has been registered, the PR authorization process is straightforward. For a platform authenticator or security key, simply click 'Authorize' and follow the prompts. For a TOTP, enter the six-digit code and submit.
Screenshot of the PR authorization screen in OTP Guard, for a test repository.

Authorizing a pull request with OTP Guard

# Authenticator Types Learn about the authenticators supported by OTP Guard, and clear up some of the confusing technologies and terminology in the authentication space. ## Supported Authenticators OTP Guard supports three main types of authenticators: * ![](/files/bduv593NEwF6vNw8YGkq) **TOTP** - A time-based six-digit code, typically accessed through a mobile app such as Google Authenticator * ![](/files/ItpRJKlu99apkwBdf9Jx) **Platform Authenticator** - the authenticators built into your browser such as Apple iCloud Keychain, Windows Hello, Chrome Password Manager, among others. * **Security Key** - Physical USB devices such as a [Yubikey](https://www.yubico.com/products/security-key/) ## Recommendations For the best security, we recommend **security keys**, because they typically need physical interaction - usually a tap - in order to be used. Malware can't press a button. If your organization requires biometric or PIN authentication on top of the security key, please [contact us](mailto:support@transfix.ai). Platform authenticators are a good middle ground for organizations that have not yet deployed widespread security keys. Additionally, some WebAuthN implementations such as iCloud Keychain will sync keys across all your connected devices. TOTP is the type of authenticator that would be familiar to most people. This is the most common second-factor outside of [SMS](#sms). However, TOTP is somewhat vulnerable: it can be [phished](/phishing-resistance#totp) or even stolen if the TOTP secret key is stored alongside a username and password. ## WebAuthn Under the hood, OTP Guard implements [WebAuthn](https://webauthn.guide/#about-webauthn) to support platform and security key authenticators. Most Webauthn-compliant device or integrations should work with OTP Guard as long as they are accessible via the `internal` or `usb` [transports](https://www.w3.org/TR/webauthn-2/#enum-transport) - which map to platform authenticators and security keys, respectively. Support for NFC (near-field communication) or Bluetooth Low Energy is untested and disabled for now. If you need support for NFC or BLE authenticators, please [contact us](mailto:support@transfix.ai). ## Passkeys Passkeys are a new WebAuthn-based login mechanism that is becoming more common. The term 'passkey' can cover multiple types of authenticators, and is usually used specifically in the context of logging into a website or service. Since OTP Guard does not use WebAuthn for logins, we do not describe our authenticators as 'passkeys' to minimize confusion in an already-confusing space. If this just makes things even more confusing, then we apologize. Please [let us know](mailto:support@transfix.ai) how things could be more clear. ## SMS SMS - mobile text messages - are the most common form of second factor authentication. However, SMS has shown to be insecure as a second factor, due to [SIM swapping](https://en.wikipedia.org/wiki/SIM_swap_scam) attacks. OTP Guard does not support SMS as an authentication method. ## Email E-mails are generally not considered secure as a second factor for authentication. In some cases, email can be used as a primary factor for logins, and there are ways to securely use emailed verification codes. However, email should not be relied on as an additional security factor, and OTP Guard does not support authentication via email. # Security Images What are security images, and how are they used by OTP Guard? The abstract pattern or image that is present on top of every logged-in OTP Guard page is a security image. Security images are a feature of OTP Guard to improve phishing resistance and make it easier to work with multiple organizations.

This smiling face is the security image.

All users have a personal security image for managing their personal account, and a different image for each organization they are a member of. This is meant as a visual cue to quickly identify which organization is active. Everyone in an organization will generally have a unique, personalized image, although it is not a problem if some accounts happen to have the same image. Security images are randomly selected when a user account is created, or when an organization is attached to an existing account. The [security image can be changed](#changing-security-images) to suit your preferences.\ \ Security images are a small cue that offers defense in depth - they help increase confidence you are on the correct site, and working with the correct organization. ### Changing Security Images Security images are securely and randomly selected when an account is created or an organization is first attached to an account. If the selected image is not to your taste, then we encourage you to set the security image to something pleasing and memorable. Make OTP Guard yours. \ \ For personal accounts: go to [dash.otpguard.com](https://dash.otpguard.com) and select the Security Image link under "My Account". For organization images, go to the organization page and select the "Security Image" link. If you are a member of multiple organizations, it may help to make the security images as differentiated as possible so it is easy at a glance to know which organization that you are working with at the moment.

Differentiated security images for multiple organizations.

### Security Image Confidentiality Security images are not a secret. They have a level of confidentiality similar to that of a home address. They are somewhat private in that you don't necesssarily want the world to know what it is, but not a secret that cannot be revealed.\ \ Sharing a screenshot that includes the security image with trusted parties, such as team members, is not a problem. However, **no one should ever ask for your security image**, and beware of anyone that does.\ \ If a phisher were somehow able to get ahold of your security image(s), then they could impersonate some aspects of the OTP Guard website. However, OTP Guard's other phishing-resistant features, such as passkey and security key authenticators, and tight GitHub integration, make any phish unlikely to have a large impact. ### Phishing Protection Security images offer a small degree of phishing protection. Without a valid OTP Guard session credential, phishers would not be able to generate the correct session image. This makes OTP Guard harder to impersonate, because any fake pages would not appear correct.\ \ If the security key does not appear correct, look closely at the URL in the browser - the host name should begin with `https://dash.otpguard.com` # Phishing Resistance This page describes phishing, how OTP Guard protects against certain attacks, and areas to be aware of Phishing is a type of online scam where criminals trick people into providing sensitive information like passwords, credit card numbers, or personal details. They usually do this by pretending to be a trustworthy source, like a bank, a popular website such as OTP Guard, or even someone you know. OTP Guard features multiple layers of resistance to protect yourself and your organization against phishers and other attackers. This page describes some phishing vectors to be aware of, and how OTP Guard can help guard against those. #### Github OAuth Github OAuth is the log-in mechanism for OTP Guard. The OAuth login screen itself could be impersonated as part of a phishing scam - users could be tricked into giving up their GitHub credentials, which in turn could access OTP Guard. To minimize the risks of a Github credential leak, whether through phishing or some other compromise, ensure 2FA is enabled for all Github accounts and follow [Github security best practices](/github-security-best-practices). Ideally, 2FA would be in the form of a phishing-resistant security key or passkey. When logging in with Github, always check that the URL says `github.com`.\ \ If GitHub credentials are compromised anyway, an attacker could gain access to OTP Guard. However, they would not be able to register new authenticators or authorize PRs due to the [step up authentication](/step-up-authentication) built into OTP Guard. Phishing Github is hard. Phishing both Github and OTP Guard is even harder, which substantially increases the barrier of entry for attackers.

GitHub OAuth login screen for OTP Guard

#### Security Images Phishers do not generally have access to credentials for the target site - usually that is the thing they are trying to gain. OTP Guard features [security images](#security-images) as a phishing-resistant feature. Without valid session credentials, the phisher would not be able to generate correct OTP Guard security images, and the phishing site should immediately appear suspicious.\ \ If the security image does not appear correct, look closely at the URL in the browser - the host name should begin with `https://dash.otpguard.com` #### WebAuthN Configuring OTP Guard with a WebAuthN authenticator - either a passkey or security key - makes phishing unlikely since the authenticator is tied to the `dash.otpguard.com` domain. This is enforced by the browser.\ \ Existing WebAuthN authenticators would not work on a phished site. It is possible that someone could register a new authenticator and not notice it was for a *different* site. However, they would not be signing anything of value related to OTP Guard, because they can not actually update anything within OTP Guard itself, or set anything in GitHub related to OTP Guard, such as PR checks. #### TOTP TOTP - the six-digit code displayed by apps such as Google Authenticator - are vulnerable to phishing, since the code can be relayed by the phisher to OTP Guard. However, the phisher would still need a valid OTP Guard session cookie to relay the code, which requires a Github credential compromise. # Github Security Best Practices OTP Guard protects your Github pull requests, but it is only as secure as your underlying Github practices. Learn how to best secure Github to maximize the protection OTP Guard offers. OTP Guard is defense in depth - it works best as part of a multi-layered security strategy that begins with securing Github. Github has excellent documentation for its own best practices around [accounts](https://docs.github.com/en/enterprise-cloud@latest/code-security/supply-chain-security/end-to-end-supply-chain/securing-accounts), [organization](https://docs.github.com/en/code-security/getting-started/quickstart-for-securing-your-organization) and [repositories](https://docs.github.com/en/code-security/getting-started/quickstart-for-securing-your-repository). Here are a few areas that are especially relevant to OTP Guard. 1. **Enable branch protection rules**\ OTP Guard works best if MFA authorization is a mandatory part of the pull request review process. Enable [branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule) in Github so that code cannot be merged without a PR review and passing [status checks](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) - OTP Guard takes effect as a status check.
Screenshot of a failing OTP Guard status check on Github

OTP Guard status check on Github

2. **Enforce 2FA for all members of the organization**\ While OTP Guard is designed to guard against Github account compromise, you still want to make it as hard as possible to compromise Github. See the Github page on enabling [organization 2FA](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization). 3. **Have more than one org admin**\ OTP Guard makes heavy use of [step-up authentication](/step-up-authentication) which is available to organization administrators to manage user authenticators and audit activity. If an org admin loses access to their own OTP Guard authenticators, another admin can reset those. See Github's own page for [ownership continuity](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization) in organizations. 4. **Keep user access up-to-date**\ OTP Guard user permissions follow the access control mechanisms set in Github. As users leave your organization, ensure they are off-boarded in Github promptly. Other users may change roles to require a lesser level of access; ensure that is also updated in Github as a matter of least privilege. OTP Guard will pick up on those Github access-control changes immediately without further work on the administrator's part. OTP Guard is only as secure as your Github organization. Don't let us be the only thing standing between you and hackers. # Step Up Authentication What is step-up authentication and how does OTP Guard use it? Step-up authentication is the process of requesting additional credentials before a high-risk operation, such as initiating a transaction - or in the case of OTP Guard, authorizing a Github pull request. OTP Guard is, at its core, a step-up authentication service for Github PRs. The step-up credentials are usually a second authentication factor such as a [TOTP code](/authenticator-types), but sites may sometimes ask for a password, email a special link, or similar. In addition to the core mechanic of authorizing pull requests, OTP Guard uses step-up authentication to manage additional authenticators. #### Adding and Deleting Authenticators on OTP Guard The first authenticator registered for a Github organization on OTP Guard can be done immediately. Additional authenticators after the first will require a step-up with an existing authenticator. Any existing authenticator will work for the step-up. Likewise, deleting an authenticator will require a step-up. It is recommended to always have multiple authenticators registered, of different types, in case access is lost to one.

Step-up authentication dialog when registering a new security key.

**The Cross-Device Problem: Stepping up with Platform Authenticators** Platform authenticators can be *device-bound* - meaning they exist only on the device they were created on. Device-bound authenticators present a challenge when trying to configure additional authenticators on different devices. How to step-up on a new device when the authenticator exists on another device? There are a few ways to work around this: * Use a security key authenticator which can be swapped between devices. * Use a TOTP code from a registered TOTP authenticator * (Not yet implemented) Use the QR code UI that some browsers offer (such as Chrome), for *hybrid* authentication * (Not yet implemented) Step-up on the old device, and generate an on-the-fly TOTP code that can be used on the new device **Losing access to an authenticator** If you have lost access to all your authenticators and are unable to step-up to create a new one, contact your Github organization administrator. They will have to delete all your existing authenticators, and then you can create a new one without having to step up. Note that the administrator still has to step-up with an authenticator of their own in order to delete someone else's.