Dokumentasie

Begin

Authagonal gee elke huurder 'n volledig standaard-voldoende OIDC-bediener. Elke huurder kry sy eie uitreiker-URL, ontdekkingsdokument en token-eindpunte — geen gedeelde infrastruktuur tussen huurders nie. Jy kan binne 5 minute van niks na 'n werkende aanmeldvloei gaan.

Skep 'n Rekening

Registreer by authagonal.io en kies 'n slug vir jou rekening. Die slug word jou issuer-domein: {slug}.authagonal.io. Bevestig jou e-posadres nadat jy jou rekening geskep het.

Kies 'n unieke slug vir jou rekening tydens registrasie

Registreer 'n Client

Gaan na Clients in die portaalsy-kieslys en klik Nuwe client. Voer 'n clientId en clientName vir jou toepassing in. Voeg dan op die client se URIs-oortjie ten minste een redirect URI by; dit is waarheen gebruikers gestuur word na verifikasie. Byvoorbeeld: https://app.example.com/callback. Nuwe clients vereis standaard 'n client secret, so skakel vir 'n blaaiertoepassing sonder 'n backend Vereis secret op die Algemeen-oortjie af.

Registreer 'n nuwe OAuth client in die portaal

Jou Eerste Aanmelding

Die vinnigste manier om te integreer is met oidc-client-ts, 'n ligte OIDC-kliëntbiblioteek vir JavaScript- en TypeScript-toepassings.

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

As jy 'n minimale benadering sonder 'n biblioteek verkies, kan jy die standaard OAuth 2.0 authorization code-vloei met gewone fetch gebruik:

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token (refresh_token only when offline_access is requested and allowed)

Die verstekbladsy vir aanmelding vir jou huurder

Paneelbord

Die portaalpaneelbord gee jou 'n intydse oorsig van jou huurder. Dit toon die maatstawwe wat die meeste saak maak — gebruikersgroei, verifikasie-aktiwiteit en vinnige navigasie na elke funksie in die portaal.

Oorsig

Bo-aan die paneelbord sal jy 'n verwelkoming sien en 'n Maak aanmeldblad oop-skakel na jou huurder se aangebode aanmelding. Onder die statistiekkaarte hou 'n Maandelikse aktiewe gebruikers-meter gebruik teen jou planlimiet dop en skakel dit na jou planopsies sodra jy verby 80% is. 'n Aanmeldaktiwiteit-grafiek en 'n Onlangse aktiwiteit-stroom van die jongste ouditinskrywings voltooi die bladsy.

Die paneelbordbladsy met statistiekkaarte en aanmeldaktiwiteit

Aktiwiteitsmaatstawwe

Ses statistiekkaarte som jou huurder in een oogopslag op:

• Aktiewe gebruikers: die totale aantal gebruikers in jou huurder
• Aanmeldings (24u): suksesvolle aanmeldings in die afgelope 24 uur
• MFA-ingeskrewe: die persentasie gebruikers met MFA geregistreer, met die ingeskrewe en totale tellings
• Mislukte pogings (24u): mislukte aanmeldings in die afgelope 24 uur, soos verkeerde geloofsbriewe, geslote rekeninge of beleidsverwerpings
• SCIM-sinchronisasie: voorsieningsaktiwiteit van gekoppelde IdP's, getoon as Ledig of as 'n aantal bewerkings
• Maandelikse besteding: besteding tot dusver hierdie maand, met 'n geprojekteerde syfer vir die einde van die maand

Die 24-uur-kaarte vergelyk die afgelope 24 uur met die 24 uur daarvoor. Die Aanmeldaktiwiteit-grafiek stip suksesvolle en mislukte aanmeldings per dag oor 14, 30 of 90 dae. Die paneelbord verfris elke minuut.

Statistiekkaarte wat die afgelope 24 uur opsom

Vinnige Navigasie

Onder die maatstawwe skakel navigasiekaarte direk na Clients, SSO, Gebruikers, SCIM, Handelsmerk, Instellings, Fakturering, Domeine en Ouditlog. Elke kaart toon 'n kort beskrywing sodat nuwe spanlede vinnig kan oriënteer.

Clients

OAuth clients verteenwoordig die toepassings wat gebruikers deur jou huurder verifieer. Elke client het sy eie konfigurasie vir redirect URI's, scopes, grant types, token-lewenstye en MFA-beleid.

Clientlys

Die Clients-bladsy toon 'n tabel van alle geregistreerde clients. Elke ry toon die clientId, vertoonname, toegelate grant types as gekleurde kentekens, en of PKCE geaktiveer is. Klik enige ry om die volledige konfigurasie-redakteur oop te maak.

Clientlys met grant type-kentekens en PKCE-aanduiders

Skep 'n Client

Klik Nuwe client om 'n nuwe toepassing te registreer. Jy moet twee velde verskaf:

• clientId — 'n unieke identifiseerder vir die client (bv. my-spa)
• clientName — 'n leesbare vertoonname

Registreer 'n nuwe OAuth client

Skrap 'n Client

Om 'n client te skrap, klik die asblik-ikoon op sy ry in die clienttabel en tik die client-ID om te bevestig. Die client word permanent verwyder en kan nie meer gebruikers aanmeld of tokens verfris nie. Access tokens wat reeds uitgereik is, word nie herroep nie en bly geldig totdat hulle verval.

Clientkonfigurasie-verwysing

Elke client het 'n omvattende stel konfigurasiekeuses wat in vyf oortjies georganiseer is: Algemeen, URIs, Scopes & Grants, Tokens en Sekuriteit.

Algemene Instellings

URI's

URI-velde gebruik 'n etiket-invoer — tik 'n waarde en druk Enter of komma om dit by te voeg. Klik die X op enige etiket om dit te verwyder.

Etiket-invoervelde vir die opstel van URI's

Scopes en Grant Types

Token-lewenstye

Stel token-lewenstye per client in

Afmelding-URI's

Clients kan beide agterkanaal- en voorkanaal-afmelding-URI's registreer. Enige of albei is opsioneel — stel op wat by hoe jou toepassing sy sessie verwyder pas.

MFA-beleid

Elke client het sy eie MFA-beleid, gestel op die client se <strong>Sekuriteit</strong>-oortjie. Die MFA-beleid-aftreklys bied drie opsies:

Per-client MFA-beleid

Enterprise SSO

Enterprise SSO laat u huurders hul eie identiteitsverskaffer bring. Authagonal ondersteun SAML 2.0 en OIDC-federasie met domeingebaseerde roering, sodat gebruikers outomaties na die korrekte IdP herlei word op grond van hul e-posadres.

Domeingebaseerde SSO-roering

SAML 2.0-verbindings

Om 'n SAML-verbinding te skep, navigeer na die SSO-bladsy en kies die SAML-oortjie. Verskaf die volgende:

Wanneer u die verbinding stoor, haal Authagonal die metadata-dokument op en voer die IdP se handtekeningsertifikaat, SSO-eindpunt-URL en naam-identifikasieformaat in. Die metadata word periodiek verfris om sertifikaatrotasies op te spoor.

Skep 'n SAML 2.0 SSO-verbinding

OIDC-verbindings

Om 'n OIDC-federasieverbinding te skep, kies die OIDC-oortjie en verskaf:

Skep 'n OIDC-federasieverbinding

Domeinroering

Domeinroering herlei gebruikers outomaties na die korrekte identiteitsverskaffer op grond van hul e-posdomein. Wanneer 'n gebruiker hul e-pos op die aanmeldingsbladsy invoer, kontroleer Authagonal of die domeingedeelte (bv. acme.com) met die allowedDomains van enige SSO-verbinding ooreenstem. As dit wel die geval is, word die gebruiker naatloos na hul organisasie se IdP herlei.

Domeinroering karteer e-posdomeins na identiteitsverskaffers

JIT-voorsiening

Wanneer 'n gebruiker vir die eerste keer via SSO aanmeld en nog nie in u huurder bestaan nie, kan Authagonal hul rekening outomaties skep (Just-In-Time-voorsiening). JIT-voorsiening is standaard af: skakel dit per verbinding aan deur Aktiveer JIT-voorsiening te merk wanneer die verbinding geskep word.

Wanneer JIT-voorsiening gedeaktiveer is, kan slegs gebruikers wat vooraf voorsien is — via SCIM, die portaal se Gebruikers-bladsy, of die API — deur dié verbinding aanmeld. Onbekende gebruikers ontvang 'n access_denied-fout en word versoek om hul administrateur te kontak.

Organisasie-omvatte Verbindings

'n Verbinding kan ook aan een organisasie binne jou huurder behoort in plaas van aan die hele huurder. Dit word eers aangebied nadat daardie organisasie reeds bepaal is: deur 'n pasgemaakte domein wat daaraan vasgepen is, 'n organization-parameter op die aanmeldskakel, of 'n client wat op daardie een organisasie geregistreer is. Dit word nooit op 'n huurderwye aanmeldbladsy getoon nie. Watter van hierdie voorrang kry, word in daardie volgorde nagegaan, die hoogste eerste.

Gebruikers

Die Gebruikers-bladsy laat u toe om alle eindgebruikers in u huurder te bestuur. U kan na gebruikers soek, hul besonderhede bekyk, nuwe gebruikers nooi en sien hoe elke gebruiker voorsien is.

Soek en bladering

Die soekbalk pas 'n presiese gebruikers-ID of e-pos, of 'n voorvoegsel van die e-pos, voornaam of van, en die filters Almal, Aktief en Inaktief vernou die lys volgens status. Soek word gedebons op 300ms sodat resultate opdateer soos u tik sonder om die API te oorweldig. Resultate is gepagineer op 50 gebruikers per bladsy; gebruik die navigasiebeheerders onderaan die tabel om tussen bladsye te beweeg.

Gebruikerstabel

Die gebruikerstabel vertoon die volgende kolomme vir elke gebruiker:

Die gebruikerslys met soekbalk en bladering

Gebruikers nooi

Klik Nooi gebruiker om iemand na u huurder te nooi. Hulle ontvang 'n e-pos om hul eie wagwoord te stel. Die vorm neem:

Nooi 'n nuwe gebruiker

Voorkeurstaal

Elke gebruiker het 'n voorkeurtaal wat hul gasheer-UI en die transaksionele e-posse wat Authagonal hulle stuur aandryf (verifikasie, wagwoordterugstelling, verwelkoming en meer). U kan dit instel wanneer u 'n gebruiker nooi en dit enige tyd van die gebruiker se besonderhede-bladsy verander. As 'n gebruiker geen voorkeurtaal het nie, val Authagonal terug op Engels. Die kieser bied alle ondersteunde tale: Engels, Chinees (Vereenvoudig), Duits, Frans, Spaans, Viëtnamees, Portugees, Japannees, Arabies, Hindi en Afrikaans.

Stel 'n gebruiker se voorkeurstaal in op die besonderhede-bladsy

Gebruikerbesonderhede

Klik enige ry in die gebruikerslys om die besonderhede-bladsy oop te maak. Van daar kan u profieldata wysig, rolle bestuur, MFA teruginstel, pasgemaakte eienskappe hersien en die gebruiker skrap.

Profiel

Wysig e-pos, voor-/van, telefoon, maatskappy, taal, eksterne ID en skakel die gebruiker se aktiewe vlag. Om die e-pos of die vlag vir bevestigde e-pos te verander, is 'n admin of eienaar nodig. E-posveranderinge moet uniek bly binne die huurder; die API gee email_already_in_use terug indien beset.

Rolle

Ken rolle wat op die Rolle-bladsy gedefinieer is toe en herroep dit. Toegewysde rolle word as die roles-eis in ID- en access tokens uitgereik wanneer die client die roles-scope versoek.

Multi-faktor-outentisering

Sien elke MFA-geloofsbrief geregistreer vir die gebruiker (outentiseerder-app (TOTP), WebAuthn/toegangssleutels en herstelkodes), elk met sy eie geregistreerde/laas-gebruikte tydstempels. Verwyder individuele geloofsbriewe, of stel alle MFA terug; albei vereis 'n admin of eienaar. Terugstelling dwing die gebruiker om by die volgende aanmelding opnuut te registreer.

Pasgemaakte eienskappe

Willekeurige sleutel/waarde-data geheg aan die gebruiker. Sleutels moet uniek wees. Eienskappe word blootgestel via die gebruikersprofiel-API en SCIM, en kan na access-token-eise gekarteer word deur 'n pasgemaakte scope se userClaims te konfigureer.

Organisasie

Die organisasie waaraan hierdie gebruiker behoort. Dit is 'n vryteks-identifiseerder van u eie, uitgereik as die org_id-eis op hul tokens en op /connect/userinfo onder die profile-scope. Authagonal lei dit nooit self af nie: dit word deur u voorsieningstoepassing gestel, deur die SCIM-geloofsbrief wat die gebruiker geskep het, of hier met die hand.

Die skakel langs die veld lys almal wat dit deel, en dieselfde filter is op die API beskikbaar as GET /api/v1/users?organizationId=. Gebruik dit om te bepaal wie aan 'n gegewe klant behoort sonder om deur die hele gids te blaai.

Skrap gebruiker

Verwyder die gebruiker en al hul MFA-geloofsbriewe permanent. Tik die gebruiker se e-pos om te bevestig — dit kan nie ongedaan gemaak word nie.

Groepe

Groepe laat u toe om gebruikers te organiseer en groeplidmaatskap in tokens in te sluit. Groepe kan handmatig in die portaal geskep word of outomaties via SCIM uit 'n eksterne identiteitsverskaffer voorsien word.

Groeplys

Groepe word gelys op die Groepe-oortjie van die SCIM-bladsy, met die volgende inligting:

Groeplys met bronindikators

'n Groep skep

Klik Nuwe Groep en voer 'n Vertoonaam vir die groep in. Groepname moet beskrywend en uniek wees binne u huurder (bv. "Engineering", "Billing Admins", "Beta Testers").

Groepbesonderhede en lede

Klik enige groep om die besonderhede-aansig oop te maak. Hier kan u alle huidige lede sien en lidmaatskap bestuur:

• Voeg lede by: soek 'n gebruiker op e-pos of naam en voeg hulle by die groep.
• Verwyder lede: klik die verwyderknoppie langs enige lid en bevestig. Enige rolle wat deur die groep toegeken is, word herroep.

Bestuur groeplidmaatskap in die besonderhede-aansig

Groepe in tokens

Wanneer Groepe in Tokens op 'n client geaktiveer is en die groups-scope versoek word, sluit uitgereikte tokens 'n groups-eis in wat die vertoonname van die gebruiker se groepe lys:

{
  "sub": "user-123",
  "email": "[email protected]",
  "groups": ["Engineering", "Beta Testers"]
}

Rolle

Rolle ondersteun rolgebaseerde toegangsbeheer (RBAC) in u toepassing. Definieer rolle in Authagonal, wys dit aan gebruikers toe en gebruik die roles-eis in tokens om magtiging in u toepassingslogika af te dwing.

Rolle bestuur

Die Rolle-bladsy vertoon 'n tabel van alle gedefinieerde rolle met inlyn-redigering. Elke rol het:

'n Rol skep

Klik Nuwe Rol en verskaf 'n naam en beskrywing. Rolname moet bondig wees en 'n konsekwente naamkonvensie in u toepassing volg (bv. kleinletters met koppeltekens: billing-admin).

Inlyn-redigering

