Hva er forskjellen på Altinn TT02 og produksjon?

Hva er TT02?

Altinns felles testmiljø: stedet der integrasjoner mot Altinn bygges og verifiseres før de møter produksjon. Det har sine egne URL-er, sine egne syntetiske testdata og sine egne testbrukere, og tjenesteeiere ruller ut appene sine der først, så flaten du integrerer mot har samme form som den du møter i produksjon, fylt med data ingen reell virksomhet eier. Det er det som gjør det trygt å feile der.

Felles er nøkkelordet. Du tester side om side med alle andre integratører, og med tjenesteeiere som verifiserer sine egne lanseringer, så behandle TT02 som et arbeidsmiljø og ikke en frossen kopi: det kan fortelle deg om mekanikken din er riktig, ikke hvordan produksjon ser ut en gitt dag. Én grense er verdt å slå fast tydelig én gang: TT02 er Altinns miljø, og det er ikke Apiers sandkasse. De to løser forskjellige problemer, og den siste seksjonen nedenfor trekker den grensen ordentlig.

Hvorfor deler ikke TT02 og produksjon klienter og nøkler?

Fordi de to miljøene kjører hver sin Maskinporten, og en klient registreres mot nøyaktig ett av dem. Registreringen skjer i selvbetjeningen i Samarbeidsportalen, per miljø: en TT02-klient og en produksjonsklient er forskjellige registreringer med forskjellige klient-id-er, selv når begge representerer samme organisasjon og samme system. Nøklene følger samme regel. Den offentlige halvdelen av hver signeringsnøkkel lastes opp i portalen for ett miljø, så et sertifikat eller en nøkkel TT02 godtar, betyr ingenting for produksjon. Hvordan selve flyten med signert assertion virker, eies av autentiseringsveiledningen.

Konfigurasjonen følger registreringen. Hvert miljø publiserer sin egen utsteder og sitt eget token-endepunkt, som er grunnen til at et live-oppsett bærer verdier som MASKINPORTEN_ISSUER og MASKINPORTEN_TOKEN_ENDPOINT som eksplisitt konfigurasjon og ikke konstanter. Den dokumenterte overgangsfeilen er den denne siden finnes for å forhindre: testverdier limt inn i en produksjonsutrulling gir en 401 uten nyttig innhold i svaret, fordi den signerte assertionen navngir en mottaker produksjonsendepunktet ikke kjenner igjen. Hva som skjer med tokenet etter utstedelse, eies av veiledningen om tokenveksling.

Hva passerer i TT02, men feiler likevel i produksjon?

Alt som avhenger av at data eller myndighet finnes på produksjonssiden. Testdataene er syntetiske, så dekningen skiller seg fra de reelle registrene, og både svartid og oppførsel kan avvike: en grønn kjøring i TT02 beviser mekanikken din, ikke produksjonsvirkeligheten. Det skarpeste gapet er myndighet. Delegeringer og godkjenninger er tildelinger inne i ett tillitsdomene, så godkjenningen en testbruker ga systemet ditt i TT02, finnes rett og slett ikke i produksjon, og hele kjeden, registrering, forespørsel og den reelle kundens godkjenning, må etableres på nytt, slik oppsettsveiledningen går gjennom steg for steg.

Det er derfor den første produksjonsfeilen etter en ren testkjøring er så forvirrende: koden er uendret, og likevel avvises kallet. Les slike avslag som miljøgap før du feilsøker noe annet, og når avslaget er en 403 eller en 500 i systembrukerkjeden, eies årsakene symptom for symptom av feilsøkingsveiledningen for systembrukere. Sjekklisten nedenfor ordner overgangen slik at hvert gap lukkes bevisst i stedet for å oppdages i produksjon.

Hvor passer Apiers sandkasse inn?

Utenfor begge banene. Apiers sandkasse er en simulert flate for å teste API-former: nøkkelløse endepunkter som svarer med produksjonsformede svar bygget av syntetiske data, så du kan prøve forespørselsformater, svarparsing og feilhåndtering uten nøkkel og uten noe Altinn-miljø av noe slag bak kallet. Den snakker ikke med TT02, den snakker ikke med produksjon, og Apier opererer ikke inne i TT02.

Den praktiske arbeidsdelingen er ryddig. Bruk sandkassen til å få integrasjonskoden riktig, for det krever ikke noe miljøoppsett i det hele tatt. Bruk TT02 når du integrerer direkte mot Altinn med egne legitimasjoner, for det er miljøet Altinn stiller til rådighet for nettopp det arbeidet. Og bruk sjekklisten over som broen mellom test og produksjon i det direkte tilfellet, for miljøskillet garanterer at ingen del av den skjer av seg selv.

