Authentication - Auk Documentation

Authentication Methods

Auk supports multiple authentication methods for Git synchronization:

SSH Keys

Most secure and convenient - no password needed

HTTPS + Token

Works everywhere, including corporate firewalls

OAuth

One-click authentication (coming soon)

Deploy Keys

Read-only or limited access for specific repositories

SSH Key Authentication

Setup SSH Keys

Generate SSH Key Pair

# Generate Ed25519 key (recommended)
ssh-keygen -t ed25519 -C "[email protected]"

# Or RSA key (if Ed25519 not supported)
ssh-keygen -t rsa -b 4096 -C "[email protected]"

When prompted:

File location: Press Enter for default (~/.ssh/id_ed25519)
Passphrase: Optional but recommended for security

Start SSH Agent

# Start the SSH agent
eval "$(ssh-agent -s)"

# Add your SSH key
ssh-add ~/.ssh/id_ed25519

For macOS, add to ~/.ssh/config:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Copy Public Key

# macOS
pbcopy < ~/.ssh/id_ed25519.pub

# Linux (requires xclip)
xclip -sel clip < ~/.ssh/id_ed25519.pub

# Windows (Git Bash)
cat ~/.ssh/id_ed25519.pub | clip

# Or just display it
cat ~/.ssh/id_ed25519.pub

Add to Git Service

Add the public key to your Git service (see platform-specific instructions below)

Platform-Specific Setup

GitHub
GitLab
Gitee
Self-Hosted

Go to github.com/settings/keys
Click “New SSH key”
Enter a title: Auk on MacBook Pro
Paste your public key
Click “Add SSH key”

Test connection:

ssh -T [email protected]
# You should see: "Hi username! You've successfully authenticated..."

Repository URL format:

[email protected]:username/repository.git

Go to gitlab.com/-/profile/keys
Paste your public key
Enter a title: Auk on MacBook Pro
Set expiration date (optional)
Click “Add key”

Test connection:

ssh -T [email protected]
# You should see: "Welcome to GitLab, @username!"

Repository URL format:

[email protected]:username/repository.git

访问 gitee.com/profile/sshkeys
点击 “添加公钥”
输入标题：Auk on MacBook Pro
粘贴公钥内容
点击 “确定”

测试连接:

ssh -T [email protected]
# 应该看到: "Hi username! You've successfully authenticated..."

仓库 URL 格式:

[email protected]:username/repository.git

For self-hosted Git servers:

Add public key to ~/.ssh/authorized_keys on server
Or use your Git server’s web interface

Test connection:

ssh -T [email protected]

Repository URL format:

[email protected]:path/to/repository.git

SSH Key Management

Multiple SSH Keys

If you have multiple Git accounts:

# ~/.ssh/config
Host github.com-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work

Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal

Use in Auk:

[email protected]:company/api-collections.git
[email protected]:username/personal-apis.git

SSH Key with Passphrase

If you set a passphrase, you’ll need to enter it when adding the key:

# Add key with passphrase
ssh-add ~/.ssh/id_ed25519

# macOS: Store passphrase in Keychain
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

HTTPS Authentication

Personal Access Token

GitHub
GitLab
Gitee

Create Token:

Go to github.com/settings/tokens
Click “Generate new token” → “Generate new token (classic)”
Enter note: Auk Git Sync
Select scopes:
- ✅ repo (Full control of private repositories)
Click “Generate token”
Copy token immediately (you won’t see it again)

Use in Auk:

https://[email protected]/username/repository.git

Or use Git credential helper:

git config --global credential.helper store

Create Token:

Go to gitlab.com/-/profile/personal_access_tokens
Enter name: Auk Git Sync
Set expiration date (optional)
Select scopes:
- ✅ read_repository
- ✅ write_repository
Click “Create personal access token”
Copy token immediately

Use in Auk:

https://oauth2:[email protected]/username/repository.git

创建令牌:

访问 gitee.com/profile/personal_access_tokens
点击 “生成新令牌”
输入描述：Auk Git 同步
选择权限：
- ✅ projects (仓库权限)
点击 “提交”
立即复制令牌

在 Auk 中使用:

https://username:[email protected]/username/repository.git