Rolle ondersteun inlyn-redigering direk in die tabel. Klik die potloodikoon op enige rol om wysigingsmodus te betree — die naam- en beskrywingsvelde word redigeerbaar. Verander die waardes en klik dan die regmerkikoon om te stoor. Veranderinge tree onmiddellik in werking.

'n Rol skrap

Klik die skrapikoon op enige rol om dit te verwyder. U sal gevra word om te bevestig voordat die rol permanent geskrap word. Die verwyder van 'n rol maak bestaande tokens nie terugwerkend ongeldig nie — die rol sal afwesig wees van nuwe tokens wat na skrapping uitgereik word.

Inlyn-redigering van rolle in die rollentabel

Rolle in tokens

Rolle wat aan 'n gebruiker toegewys is, word as 'n roles-eis in ID- en access tokens ingesluit wanneer die client die roles-scope versoek. U toepassing kan hierdie eis lees om magtigingsbesluite te neem:

{
  "sub": "user-123",
  "email": "[email protected]",
  "roles": ["admin", "billing-admin"]
}

SCIM-voorsiening

SCIM 2.0 (System for Cross-domain Identity Management) maak outomatiese gebruiker- en groepinrigting moontlik vanaf ondernemingsidentiteitsverskaffers soos Okta, Azure AD, OneLogin en JumpCloud. Wanneer dit opgestel is, word gebruikersrekeninge en groeplidmaatskappe outomaties gesinkroniseer vanaf die stroomop-IdP na jou Authagonal-huurder.

SCIM-gebruikerslewensiklus-sinkronisasie met stroomaf-inrigting

Opstelstappe

Volg hierdie stappe om SCIM-inrigting vir 'n client te aktiveer:

1. Kies die client-toepassing — Kies die OAuth-client waaraan SCIM-inrigting gekoppel sal word.
2. Genereer 'n SCIM-token — Verskaf 'n beskrywing en 'n verstryktermyn in dae, en genereer dan die token.
3. Kopieer die token onmiddellik — Die rou token-waarde word slegs een keer vertoon. Kopieer dit voor jy die dialoog sluit.
4. Stel jou IdP op — In jou identiteitsverskaffer se SCIM-instellings, voer die basis-URL en bearer token in.
5. Toets gebruikersinkronisasie — Aktiveer 'n toetssinkronisasie vanuit jou IdP en verifieer dat gebruikers in die Authagonal-portaal verskyn.

SCIM-basis-URL

Stel jou identiteitsverskaffer op met die volgende basis-URL:

https://{slug}.authagonal.io/scim/v2

Vervang {slug} met jou huurder se slug.

SCIM-opstelbladsy met tokengenerering

Tokenbestuur

SCIM-tokens verifieer inrigtingversoeke vanaf jou IdP. Jy kan meerdere tokens per client bestuur:

Om 'n token te herroep, klik die Herroep-knoppie langs dit. Herroepte tokens bly in die lys sigbaar vir ouditeringsdoeleindes, maar stop onmiddellik om versoeke te aanvaar.

Tokenbestuur met aktiewe en herroepte tokenaanduidings

Konnektiwiteit Toets

Verifieer dat jou SCIM-integrasie werk deur die ServiceProviderConfig-endpoint te bevraagteken:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

'n Suksesvolle respons gee 'n JSON-dokument terug wat die ondersteunde SCIM-funksies beskryf: PATCH en filtrering word ondersteun, terwyl massaoperasies, wagwoordwysigings, sortering en ETags nie ondersteun word nie.

Wat 'n geloofsbrief kan sien

'n SCIM-geloofsbrief sien slegs die gebruikers en groepe wat dit voorsien het. Om 'n gebruiker wat 'n ander konnektor geskep het te lees, op te dateer of te skrap antwoord 404, 'n lys gee slegs sy eie terug, en 'n groep se lidmaatskap mag slegs gebruikers noem wat dieselfde konnektor voorsien het. Rekeninge wat op enige ander manier geskep is, deur 'n administrateur, deur selfdiens-registrasie of deur SSO se net-betyds-voorsiening, is heeltemal onsigbaar vir SCIM.

Daardie grens is per client, nie per token nie. Twee geloofsbriewe wat teen dieselfde client uitgereik is, is een identiteit met twee geheime, en elkeen kan wysig wat die ander geskep het. Gee wedersyds onvertroude konnektors elk 'n eie client. externalId word op dieselfde manier begrens, dus mag twee konnektors elk ext-001 vir verskillende mense gebruik sonder om te bots.

Ontvoorsiening

DELETE /scim/v2/Users/{id} deaktiveer die rekening en merk dit as geskrap. Die rekord word behou, soos RFC 7644 toelaat, maar dit antwoord 404 op elke daaropvolgende operasie en word uit lyste weggelaat. Hul MFA-registrasies en groeplidmaatskappe word uitgevee, hul externalId-kartering word vrygestel, en enige uitgereikte tokens word herroep, sodat toegang onmiddellik eindig eerder as by die volgende token se verstryking.

As dieselfde persoon later weer aangestel en herskep word, kry hulle 'n nuwe gebruiker-ID. Identifiseerders word nooit hergebruik nie: die ID is die subject in elke token wat jy nog ooit uitgereik het, dus sou hergebruik daarvan die nuwe werknemer stilweg die vorige houer se geskiedenis gee by elke toepassing wat dit vertrou.

Gesinkroniseerde gebruikers met 'n organisasie merk

SCIM bied geen manier vir 'n konnektor om te sê watter van jou klante dit sinkroniseer nie. Kern-SCIM definieer geen organisasie-attribuut nie, dus vertel 'n gewone gebruikerskepping jou die persoon se naam en e-pos en niks oor aan wie hulle behoort nie. As verskeie klante in jou huurder in voorsien, kom hul gebruikers ononderskeibaar aan.

Die geloofsbrief antwoord dit in plaas van die versoek. Wanneer jy 'n SCIM-token skep, kies een van jou huurder se organisasies onder Organisasie (die kieser verskyn sodra jou huurder organisasies het). Elke gebruiker wat deur daardie token voorsien word, word 'n aktiewe lid van daardie organisasie en dra dit van dan af as die org_id-eis op hul tokens. Reik een geloofsbrief per klant uit teen dieselfde client, en hul gesinkroniseerde gebruikers kom korrek toegeskryf uit sonder 'n client-registrasie elk. Laat dit leeg en gebruikers bly ongemerk.

Die merker word toegepas wanneer die gebruiker geskep word en nooit by 'n latere opdatering nie, dus kan 'n roetine inkrementele sinkronisasie nie stilweg 'n bestaande rekening skuif nie. As jy ook 'n voorsieningstoepassing gebruik, wen 'n uitdruklike geloofsbrief-merker: 'n /try-respons vul slegs 'n organisasie wat nog leeg is.

Ondersteunde skemas

Ons implementeer die kern-SCIM 2.0 User- en Group-skemas (RFC 7643). Ondersteunde gebruiker-attribute is userName, name.givenName, name.familyName, displayName, emails, active, externalId en preferredLanguage / locale.

Die enterprise user-uitbreiding is nie geïmplementeer nie, dus word department, manager, employeeNumber, costCenter, division en organization aanvaar en geïgnoreer eerder as gestoor, by skep, vervang en PATCH gelyk. Entra en Okta karteer albei sommige hiervan by verstek, dus hoef jy hulle nie uit jou attribuutkartering te verwyder nie. Om 'n gebruiker aan een van jou klante toe te skryf, stel eerder die organisasie op die SCIM-geloofsbrief: die enterprise organization-attribuut word deur jou klant se identiteitsverskaffer beweer, en word doelbewus nie hul org_id nie.

OAuth Scopes

Scopes laat clients toe om spesifieke dele van 'n gebruiker se data of toestemmings te versoek. Authagonal ondersteun beide standaard OIDC-scopes en pasgemaakte scopes wat jy vir jou API's definieer.

Ingeboude Scopes

Pasgemaakte Scopes

Definieer jou eie scopes op die Scopes-bladsy. Elke scope beskryf 'n toestemming of hulpbron wat 'n client kan versoek (byvoorbeeld billing.read, orders.write).

Pasgemaakte eise op tokens

Pasgemaakte eise het twee helftes. Die bron is per-gebruiker-data: elke AuthUser het 'n customAttributes-woordeboek wat jy kan bevolk vanaf die Portaal (Gebruikers → gebruiker → Pasgemaakte Attribute), via SCIM, of via 'n TCC-inrigtinghaak. Die vrystelling is per-scope: elke scope se userClaims-lys noem die sleutels wat dit toelaat om die bediener te verlaat.

Wanneer 'n client scopes versoek, deurstap Authagonal die toegestane scopes, voeg hul userClaims-lyste saam, en stuur slegs die sleutels van die gebruiker se customAttributes uit. Onbekende sleutels word stilweg gedroppeer — 'n client kan nie 'n attribuut lees deur die naam te raai nie. Standaard OIDC-eise (sub, email, name, ens.) volg die spesifikasie en is nie onderhewig aan die witlys nie.

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted; it's not in the whitelist for any granted scope.
}

Scopes aan Clients Toewys

Voeg toegelate scopes by op die Clients → Scopes & Grants-oortjie. 'n Client kan slegs scopes versoek wat toegestaan is; onbekende scopes word verwerp met invalid_scope.

Handelsmerk

Pas die voorkoms van jou huurder se aanmeldbladsye aan. Handelsmerk-instellings laat jou toe om die verifikasie-ervaring op jou produk se visuele identiteit te stem — van logos en kleure tot gevorderde CSS-oorskrywings.

Voorkoms

Voorkoms-instellings met regstreekse kleurvoorskou

Kontakinligting

Aanmeldbladsywisselaars

Beheer watter elemente op jou huurder se aanmeldbladsy verskyn:

Voorbeeld aanmeldbladsy met pasgemaakte handelsmerk toegepas

Pasgemaakte CSS

Vir volle beheer oor die aanmeldbladsyvoorkoms, verskaf 'n CSS-lêer-URL in jou handelsmerk-instellings. Die lêer word na die verstekstyle gelaai, sodat jou reëls voorrang het. Die URL moet op dieselfde oorsprong as die aanmeldbladsy wees; stylblaaie van ander oorspronge word nie gelaai nie.

Donkermodus

Die aanmeldtoepassing word gestuur met lig-, donker- en stelseltemas. Die Donker Modus-instelling op die Handelsmerk-bladsy kies die verstek: af, outo (volg die stelselvoorkeur, die verstek) of forseer. Gebruikers kan steeds vanuit 'n wisselaar op die aanmeldbladsy kies; die keuse bly behoue oor sessies. Wanneer op system gestel, volg die SPA prefers-color-scheme regstreeks.

Ligwaardes word verklaar by :root; donker-oorskrywings is begrens na .dark. Huurder-handelsmerk ingestel via customCssUrl wen altyd — sodat jou kleure behoue bly ongeag die gebruiker se tema.

Instellings

Stel huurder-wye sekuriteitsbeleide, webhooks en omgewingsinstellings in. Hierdie instellings geld globaal vir alle clients, tensy op client-vlak oorskryf.

Wagwoordbeleid

Definieer die wagwoordkompleksiteitsvereistes vir alle gebruikers in jou huurder, onder Gebruikers → Instellings:

Wagwoordbeleid-konfigurasie

MFA-beleid

Die huurder-wye MFA-beleid, gestel onder Gebruikers → Instellings, stel die standaard multi-faktor-stawingsgedrag. Individuele clients kan hierdie instelling oorskryf.

Sessie en Uitsluit

Beheer sessieduur en rekeninguitsluitgedrag:

Sessie- en uitsluit-konfigurasie

Webhooks

Webhooks laat jou in reële tyd op stawingsgebeure reageer. Twee gebeure (onUserAuthenticated, onTokenIssued) is afdwingbaar — by verstek vuur hulle asinchronies en blokkeer nie die gebruiker nie, maar jy kan afdwinging per geleentheid aktiveer sodat 'n nie-2xx-respons of {"allow": false}-liggaam die aksie verwerp. Die oorblywende gebeure is kennisgewings — altyd brand-en-vergeet, blokkeer nooit.

Bykomende webhook-instellings:

Webhook-geleentheid-konfigurasie

Webhooks verifieer

Sodra enige webhook-URL opgestel is, munt Authagonal 'n per-huurder ondertekeninggeheim ('n whsec_… waarde wat slegs-leesbaar onder Instellings → Webhooks gewys word). Elke uitgaande aflewering dra 'n X-Authagonal-Signature: t=<unix>,v1=<hex>-opskrif, waar v1 HMAC-SHA256(secret, "{t}.{body}") is, bereken oor die rou versoekliggaam. Herbereken dit op jou eindpunt en vergelyk met konstante tyd om te bevestig die versoek het werklik van Authagonal gekom en nie gemanipuleer is nie — en verwerp afleveringe waarvan die t te oud is om herspeling te blokkeer.

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent: verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Onderhoudvenster

Stel 'n voorkeur-onderhoudvenster in vir ontwrigtende bewerkings soos die skuif van jou huurder se data tussen berging-shards. Kies 'n UTC-uur (0–23); die portaal wys ook die ekwivalente tyd in jou plaaslike tydsone vir gemak.

Registrasie en toegang

Wie toegelaat word om 'n gebruiker in jou huurder te word, en onder watter voorwaardes hulle kan aanmeld.

Bewaring van onaktiewe gebruikers

Deaktiveer opsioneel, en skrap dan, rekeninge wat ongebruik geraak het, sodat 'n gebruikersgids nie vir ewig slapende identiteite opgaar nie. Albei is af tensy jy hulle stel, en skrapping is permanent.

Oudit-uitvoer en afgeleë rugsteun

Twee maniere om jou data volgens 'n skedule uit te kry eerder as op versoek. Oudit-uitvoer stoot elke voltooide dag se ouditgebeure na 'n URL wat jy aanwys, onderteken sodat jy kan verifieer dat dit van ons af gekom het, om 'n SIEM of 'n nakomingsargief te voed. Afgeleë rugsteun stuur kopieë van jou daaglikse en weeklikse rugsteun na 'n bestemming wat jy beheer, met geen stawing, met basiese stawing, of met 'n bearer token. Oudit-uitvoer word op die Ouditlog-bladsy se Uitvoer-oortjie opgestel en afgeleë rugsteun op die Rugsteune-bladsy; albei is joune om te hou, onafhanklik van die rugsteun wat ons hou.

Sandput-omgewings

Die Omgewings-bladsy bestuur sandput-omgewings: benoemde, geïsoleerde omgewings met hul eie gebruikers, clients, ondertekeningsleutels, MFA-inskrywings en grants, elk bereikbaar by 'n aparte URL. Handelsmerk, plan en fakturering word met live gedeel. Gebruik hulle om konfigurasiewysigings, SSO-integrasies en webhook-eindpunte te toets sonder om aktiewe gebruikers te beïnvloed. Jy kan standaard tot 5 skep, en aktiewe sandput-gebruikers tel by jou MAU.

Elke omgewing is bereikbaar by {name}-{slug}.authagonal.io.

Sandput-omgewingbeheer

Fakturering

Bestuur jou intekening en fakturering deur die portaal se Faktureringsbladsy. Hierdie bladsy gee jou 'n oorsig van jou huidige plan en bied toegang tot die Stripe-faktureringportaal vir die bestuur van betaalmetodes, fakture en planveranderings.