Gjør det første kallet

Sandkassekallet svarer på hvem som kan opptre for et selskap, fra simulerte data, uten nøkkel og uten Altinn-miljø. TypeScript-eksempelet er overgangsvanen denne siden argumenterer for: et myndighetsoppslag som bare leser, og som beviser produksjonskjeden fra ende til ende før noe bindende får kjøre.

# Nøkkelløs sandkasse: hvem som kan opptre for et selskap, fra simulerte data.
# Ingen nøkkel, og ikke noe Altinn-miljø av noe slag bak kallet.
curl -s https://www.apier.no/api/v1/sandbox/public/company/999999999/authority

// Overgangsvanen: etter at konfigurasjonen er byttet til
// produksjonsverdier, gjør ett lesekall før noen bindende handling.
// Det beviser kjeden fra ende til ende uten å endre noe som helst.
const res = await fetch(
  "https://www.apier.no/api/v1/company/999999999/authority",
  { headers: { Authorization: `Bearer ${process.env.APIER_API_KEY}` } },
);

if (!res.ok) {
  // Alle ikke-2xx-svar bruker den samme strukturerte konvolutten.
  // En 401 her betyr at selve legitimasjonskjeden er feil: stopp og
  // rett konfigurasjonen.
  const { error_code, explanation } = await res.json();
  throw new Error(`${error_code}: ${explanation.summary}`);
}

const { data } = await res.json();
// Kun lesing: hvem som kan opptre for selskapet, og hvordan
// signaturbildet klassifiseres. Svarer dette rent, virker kjeden;
// ingenting ble sendt inn noe sted.
console.log(data.classification);

Ofte stilte spørsmål

Kan jeg gjenbruke TT02-klienten min i produksjon?

Nei. En Maskinporten-klient registreres mot ett miljø, så TT02-klienten og produksjonsklienten er to forskjellige registreringer selv når de representerer samme organisasjon og samme system. Produksjonsklienten opprettes for seg i selvbetjeningen i Samarbeidsportalen, får sin egen klient-id, og får sine egne nøkler lastet opp. Ingenting ved TT02-registreringen, verken scopene, nøklene eller historikken, følger med over i produksjonsregistreringen.

Hvorfor får jeg 401 i produksjon med konfigurasjon som virket i TT02?

Fordi de to miljøene har forskjellige verdier for utsteder og token-endepunkt, og en signert assertion bygget på testverdier navngir feil mottaker. Den dokumenterte feilformen er nettopp denne: testkonfigurasjon limt inn i en produksjonsutrulling gir en 401 uten nyttig innhold i svaret, fordi assertionens aud ikke stemmer med det produksjonsendepunktet forventer. Løsningen er konfigurasjon, ikke kode: oppdater utsteder- og endepunktverdiene sammen.

Finnes delegeringer gjort i TT02 også i produksjon?

Nei. Test og produksjon er separate tillitsdomener, og en delegering er en tildeling inne i ett av dem. En kundegodkjenning gitt av syntetiske testbrukere beviser at flyten din virker mekanisk, men produksjonssystembrukeren, produksjonsforespørselen og den reelle kundens godkjenning må alle etableres på nytt på produksjonssiden. Planlegg overgangen slik at godkjenningskjeden kjøres på nytt med den reelle organisasjonen før noe avhenger av den.

Trenger jeg TT02 i det hele tatt hvis jeg bruker Apier?

Ikke for å teste API-former. Apiers sandkasse er en egen simulert flate: nøkkelløse endepunkter som svarer med produksjonsformede svar fra syntetiske data, uten noe Altinn-miljø i det hele tatt. Det dekker forespørsels- og svarformer, feilhåndtering og integrasjonskode. TT02 forblir Altinns eget miljø, og er fortsatt relevant når du integrerer direkte mot Altinn med egne legitimasjoner. Apier opererer ikke inne i TT02, og sandkassen er ikke TT02.

Hva bør jeg verifisere først etter overgangen?

Et lesekall. Det bruker hele produksjonskjeden, klienten, nøklene og utsteder- og endepunktverdiene, uten å endre noe som helst, så en konfigurasjonsfeil dukker opp som en ren feil i stedet for inne i en bindende handling. Et myndighetsoppslag er en god kandidat, fordi et riktig svar samtidig bekrefter at du ser på reelle registerdata. Først når det kallet svarer rent, bør noe som skriver eller sender inn få kjøre.