Credential Storage

Store credentials securely:

macOS
Windows
Linux

Use macOS Keychain:

git config --global credential.helper osxkeychain

First time you push/pull, enter your token as the password. macOS will store it securely.

Use Windows Credential Manager:

git config --global credential.helper wincred

Or use Git Credential Manager:

git config --global credential.helper manager

Use libsecret:

git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret

Or cache credentials temporarily:

# Cache for 1 hour
git config --global credential.helper 'cache --timeout=3600'

Deploy Keys

For read-only or repository-specific access:

GitHub Deploy Keys

Generate Deploy Key

ssh-keygen -t ed25519 -C "auk-deploy-key" -f ~/.ssh/auk_deploy_key

Add to Repository

Go to repository → Settings → Deploy keys
Click “Add deploy key”
Title: Auk Sync
Paste public key
Check “Allow write access” if needed
Click “Add key”

Configure SSH

Add to ~/.ssh/config:

Host github.com-deploy
  HostName github.com
  User git
  IdentityFile ~/.ssh/auk_deploy_key

Use in Auk

[email protected]:username/repository.git

GitLab Deploy Tokens

Create Deploy Token

Go to repository → Settings → Repository → Deploy tokens
Name: Auk Sync
Scopes:
- ✅ read_repository
- ✅ write_repository (if needed)
Click “Create deploy token”
Copy username and token

Use in Auk

https://USERNAME:[email protected]/username/repository.git

OAuth (Coming Soon)

One-click authentication with popular Git services:

GitHub OAuth - Authorize Auk to access your repositories
GitLab OAuth - Seamless integration with GitLab
Automatic Token Refresh - No manual token management

Security Best Practices

Use SSH Keys Over HTTPS

SSH keys are more secure and convenient:

No password to remember
Can’t be accidentally committed
Easier to revoke if compromised

Set Token Expiration

Always set expiration dates for access tokens:

30-90 days for active use
Shorter for testing
Rotate regularly

Use Minimal Permissions

Grant only necessary permissions:

Read-only for viewing
Write access only when needed
Avoid admin permissions

Protect Private Keys

Keep SSH private keys secure:

Never share private keys
Use passphrase protection
Store in secure location
Revoke if compromised

Use Deploy Keys for CI/CD

For automated systems:

Use deploy keys instead of personal keys
Limit to specific repositories
Read-only when possible

Troubleshooting

SSH: Permission denied (publickey)

Cause: SSH key not added or not loadedSolution:

# Check if key is loaded
ssh-add -l

# If not, add it
ssh-add ~/.ssh/id_ed25519

# Test connection
ssh -T [email protected]

HTTPS: Authentication failed

Cause: Invalid token or expired credentialsSolution:

Verify token is correct and not expired
Check token has required permissions
Clear credential cache and try again:

git credential-cache exit

Could not resolve hostname

Cause: Network or DNS issuesSolution:

Check internet connection
Verify Git service is accessible
Try using IP address instead of hostname

Next Steps

Git Sync Setup

Complete Git synchronization setup

Auto Sync

Configure automatic synchronization

Troubleshooting

Solve common Git issues

Security

Learn about security best practices

​Authentication Methods

SSH Keys

HTTPS + Token

OAuth

Deploy Keys

​SSH Key Authentication

​Setup SSH Keys

​Platform-Specific Setup

​SSH Key Management

​Multiple SSH Keys

​SSH Key with Passphrase

​HTTPS Authentication

​Personal Access Token

​Credential Storage

​Deploy Keys

​GitHub Deploy Keys

​GitLab Deploy Tokens

​OAuth (Coming Soon)

​Security Best Practices

​Troubleshooting

​Next Steps

Git Sync Setup

Auto Sync

Troubleshooting

Security

Authentication Methods

SSH Key Authentication

Setup SSH Keys

Platform-Specific Setup

SSH Key Management

Multiple SSH Keys

SSH Key with Passphrase

HTTPS Authentication

Personal Access Token

Credential Storage

Deploy Keys

GitHub Deploy Keys

GitLab Deploy Tokens

OAuth (Coming Soon)

Security Best Practices

Troubleshooting

Next Steps