Intekenginligting

Die faktureringsbladsy toon jou huidige intekenbonderhede in 'n oogopslag. Jy sal 'n statuskenteken sien wat jou intekenstatus aandui — active, trialing, past_due, canceled of unpaid — saam met jou plannaam, die huidige faktureringstydperk (begin- en einddatums), en of jou intekening ingestel is om aan die einde van die huidige tydperk te kanselleer.

Bestuur Intekening

Klik die Bestuur Intekening-knoppie om die Stripe-faktureringportaal in 'n nuwe venster oop te maak. Van daar kan jy jou betaalmetodes werk by, fakture bekyk en aflaai, jou plan verander of jou intekening kanselleer.

As daar nog geen intekening bestaan nie, word 'n Stel Fakturering Op-aksie-oproep vertoon, wat jou deur die keuse van 'n plan en die invul van betalingsbesonderhede lei.

Die faktureringsbladsy toon jou huidige intekenbonderhede en bied toegang tot Stripe

Persoonlike Domeine

Bedien jou verifikasiebladsye vanaf jou eie domein (bv. auth.yourdomain.com) in plaas van die verstek {slug}.authagonal.io. Persoonlike domeine gee jou gebruikers 'n naatlose, handelsmerk-verifikasie-ervaring.

Voeg 'n Domein By

Voer die gasheernaam in wat jy wil gebruik in die domein-byvoegvorm (bv. auth.yourdomain.com). Sodra dit bygevoeg is, sal die domein in jou domeinlys verskyn met 'n pending_verification-status.

DNS-verifikasie

Skep die twee CNAME-rekords wat die portaal vir die domein wys, albei wat na {slug}.authagonal.io wys: een by die gasheernaam self, wat verkeer bedien en geproksie mag word, en een by _authagonal-challenge. gevolg deur die gasheernaam, wat eienaarskap bewys en slegs-DNS moet wees (nie geproksie nie). Sodra die rekords in plek is, klik Kontroleer DNS om te verifieer. Hangende domeine word ook outomaties weer nagegaan.

auth.yourdomain.com.                        CNAME  acme.authagonal.io.
_authagonal-challenge.auth.yourdomain.com.  CNAME  acme.authagonal.io.

TLS-sertifikate

Sodra jou domein geverifieer is, benodig jy 'n TLS-sertifikaat sodat gebruikers veilig via HTTPS kan koppel. Authagonal ondersteun twee opsies:

Outomaties (cert-manager) — Authagonal stel TLS-sertifikate outomaties in en hernu dit deur cert-manager. Dit is die aanbevole opsie vir die meeste gebruikers. Geen verdere konfigurasie is nodig nie.

Bring Jou Eie (BYO) — Laai jou eie sertifikaat en private sleutel in PEM-formaat op. Hierdie opsie is nuttig as jou organisasie sertifikate van 'n spesifieke sertifikaatowerheid vereis. Sertifikaatverval word nagespoor sodat jy voor die verloping kan hernu.

Domeinstatus

Elke domein toon 'n statuskenteken wat sy huidige toestand aandui: pending_verification (DNS nog nie bevestig nie), verified (DNS bevestig, TLS hangende), of active (volledig operasioneel).

Die domeinlys toon elke persoonlike domein en sy huidige status

Laai jou eie TLS-sertifikaat en private sleutel in PEM-formaat op

Organisasies

'n Organisasie is 'n kliënt binne 'n huurder. Die huurder bly die isolasiegrens: een tabelvoorvoegsel en een handtekeningsleutel, met elke gasheer van die huurder as sy eie issuer. 'n Organisasie verdeel identiteit binne die huurder, sodat een huurder baie kliëntorganisasies kan bedien sonder 'n huurder per kliënt.

Organisasies staan langs pasgemaakte domeine (een domein kan aan 'n organisasie vasgepen word) en voorsieningsapps ('n voorsieningsapp kan 'n nuwe gebruiker met 'n organisasie merk). Sien die Multi-kliëntetoepassings-gids vir die volledige "een huurder, baie gebrandmerkte kliënte"-patroon waarvoor hierdie funksie bestaan.

Model en ids

Elke organisasie het 'n stabiele, onveranderlike id (in die vorm org_<32 hex>) wat as die org_id-token-claim uitgereik word, en 'n onveranderlike, huurder-unieke slug wat as org_slug uitgereik word en deur die organization-authorize-parameter aanvaar word. Ids en slugs deel een opsoekruimte: 'n slug wat gelyk is aan 'n ander organisasie se id word as 'n botsing geweier, presies soos 'n gewone duplikaat-slug.

Lidmaatskappe

'n Lidmaatskap is die baie-tot-baie-koppeling tussen 'n gebruiker en 'n organisasie, een ry per (organisasie, gebruiker)-paar. 'n Gebruiker kan baie hê. Die lidmaatskapry, nie die ou per-gebruiker-organisasiemerker nie, magtig aanmelding as 'n organisasie.

'n Lidmaatskap se roles word uit die huurder se bestaande rolkatalogus geneem en met die roles-claim verenig, maar slegs wanneer die organisasie uitdruklik gekies is deur die versoek (sien Token-organisasiekeuse) en slegs uit 'n aktiewe lidmaatskapry. 'n Rol wat in een organisasie gehou word, bereik nooit 'n token wat vir 'n ander uitgereik is nie.

Uitnooi in 'n organisasie

POST /api/v1/users/invite aanvaar 'n opsionele organizationId en organizationRoles. Een oproep skep die rekening met 'n invited-lidmaatskap en stuur 'n uitnodigings-e-pos met die organisasie se handelsmerk. Die skakel maak oop op die organisasie se vasgepende pasgemaakte domein as dit een het. Wanneer die persoon aanvaar, word die lidmaatskap active. Om 'n organisasie te noem vereis 'n eienaar of admin.

SCIM-voorsiening in 'n organisasie

