Kontrollen für öffentlichen Zugriff
Standardmäßig hat ein öffentlicher Space keine Authentifizierungsmethode, aber Sie können einige auswählen und einstellen:
- Space-weites Passwort;
- Gastkonten, bei denen Sie E-Mail- + Passwort-Kombinationen manuell erstellen und an Ihre Nutzer verteilen;
- Magische Links, bei denen Sie bestimmte E-Mails oder ganze Domains eingeben und sich Nutzer über einen Link authentifizieren, den wir an ihre E-Mail-Adresse senden;
- Private Konten, bei denen Sie bestimmte Domains hinzufügen, um Nutzern die Authentifizierung/Accounterstellung mit ihrer E-Mail-Adresse zu ermöglichen
- Private Links, bei denen Sie private Links generieren und sie mit Ihren Nutzern und Teams teilen können. Verwalten Sie die Zugriffskontrolle pro Nutzergruppe über Links;
- JWT, bei denen Ihr Dev-Team ein JWT mit einem geheimen Schlüssel generiert, den Sie in unserer UI bereitstellen, und es uns dann als Teil eines Links übergibt. Dies ist am einfachsten zu verwalten, erfordert jedoch Entwicklerzeit.
- SAML, wenn Sie eine externe Anwendung haben, die als Router zu Ihrer Space-Domain fungieren kann, sodass das öffentliche Portal nur von Mitgliedern aufgerufen werden kann, die in Anbietern wie Google, Azure, Okta hinterlegt sind.
Keine
Das Standardverhalten ist auf Keine gesetzt, was bedeutet, dass es öffentlich verfügbar ist. Sie können zu Kontrollen wechseln, um den Zugriff für Leser einzuschränken.
Jeder mit dem Link kann Inhalte lesen.
Links sind sicher zu teilen, da sie kryptografisch generiert und nicht erratbar sind.
Wenn Sie Inhalte für bestimmte Leser beschränken möchten, probieren Sie eine der folgenden Optionen aus.
Gastkonten
Erstellen Sie Gastkonten. Jeder mit dem Link und einem Gastkonto kann den Inhalt lesen. Gastkonten werden in Archbee nicht als Seats berechnet.
Private Accounts
Nutzer können sich mit ihrer E-Mail-Adresse/Ihrem Passwort in Ihrem Space authentifizieren/ein Konto erstellen, wenn Sie ihre E-Mail-Adresse oder deren Domain zur Liste unten hinzufügen.
Jeder mit dem Link und einem passenden Konto kann den Inhalt lesen. Konten werden in Archbee nicht als Seats berechnet.
Die Liste der Nutzer mit aktiven Konten wird im Fenster 'Aktive Konten' angezeigt.
Magic Link
Nutzer können sich mit ihrer E-Mail-Adresse in Ihrem Space authentifizieren, wenn Sie ihre E-Mail-Adresse oder deren Domain zur Liste unten hinzufügen. Jeder mit dem Link und einem passenden Konto kann den Inhalt lesen. Konten werden in Archbee nicht als Seats berechnet.
Private Links
Generieren Sie Private Links für bestimmte Nutzergruppen/Teams. Jede Nutzergruppe/jedes Team hat ihren eigenen Link zur gleichen Dokumentation, und Sie können die Zugriffskontrolle über diese Links verwalten. Sie müssen den Zugriff für Team 1 entfernen? Löschen Sie den privaten Link, der Team 1 zugeordnet ist.
Wie JWT funktioniert
JWT - geheime Besucher-Authentifizierung
Gehen Sie zu den Spaces Einstellungen und legen Sie einen JWT-Secret-Key fest, den Sie auf Ihrem Server generieren
JSON WEB Key Besucher-Authentifizierung
Gehen Sie zu den Spaces Einstellungen und legen Sie eine JSON WEB Key Set URL fest. Eine JSON Web Key Set (JWKS) URL ist ein URL-Endpunkt, an dem ein Server seine öffentlichen Schlüssel im JSON-Format veröffentlicht.
Die JWKS URL verweist typischerweise auf ein JSON-Dokument, das ein Array kryptografischer Schlüssel enthält, die zur Überprüfung von Signaturen verwendet werden.
Wenn Archbee ein JWT erhält, kann es den entsprechenden öffentlichen Schlüssel von der JWKS URL abrufen und verwenden, um die Signatur des JWT zu überprüfen. Dadurch wird sichergestellt, dass das Token nicht manipuliert wurde und tatsächlich von einer vertrauenswürdigen Stelle ausgestellt wurde.
Eine JWKS URL bietet eine standardisierte Möglichkeit für Clients, die öffentlichen Schlüssel zu erhalten, die zur Überprüfung von JWT-Signaturen in sicherer und skalierbarer Weise benötigt werden.
Dies ist eine Beispiel-jwks.json Datei:
{
"keys": [{
"kid": "1234example=",
"alg": "RS256",
"kty": "RSA",
"e": "AQAB",
"n": "1234567890",
"use": "sig"
}, {
"kid": "5678example=",
"alg": "RS256",
"kty": "RSA",
"e": "AQAB",
"n": "987654321",
"use": "sig"
}]
}JWT-Token generieren
Verwenden Sie eines der folgenden Beispiele, um den JWT-Token zu generieren.
Sie müssen außerdem die URL durch die Subdomain Ihrer Dokumentationsseite ersetzen.
const sign = require('jsonwebtoken').sign;
exports.buildArchbeeLoginURL = function() {
// Optional user credentials that you want to send back to Archbee
const user = {
name: 'John',
email: 'Wick',
};
//create a signed token out of the user credentials with the
//secret you set in Archbee
const jwtToken = sign(user, '<archbeeJwtSecret>');
//yourdomain is set in the Custom Domain tab
const archbeeUrl = 'https://yourdomain.com';
//create the complete URL containing the signed token that you'll send back to Archbee
return `${archbeeUrl}?jwt=${jwtToken}&reload`;
};Hier ist ein Beispiel, um einen JWT-Token mit .NET zu generieren: https://github.com/dragosbulugean/archbee-jwt-dotnet
using JWT;
using JWT.Algorithms;
using JWT.Serializers;
var payload = new Dictionary<string, object>
{
{ "name", "John Wick" },
{ "email", "[email protected]" }
};
const string secret = "TW9zaGVFcmV6UHJpdmF0ZUtleQ";
IJwtAlgorithm algorithm = new HMACSHA256Algorithm(); // symmetric
IJsonSerializer serializer = new JsonNetSerializer();
IBase64UrlEncoder urlEncoder = new JwtBase64UrlEncoder();
IJwtEncoder encoder = new JwtEncoder(algorithm, serializer, urlEncoder);
var jwtToken = encoder.Encode(payload, secret);
var archbeeLink = $"https://docs.yourcompany.com/?jwt={jwtToken}&reload";
Console.WriteLine($"JWT Token: {jwtToken}");
Console.WriteLine($"Archbee Link: {archbeeLink}");JWT-Tokens werden in Preview/Staging umgangen
SAML - Security Assertion Markup Language
SAML kann für den Zugriff auf öffentliche Spaces auf die gleiche Weise konfiguriert werden wie für die Team-Integration, siehe SAML‑Integration für detailliertere Schritte zur Einrichtung der einzelnen Anbieter.
Beachten Sie, dass nur die Metadata-URL als Eingabe benötigt wird. Außerdem wird vorausgesetzt, dass der Space bereits auf einer benutzerdefinierten Domain gehostet wird.
Auf diese Weise wird der veröffentlichte Space-Link über die neue SAML-Anwendung geleitet; daher können nur in der Provider-Anwendung eingerichtete Mitglieder auf das öffentliche Portal zugreifen.
So richten Sie SAML als öffentliche Zugriffskontrolle ein
Gehen Sie zu Azure Services -> Microsoft Entra ID -> "+Add" -> App registration
Wählen Sie "Accounts in this organizational directory only -Single tenant" und fügen Sie die CallBack URL aus Archbee Space Settings ->Public Access Control -> SAML in "Redirect URI" ein, wie im folgenden Bild dargestellt, und wählen Sie Web auth:
Klicken Sie auf "Register"
Gehen Sie in der neu erstellten App in Azure zu "Endpoints" und kopieren Sie das "Federation metadata document" aus der Azure App in die Archbee Space Settings -> Public Access Control -> SAML in die "Set SAML Metatada URL"
Eine eindeutige Entity ID wird in Archbee generiert, kopieren Sie den Link "api://PUBLISHED..." in Ihrer Azure App - Expose an API -> Add -> URL ausfüllen -> Speichern
Gehen Sie zu Ihrem Archbee Space und veröffentlichen Sie ihn erneut
Versuchen Sie, auf den Link zuzugreifen, und testen Sie die SAML-Authentifizierung
Vorschau-Einstellungen
Diese Funktion ermöglicht es Ihnen, Authentifizierungseinstellungen in einer kontrollierten Vorschauumgebung zu simulieren, bevor diese für interne Benutzer live gehen.
Zweck
Aktivieren Sie diese Einstellung, um Authentifizierungsschutz auf Ihre Vorschauumgebung anzuwenden, wodurch der Zugriff auf nur interne Benutzer beschränkt wird. Dies hilft Ihnen, Ihre Auth-Konfigurationen, Benutzerzugriffsabläufe und Schutzeinstellungen zu überprüfen, ohne Änderungen öffentlich sichtbar zu machen.
So aktivieren Sie es
- Navigieren Sie zum Bereich Public Access Control, während Sie sich in Space Settings befinden
- Wählen Sie beliebige Authentifizierungsmethoden aus
- Schalten Sie die Vorschau‑Einstellungen aus
- Veröffentlichen Sie Ihre Änderungen in der Vorschau und testen Sie die Authentifizierung
Mehrfach-Authentifizierung
Die Mehrfach-Authentifizierung ermöglicht es Ihnen, mehr als eine Authentifizierungsmethode für den Zugriff auf Ihr Dokumentationsportal zu aktivieren. Dies gibt Ihren Benutzern Flexibilität und verbessert die Zugänglichkeit.
Funktionsweise
In den Public Access Control Einstellungen können Sie mehrere Authentifizierungsmethoden gleichzeitig aktivieren. Benutzer, die auf Ihr Portal zugreifen, können sich mit einer der aktivierten Methoden authentifizieren.
Beispielanwendungsfall
Wenn Sie sowohl Privater Link als auch Passwort aktivieren, können Benutzer mithilfe einer der beiden Optionen auf Ihre Dokumentation zugreifen:
- Einem sicheren privaten Link, den Sie ihnen bereitstellen
- Oder einem gemeinsamen Passwort, das Sie festlegen
Nur Benutzer, die eine der aktivierten Authentifizierungsmethoden erfüllen, erhalten Zugriff. Sie können jede Methode jederzeit über den Umschalter in den Public Access Control Einstellungen deaktivieren.