Preskočiť na obsah

Prístupové tokeny

Sprievodca konfiguráciou GitLab prístupových tokenov pre GitPulse.

Typy tokenov

graph TB
    subgraph "GitLab Tokeny"
        PAT["Personal Access Token"]
        GAT["Group Access Token"]
        PAT2["Project Access Token"]
        OAUTH["OAuth2 Token"]
    end

    PAT --> |"Vhodný pre"| DEV["Development"]
    GAT --> |"Vhodný pre"| PROD["Production"]
    PAT2 --> |"Vhodný pre"| SINGLE["Single project"]
    OAUTH --> |"Vhodný pre"| USER["User context"]
Typ Použitie Scope Životnosť
Personal Access Token Development User-level Konfigurovateľná
Group Access Token Production Group-level Max 1 rok
Project Access Token Single project Project-level Max 1 rok
OAuth2 Token User auth User-level Short-lived

Personal Access Token

Vytvorenie

  1. Prihláste sa do GitLab
  2. Kliknite na avatar -> Preferences
  3. V ľavom menu: Access Tokens
  4. Vyplňte:
  5. Token name: GitPulse Production alebo GitPulse Development
  6. Expiration date: Max 1 rok (365 dní)
  7. Scopes: Pozri nižšie

Požadované scopes

Text Only
1
2
3
4
5
Yes api           - Full API access
Yes read_api      - Read-only API access
Yes read_user     - Read user info
Yes read_repository - Clone/fetch repositories
□ write_repository - Push (nepotrebné)

Minimum privilege

Pre produkciu používajte len minimálne potrebné oprávnenia. Pre read-only prístup stačí: read_api, read_repository.

Príklad

Bash
1
2
3
4
5
6
# Token vyzerá takto:
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

# Test tokenu
curl -H "Private-Token: ${GITLAB_TOKEN}" \
  "https://gitlab.kpi.tuke.sk/api/v4/user"

Group Access Token

Pre produkčné nasadenie odporúčame Group Access Token.

Vytvorenie

  1. Prejdite do GitLab Group (napr. /kpi/tp-2024)
  2. Settings -> Access Tokens
  3. Vyplňte:
  4. Token name: GitPulse Sync Token
  5. Expiration date: Koniec semestra
  6. Role: Reporter alebo Developer
  7. Scopes: api, read_repository

Výhody

  • Nie je viazaný na konkrétneho používateľa
  • Funguje aj keď používateľ odíde
  • Granulárnejšia kontrola scope
  • Audit log na group úrovni

Project Access Token

Pre single-project integráciu:

Bash
1
2
# Na úrovni projektu: Settings -> Access Tokens
# Vytvorte token s rolou Reporter a scope read_api

Konfigurácia v GitPulse

Environment variables

Bash
1
2
3
4
5
6
7
8
9
# .env
GITLAB_URL=https://gitlab.kpi.tuke.sk
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

# Pre viacero inštancií (advanced)
GITLAB_TOKENS='[
  {"name": "primary", "token": "glpat-xxx", "url": "https://gitlab.kpi.tuke.sk"},
  {"name": "backup", "token": "glpat-yyy", "url": "https://gitlab.example.com"}
]'

Docker secrets (produkcia)

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# docker-compose.yml
services:
  api:
    secrets:
      - gitlab_token
    environment:
      GITLAB_TOKEN_FILE: /run/secrets/gitlab_token

secrets:
  gitlab_token:
    file: ./secrets/gitlab_token.txt
Bash
1
2
3
4
# Vytvorenie secret súboru
mkdir -p secrets
echo "glpat-xxxxxxxxxxxxxxxxxxxx" > secrets/gitlab_token.txt
chmod 600 secrets/gitlab_token.txt

Rotácia tokenov

Automatická notifikácia

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Monitoring expirácie tokenu
from datetime import datetime, timedelta

def check_token_expiry(token_info: dict) -> bool:
    expiry = datetime.fromisoformat(token_info['expires_at'])
    warning_threshold = datetime.now() + timedelta(days=30)

    if expiry < warning_threshold:
        send_alert(f"Token expires in {(expiry - datetime.now()).days} days")
        return True
    return False

Manuálna rotácia

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 1. Vytvorte nový token (pozri vyššie)

# 2. Aktualizujte .env
nano .env
# Zmeňte GITLAB_TOKEN na nový

# 3. Reštartujte služby
docker compose restart api worker

# 4. Overte funkčnosť
curl http://localhost:8000/api/v1/health

# 5. Revokujte starý token v GitLab UI

Zero-downtime rotácia

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# 1. Pridajte nový token ako sekundárny
GITLAB_TOKEN_NEW=glpat-newtoken

# 2. Update konfigurácie na používanie oboch
# (aplikácia skúsi primary, potom fallback)

# 3. Prepnite na nový ako primary
GITLAB_TOKEN=${GITLAB_TOKEN_NEW}

# 4. Odstráňte starý

Troubleshooting

Token nefunguje

Bash
1
2
3
4
5
6
7
# Test základného prístupu
curl -I -H "Private-Token: ${GITLAB_TOKEN}" \
  "https://gitlab.kpi.tuke.sk/api/v4/user"

# Očakávaná odpoveď: HTTP 200
# Ak 401: Token je neplatný alebo expirovaný
# Ak 403: Nedostatočné oprávnenia

Rate limiting

Bash
1
2
3
4
5
6
7
# Kontrola rate limit headers
curl -i -H "Private-Token: ${GITLAB_TOKEN}" \
  "https://gitlab.kpi.tuke.sk/api/v4/projects" | head -20

# RateLimit-Limit: 600
# RateLimit-Remaining: 599
# RateLimit-Reset: 1699999999

Scope problémy

Bash
1
2
3
4
5
6
7
# Test read-only scope
curl -H "Private-Token: ${GITLAB_TOKEN}" \
  "https://gitlab.kpi.tuke.sk/api/v4/projects/123/repository/commits"

# Test API scope
curl -H "Private-Token: ${GITLAB_TOKEN}" \
  "https://gitlab.kpi.tuke.sk/api/v4/projects/123/issues"

Bezpečnostné odporúčania

Best practices

  1. Používajte Group/Project tokeny namiesto Personal tokenov
  2. Minimálne oprávnenia - len potrebné scopes
  3. Krátka expirácia - max 6 mesiacov pre produkciu
  4. Rotácia - pravidelná výmena tokenov
  5. Audit - monitorujte použitie tokenov

Čomu sa vyhnúť

  1. Zdieľanie tokenov medzi prostrediami
  2. Tokeny v Git repozitári
  3. Personal tokeny v produkcii
  4. Tokeny bez expirácie

Audit log

SQL
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
-- Všetky API volania s tokenom
SELECT 
    timestamp,
    endpoint,
    method,
    response_status,
    user_agent
FROM api_audit_log
WHERE token_hash = 'sha256:xxxx'
ORDER BY timestamp DESC
LIMIT 100;

Ďalšie čítanie

Vytvorené na TUKE v Košiciach ako súčasť diplomovej práce.