'n SCIM-token kan aan 'n organisasie gebind word (organizationId op POST /api/v1/scim/tokens, of die Organisasie-kieser wanneer 'n token geskep word). Die id moet 'n organisasie van die huurder noem. Elke gebruiker wat daardie token skep, word 'n active-lid en dra die organisasie as org_id. Die binding geld slegs by skepping, en dit bepaal lidmaatskap, nie toegang nie: twee tokens op een client sien steeds mekaar se gebruikers. Wanneer 'n gebruiker op enige manier uitgevee word, word hul lidmaatskappe verwyder.

Beleidsvlaggies

enabled (verstek aan): 'n gedeaktiveerde organisasie reik geen tokens vir homself uit nie, nagegaan by authorize en by elke refresh, sodat deaktivering lewendige sessies by hul volgende rotasie stop eerder as om net nuwe aanmeldings te blokkeer.

requireMembershipForTokens (verstek aan): of 'n gebruiker 'n aktiewe lidmaatskap moet hê om 'n token vir hierdie organisasie te kry. Dit geld net vir 'n uitdruklike keuse ('n versoek wat die organisasie noem, 'n refresh wat dit dra, 'n organisasie-omvatte verbinding, of 'n client wat tot presies een beperk is). 'n Organisasie wat bloot van die rekening se eie ou merker oorgeërf is, word nooit deur hierdie vlag beheer nie.

allowAutoMembership (verstek af) laat 'n gebruiker sonder 'n uitnodiging aansluit wanneer hul bevestigde e-posadres op een van die organisasie se geverifieerde domeine is. Dit word by authorize en by elke refresh afgedwing. Sien E-posdomeine en outomatiese lidmaatskap hieronder.

E-posdomeine en outomatiese lidmaatskap

'n Organisasie eis 'n e-posdomein op en bewys dat dit dit beheer met 'n DNS TXT-rekord. Met allowAutoMembership aan, word 'n gebruiker wie se bevestigde e-posadres op daardie domein is 'n lid die eerste keer wat hulle as die organisasie aanmeld.

1. Eis dit op. POST /api/v1/organizations/{id}/domains met die domein. Die antwoord is 201 met recordName (_authagonal-org.acme.com) en recordValue (authagonal-org-verify=<token>). Die token is ewekansig en per eis.
2. Publiseer die rekord. Voeg 'n TXT-rekord met daardie naam en presiese waarde by die domein se DNS by.
3. Verifieer dit. POST /api/v1/organizations/{id}/domains/{domain}/verify soek die rekord op. 'n Passing gee 200 met verified: true. 'n Mis gee 409 verification_failed, nooit 200 met verified: false nie, sodat 'n client wat op sukses poll nie 'n mis vir sukses kan aansien nie.
4. Verwyder dit. DELETE /api/v1/organizations/{id}/domains/{domain} gee 204. Bestaande lidmaatskappe bly; slegs toekomstige outomatiese aansluitings hou op.

POST /api/v1/organizations/org_7fa2c9e1.../domains
Content-Type: application/json

{ "domain": "acme.com" }

201 Created
{
  "domain": "acme.com",
  "verified": false,
  "verifiedAt": null,
  "createdAt": "2026-10-03T01:02:03Z",
  "recordName": "_authagonal-org.acme.com",
  "recordValue": "authagonal-org-verify=Qm9...base64url"
}

Weierings: 400 domain_invalid (nie 'n kaal DNS-naam nie), 409 domain_exists (reeds op hierdie organisasie), 409 domain_taken (nog 'n organisasie in die huurder hou dit), 404 organization_not_found en 404 domain_not_found. 'n Domein behoort aan hoogstens een organisasie per huurder, en dit word by verifikasie weer nagegaan.

Die outomatiese lidmaatskapreël

Die kieser laat 'n gebruiker toe wat geen aktiewe lidmaatskap het nie wanneer al hierdie geld:

• Die organisasie is uitdruklik gekies: 'n meegedraagde refresh-grant, 'n organisasie-omvatte verbinding, die organization-parameter ('n domeinpen verskaf dit), of 'n client wat tot presies een organisasie beperk is. Die rekening se eie ou merker sluit nooit outomaties aan nie.
• Die organisasie is geaktiveer en allowAutoMembership is aan.
• Die gebruiker se e-pos is bevestig, want enigiemand kan as [email protected] registreer.
• Die deel van die e-pos na die laaste @, in kleinletters, is presies gelyk aan een van die organisasie se domeine wat geverifieer is. Daar is geen subdomeinpassing nie: 'n geverifieerde acme.com laat nie [email protected] toe nie. Eis en verifieer elke subdomein afsonderlik.

Wat dit skryf, voordat die lidmaatskaphek loop: geen ry word 'n nuwe active-lidmaatskap sonder rolle; 'n invited-ry word tot active bevorder met sy rolle behou; 'n active-ry word met rus gelaat; 'n suspended-ry word nooit bevorder nie.

Token-organisasiekeuse

Watter organisasie 'n versoek oplos, word op presies een plek bepaal, so die antwoord is identies by /connect/authorize, by elke refresh, en op die device grant. Voorrang, die hoogste eerste:

Domeinpen

'n Pasgemaakte domein kan aan een organisasie vasgepen word, wat daardie domein die organisasie se eie voordeur maak. Die pen word deur die huurder-oplossing-middleware afgedwing vir beide GET /connect/authorize (by die navraagstring gevoeg) en POST /connect/par (die gestoote liggaam word herskryf, aangesien PAR sy parameters uit die gestoorde loonvrag lees). Sien Pasgemaakte Domeine vir die volledige meganisme.

PUT /api/v1/custom-domains/auth.acme.com/organization
Content-Type: application/json

{ "organizationId": "org_7fa2c9e1..." }

Organisasie-omvatte verbindings

'n SAML- of OIDC-verbinding kan aan een organisasie behoort. Aanmelding daardeur kies daardie organisasie en skep 'n active-lidmaatskap wanneer die gebruiker geen het nie. 'n invited-ry word aanvaar: dit word active en behou sy rolle en uitnooier, sodat 'n genooide wat deur hul IdP aanmeld nooit die e-pos nodig het nie. 'n suspended-lid bly opgeskort en word by tokenuitreiking geweier. Dit hang nie af van allowAutoMembership of van domeine nie, omdat die organisasie reeds deur die verbinding gekies is.

Die organisasienaam op die aanmeldbladsy

Die aanmeldbladsy wys Signing in to {name} onder die toepassingsnaam. Die naam kom van dieselfde organisasie waarvan die bladsy se handelsmerk kom: die vasgepende domein se organisasie, dan die organisasie wat deur die authorize-versoek genoem word, dan die client se enkele beperkte organisasie. Dit is versteek wanneer daar geen organisasie is nie, of wanneer die organisasie se naam gelyk is aan die toepassingsnaam, sodat die opskrif nooit "Acme / Signing in to Acme" lees nie.

Handelsmerk-oorheersing

'n Organisasie se brandingJson word veld vir veld oor die huurder se handelsmerk vir die aanmeldbladsy saamgevoeg: 'n sleutel wat teenwoordig en nie-null is oorheers, 'n afwesige of null sleutel erf, en 'n onbekende sleutel word geïgnoreer. Misvormde JSON val terug na die huurder se eie handelsmerk met 'n waarskuwing wat aangeteken word, nooit 'n mislukte bladsylaai nie.

Die Handelsmerk-oortjie wysig al 21 saamvoegbare velde: voorkoms (appName, logoUrl, primaryColor, customCssUrl), ligte- en donkermoduskleure, e-poskleure, supportEmail, showForgotPassword, poweredBy en languages. Elke veld erf óf die huurder se waarde, as wenk getoon, óf oorheers dit, met 'n Maak skoon-kontrole wat die sleutel verwyder.

Terugvul vanaf die ou organisasiemerker

Voordat organisasies bestaan het, kon 'n gebruiker 'n vryteks-organisasiemerker dra sonder enige rekord daaragter. POST /api/v1/organizations/backfill migreer dit na werklike organisasies en lidmaatskappe, gegroepeer volgens elke afsonderlike ou waarde. Dit is 'n proeflopie tensy die liggaam { "dryRun": false } is.

• Begrens: skandeer hoogstens 50 000 gebruikers per oproep. 'n truncated-antwoord beteken laat loop dit weer; reeds gemigreerde gebruikers word by die herloop oorgeslaan.
• Idempotent: 'n afsonderlike ou waarde wat reeds gemigreer is, word met 'n interne stempel gepas, nie met die organisasie se (wysigbare) vertoonnaam nie, so om die gevolglike organisasie daarna te hernoem veroorsaak nie 'n duplikaat met die volgende lopie nie.

{
  "dryRun": true,
  "organizationsCreated": 3,
  "membershipsCreated": 41,
  "usersSkipped": 0,
  "organizations": [
    { "legacyValue": "acme-corp", "slug": "acme-corp", "users": 22 }
  ],
  "truncated": false
}

Portaal-UI-deurloop

Die Organisasies-bladsy lys elke organisasie in die huurder, 50 op 'n slag met 'n Laai meer-knoppie, en bied Nuwe Organisasie (slegs slug + naam; beleidsvlaggies, domeine en handelsmerk word daarna gestel) en 'n Vul terug vanaf erfenisorganisasieveld-vloei wat die terugvulling hierbo eers as 'n voorskou laat loop, en dan Pas toe.

Die organisasielys wys elke kliëntorganisasie in die huurder met sy slug, naam en skeppingsdatum

Elke organisasie se detailbladsy het drie oortjies: Algemeen (naam, slegs-lees-slug, die drie beleidskakelaars, 'n E-posdomeine-kaart om e-posdomeine by te voeg, te verifieer en te verwyder en die TXT-rekord te kopieer, en 'n tik-die-slug-om-te-bevestig-uitvee), Handelsmerk (elke oorheerbare veld, elk erf die huurder se waarde of oorheers dit), en Lede (voeg by per e-pos, met 'n uitnodiging aangebied wanneer geen rekening bestaan nie, statusverandering en verwydering per ry, met Laai meer).

Die Lede-oortjie lys elke lidmaatskap met sy status en 'n kontrole per ry om dit te verander of te verwyder

Die Handelsmerk-oortjie oorheers die huurder se aanmeldbladsy-handelsmerk veld vir veld vir hierdie organisasie

Die Domeine-bladsy dra die domein → organisasie-kieser: elke domeinkaart het 'n inlyn-aftreklys wat die huurder se organisasies lys plus 'n "Huurder (geen)"-opsie wat die pen skoonmaak, onmiddellik toegepas by verandering. Dieselfde kieser verskyn wanneer 'n domein bygevoeg word.

Die inlyn-organisasiekieser op 'n domeinkaart pen daardie pasgemaakte domein aan een organisasie vas

Ouditgebeurtenisse

organization.created · organization.updated · organization.deleted · organization.member.added · organization.member.invited · organization.member.joined · organization.member.updated · organization.member.removed · organization.domain_added · organization.domain_verified · organization.domain_removed · organization.backfill · domain.organization_set

Bladsynering

Die organisasielys en die ledelys word met 'n wyser gebladsy en antwoord { items, nextCursor }. Gee limit (verstek 50, vasgeklem op 1 tot 200) en, ná die eerste bladsy, die vorige antwoord se nextCursor onveranderd as cursor. 'n Null nextCursor is die laaste bladsy. Die wyser is 'n ondeursigtige sleutelstel-posisie oor organisasie-id (of gebruiker-id vir lede), sodat rye tussen oproepe byvoeg of verwyder nie 'n bladsy kan skuif of herhaal nie. 'n Wyser wat die lys nie uitgereik het nie is 400 invalid_cursor.

Bestuur organisasies vanaf 'n KI-assistent

Die gehoste portaal-MCP bied dertien organisasiehulpmiddels, almal met die huurder-admin-rol vereis: lys, haal, skep, werk by en vee organisasies uit; lys, voeg by, werk by en verwyder lede; voeg e-posdomeine by, verifieer en verwyder hulle; en lys 'n gebruiker se organisasies. Hulle roep dieselfde bewerkings as die API hierbo aan, sodat 'n hulpmiddel nie van sy roete kan afwyk nie. Sien Bestuur jou portaal vanaf 'n KI-assistent.

Een issuer per gasheer

Elke gasheer van 'n huurder is sy eie OIDC-issuer. Wanneer die versoekgasheer deur die huurder se domeintabel opgelos is, is die issuer en elke eindpunt-URL wat ontdekking adverteer https://{host}, sodat elke aktiewe pasgemaakte domein sy eie iss bevestig en die kanonieke huurdergasheer onveranderd bly. Handtekeningsleutels is per huurder, so elke gasheer bedien dieselfde sleutelstel. Dit is wat een huurder in staat stel om verskeie kliënte te bedien, elk op sy eie gebrandmerkte domein wat aan sy eie organisasie vasgepen is. Sien Pasgemaakte Domeine.

E-poskonfigurasie

Stel in hoe jou huurder transaksionele e-posse stuur, soos verifikasie-, wagwoordherstel- en uitnodigings-e-posse. Kies tussen die gedeelde versteksender, 'n geverifieerde pasgemaakte domein via Resend, of jou eie SMTP-bediener.

Gelokaliseerde E-posse

Transaksionele e-posse word in die ontvanger se voorkeurtaal gestuur. Verifikasie-, wagwoordherstel-, rekening-bestaan-, verwelkoming-, uitnodiging-, rekeningskrapping-, ondersteunings- en fakturering-e-posse is in elf tale gesjabloneer: Engels, Duits, Frans, Spaans, Portugees, Viëtnamees, Vereenvoudigde Chinees, Japannees, Arabies, Hindi en Afrikaans. Wanneer geen sjabloon vir 'n ontvanger se taal bestaan nie, val die e-pos terug na Engels.

Die taal word opgelos uit die ontvanger se gestoorde voorkeur ten tyde van stuur. Hierdie voorkeur kan van verskeie plekke kom:

• Registrasie — vasgelê uit die taal wat die gebruiker op die aangebode aanmeldskenne gekies het.
• Die portaal-Gebruikersblad — gestel deur 'n admin by die skep of wysig van 'n gebruiker.
• SCIM-voorsiening: gekarteer uit die IdP se preferredLanguage (of locale) wanneer gebruikers via SCIM gesinkroniseer word.
• Die self-diens-rekeningbladsy — deur die gebruiker self gekies by /login/account.

E-posverskaffers

Stuurderidentiteit

Stuurder-e-pos en naam word gedeel oor alle verskaffer-modi. Stuurder-e-pos is vereis vir die Pasgemaakte Domein (Resend)- en Pasgemaakte SMTP-verskaffers; stuurdernaam val terug na die handelsmerk se toepassingsnaam as dit leeg is.

Resend Pasgemaakte Domein

Verifieer jou stuurdomein eenmalig met Resend, gebruik dit dan as die Van-adres vir hierdie huurder. Die DNS-rekords (SPF, DKIM) word in die Pasgemaakte Stuurdomein-paneel op Instellings → E-pos gewys; Resend kontroleer hulle wanneer jy <strong>Kontroleer Verifikasie</strong> klik.

Pasgemaakte SMTP

Bring jou eie SMTP-bediener — nuttig vir interne relais, verskaffers nie deur Resend gedek nie, of regulatoriese vaspen.

Pasgemaakte Stuurdomein

By gebruik van die Pasgemaakte Domein (Resend)-verskaffer kan jy jou eie domein registreer sodat e-posse van jou handelsmerk kom (bv. [email protected]) in plaas van @authagonal.io.

1. Gaan na Instellings → E-pos en kies die Pasgemaakte Domein (Resend)-verskaffer.
2. Voer jou domeinnaam in en klik Registreer Domein.
3. Voeg die getoonde DNS-rekords (DKIM, SPF en terugkeerpad) by jou domein se DNS.
4. Klik Kontroleer Verifikasie — sodra DNS versprei (gewoonlik 1–10 minute), verander die domeinstatus na geverifieer.

Toetsing

Gebruik die Stuur Toets-e-pos-knoppie in Instellings → E-pos om jou konfigurasie te verifieer. 'n Toets-e-pos sal na jou admin-e-posadres gestuur word met die huidige gestoorde instellings.

Ouditlys

Die Ouditlys bied 'n leesalleen-rekord van alle administratiewe aksies wat op u huurder uitgevoer is. Elke wysiging via die portaal of API word met volledige konteks vasgelê, sodat u 'n volledige spoor het vir nakoming en foutopsporing.

Lyskolonne

Gedopte Aksies

Die volgende administratiewe aksies word in die ouditlys aangeteken:

Die ouditlys bied 'n volledige rekord van alle administratiewe aksies

Rugsteun

Authagonal maak outomaties 'n rugsteun van jou huurderdata op 'n uurlikse skedule. Rugsteun sluit alle gebruikers, groepe, rolle, clients, SSO-verbindings, SCIM-tokens, handelsmerke en instellings in. Jy kan rugsteungeskiedenes bekyk en die jongste volledige rugsteun van die Rugsteunbladsy aflaai.

Hoe Rugsteun Werk

• Een keer per dag word die uurlikse inkrementele rugsteune in 'n nuwe volledige rugsteun saamgerol, en op Sondae word die daaglikse volledige rugsteune in 'n weeklikse rugsteun saamgerol. Sewe daaglikse en vier weeklikse rugsteune word gehou.
• Inkrementele rugsteun loop uurliks en neem slegs rye wat sedert die laaste rugsteun verander het.
• Rugsteun word in Azure Blob Storage gestoor met dieselfde bestuurde identiteit as jou huurder.
• Geskrapte rekords word via grafsteen-rekords nagespoor en ingesluit in rugsteun vir oudit-volledigheid.

Rugsteun Aflaai

Klik Laai Jongste Af om 'n ZIP-leëer te kry wat die jongste volledige rugsteun saamgevoeg met alle daaropvolgende inkrementele rugsteun bevat. Elke tabel word as 'n JSONL-leëer uitgevoer (een JSON-objek per lyn).

Inrigtingsapps

Voorsieningsapps is jou eie dienste wat Authagonal roep elke keer as 'n gebruiker geskep word, sodat hulle 'n rekening kan opstel, 'n lisensie kan toeken, kan besluit aan watter organisasie die gebruiker behoort, of die registrasie heeltemal kan weier.

Hoe Dit Werk

Wanneer 'n gebruiker geskep word, roep Authagonal jou voorsieningsapp se terugroep-URL met die TCC (Try/Confirm/Cancel)-patroon. Elke app moet in die Try-fase aanvaar voordat enige van hulle vasgelê word, sodat verskeie stroomaf-stelsels kan saamstem, of een kan veto, sonder om halfgeskepte rekeninge agter te laat.

Wanneer voorsiening loop

Voorsiening loop op elke pad wat 'n gebruiker skep, nie net selfdiens-registrasie nie. App-en-gebruiker-kombinasies wat reeds voorsien is, word oorgeslaan, sodat 'n app elke gebruiker een keer sien.

Die Try-versoek

Authagonal POST hierdie JSON na <code>{callbackUrl}/try</code>. Velde sonder 'n waarde word weggelaat eerder as om as null gestuur te word.

'n Gebruiker wat deur SSO aankom, is die algemene geval waarvoor dit die moeite werd is om te beplan: hulle het nog geen organisasie nie, en federated_connection sê vir jou van watter van jou klante hulle af kom.

{
  "transactionId": "8f14e45fceea167a5a36dedd4bea2543",
  "userId": "0f6b1c8e-3d2a-4f51-9e77-2c1a4b5d6e7f",
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "customAttributes": {
    "federated_connection": "acme-okta"
  }
}

Die Try-antwoord

Jou app antwoord met 200 en 'n JSON-liggaam. Die liggaam is nie net 'n erkenning nie: dit is hoe 'n stroomaf-app die organisasie en kenmerke toeken wat op die gebruiker se tokens beland.

{
  "approved": true,
  "organizationId": "org_acme",
  "customAttributes": { "org_role": "member" }
}

Merk gebruikers met die regte organisasie

Besluit die organisasie hier, op een plek, eerder as by elke skeppingspad. 'n SSO-gebruiker dra federated_connection, wat die verbinding identifiseer wat hulle geverifieer het en daarom ook die klant, en dit bly korrek wanneer een klant verskeie e-posdomeine federeer. 'n Genooide gebruiker het geen verbinding nie, so pas hulle by die uitnodiging wat jy uitgereik het. Albei paaie bereik /try voordat die gebruiker bestaan, so een stuk logika dek hulle en daar is nie twee reëls wat uitmekaar kan dryf nie.

// POST {callbackUrl}/try
app.post('/provisioning/try', async (req, res) => {
  const { email, customAttributes } = req.body;

  // An SSO user carries the connection that vouched for them. That is the
  // customer, and it stays right when one customer has several domains.
  const connection = customAttributes?.federated_connection;

  const org = connection
    ? await orgByConnection(connection)
    : await orgByPendingInvite(email);

  if (!org) return res.json({ approved: false, reason: 'No organization for this user' });

  // Stamped on the user and emitted as org_id on every token from now on.
  res.json({ approved: true, organizationId: org.id });
});

Voeg 'n Inrigtingsapp by

Om 'n inrigtingsapp by te voeg, verskaf 'n Toepassingsnaam, 'n Terugbel-URL, 'n opsionele API-sleutel en 'n opsionele Try-tydsbeperking (sekondes, verstek 60, reeks 5 tot 300; Confirm en Cancel gebruik 'n vaste kort tydsbeperking). Die API-sleutel word as 'n Bearer-token in die Authorization-opskrif van elke webhook-versoek gestuur, sodat u app versoeke van Authagonal kan verifieer.

Toetsing

Klik Toets langs enige inrigtingsapp om 'n toetsversoek na u terugbel-URL te stuur. Die toetsresultate wys die HTTP-statuskode en responliggaam, wat u help om te bevestig dat u app webhooks korrek ontvang en verwerk.

Toets inrigtingsapps om webhook-aflewering en responsverwerking te bevestig

Plan-perke

Die maksimum aantal inrigtingsapps is per huurder instelbaar, met 'n verstekgrens van 6. 'n Admin kan hierdie grens aanpas as u werkvloei addisionele inrigtingsteikens vereis.

Span

Die Span-bladsy bestuur portaaladmins: die mense wat jou huurder deur die bestuurportaal kan bereik en opstel. Elke spanlid het 'n rol (Eienaar, Admin, Ontwikkelaar of Ondersteuning) wat bepaal wat hulle kan verander.

Adminlys

Die adminlys toon elke spanlid se naam, e-posadres, rol en die datum wat hulle bygevoeg is. 'n "Jy"-aanduider word langs die huidige gebruiker se ry getoon sodat jy jou eie rekening maklik kan identifiseer.

Admins Nooi

Om 'n nuwe spanlid te nooi, verskaf hul e-posadres, naam en rol. Hulle ontvang 'n e-pos met 'n skakel om hul wagwoord te stel en hul rekening te aktiveer; die skakel is 7 dae geldig.

Nooivelde

Admin-uitnodigings skep 'n hangende rekening en stuur 'n aktiveringskakel per e-pos aan die genooide.

Admins Verwyder

Die huurder-eienaar kan Verwyder langs enige spanlid klik om hul toegang te herroep. 'n Bevestigingsdialoog word getoon voordat die verwydering gefinaliseer word. Jy kan jouself nie verwyder nie, en die huurder behou altyd sy eienaar.

Bestuur portaaladmins vanaf die Spansbladsy

Ondersteuning

Maak 'n ondersteuningskaartjie oop by die Authagonal-span sonder om die portaal te verlaat. Elke kaartjie is 'n draadvormige gesprek, so jy en ons span bly op dieselfde bladsy van die eerste verslag tot oplossing.

Jou kaartjies

Die ondersteuningsbladsy lys elke kaartjie wat jy ingedien het, jongste aktiwiteit eerste. Gebruik die statuskenteken om in 'n oogopslag te sien wat op jou wag en wat op ons wag.

Jou ondersteuningskaartjies met onderwerp, status, prioriteit en laaste aktiwiteit

• Elke ry toon die onderwerp, huidige status (oop, hangende, opgelos of gesluit), prioriteit en tyd van die laaste aktiwiteit.
• Klik Nuwe kaartjie om een oop te maak, gee dit dan 'n onderwerp, prioriteit en jou eerste boodskap.
• Kleurgekodigde statuskentekens maak dit maklik om die lys te deurkyk vir kaartjies wat jou aandag benodig.

Kaartjiedraad

Die oopmaak van 'n kaartjie toon die volledige gesprek. Antwoorde word in volgorde geplaas, en nuwe boodskappe van ons span verskyn sonder 'n bladsyherlaai.

Kaartjiedraad tussen jou en die Authagonal-span

• Draadvormige boodskappe tussen jou en die Authagonal-span word in chronologiese volgorde getoon.
• Antwoord inlynig en heg leëers aan om logs, skermkiekies of konfigurasie te deel.
• Die draad word lewendig bygewerk, so 'n antwoord van ons span verskyn sodra dit gestuur is.
• As jy op 'n kennisgewing-e-pos antwoord, word jou boodskap outomaties ingedraad.

Ondersteuningsbalie vir jou gebruikers

Apart van die ondersteuning wat jy van ons kry, kan Authagonal 'n ondersteuningsbalie vir jou eindgebruikers bedryf. Hulle maak kaartjies oop vanaf hul rekeningbladsye op jou huurder se eie gasheer met jou handelsmerk, en jou span antwoord hulle vanuit die portaal.

Dit bestaan omdat die mense wat nie kan aanmeld nie, presies die mense is wat nie 'n ondersteuningsinstrument kan bereik wat aanmelding vereis nie. Die balie sit langs die aanmeldskerms, so 'n uitgesluite gebruiker het steeds 'n pad deur, en elke kaartjie kom reeds gekoppel aan 'n werklike rekening in jou gebruikersgids aan, eerder as aan watter adres iemand ook al ingetik het.

Om dit aan te skakel

Maak Klantondersteuning in die portaal oop, skakel oor na sy Instellings-oortjie en skakel Aktiveer kliënteondersteuning aan. Die oortjie is daar vir eienaars en admins. Niks is vir jou gebruikers sigbaar voordat jy dit doen nie.

Wat jou gebruikers sien

Aangemelde gebruikers kry 'n ondersteuningsafdeling in hul rekeningbladsye op jou huurder-gasheer, met jou handelsmerk. Hulle kan 'n kaartjie oopmaak, alles sien wat hulle oopgemaak het, en in 'n draad antwoord. Antwoorde van jou span kom ook per e-pos aan, sodat 'n gebruiker nie heeltyd hoef te gaan kyk nie.

Met anonieme kaartjies geaktiveer, kan iemand wat nie kan aanmeld nie, steeds een oopmaak. Hulle gee 'n e-posadres en hul boodskap, en kry 'n private skakel na die gesprek terug. Daardie skakel is die enigste pad in, so behandel dit soos 'n geloofsbrief: dit is onraaibaar, en enigiemand wat dit het, kan daardie een draad lees en daarop antwoord.

Die operateur-inmandjie

Jou span antwoord vanuit Klantondersteuning in die portaal se sykieslys. Dit is 'n aparte plek van jou eie kaartjies by ons, en dit is beskikbaar vir die tenant:support-rol en hoër, sodat jy 'n agent toegang tot die balie kan gee sonder om hulle die res van die portaal te gee.

Gebruikers skryf in hul eie taal

'n Kaartjie word gestoor in die taal waarin die gebruiker dit geskryf het, en elke persoon in die draad lees dit in syne. Jou agent sien 'n boodskap wat in sy portaaltaal vertaal is, die gebruiker sien jou antwoord in syne vertaal, en die oorspronklike teks word altyd daarnaas gehou. Die taal word uit die eerste boodskap opgespoor en aan die kaartjie vasgepen. Vertalings word een keer per taal bereken en hergebruik, sodat 'n lang draad nie homself oor en oor vertaal nie.

Tydsones

'n Kaartjie teken die tydsone aan waaruit die gebruiker dit oopgemaak het. Elke boodskap wys dan hul plaaslike tyd langs joune, sodat 'n antwoord om 14:32 gelees word as die 02:32 wat dit werklik was vir die persoon wat daarop wag. Wanneer die sone onbekend is, soos by 'n kaartjie wat per e-pos aangekom het, of wanneer dit met joune ooreenstem, word niks gewys nie.

Webhooks

Stel 'n ondersteuning-webhook-URL om kaartjiegebeure te ontvang soos hulle gebeur, om 'n waarskuwing op te wek of kaartjies na jou eie stelsel te spieël. Ladings word onderteken sodat jy kan verifieer dat hulle van ons af gekom het.

Invoer en migreer

Migreer 'n bestaande identiteitsstelsel na u Authagonal-huurder. Twee bronne word ondersteun — Duende IdentityServer ('n SQL Server-databasis) en Auth0 (die Management API). Elk laat 'n leesalleen-voorskou toe sodat u presies kan sien wat gekopieer sal word voordat u verbind.

Invoer vanaf Duende IdentityServer

Migreer clients, scopes, gebruikers en rolle vanaf 'n bestaande Duende IdentityServer SQL Server-databasis na u Authagonal-huurder. Die invoer loop in twee fases — voorskou en verbind — sodat u kan sien wat gekopieer sal word voordat enige wysigings gemaak word.

Wat Ingevoer Word

Die invoerder lees uit Duende se ConfigurationDb en ASP.NET Identity-tabelle en skryf gekarteerde rye na u huurder. Kortstondige artefakte soos aanhoudende toelatings, toestelkodes en ondertekeningssleutels word oorgeslaan.

Voorskou Voor Verbind

Plak u Duende ConfigurationDb / IdentityDb-verbindingstring en klik Voer voorskou uit. Die voorskou open 'n leesalleen-verbinding en tel elke ry wat ingevoer sou word. Geen skryfwerk vind plaas nie.

• Entiteitstellings vir clients, scopes, gebruikers, rolle en roltoekennings.
• Botsingswaarskuwings wanneer die teikenhuurder reeds clients (ooreenstemmende ClientIds word oorskryf), rolle of scopes (ooreenstemmende name word oorgeslaan) het.
• Waarskuwings vir onbekende tabelle en ongekartte kolomme sodat u weet watter data geskrap sal word.

Voorskoupaneel met tellings en waarskuwings

Wagwoordhasse

Duende stoor wagwoorde met ASP.NET Identity V3 (PBKDF2). Authagonal se PasswordHasher verifieer daardie formaat direk en herhash na die inheemse formaat by die eerste suksesvolle aanmelding — gebruikers behou hul bestaande wagwoorde sonder 'n hersettingsvloei.

Gebruiker-ID-rekonsiliasie

As 'n gebruiker wat reeds in hierdie huurder is dieselfde e-pos het as 'n inkomende rekord, roteer die invoer daardie rekening se userId na die bron-sub voor invoer, sodat die ingevoerde rolle, aanmeldings, en eise aan die bestaande rekening heg en toepassings wat die gebruiker reeds deur hul bron-sub verwys, bly oplos na die oorskakeling. Die rekening se bestaande wagwoord en profiel word behou; die bronrolle smelt bo-op saam. Die voorskou lys elke rekening wat gerekonsilieer sal word voordat u verbind.

Die Invoer Uitvoer

Klik Begin invoer nadat u die voorskou hersien het. Die verbindingsfase skryf clients, scopes, gebruikers, rolle en eksterne-aanmelding-verwysings na u huurder se stoor. Clients met 'n ooreenstemmende clientId word oorskryf; rye met 'n ooreenstemmende scope name, email of role name word oorgeslaan, so die invoerder is veilig om weer uit te voer.

Wat Nie Ingevoer Word Nie

• Aanhoudende toelatings, toestelkodes, bediener-sessies — kortstondige artefakte, word outomaties hergenereer.
• Ondertekeningssleutels — Authagonal gee sy eie per-huurder-sleutels uit.
• Pasgemaakte kolomme en tabelle — alles buite Duende se standaardskema word as 'n waarskuwing aangedui sodat u weet die data is geskrap.
• Gedeaktiveerde clients — word in 'n gedeaktiveerde toestand ingevoer; heraktiveer hulle via die Clients-bladsy wanneer gereed.

Invoer vanaf Auth0

Koppel Authagonal aan u Auth0-huurder se Management API en bring u toepassings, API's, rolle, gebruikers en ondernemingsverbindings oor. Ingevoerde gebruiker- en toepassings-ID's word behou, sodat bestaande sub- en client_id-verwysings na die oorskakeling bly werk.

Wat u nodig het

Skep 'n Machine-to-Machine-toepassing in Auth0 wat gemagtig is vir die Management API, met hierdie leesscopes: read:users, read:clients, read:resource_servers, read:roles, read:connections, read:client_grants. Plak sy domein, client ID en client secret in die invoervorm — dit word slegs vir die invoer gebruik.

Wat Ingevoer Word

Wagwoorde

Auth0 se Management API gee nooit wagwoordhasse terug nie. As u Auth0 se ondersteuningsgeholpe massa-wagwoorduitvoer (NDJSON) het, verskaf dit — bcrypt-hasse word woordeliks ingevoer en u gebruikers behou hul wagwoorde sonder herinstel. Daardie lêer dra ook u volledige gebruikersstel, wat Auth0 se 1 000-gebruiker-API-lysgrens hef. Sonder dit word gebruikers as profiele ingevoer en stel 'n nuwe wagwoord by eerste aanmelding in.

API-verwysing

Elke huurder stel 'n standaard-voldoende OIDC-bediener bloot by https://{slug}.authagonal.io. Alle eindpunte volg die OAuth 2.0- en OpenID Connect-spesifikasies. Hierdie verwysing dek elke eindpunt waarmee u toepassing moontlik moet kommunikeer.

Magtigingskodestroom met PKCE

OIDC-ontdekking & JWKS

Die ontdekkingsdokument laat OIDC-kliëntbiblioteek toe om hulself outomaties te konfigureer. Geen verifikasie word vereis vir enige van die eindpunte nie.

GET /.well-known/openid-configuration

Gee die OpenID-aanbieder-konfigurasiedokument terug. Die respons bevat al die metadata wat u kliënt nodig het om met hierdie huurder te kommunikeer.

GET /.well-known/openid-configuration/jwks

Gee die JSON Web Key Set terug wat gebruik word om token-handtekeninge te verifieer. Die respons bevat 'n keys-reeks van EC P-256-publieke sleutels (tokens word met ES256 onderteken), elk met kty- (EC), use-, kid-, alg-, crv-, x- en y-velde.

curl https://acme.authagonal.io/.well-known/openid-configuration

Magtigingseindpunt

GET /connect/authorize

Begin 'n magtigingskodestroom. Die gebruiker moet 'n aktiewe sessie hê, anders word hy aangestuur na die aanmeldblad. By sukses word die gebruiker teruggestuur na u toepassing met 'n magtigingskode.

Sukses-respons: 302-aanstuur na redirect_uri met code- en state-navraagparameters.

Fout-respons: 302-aanstuur met error-, error_description- en state-navraagparameters.

Pushed Authorization Requests (PAR)

RFC 9126. In plaas van om elke magtigingsparameter op die URL te plaas, POST u kliënt hulle na /connect/par met normale kliënt-verifikasie en ontvang 'n kortstondige, ondeursigtige request_uri terug. Die blaaier besoek dan /connect/authorize?client_id=...&request_uri=... — niks anders beland in die blaaier se geskiedenis, bedienerlêers, of Referer-opskrifte nie, en die bediener het reeds die parameters onder kliënt-verifikasie se integriteit nagegaan.

POST /connect/par

Kliënt-verifikasie is dieselfde as vir /connect/token: HTTP Basic met client_id/client_secret, of vorm-geënkodeerde geloofsbriewe. Publieke kliënte stuur sonder 'n secret. Die liggaam dra dieselfde parameters as wat u normaalweg na /connect/authorize sou stuur; request_uri self word verwerp (koppeling van 'n PAR word verbied deur §2.1 van die spesifikasie). Gee 201 Created terug.

