AXIOS s využitím Trezoru

Tento článek popisuje, jak ve výpočtech TAS bezpečně volat externí API přes knihovnu axios a přitom použít tajné klíče uložené ve Vaultu (servisní tokeny, API klíče, hesla). Vault je dostupný od verze TAS 5.17.

Princip — proč Vault místo hardcoded klíče

Funkce vault.get('NAZEV') nevrací tajný klíč jako čitelný text, ale tzv. opaque referenci (VaultSecretRef). Tuto referenci nelze zalogovat, serializovat ani vypsat — pokus o JSON.stringify, .toString() nebo zápis do proměnné vrátí pouze [VaultSecretRef].

Předpoklady

• TAS verze 5.17 nebo vyšší,
• tajný klíč založený ve Vaultu (Administrace → Vault) pod konkrétním názvem,

Základní postup

Použití Vaultu s axiosem má vždy tři kroky:

1. Načti referenci na secret přes vault.get('NAZEV_SECRETU').
2. Vytvoř klienta přes axios.getAxios({ baseURL }).
3. Dosad' referenci do požadavku jednou z vault metod (setVaultHeader / setVaultQueryParam / requestWithVaultField).

Minimální příklad — Bearer token v hlavičce Authorization:

// 1) reference na secret z Vaultu
const tokenRef = vault.get('EXTERNAL_API_TOKEN');

// 2) klient s base URL + 3) dosazení tokenu do hlavičky
const client = axios.getAxios({ baseURL: 'https://api.partner.com/v2' })
    .setVaultHeader('Authorization', tokenRef, 'Bearer ');

// volání — token TAS dosadí interně až teď
const response = client.get('/users/42');
return response.data;

Tři způsoby dosazení secretu

Podle toho, kam API tajemství očekává, vyber odpovídající metodu.

1. Do HTTP hlavičky — setVaultHeader

Nejčastější případ: Bearer token nebo API klíč v hlavičce. Hlavička se přidá ke všem následným požadavkům daného klienta.

// setVaultHeader(nazevHlavicky, secretRef, prefix?)
const apiKeyRef = vault.get('PARTNER_API_KEY');

const client = axios.getAxios({ baseURL: 'https://api.partner.com' })
    .setVaultHeader('x-api-key', apiKeyRef);          // bez prefixu
    // nebo s prefixem: .setVaultHeader('Authorization', apiKeyRef, 'Bearer ');

const response = client.get('/protected-resource');
return response.data;

2. Do query parametru — setVaultQueryParam

Pro API, která očekávají klíč v URL (např. ?apiKey=...). Parametr se automaticky připojí ke každému požadavku klienta.

const apiKeyRef = vault.get('PUBLIC_API_KEY');

const client = axios.getAxios({ baseURL: 'https://api.example.com' })
    .setVaultQueryParam('apiKey', apiKeyRef);

// každý request automaticky obsahuje ?apiKey=<resolved-secret>
const response = client.get('/results');
return response.data;

3. Do těla požadavku — requestWithVaultField

Když API očekává tajemství přímo v těle (typicky OAuth2 client_credentials flow s client_secret). Secret se vloží do zadaného pole v data, aniž by prošel kódem.

const clientSecretRef = vault.get('OAUTH_CLIENT_SECRET');

const client = axios.getAxios({ baseURL: 'https://auth.example.com' });

// requestWithVaultField(config, [{ fieldName, ref }])
const tokens = client.requestWithVaultField(
    {
        method: 'POST',
        url: '/oauth/token',
        data: {
            grant_type: 'client_credentials',
            client_id: 'tas-service'
        }
    },
    [{ fieldName: 'client_secret', ref: clientSecretRef }]
);

return tokens.data.access_token;

Plná odpověď — requestRawWithVaultField

Pokud potřebuješ kromě dat i status, statusText nebo hlavičky odpovědi, použij raw variantu. Dostupné od v5.7.37 (raw varianty axiosu), vault pole od 5.17.

const secretRef = vault.get('SERVICE_PASSWORD');

const client = axios.getAxios({ baseURL: 'https://api.example.com' });

const raw = client.requestRawWithVaultField(
    {
        method: 'POST',
        url: '/login',
        data: { username: 'tas-service' }
    },
    [{ fieldName: 'password', ref: secretRef }]
);

if (raw.status !== 200) {
    proc.error('Login selhal', { status: raw.status });
    debug.error('Přihlášení k externí službě selhalo.');
}

return raw.data;

Kompletní příklad — OAuth2 token a navazující volání

Typický scénář: získání access tokenu přes client_secret z Vaultu a jeho použití pro autorizované volání.

// 1) reference na client secret
const clientSecretRef = vault.get('OAUTH_CLIENT_SECRET');

const auth = axios.getAxios({ baseURL: 'https://auth.service.com' });

// 2) výměna za access token (secret v těle)
const tokenResp = auth.requestWithVaultField(
    {
        method: 'POST',
        url: '/token',
        data: { grant_type: 'client_credentials', client_id: 'tas-service' }
    },
    [{ fieldName: 'client_secret', ref: clientSecretRef }]
);

const accessToken = tokenResp.data.access_token;

// 3) autorizované volání s tokenem v hlavičce
const api = axios.getAxios({ baseURL: 'https://api.service.com' })
    .setVaultHeader('Authorization', accessToken, 'Bearer ');

const me = api.get('/me');
return me.data;

Logování a ošetření chyb

Ve výpočtech TAS loguj výhradně přes proc.info / proc.warn / proc.error — nikdy console.log. Pro zablokování úkolu s chybovou hláškou použij debug.error.

const tokenRef = vault.get('EXTERNAL_API_TOKEN');
const client = axios.getAxios({ baseURL: 'https://api.example.com' })
    .setVaultHeader('Authorization', tokenRef, 'Bearer ');

try {
    const resp = client.post('/users', { email: vars['EMAIL'].getValue() });
    return resp.data;
} catch (err) {
    proc.error('Volání API selhalo', { message: err.message });
    debug.error('Nepodařilo se vytvořit uživatele v externím systému.');
}

Co nedělat

Řešení potíží