Understand how Esadax enables secure and seamless authentication using third-party providers like GitHub, GitLab, Bitbucket, and the OAuth 2.0 protocol.

Table of Contents

1. Overview of Login Connections
2. GitHub Authentication
3. GitLab Authentication
4. Bitbucket Authentication
5. Understanding OAuth 2.0
6. Security Best Practices
7. Troubleshooting
8. Glossary

---

Overview of Login Connections

Esadax supports developer-friendly login options using popular version control services and industry-standard protocols:

• GitHub
• GitLab
• Bitbucket
• OAuth 2.0

These connections allow you to:

• Authenticate quickly without creating new passwords.
• Manage access through your preferred code hosting platform.
• Simplify team onboarding and permission handling.

---

GitHub Authentication

• Why GitHub?

  • GitHub is widely used in the developer community and provides reliable OAuth 2.0 support.

• Steps to Log In via GitHub:

  1. Click on the “Login with GitHub” button on the Esadax login page.
  2. You’ll be redirected to GitHub's OAuth consent screen.
  3. Grant Esadax access to your GitHub profile.
  4. You will be securely logged into Esadax.

• Scopes Used:

  • read:user
  • user:email

• Notes:

  • No write access or repository access is requested.
  • Your password is never shared with Esadax.

---

GitLab Authentication

• Steps to Log In via GitLab:

  1. Choose “Login with GitLab” from the Esadax login options.
  2. You’ll be taken to GitLab’s authentication prompt.
  3. Approve the requested scopes.
  4. You'll return to Esadax with your session authenticated.

• Supported GitLab Instances:

  • GitLab.com (public)
  • Self-hosted GitLab instances (coming soon)

• Scopes Used:

  • read_user

---

Bitbucket Authentication

• Steps to Log In via Bitbucket:

  1. Click the “Login with Bitbucket” option.
  2. Authorize the connection via Bitbucket's OAuth flow.
  3. Return to Esadax as a verified user.

• Scopes Used:

  • account
  • email

• Notes:

  • Ideal for teams using Bitbucket Cloud.
  • Bitbucket Server support is not currently available.

---

Understanding OAuth 2.0

OAuth 2.0 is the secure industry-standard protocol Esadax uses to integrate with external services.

• How It Works:

  1. The user is redirected to a provider (e.g., GitHub) to approve access.
  2. The provider issues an authorization code.
  3. Esadax exchanges this code for a short-lived access token.
  4. The token is used to fetch basic user information.

• Benefits:

  • No need to manage passwords.
  • Decentralized identity — users control access.
  • Expirable tokens reduce security risk.

---

Security Best Practices

• Token Storage:

  • Tokens are stored securely and encrypted at rest.

• Session Management:

  • Sessions are short-lived with automatic expiration.
  • Optional 2FA support for extra security.

• Minimal Permissions:

  • Only essential scopes are requested.
  • No write or repository access unless explicitly needed.

---

Troubleshooting

• Login Not Working?:

  • Ensure your third-party account is active.
  • Verify your email address with the provider.
  • Try clearing your cookies or using an incognito window.

• Account Already Linked?

  • If you previously logged in using a different method (e.g., email), go to Account Settings → Connections to link accounts.

• Access Denied Error?

  • This usually occurs if required scopes are not granted. Reattempt login and ensure all prompts are accepted.

---

Glossary

• OAuth 2.0: A protocol for delegating authorization between applications without sharing passwords.
• Scopes: Permissions requested during OAuth login to access specific data.
• Access Token: A temporary credential used to access the user’s data from the provider.
• Provider: The external service used for authentication (e.g., GitHub, GitLab).
• Consent Screen: The UI shown by the provider where users approve requested access.

---