Respons

By die opvolgversoek GET /connect/authorize?client_id=…&request_uri=… word alle ander parameters uit die gestuurde lading gehaal en enige ekstra navraagparameters word geïgnoreer. Die client_id op die magtigingsoproep moet ooreenstem met die kliënt wat die versoek gestuur het. Sodra dit gebruik is (of sodra expires_in verstreke is), word die request_uri uit die stoor verwyder.

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

Token-eindpunt

POST /connect/token

Ruil geloofsbriewe vir tokens uit. Versoeke moet Content-Type: application/x-www-form-urlencoded gebruik. Kliënt-verifikasie kan verskaf word via HTTP Basic auth (Authorization: Basic base64(client_id:client_secret)) of as vorm-liggaam-parameters (client_id + client_secret).

Magtigingskode-subsidie

Refresh Token Grant

Client Credentials-subsidie

Toestelkode-subsidie

Token-respons:

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

UserInfo-eindpunt

GET /connect/userinfo

Gee eise oor die geverifieerde gebruiker terug. Vereis 'n geldige access token met die openid-scope.

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Token-inspeksie (RFC 7662)

POST /connect/introspect

Valideer 'n token en gee sy metadata terug. Vereis kliëntgeloofsbriewe (Basic auth of vorm-liggaam-parameters).

Aktiewe token-respons:

Onaktiewe token-respons: { "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

Token-herroeping (RFC 7009)

POST /connect/revocation

Herroep 'n voorheen uitgereike token. Vereis kliëntgeloofsbriewe.

Die eindpunt gee altyd 200 OK terug, selfs vir ongeldige of reeds herroepde tokens, ooreenkomstig die RFC 7009-spesifikasie.

Toestelmagtiging (RFC 8628)

POST /connect/deviceauthorization

Begin die toestelmagtigingstroom vir invoer-beperkte toestelle (CLI's, slim TV's, IoT-toestelle). Die toestel vertoon 'n kode aan die gebruiker, wat dan die versoek op 'n aparte toestel met 'n blaaier goedkeur.

Respons:

Goedkeuringstroom: Die gebruiker besoek die verification_uri, voer die user_code in en keur die versoek goed. Intussen peil die toestel die token-eindpunt met die device_code.

Peilings-foutkodes:

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

Sessie-beëindiging / Afmeld

GET POST /connect/endsession

Meld die huidige gebruikerssessie af, stel elke kliënt met 'n geregistreerde back-channel- of front-channel-logout-URI in kennis, en herroep die grants wat aan daardie sessie gebind is. Sonder 'n id_token_hint wat met die huidige sessie ooreenstem, word die gebruiker eers gevra om die afmelding te bevestig.

As 'n geldige post_logout_redirect_uri verskaf word en met 'n geregistreerde URI ooreenstem, ontvang die gebruiker 'n 302-aanstuur. Andersins bevestig 'n JSON-respons dat die sessie beëindig is.

SCIM 2.0 API-verwysing

Authagonal ondersteun die SCIM 2.0-protokol vir outomatiese gebruiker- en groepvoorsiening. Identiteitsverskaffer soos Okta, Azure AD en OneLogin kan hierdie API gebruik om jou Authagonal-huurder gesinkroniseer te hou met jou korporatiewe gids.

Basis-URL: https://{slug}.authagonal.io/scim/v2

Verifikasie: Alle versoeke vereis 'n Bearer-token. Genereer 'n SCIM-token in die portaal op die SCIM-bladsy: kies die client waarvoor jou IdP voorsien, dan Skep Token.

Algemene opskrifte:

Lyseinpunte neem count (verstek 100, maks. 200; 0 gee slegs die totaal terug) en filtrering via die filter-parameter (bv. userName eq "[email protected]"). Gebruikers blaai met cursor: gee die vorige respons se nextCursor deur. Groepe aanvaar óf startIndex (1-gebaseer) óf cursor.

Gebruikers

GET /scim/v2/Users: Lys gebruikers met opsionele bladering en filtrering.

GET /scim/v2/Users/{id}: Kry 'n enkele gebruiker aan die hand van hul Authagonal-gebruiker-ID.

POST /scim/v2/Users: Skep 'n nuwe gebruiker. Gee 201 Created terug.

PUT /scim/v2/Users/{id}: Volledige vervanging van 'n gebruikerhulpbron. Alle velde moet verskaf word.

PATCH /scim/v2/Users/{id}: Gedeeltelike opdatering via SCIM PatchOp.

DELETE /scim/v2/Users/{id}: Sagte skrap van die gebruiker (deaktiveer die rekening en herroep alle tokens). Gee 204 No Content terug.

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

Groepe

GET /scim/v2/Groups: Lys alle groepe met opsionele bladering en filtrering.

GET /scim/v2/Groups/{id}: Kry 'n enkele groep aan die hand van ID, insluitend sy ledelist.

POST /scim/v2/Groups: Skep 'n nuwe groep. Gee 201 Created terug.

PUT /scim/v2/Groups/{id}: Volledige vervanging van 'n groephulpbron (insluitend sy ledelist).

PATCH /scim/v2/Groups/{id}: Gedeeltelike opdatering: voeg lede by, verwyder of vervang hulle, of verander displayName en externalId.

DELETE /scim/v2/Groups/{id}: Harde skrap van die groep. Gee 204 No Content terug.

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

Portal API (outomatisering)

Die Portal API laat jou eie agterkant toe om alles te outomatiseer wat jy in die portaal kan doen — bestuur gebruikers, clients, groepe, rolle, skope, SSO-verbindings en instellings — met 'n masjien-tot-masjien-geloofsbrief. Dit is dieselfde API wat die portaal-koppelvlak gebruik.

Basis-URL: https://portal-api.<your-domain>/api/v1. Versoeke verifieer met 'n Bearer access token; die huurder word uit die token geneem, nie die URL nie.

Skep 'n API-geloofsbrief

Maak in die portaal Clients → Skep API-geloofsbrief oop, kies 'n toegangsvlak en gee dit 'n naam. Authagonal genereer 'n OAuth client_credentials-client wat vir die Portal API opgestel is en gee 'n client-ID en -geheim terug.

Toegangsvlakke

Kry 'n token

Ruil die geloofsbrief vir 'n access token by jou huurder se token-eindpunt — https://<your-tenant>.<your-domain>/connect/token — en stuur dan die token as 'n Bearer-opskrif na die Portal API. Tokens is een uur geldig.

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Eindpunte

Alle paaie is relatief tot die basis-URL en vereis 'n Bearer access token. Die skopus langs elke groep is die minimum geloofsbrief-toegangsvlak wat dit benodig. Bladering verskil per hulpbron: gebruikers en die ouditlog neem count (1 tot 200, verstek 50) en after, gestel op die vorige respons se continuationToken; groepe neem startIndex en count; organisasies neem limit en cursor; clients, rolle en scopes gee elke ry terug.

GET/api/v1/clientsLys OAuth-clients.

GET/api/v1/clients/{id}Kry 'n enkele client aan die hand van ID.

POST/api/v1/clientsSkep 'n client. Gee 201 terug met die client-rekord. Geheime word nie hier teruggegee nie: munt een met POST /api/v1/clients/{clientId}/secrets, wat dit een keer wys.

PUT/api/v1/clients/{id}Werk 'n client by (herleidings-URI's, toekenningtipes, token-lewensduur, PKCE/PAR-vereistes).

DELETE/api/v1/clients/{id}Skrap 'n client.

POST/api/v1/clients/api-credentialGenereer 'n masjien-tot-masjien Portal API-geloofsbrief.

GET/api/v1/usersLys gebruikers. Ondersteun count, search (e-pos- of naamvoorvoegsel), organizationId om na een organisasie te filter, en after vir wyser-blaaiery.

GET/api/v1/users/countTotale gebruikertelling vir die huurder.

GET/api/v1/users/stats/mfaMFA-inskrywingstatistieke.

GET/api/v1/users/{id}Kry 'n enkele gebruiker.

POST/api/v1/users/inviteNooi 'n gebruiker per e-pos. Skep 'n hangende rekening en stuur 'n skakel per e-pos waar die genooide hul eie wagwoord stel. Opsionele organizationId en organizationRoles voeg ook 'n organisasielidmaatskap by.

PUT/api/v1/users/{id}Werk 'n gebruiker by (profiel, e-pos, isActive, emailConfirmed, organizationId). Om die e-pos of emailConfirmed te verander, is tenant:admin nodig.

DELETE/api/v1/users/{id}Skrap 'n gebruiker.

GET/api/v1/users/{id}/mfaGet a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfaReset a user's MFA enrollment. Needs tenant:admin.

GET/api/v1/rolesLys rolle.

POST/api/v1/rolesSkep 'n rol.

DELETE/api/v1/roles/{id}Skrap 'n rol.

POST/api/v1/roles/assignKen 'n rol aan 'n gebruiker toe.

POST/api/v1/roles/unassignVerwyder 'n rol van 'n gebruiker.

GET/api/v1/groupsLys groepe.

GET/api/v1/groups/{id}Kry 'n groep met sy leede.

POST/api/v1/groupsSkep 'n groep.

POST/api/v1/groups/{id}/membersVoeg leede by 'n groep.

DELETE/api/v1/groups/{groupId}/members/{userId}Verwyder 'n lid van 'n groep.

DELETE/api/v1/groups/{id}Skrap 'n groep.

GET/api/v1/group-role-mappingsLys groep-tot-rol-koppelinge (rolle wat by token-uitreiking deur groeplidmaatskap toegeken word).

GET/api/v1/scopesLys API-skope.

POST/api/v1/scopesSkep 'n skopus.

DELETE/api/v1/scopes/{name}Skrap 'n skopus.

GET/api/v1/saml/connectionsLys SAML-verbindings.

POST/api/v1/saml/connectionsSkep 'n SAML-verbinding.

DELETE/api/v1/saml/connections/{id}Skrap 'n SAML-verbinding.

GET/api/v1/oidc/connectionsLys OIDC-verbindings.

POST/api/v1/oidc/connectionsSkep 'n OIDC-verbinding.

DELETE/api/v1/oidc/connections/{id}Skrap 'n OIDC-verbinding.

GET/api/v1/sso/domainsLys die domeine wat na SSO-verbindings geroeteer word (tuis-realmontdekking).

GET/api/v1/brandingKry die huurder se handelsmerk (kleure, logo, ondersteunde tale).

PUT/api/v1/brandingWerk die huurder se handelsmerk by.

GET/api/v1/settingsKry huurderinstellings (webhooks, openbare aanmelding, token-beleid).

PUT/api/v1/settingsWerk huurderinstellings by.

POST/api/v1/settings/webhook-secret/regenerateRoteer die webhook-ondertekeningsgeheim.

POST/api/v1/settings/test-emailStuur 'n toets-e-pos met die huidige e-poskonfigurasie.

GET/api/v1/custom-domainsLys pasgemaakte aanmelddomeine en hul verifikasietatus.

POST/api/v1/custom-domainsVoeg 'n pasgemaakte domein by.

POST/api/v1/custom-domains/{domain}/verifyBegin DNS-verifikasie vir 'n pasgemaakte domein.

DELETE/api/v1/custom-domains/{domain}Verwyder 'n pasgemaakte domein.

GET/api/v1/email/domains/{domainId}Kry 'n sender-e-posdomein se DNS-rekords en verifikasiestatus.

GET/api/v1/auditBevraagteken die huurder se ouditlog.

Voorbeeld: nooi 'n gebruiker

curl -X POST https://portal-api.authagonal.io/api/v1/users/invite \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "[email protected]" }

Organisasies-API

Al die roetes hieronder vereis die TenantAdmin-beleid en is onder /api/v1/organizations tensy anders vermeld. Sien Portaal-API oor hoe om 'n credential te maak. Die twee lysroetes word met 'n wyser gebladsy: gee limit (verstek 50, 1 tot 200) en die vorige nextCursor as cursor; hulle antwoord { items, nextCursor }, en 'n slegte wyser is 400 invalid_cursor. Die organisasie-objek dra 'n slegs-lees domains-lys.

Aanmeldskerms

Dit is die aangebied skerms wat jou eindgebruikers op jou huurder se verifikasie-bediener sien. Authagonal lewer elke skerm gebruiksklaar, sodat jy 'n volledige, veilige aanmeld-ervaring kry sonder om enige koppelvlak te bou. Hierdie bladsy loop deur elke skerm en wys watter portaalinstellings dit beheer.

Aanmelding

• E-pos-eerste, tweestap-vloei: die gebruiker voer hul e-pos in en klik Gaan voort, dan verskyn die wagwoordveld.
• "Gaan voort met {provider}" enkelteken-op-knoppies verskyn outomaties wanneer SSO-verbindings bestaan.
• Wagwoord vergeet- en skep rekening-skakels, elk wat gewys of verberg kan word.
• Opsionele Cloudflare Turnstile-captcha om outomatiese aanmeldpogings te ontmoedig.

Beheer in die portaal-admin

• Branding stel die logo, kleur, app-naam, ondersteunings-e-pos en pasgemaakte CSS in.
• Wys of verberg die wagwoord-vergeet- en registrasie-skakels (Branding).
• SSO-verbindings voeg die sosiale aanmeldknoppies by (SSO-bladsy).
• Sessie-lewensduur en blokkeringsdrempelwaardes (Instellings → Sessie).

Registrasie

• Versamel voor- en van (opsioneel), e-pos en 'n wagwoord.
• 'n Lewendige wagwoordbeleid-kontrolelys werk by soos die gebruiker tik, sodat vereistes duidelik is voor indiening.
• Opsionele Cloudflare Turnstile-captcha.
• 'n "Meld aan"-skakel vir gebruikers wat reeds 'n rekening het.

Beheer in die portaal-admin

• Wys of verberg die registrasie-skakel (Handelsmerk). Om registrasie heeltemal af te skakel, skakel Laat publieke registrasie toe af (Instellings → Sessie).
• Jou huurder se wagwoordbeleid dryf die kontrolelys.
• Branding stileer die hele skerm.

Wagwoord vergeet

• Die gebruiker voer hul e-pos in en sien dan 'n neutrale "kyk jou e-pos"-bevestiging.
• Die skerm onthul nooit of 'n rekening bestaan nie, wat rekeningopsomming-peiling verhinder.
• 'n "Terug na aanmelding"-skakel neem die gebruiker terug na die aanmeldskerm.

Beheer in die portaal-admin

• Wys of verberg die wagwoord-vergeet-skakel (Branding).
• Jou huurder se e-posaflewering stuur die herstellingsboodskap.
• Branding stileer die hele skerm.

Wagwoord herstel

• Nuwe wagwoord- en bevestig wagwoord-velde met 'n lewendige per-reël-vereistelys.
• 'n Duidelike ongeldige of verstreke skakel-toestand wanneer die herstel-token nie meer geldig is nie.
• 'n Sukses-toestand wat bevestig dat die wagwoord verander is.

Beheer in die portaal-admin

• Jou huurder se wagwoordbeleid dryf die kontrolelys.
• Branding stileer die hele skerm.

MFA-uitdaging

• 'n Metode-wisselaar tussen stawings-app, toegangssleutel en herstelkode.
• 'n 6-syfer TOTP-veld wat outomaties indien sodra alle syfers ingevoer is.
• Herstelkode-inskrywing vir gebruikers wat toegang tot hul stawer verloor het.
• 'n Toegangssleutel-knoppie vir hardeware-gesteunde verifikasie.

Beheer in die portaal-admin

• MFA-beleid word per toepassing ingestel (Clients → Sekuriteit).
• Enige gebruiker met 'n geregistreerde faktor word altyd uitgedaag, ongeag beleid.

MFA-opstelling

• Wys die status van geregistreerde metodes sodat die gebruiker weet wat reeds opgestel is.
• Stawer-opstelling via QR-kode, 'n handmatige sleutelalternatief en 'n bevestigingstap.
• Toegangssleutel-inskrywing vir hardeware-gesteunde stawing.
• Herstelkode-generering vir rekeningherstel.
• 'n Opsionele oorslaan wanneer MFA selfbedien eerder as vereis is.

Beheer in die portaal-admin

• MFA-beleid word per toepassing ingestel; Vereis dwing opstelling by aanmelding (Clients → Sekuriteit).
• Branding stileer die hele skerm.

Toestel-magtiging

• 'n Gesentreerde gebruikerskode-inskrywing-veld vir die kode wat op die toestel gewys word.
• 'n Goedkeur-stap om die toestel te magtig.
• 'n Aanmeld-tussenblad wanneer die gebruiker nog nie geverifieer is nie.
• 'n Goedgekeurde bevestiging sodra die toestel gemagtig is.

Beheer in die portaal-admin

• Aktiveer die toestelkode-grant op die toepassing (Clients → Scopes & Grants).
• Stel die toestelkode-lewensduur in (Clients → Tokens).

Toestemming

• Wys die versoekende client se logo en naam.
• 'n Per-scope-lys met gebruikersvriendelike, leesbare etikette vir elke toestemming.
• Toelaat- en Weier-knoppies om toegang toe te staan of te weier.
• 'n Toestemming-wenk-voetteks wat verduidelik wat die beslissing beteken.

Beheer in die portaal-admin

• Aktiveer Vereis toestemming per toepassing (Clients → Algemeen).
• Die logo, naam en URL kom van die toepassing se eie metadata.
• Branding stileer die toestemmingskaart.

Gekoppelde toepassings (grants)

• Lys elke toepassing wat die gebruiker gemagtig het, met sy naam, scopes en toestemmingsdatum.
• Herroep toegang tot 'n toepassing, met 'n bevestigingstap voordat dit van krag word.
• 'n Vriendelike leë toestand wanneer die gebruiker geen toepassings gemagtig het nie.

Beheer in die portaal-admin

• Die lys word gevul deur toestemming-vereiste toepassings.
• Branding stileer die hele skerm.

Rekening

'n Aangebied selfbediens-rekeningbladsy by /login/account waar aangemelde gebruikers hul eie profiel en voorkeurstaal bestuur, sonder portaaltoegang.

• Wysig voor- en van, maatskappy en telefoon; die e-posadres word leesalleen gewys.
• Kies 'n voorkeurstaal uit die ondersteunde lande; die koppelvlak voorskou die keuse onmiddellik en stoor dit by stoor.
• Die gestoorde taal dryf die gebruiker se aangebied koppelvlak en die taal van die transaksioneele e-posse wat hulle ontvang.

Beheer in die portaal-admin

• Branding stileer die hele skerm.
• Dieselfde voorkeurstaal is wysigbaar deur 'n admin op die portaal se Gebruikers-bladsy.

Stawingsvloeie

Stawingsvloeie dek hoe eindgebruikers met jou Authagonal-huurder kommunikeer — aanmeld, registreer, wagwoorde herstel en MFA opstel. Hierdie endpoints word gebruik deur die aangebied aanmeldbladsy en kan direk geroep word as jy 'n pasgemaakte aanmeld-koppelvlak bou.

Aanmelding

POST /api/auth/login

Staaf 'n gebruiker met e-pos en wagwoord. By sukses, teken 'n sessie-cookie en gee die gebruikersprofiel terug. As MFA opgestel is, dui die respons aan dat 'n tweede faktor vereis word voordat die sessie ten volle tot stand gekom het.

Versoekliggaam:

{
  "email": "[email protected]",
  "password": "correct-horse-battery-staple"
}

Sukses-respons:

MFA-vereiste respons: Wanneer die gebruiker MFA geregistreer het, sluit die respons mfaRequired: true in saam met 'n challengeId en 'n methods-skikking wat beskikbare MFA-metodes lys.

MFA-opstelling vereiste respons: Wanneer die toepassing se MFA-beleid Vereis is maar die gebruiker nog nie geregistreer het nie, sluit die respons mfaSetupRequired: true in met 'n setupToken vir die registrasie-vloei.

Fout-responsies:

SSO-kontrole: As die gebruiker se e-posdomein 'n SSO-verbinding opgestel het, gee die aanmeld-endpoint sso_required terug met 'n redirectUrl. Die client moet die gebruiker na die SSO-verskaffer herlei.

Rekening-blokkering: Na maxFailedAttempts agtereenvolgende mislukte aanmeldpogings, word die rekening gesluit vir lockoutDurationMinutes. Beide waardes is instelbaar in huurder-instellings.

Registrasie

POST /api/auth/register

Skep 'n nuwe gebruikersrekening en stuur 'n verifikasie-e-pos. Terwyl <strong>Vereis e-posverifikasie om aan te meld</strong> (Instellings &rarr; Sessie) aan is, wat die verstek is, moet die gebruiker hul e-pos verifieer voordat hulle kan aanmeld.

Versoekliggaam:

{
  "email": "[email protected]",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

Sukses: 201 Geskep met die userId van die nuwe rekening. Registreer met 'n e-pos wat reeds gebruik word, gee ook 201 terug: ons onthul nooit of 'n e-pos bestaan nie (om rekeningopsomming te verhinder), en stel eerder die werklike rekeninghouer per e-pos in kennis.

Fout-responsies:

Wagwoordherstel

POST /api/auth/forgot-password

Versoek 'n wagwoordherstel-e-pos. Die endpoint gee altyd 'n sukses-respons terug, ongeag of die e-pos bestaan, om e-posopsomming te verhinder.

{
  "email": "[email protected]"
}

POST /api/auth/reset-password

Herstel die gebruiker se wagwoord met behulp van die token uit die e-pos-skakel.

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

Newe-effekte van 'n suksesvolle wagwoordherstel:

• Mislukte aanmeldpoging-teller word na nul herstel
• Alle bestaande refresh tokens word herroep
• 'n Nuwe sekuriteitstempel word gegenereer (wat alle bestaande sessies ongeldig maak)

MFA-opstelling en -verifikasie

Authagonal ondersteun drie MFA-metodes: TOTP (stawings-apps), WebAuthn (sekuriteitssleutels en biometrie) en enkelmaal-herstelkodes.

TOTP-opstelling

POST /api/auth/mfa/totp/setup: Gee 'n <code>setupToken</code>, 'n QR-kode-data-URI en 'n handmatige invoersleutel terug. Die gebruiker skandeer die QR-kode met hul stawings-app (Google Authenticator, Authy, 1Password, ens.), en bevestig dan inskrywing.

POST /api/auth/mfa/totp/confirm: Bevestig TOTP-inskrywing deur die <code>setupToken</code> van die opstelling saam met 'n 6-syfer-kode van die stawings-app te stuur.

{
  "setupToken": "SETUP_TOKEN_FROM_SETUP_RESPONSE",
  "code": "123456"
}

WebAuthn-opstelling

POST /api/auth/mfa/webauthn/setup — Gee geloofsbrief-skeppingsopsies vir die WebAuthn API terug. Die blaaier roep navigator.credentials.create() met hierdie opsies.

POST /api/auth/mfa/webauthn/confirm: Bevestig WebAuthn-inskrywing deur die bevestigingsrespons van die blaaier in te dien.

Herstelkodes

POST /api/auth/mfa/recovery/generate: Genereer 10 enkelmaal-gebruikbare herstelkodes van 10 karakters (formaat <code>XXXXX-XXXXX</code>). Elke kode kan presies een keer gebruik word om MFA te omseil. 'n Stawings-app of toegangssleutel moet eers geregistreer wees.

MFA-verifikasie

POST /api/auth/mfa/verify: Voltooi die MFA-uitdaging na 'n suksesvolle wagwoord-aanmelding.

MFA-status

GET /api/auth/mfa/status: Gee die gebruiker se tans geregistreerde MFA-metodes terug.

SSO-aanmeld-vloei

Authagonal ondersteun beide SAML 2.0 en OIDC-gebaseerde SSO-verbindings. Domein-gebaseerde roeteplanning speur outomaties watter SSO-verskaffer gebruik moet word op grond van die gebruiker se e-posadres.

SSO-kontrole

GET /api/auth/[email protected]

SAML-vloei

Die gebruiker word herlei na GET /saml/{connectionId}/login wat 'n SAML AuthnRequest na die identiteitsverskaffer stuur. Die IdP staaf die gebruiker en plaas 'n SAML-respons terug na die Assertion Consumer Service (ACS) endpoint. Authagonal valideer die bewering, skep of werk die gebruiker by, en teken 'n sessie-cookie.

SAML-metadata vir die opstelling van jou IdP is beskikbaar by GET /saml/{connectionId}/metadata.

OIDC-vloei

Die gebruiker word herlei na GET /oidc/{connectionId}/login wat na die boontoe identiteitsverskaffer herlei met PKCE. Nadat die gebruiker gestaaf het, ruil die callback by /oidc/callback die magtigingskode in, valideer die ID token en skep of werk die gebruiker by.

JIT-voorsiening: Beide SAML- en OIDC-vloeie ondersteun just-in-time-voorsiening, wat standaard af is op elke verbinding (Aktiveer JIT-voorsiening). Wanneer dit aan is en die gebruiker nog nie in die huurder bestaan nie, word hulle outomaties geskep uit die identiteitsverskaffer se eise. As hulle wel bestaan, word hul profieleienskappe opgedateer om die nuutste waardes van die verskaffer te weerspieël.

Backend-for-Frontend (BFF)

'n BFF hou OAuth-tokens heeltemal uit die blaaier uit. Jou enkelbladsy-toepassing hou niks meer as 'n httpOnly-sessiekoekie nie, en 'n vertroulike client op jou eie bediener doen die OpenID Connect-vloei en hou die tokens bedienerkant.

Enigiets wat 'n enkelbladsy-toepassing kan lees, kan kruisterrein-skripting steel, en dit sluit 'n access token in geheue en 'n refresh token in localStorage in. Om tokens in die blaaier te stoor, beperk ook hul lewensduur, want 'n langlewende refresh token binne bereik van skrifte is 'n staande risiko. Die IETF se beste huidige praktyk, OAuth 2.0 for Browser-Based Apps, beveel hierdie patroon om presies daardie rede aan.

In ruil kry jy 'n sessie wat 'n bladsyherlaai kan oorleef sonder dat 'n token te sien is, verversing wat bedienerkant vir jou hanteer word, onmiddellike herroeping deur agterkanaal-afmelding, en 'n gestaafde proxy sodat jou API nooit 'n token hoef te ontleed wat die blaaier kon gemanipuleer het nie.

Skep die client

Maak Clients in die portaal oop en kies Skep BFF-app. Gee dit die basis-URL waarvandaan jou toepassing bedien word, byvoorbeeld https://app.acme.com, en Authagonal registreer 'n korrek opgestelde vertroulike client vir jou eerder as om jou dit self te laat saamstel:

Koppel dit aan jou bediener

Twee looptydomgewings word ondersteun en deel dieselfde kernprotokol: Authagonal.Bff vir .NET en @authagonal/bff vir Node, laasgenoemde met adapters vir Express en Next.js. Rig enige van die twee op die waardes wat die portaal pas vir jou gegee het. Die Node-pakket benodig ook 'n eie cookieSecret, wat dit gebruik om sy koekies te enkripteer.

// dotnet add package Authagonal.Bff
builder.Services.AddAuthagonalBff(o =>
{
    o.Authority    = "https://acme.authagonal.io";       // your tenant auth host
    o.ClientId     = builder.Configuration["Bff:ClientId"]!;
    o.ClientSecret = builder.Configuration["Bff:ClientSecret"]!;
    o.Scope        = ["openid", "profile", "email", "offline_access"];
    o.PostLogoutRedirectUri = "https://app.acme.com/";
});

// Trust X-Forwarded-Proto from your ingress. With no options, UseForwardedHeaders() changes nothing.
builder.Services.Configure<ForwardedHeadersOptions>(o =>
{
    o.ForwardedHeaders = ForwardedHeaders.XForwardedProto;
    o.KnownNetworks.Clear();
    o.KnownProxies.Clear();
});

var app = builder.Build();

app.UseForwardedHeaders();   // required behind a proxy or ingress, see the note below
app.MapAuthagonalBff();
app.MapFallbackToFile("index.html");   // your SPA
app.Run();

// npm install @authagonal/bff
import express from 'express';
import { authagonalBff } from '@authagonal/bff/express';

const app = express();

app.use(authagonalBff({
  authority: 'https://acme.authagonal.io',
  clientId: process.env.BFF_CLIENT_ID,
  clientSecret: process.env.BFF_CLIENT_SECRET,
  cookieSecret: process.env.BFF_COOKIE_SECRET,   // encrypts the session and login cookies
  scope: ['openid', 'profile', 'email', 'offline_access'],
  postLogoutRedirectUri: 'https://app.acme.com/',
}));

app.listen(8080);

Eindpunte

Word by verstek onder /bff gemonteer. Hulle moet vanaf dieselfde oorsprong as jou SPA bedien word, want die sessiekoekie is httpOnly en dieselfde-oorsprong: plaas hulle agter dieselfde gasheernaam eerder as op 'n aparte API-domein.

Vanuit die blaaier

Elke versoek wat nie 'n navigasie is nie, moet 'n statiese anti-vervalsing-opskrif dra. Dit verdedig saam met die koekie se SameSite-attribuut teen kruisterrein-versoekvervalsing: 'n kruisterrein-vormplasing kan nie 'n pasgemaakte opskrif stel nie, so 'n versoek daarsonder word geweier.

const me = await fetch('/bff/user', {
  headers: { 'X-Authagonal-Bff': '1' },
}).then(r => r.json());

if (!me.isAuthenticated) {
  // Navigate, do not fetch: this is a redirect to your identity provider.
  window.location.href = '/bff/login?returnUrl=' + encodeURIComponent(location.pathname);
}

Meld aan en af deur te navigeer, nie met 'n haalversoek nie: location.href = '/bff/login'. Daardie roetes antwoord met 'n herverwysing na jou identiteitsverskaffer, en 'n herverwysingsketting is nie iets wat fetch sinvol kan volg nie.

Om jou API te roep

Die BFF kan jou API onder sy eie basispad aanstuur en die sessie se access token op pad deur aanheg. Die blaaier stuur 'n koekie, jou API ontvang 'n bearer token wat dit normaalweg valideer, en niks van daardie token is vir die bladsy sigbaar of deur die bladsy vervalsbaar nie. Registreer 'n stroomop-diens en versoeke na /bff/api/** bereik dit gestaaf. Laat die lys leeg en die proxy is heeltemal gedeaktiveer.

o.Upstreams.Add(new BffUpstream
{
    Prefix        = "/orders",                        // matches /bff/api/orders/**
    TargetBaseUrl = "https://api.internal.acme.com",
    StripPrefix   = false,                            // keep /orders in the forwarded path
});

WebSockets

'n WebSocket-handdruk kan nie 'n pasgemaakte opskrif of 'n bearer token dra nie, so nóg die anti-vervalsing-opskrif nóg die proxy help. Aktiveer kaartjies en die SPA kan GET /bff/ws-ticket roep, die kortlewende eenmalige kaartjie op die verbind-URL sit, en jou API dit laat inlos. Munt een net voor elke verbinding: dit word met die eerste gebruik geskrap en verval binne sekondes.

Om doelbewus 'n token aan die blaaier te gee

Die hele punt van 'n BFF is dat die blaaier geen token hou nie, so dit moet doelbewus geaktiveer word en is eng afgebaken. Dit bestaan vir die een geval wat die koekiemodel nie kan bereik nie: 'n hulpbronbediener op 'n ander oorsprong, soos 'n toepassing wat jy in 'n iframe insluit, wat met 'n bearer geroep moet word. Wanneer dit geaktiveer is, gee GET /bff/token?resource=… 'n uitgeruilde token terug: die sessie se token, afgeskaal na een hulpbron op die toelaatlys en gebind aan enige konteksparameter op die toelaatlys. Die blaaier sien nooit die sessie se eie token nie, en wat dit wel kry, is kortlewend en het 'n enkele audience. 'n Versoek wat 'n hulpbron buite die toelaatlys noem, word geweier, en dit is wat verhoed dat dit 'n algemene muntery word.

Om verskeie huurders vanaf een BFF te bedien

Stel 'n huurder-navraagparameter en een ontplooiing bedien baie huurders: /bff/login?slug=acme kies die huurder, 'n oplosser verskaf daardie huurder se authority en client-geloofsbriewe, die sleutel ry op die korrelasiekoekie tot in die sessie, en agterkanaal-afmelding los die huurder op uit die token se uitreiker. Die verstek-oplosser hou enkelhuurder-gedrag greep-identies, so jy betaal niks hiervoor tensy jy dit gebruik nie.

Om meer as een instansie te loop

Sessies leef agter IBffSessionStore, wat by verstek 'n in-proses-kas is. Dit is reg vir 'n enkele instansie en verkeerd vir meer as een: 'n gebruiker wie se volgende versoek op 'n ander replika beland, word afgemeld. Registreer 'n gedeelde stoor, soos Redis deur IDistributedCache, voordat jy die BFF byvoeg.

Opsies wat die moeite werd is om te ken

Die volledige stel, in die .NET-spelling. Die Node-pakket neem die kernopsies in camelCase, so BasePath is basePath en SessionLifetime is sessionLifetimeSeconds. PersistentCookie, CorrelationLifetime (vas op 15 minute in Node) en LoginPassthroughParams is slegs .NET.

Bestuur jou portaal vanaf 'n KI-assistent

Koppel 'n KI-assistent aan jou huurder en vra dit om die dinge te doen wat jy andersins self sou deurklik: vind 'n gebruiker wat nie kan aanmeld nie, kontroleer of hulle nog 'n tweede faktor het, nooi iemand, sien wie 'n admin-rol hou.

Dit is 'n gewone OAuth-verbinding, nie 'n API-sleutel nie. Elke persoon meld as hulself aan en keur die toegang goed, dus kan 'n assistent presies doen wat daardie persoon in die portaal kan doen, en niks meer nie. Niks nuuts word geskep wat kan uitlek nie, en om een assistent te herroep laat almal anders onaangeraak.

Om dit aan te skakel

Maak Instellings oop en aktiveer KI-assistenttoegang. Dit is af totdat jy dit doen, en terwyl dit af is bestaan die eindpunt nie, eerder as dat dit bloot weier. Sodra dit aan is, wys die paneel die URL wat jy in jou KI-client moet plak:

https://portal-api.authagonal.io/api/v1/mcp/{your-tenant}

Wat 'n assistent kan doen

Presies wat die persoon wat dit gekoppel het kan doen, per oproep teen hul eie token besluit. 'n tenant:support-agent kry die diagnostiese en alledaagse hulpmiddels; die admin-hulpmiddels word nie bloot vir hulle weggesteek nie, dit word geweier as dit direk genoem word. Enigiets wat binne die portaal beperk is bly beperk: om 'n gebruiker se e-posadres te verander verg daar die admin-rol, en dit verg dit hier ook.

Omdat dit 'n gewone grant is, bestuur jy dit op die gewone manier: verwyder die assistent op die Gemagtigde Toepassings-bladsy van jou rekening en dit kan nie meer verfris nie, so dit hou op werk wanneer sy huidige access token verval. Elke verandering wat 'n assistent maak, word in jou ouditlys aangeteken as die persoon vir wie dit opgetree het, dus is die spoor dieselfde een wat jy reeds lees.

Die hulpmiddels

Drie-en-dertig in hierdie vrystelling. Jou KI-client besluit watter aangeskakel word, dus kan jy 'n assistent net die leeshulpmiddels gee as dit al is wat jy dit wil laat doen.

Wat nog nie ingesluit is nie

Die verwydering van gebruikers, die skep of redigeer van SSO-verbindings, fakturering, rugsteune en client secrets ontbreek almal in hierdie vrystelling. Verwydering hoort saam met jou uitwissingstou, eerder as langs dit; 'n SSO-verbinding is groot genoeg dat een verkeerde redigering 'n hele werksmag uitsluit, dus is daardie een voorlopig leesalleen; en 'n hulpmiddel wat 'n client secret teruggee sou dit in 'n assistent se transkripsie plaas. Sê vir ons watter van hierdie jy wil hê en in watter volgorde.

MCP-bediener-verifikasie

As jy 'n Model Context Protocol-bediener blootstel, kan Authagonal die magtigingsbediener daaragter wees. 'n KI-assistent koppel, die persoon daaragter meld aan en verleen toegang, en jou bediener ontvang 'n gewone bearer token wat jy soos enige ander API valideer.

Die alternatief is 'n API-sleutel wat in 'n assistent se konfigurasie geplak word, en dit is 'n geloofsbrief met geen gebruiker daaragter nie, geen vervaldatum nie, geen toestemmingstap nie, en geen manier om een koppelaar te herroep sonder om vir almal te roteer nie. Om dit as OAuth te doen, beteken die grant behoort aan 'n benoemde persoon, is sigbaar in jou ouditlys, en kan vanaf die portaal herroep word sonder om aan enigiets anders te raak.

Hoe die verbinding tot stand kom

Die hele uitruil word deur ontdekking gedryf, dus het 'n konforme client niks gekonfigureer nodig behalwe jou bediener se URL nie.

Niks in daardie volgorde is Authagonal-spesifiek nie: dit is die MCP-magtigingspesifikasie, gebou op RFC 9728 vir die hulpbronmetadata, RFC 8414 om die magtigingsbediener te ontdek, RFC 7591 vir registrasie en RFC 8707 om die hulpbron te noem. 'n Koppelaar wat die spesifikasie volg, werk sonder om ons as 'n spesiale geval te hanteer.

Laat koppelaars hulself registreer

'n Koppelaar wat jy nog nooit teëgekom het nie, kan nie 'n client gebruik wat jy met die hand geskep het nie, dus registreer dit een tydens looptyd. Dit is by verstek af. Skakel dinamiese client-registrasie in Instellings aan en die registrasie-eindpunt verskyn in jou ontdekkingsdokument; laat dit af en die eindpunt word nie geadverteer nie en weier. Om dit te aktiveer, open registrasie vir jou huurder alleen, nooit vir iemand anders s'n nie.

Wat jou MCP-bediener implementeer

Twee klein dingetjies, en daarna is dit 'n gewone hulpbronbediener. Eerstens, publiseer beskermde-hulpbron-metadata wat jou huurder as die magtigingsbediener noem. Bedien dit by die well-known-pad en, as jou MCP-eindpunt op 'n subpad is, ook in die pad-agtervoegselvorm, want clients probeer albei.

GET https://your-app.example/.well-known/oauth-protected-resource

{
  "resource": "https://your-app.example/mcp",
  "authorization_servers": ["https://acme.authagonal.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"]
}

Tweedens, wanneer 'n oproep sonder 'n geldige token aankom, antwoord 401 met 'n WWW-Authenticate-kopstuk wat na daardie metadata wys. Daardie kopstuk is wat 'n weiering in 'n verbinding verander: daarsonder het die client geen manier om te ontdek waar om te verifieer nie, en misluk eenvoudig.

// Validate the connector's token like any other resource server.
builder.Services.AddAuthentication().AddJwtBearer("McpBearer", o =>
{
    o.Authority = "https://acme.authagonal.io";              // your tenant
    o.TokenValidationParameters.ValidAudience = "https://your-app.example/mcp";
});

// Unauthenticated? Point the connector at the metadata rather than just refusing.
http.Response.Headers.WWWAuthenticate =
    "Bearer resource_metadata=\"https://your-app.example/.well-known/oauth-protected-resource\"";
return Results.Unauthorized();

Scopes, planne en herroeping

Definieer 'n scope genaamd mcp op jou Scopes-bladsy, sonder rolbeperkings, en 'n self-registrerende koppelaar mag dit versoek; dit verskyn op die toestemmingskerm sodat die gebruiker kan sien wat hulle goedkeur. Die token se subjek is die persoon wat aangemeld het, sodat jou bediener kan besluit wat hierdie spesifieke persoon mag doen eerder as om elke koppelaar eenders te behandel. 'n Self-geregistreerde koppelaar kan nie die roles- of groups-scopes versoek nie, so soek dit aan jou kant op eerder as om dit in die token te verwag.

Omdat dit 'n gewone OAuth-grant is, werk herroeping op die gewone manier: die gebruiker verwyder die koppelaar op die Gemagtigde Toepassings-bladsy van hul rekening, wat sy grant en refresh token laat val sodat dit nie kan hernu nie. Sy bestaande access tokens word dadelik deur /connect/introspect en /connect/userinfo geweier; 'n bediener wat die JWT slegs plaaslik valideer, aanvaar een totdat dit verval. Die ouditlys teken elke aanmelding aan saam met die client waarvoor dit was.

Bou 'n pasgemaakte aanmeld-UI

Vervang Authagonal se aangebode aanmeld-, registrasie-, wagwoordherstel- en MFA-skerms met jou eie UI, terwyl Authagonal steeds stawing, MFA, SSO, sessies en token-uitreiking hanteer. Twee opsies: gebruik ons React-komponentbiblioteek, of roep die auth API direk vanuit enige raamwerk. Dit is opt-in: aktiveer eers Pasgemaakte aanmeld-UI onder Instellings → Sessie.

Vereiste: 'n pasgemaakte domein op jou wortel

Die aanmeldsessie is 'n eerste-party-koekie, sodat jou UI en die Authagonal-auth-bediener 'n registreerbare domein moet deel. Wys 'n pasgemaakte auth-domein na Authagonal op dieselfde wortel as jou toepassing — bv. auth by login.acme.com, toepassing by app.acme.com. Die Pasgemaakte aanmeld-UI-instelling bly gedeaktiveer totdat 'n aktiewe pasgemaakte domein bestaan.

Geen client-CORS-instelling is nodig vir die /api/auth-oproepe nie: sodra Pasgemaakte aanmeld-UI aan is, word enige oorsprong op dieselfde registreerbare domein as jou auth-domein outomaties toegelaat. Voeg jou UI se oorsprong (bv. https://app.acme.com) slegs by die client se Toegelate CORS-oorspronge (Clients → URIs) as die blaaier ook die token-uitruiling doen.

React: @authagonal/login

npm i @authagonal/login lewer die auth-logika en UI as een pakket — dieselfde as waarop Authagonal se aangebode aanmelding gebou is. Kies jou vlak:

• Volledige toepassing — sit App in en temeer dit via handelsmerking.
• Stel bladsye saam — gebruik LoginPage, MfaChallengePage, ResetPasswordPage… binne jou eie uitleg.
• Primitiewe + logika — bou jou eie skerms met AuthLayout/Button/Input en die API-kliënt (login, mfaVerify, forgotPassword, …).

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

// returnUrl: the /connect/authorize URL your login page was opened with
function MyLogin({ returnUrl }: { returnUrl: string }) {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login(email, password, returnUrl);  // POST /api/auth/login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step, then mfaVerify(res.challengeId!, 'totp', code) */}
      else if (res.mfaSetupRequired) {/* enrol first: mfaTotpSetup(res.setupToken) */}
      else window.location.href = returnUrl;                 // resume /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message; e.error is the error code */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

Enige raamwerk: roep die auth API

Nie op React nie? Roep die auth-vloei-eindpunte direk (onder /api/auth), gee dan oor aan die standaard OIDC /connect/authorize-vloei. Stuur credentials: 'include' sodat die sessiekoekie gestoor word.

# 1. Authenticate (browser fetch; credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"[email protected]","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow: top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

Een Huurder, Baie Kliënte

'n Patroon vir een integreerder, een huurder en N gebrandmerkte kliënte, elk met hul eie aanmelddomein en hul eie gebruikers, sonder 'n huurder per kliënt. Dit is waarvoor deklaratiewe voorsiening en organisasies bestaan: om dit 'n konfigurasieverandering te maak in plaas van 'n ingenieurstaak.

Die vorm

• Een organisasie per kliënt, binne 'n enkele huurder.
• Een gebrandmerkte aanmelddomein per kliënt, elk vasgepen aan daardie kliënt se organisasie. Aanmelding daarop kan net ooit 'n token vir daardie organisasie maak.
• Die toepassing word ook per kliëntgasheer bedien, alles vanaf dieselfde ontplooiing. Niks aan die kode, bou of image verskil tussen kliënte nie.
• Die relying party kies sy authority volgens die gasheer waarop dit loop, nie volgens 'n boutydkonstante nie. Dieselfde bundel koppel homself aan 'n ander aanmelddomein, afhangend van watter kliëntgasheer dit bedien het.

Stap vir stap

Voorsien die kliënt. Roep die deklaratiewe voorsiening-eindpunt aan met 'n spesifikasie wat die nuwe organisasie en sy domein noem. Die oproep is idempotent en afdeling-omvat.

{
  "organizations": [
    { "slug": "acme", "name": "Acme Pty Ltd" }
  ],
  "customDomains": [
    { "domain": "login.acme.example", "organizationSlug": "acme" }
  ]
}

Wys die kliënt se DNS na die huurder. Een CNAME vanaf die kliënt se eie sone, wat beheer en voorneme bewys, geen TXT-token nie.

_authagonal-challenge.login.acme.example.  CNAME  <slug>.<platformDomain>.

Wys die toepassing na die kliënt se gasheer. Die relying party los sy eie OIDC-authority per versoek op, volgens die gasheer wat dit tans bedien. 'n Gasheer sonder inskrywing in die kliëntekaart val terug op die klassieke enkelhuurder-afleiding, so om 'n kliënt by te voeg is suiwer additief.

export function resolveCustomer(): { authority: string; clientId: string } {
  const cfg = getConfig();
  const customer = cfg.customers?.[window.location.host];
  if (customer) return customer;
  const baseDomain = cfg.baseDomain || window.location.hostname.replace(/^consumer\./, '');
  return { authority: `https://${cfg.tenantSlug}.${baseDomain}`, clientId: cfg.clientId };
}

Die client vra vir niks organisasie-spesifiek nie: geen organization-parameter, geen per-kliënt-scope nie. Die domeinpen doen die organisasiekeuse geheel en al bedienerkant, wat "die toepassing is dieselfde kode vir elke kliënt" werklik waar maak.

Wat die kliënt sien

Die aanmeldbladsy wys elke organisasie se eie handelsmerk saamgevoeg oor die huurder s'n. Sien Handelsmerk-oorheersing. Elke kliënt kan sy eie toepassingsnaam, logo, kleur en ondersteunings-e-pos hê sonder om die ander te raak.

'n Gebruiker van kliënt A wat probeer aanmeld op kliënt B se gasheer word geweier en kry nie kliënt B se data te sien nie, in een van twee vorme, afhangend van hoe die konflik ontstaan het:

• Die relying party stuur niks en beland net op die vasgepende domein. Die pen verskaf die organisasie namens die gebruiker, keuse is dan uitdruklik, en 'n kliënt-A-gebruiker sonder lidmaatskap in B word geweier op die punt waar die token gemaak sou word.
• Die relying party noem self 'n ander organisasie. Dit word direk deur die domeinpen-middleware met 'n 400 geweier, voordat enige aanmeldbladsy getoon word.

Inskakeling van kliënt N+1

Met Terraform wat die voorsieningsoproep aandryf, is die inskakeling van nog 'n kliënt 'n wysiging aan een lêer: nog 'n inskrywing in die organizations-skikking, nog 'n domeininskrywing wat dit vaspen, nog 'n DNS-rekord. Niks aan die toepassing, sy ontplooiing of sy bou verander nie. Die gasheergebaseerde resolver tel die nuwe kliënt op die oomblik op wanneer sy konfigurasie-inskrywing bestaan.

Verwysingsimplementering

'n Aanhoudende dev-huurder oefen hierdie hele patroon van begin tot einde teen twee werklike kliëntdomeine uit, met 'n end-to-end-toetsstel wat lede voorsien, handelsmerk en die org_id-claim nagaan, en albei weieringsvorme hierbo bevestig: uitvoerbare dokumentasie, nie net 'n beskrywing nie.

cd e2e-consumer && DOMAIN=authagonal.dev npx playwright test organizations-domains

Die toetsstel loop by verstek soos elke ander spec; dit kan oorgeslaan word in 'n omgewing waar die verwysingsdomeine nie voorsien is nie, aangesien dit die een spec in die stel is wat afhang van infrastruktuur buite die repo se eie beheer.

Planne & Limiete

Authagonal bied 'n Gratis-plan en vier betaalde vlakke aan. Elke plan sluit elke stawingsfunksie in. Planne verskil in die Maandelikse Aktiewe Gebruiker (MAU)-limiet en oorskrydingsprysing, en die Gratis-plan het slegs gemeenskapsondersteuning, sonder die huurder-ondersteuningstoonbank.

Plantrae

Maandelikse Aktiewe Gebruikers (MAU)

'n Maandelikse Aktiewe Gebruiker is enige unieke gebruiker wat minstens een keer suksesvol verifieer tydens 'n kalendermaand (UTC). Gebruikers wat via SCIM voorsien is maar nie aangemeld het nie, tel nie teen jou MAU-totaal nie.

Oorskryding: as jou plan oorskryding ondersteun (Pro en hoër) en oorskryding vir jou huurder geaktiveer is (dit is standaard af), word gebruikers bo die MAU-limiet gefaktureer teen die per-gebruiker-tarief in die plantabel hierbo. 'n Oorskrydingsgrens stel die maksimum aantal ekstra gebruikers wat bo die limiet toegelaat word.

Handhawing: as jou plan nie oorskryding ondersteun nie (Gratis, Starter) of oorskryding nie geaktiveer is nie, behou gebruikers wat reeds hierdie maand aangemeld het altyd toegang. Wanneer die huurder sy limiet die eerste keer oorskry, begin 'n grasietydperk van 10 dae waartydens nuwe gebruikers steeds kan aanmeld. Daarna word gebruikers wat nie hierdie maand aangemeld het nie, geweier tot die volgende maand of totdat jy opgradeer.