Zum Hauptinhalt springen

Casdoor als Open-Source-SAML-2.0-Identitätsanbieter (IdP)

Casdoor ist ein SAML 2.0-Identitätsanbieter (IdP). Diese Seite erklärt, was Sie im Diensteanbieter (SP) und in Casdoor konfigurieren müssen und welche Benutzerdaten die SAML-Antwort enthält. Schritt-für-Schritt-Anleitungen für bestimmte Diensteanbieter finden Sie auf den anderen Seiten dieses Abschnitts.

Den Diensteanbieter konfigurieren​

Ein Diensteanbieter fragt typischerweise nach drei Werten: der Single Sign-On-URL, dem Issuer und dem öffentlichen Zertifikat des IdP. Die meisten Diensteanbieter lesen alle drei Werte aus den SAML-Metadaten des IdP, entweder per URL oder aus einer hochgeladenen Datei.

Die Metadaten-URL einer Casdoor-Anwendung lautet:

<casdoor-host>/api/saml/metadata?application=admin/<application-name>

Zum Beispiel für Casdoor unter https://door.casdoor.com und die Anwendung app-built-in:

https://door.casdoor.com/api/saml/metadata?application=admin/app-built-in

Um die URL in der Casdoor-Administratorkonsole zu erhalten, öffnen Sie die Bearbeitungsseite der Anwendung, gehen Sie zum Tab SAML und klicken Sie auf Copy SAML metadata URL. Um die Metadaten als XML-Datei herunterzuladen, öffnen Sie die URL in einem Browser.

SAML metadata of the application

Die Casdoor-Anwendung konfigurieren​

Legen Sie auf der Bearbeitungsseite der Anwendung zwei Felder fest:

FieldWert
Redirect URLsThe identifier of the service provider, which the SP calls the audience or the entity ID. Enter exactly the same value as in the SP
SAML reply URLDie Assertion Consumer Service (ACS)-URL des SP, die die SAML-Antwort empfängt und überprüft. Lassen Sie das Feld leer, um das Redirect-Binding zu verwenden

Redirect URLs field with the entity ID

SAML reply URL field

Response-Binding​

Casdoor kann die SAMLResponse über eine HTTP-POST-Anfrage oder eine HTTP-GET-Anfrage senden. Wählen Sie das Verfahren, das Ihr Diensteanbieter unterstützt:

SAML reply URLBindingWhere Casdoor sends the response
SetPOSTTo the reply URL. The reply URL overrides the AssertionConsumerServiceURL of the SAMLRequest
EmptyGETTo the AssertionConsumerServiceURL that Casdoor reads from the SAMLRequest
Notiz

Wenn Casdoor selbst Benutzer bei einem externen SAML-IdP, wie z. B. Azure AD, anmeldet, sendet das externe IdP seine SAML-Antwort an den /api/acs-Endpunkt von Casdoor. Dieser Endpunkt akzeptiert Cross-Origin-POST-Anfragen, sodass ein IdP auf einer anderen Domain die Antwort senden kann.

Die Anmeldung von Casdoor aus starten (IdP-initiiertes SSO)​

Beim IdP-initiierten SSO beginnt der Benutzer bei Casdoor und nicht beim Diensteanbieter. Casdoor sendet dem SP eine SAML-Antwort, ohne dass ein AuthnRequest angefordert wurde. Verwenden Sie dies für Portal-Links und Lesezeichen.

  1. Legen Sie im Tab SAML der Anwendung SAML reply URL auf die ACS-URL des SP fest. Ohne diese Angabe schlägt die Anmeldung fehl mit the SAML reply URL should not be empty for IdP-initiated SSO.

  2. Stellen Sie sicher, dass der erste Eintrag von Redirect URLs die Entitäts-ID des SP ist. Casdoor verwendet sie als Audience der Assertion.

  3. Speichern Sie die Anwendung. Der Tab SAML zeigt dann die IdP-initiated SSO URL an:

    <casdoor-host>/login/saml/authorize/admin/<application-name>
  4. Klicken Sie auf Copy IdP-initiated SSO URL und geben Sie die URL an Ihre Benutzer weiter.

Ein Benutzer, der die URL öffnet, meldet sich bei Casdoor an, und Casdoor sendet die SAML-Antwort über das HTTP-POST-Binding an die Reply-URL. Die Antwort hat kein InResponseTo-Attribut, da keine vorherige Anfrage vorlag. Um einen RelayState an den SP zu übergeben, fügen Sie ihn als Abfrageparameter zur URL hinzu, beispielsweise ?RelayState=/dashboard.

Benutzer vom SP abmelden (Single Logout)​

Casdoor unterstützt SAML Single Logout (SLO) in beide Richtungen. Um es zu aktivieren, setzen Sie die SAML single logout URL im Tab SAML der Anwendung auf die SingleLogoutService-URL des SP.

Die Metadaten der Anwendung geben den SingleLogoutService von Casdoor mit den HTTP-Redirect- und HTTP-POST-Bindings an unter:

<casdoor-backend-host>/api/saml/logout/admin/<application-name>

Jede Assertion enthält einen SessionIndex in ihrem AuthnStatement, der die Casdoor-Sitzung der Anmeldung identifiziert.

SP-initiiertes Logout​

Wenn sich ein Benutzer beim SP abmeldet, sendet der SP eine LogoutRequest an den SingleLogoutService von Casdoor, per GET oder POST, im Parameter SAMLRequest und einem optionalen RelayState:

  1. Casdoor prüft die Anfrage. Ihr Issuer muss in Redirect URLs enthalten sein, sie muss eine NameID enthalten, und die Anwendung muss eine SAML single logout URL haben.
  2. Casdoor beendet die Casdoor-Sitzungen, die durch die SessionIndex-Werte der Anfrage benannt werden. Ohne einen SessionIndex beendet es nur die Browsersitzung, die die Anfrage gesendet hat, und nur wenn die NameID zu ihrem Benutzer gehört.
  3. Casdoor meldet den Benutzer bei den anderen Anwendungen dieser Sitzungen ab, über OIDC Back-Channel Logout und SAML Logout-Anfragen.
  4. Casdoor antwortet mit einer signierten LogoutResponse über das Binding der Anfrage: eine Weiterleitung zur SAML single logout URL für GET, oder ein Formular, das der Browser dort postet, für POST.

IdP-initiiertes Logout​

Wenn sich ein Benutzer bei Casdoor abmeldet, entweder über /api/logout oder über /api/sso-logout, sendet Casdoor eine signierte LogoutRequest an die SAML single logout URL jeder SAML-Anwendung, bei der sich der Benutzer in den beendeten Sitzungen angemeldet hatte. Dasselbe passiert, wenn Casdoor Sitzungen aus anderen Gründen beendet, zum Beispiel wenn einem Benutzer die Anmeldung untersagt wird oder wenn eine neue Anmeldung das Sitzungslimit überschreitet. Casdoor postet diese Anfragen vom Server aus, wie bei OIDC Back-Channel Logout, nicht über den Browser. Wenn der SP seine LogoutResponse an denselben SingleLogoutService-Endpunkt sendet, prüft Casdoor, ob ihr Issuer in Redirect URLs enthalten ist und ob ihr Status Success ist.

Benutzerprofil in der Antwort​

Standardmäßig trägt die SAMLResponse drei Attribute des Benutzers:

XML-AttributnameBenutzerfeld
E-MailE-Mail
Anzeigenameanzeigename
Bezeichnungbezeichnung

Wenn der Service Provider nur die NameID benötigt und keine Attribute, aktivieren Sie Disable SAML attributes in der Anwendung. Casdoor lässt dann die Attribute in der Antwort weg. Dies vermeidet XML-Namespace-Probleme mit Service Providern, die die Antwort streng validieren.

SAML-Attribute hinzufügen​

Wenn der Service Provider andere Attribute erfordert, fügen Sie sie der Tabelle SAML attributes der Anwendung hinzu. Ein Wert kann die folgenden Variablen enthalten: $user.owner, $user.name, $user.displayName, $user.email, $user.id, $user.phone, $user.roles, $user.permissions und $user.groups.

Zum Beispiel erzeugen die folgenden zwei Zeilen:

BezeichnungNamensformatValue
https://www.aliyun.com/SAML-Role/Attributes/RoleSessionNameUnspezifiziert$user.name
https://www.aliyun.com/SAML-Role/Attributes/RoleUnspezifiziertacs:ram::1879818006829152:role/$user.roles,acs:ram::1879818006829152:saml-provider/testa

diese Attribute in der Antwort:

<saml:Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/RoleSessionName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:string">admi122n@outlook.com</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/Role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:string"> acs:ram::1879818006829152:role/role1,acs:ram::1879818006829152:saml-provider/testa</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string"> acs:ram::1879818006829152:role/role2,acs:ram::1879818006829152:saml-provider/testa</saml:AttributeValue>
</saml:Attribute>

Kontrolle der Assertion-Signatur​

Casdoor signiert immer die SAML-Antwort. Um auch die Assertion innerhalb der Antwort zu signieren, aktivieren Sie Enable SAML assertion signature in der Anwendung. Die Option ist standardmäßig deaktiviert.

Versionen 2.81.0 bis 2.247.x haben die Assertion immer ebenfalls signiert. Einige Service Provider, wie z. B. Sentry, lehnen Antworten mit signierter Assertion ab. Seit Version 2.248.0 signiert Casdoor daher nur den Antwort-Umschlag (Envelope), es sei denn, die Option ist aktiviert. Die signierte Antwort hält die Assertion dennoch authentisch.

Testen mit einem Go-Service-Provider​

gosaml2 ist eine SAML 2.0-Implementierung für Service Provider in Go. Das folgende Programm verwendet sie, um Casdoor als IdP zu testen.

Das Beispiel geht davon aus, dass Casdoor unter http://localhost:7001/ läuft und die Anwendung app-built-in der Organisation built-in verwendet wird.

  1. Fügen Sie http://localhost:6900/acs/example und http://localhost:6900/saml/acs/example zu den Redirect URLs von app-built-in hinzu.

  2. Führen Sie das Programm aus:

    import (
    "crypto/x509"
    "fmt"
    "net/http"

    "io/ioutil"

    "encoding/base64"
    "encoding/xml"

    saml2 "github.com/russellhaering/gosaml2"
    "github.com/russellhaering/gosaml2/types"
    dsig "github.com/russellhaering/goxmldsig"
    )

    func main() {
    res, err := http.Get("http://localhost:7001/api/saml/metadata?application=admin/app-built-in")
    if err != nil {
    panic(err)
    }

    rawMetadata, err := ioutil.ReadAll(res.Body)
    if err != nil {
    panic(err)
    }

    metadata := &types.EntityDescriptor{}
    err = xml.Unmarshal(rawMetadata, metadata)
    if err != nil {
    panic(err)
    }

    certStore := dsig.MemoryX509CertificateStore{
    Roots: []*x509.Certificate{},
    }

    for _, kd := range metadata.IDPSSODescriptor.KeyDescriptors {
    for idx, xcert := range kd.KeyInfo.X509Data.X509Certificates {
    if xcert.Data == "" {
    panic(fmt.Errorf("metadata certificate(%d) must not be empty", idx))
    }
    certData, err := base64.StdEncoding.DecodeString(xcert.Data)
    if err != nil {
    panic(err)
    }

    idpCert, err := x509.ParseCertificate(certData)
    if err != nil {
    panic(err)
    }

    certStore.Roots = append(certStore.Roots, idpCert)
    }
    }

    randomKeyStore := dsig.RandomKeyStoreForTest()

    sp := &saml2.SAMLServiceProvider{
    IdentityProviderSSOURL: metadata.IDPSSODescriptor.SingleSignOnServices[0].Location,
    IdentityProviderIssuer: metadata.EntityID,
    ServiceProviderIssuer: "http://localhost:6900/acs/example",
    AssertionConsumerServiceURL: "http://localhost:6900/v1/_saml_callback",
    SignAuthnRequests: true,
    AudienceURI: "http://localhost:6900/saml/acs/example",
    IDPCertificateStore: &certStore,
    SPKeyStore: randomKeyStore,
    }

    http.HandleFunc("/v1/_saml_callback", func(rw http.ResponseWriter, req *http.Request) {
    err := req.ParseForm()
    if err != nil {
    rw.WriteHeader(http.StatusBadRequest)
    return
    }
    samlReponse := req.URL.Query().Get("SAMLResponse")
    assertionInfo, err := sp.RetrieveAssertionInfo(samlReponse)
    if err != nil {
    fmt.Println(err)
    rw.WriteHeader(http.StatusForbidden)
    return
    }
    fmt.Println(assertionInfo)
    if assertionInfo.WarningInfo.InvalidTime {
    fmt.Println("here12:", assertionInfo.WarningInfo.InvalidTime)
    rw.WriteHeader(http.StatusForbidden)
    return
    }

    if assertionInfo.WarningInfo.NotInAudience {
    fmt.Println(assertionInfo)
    fmt.Println("here13:", assertionInfo.WarningInfo.NotInAudience)
    rw.WriteHeader(http.StatusForbidden)
    return
    }

    fmt.Fprintf(rw, "NameID: %s\n", assertionInfo.NameID)

    fmt.Fprintf(rw, "Assertions:\n")

    for key, val := range assertionInfo.Values {
    fmt.Fprintf(rw, " %s: %+v\n", key, val)
    }
    fmt.Println(assertionInfo.Values.Get("FirstName"))
    fmt.Fprintf(rw, "\n")

    fmt.Fprintf(rw, "Warnings:\n")
    fmt.Fprintf(rw, "%+v\n", assertionInfo.WarningInfo)
    })

    println("Visit this URL To Authenticate:")
    authURL, err := sp.BuildAuthURL("")
    if err != nil {
    panic(err)
    }

    println(authURL)

    println("Supply:")
    fmt.Printf(" SP ACS URL : %s\n", sp.AssertionConsumerServiceURL)

    err = http.ListenAndServe(":6900", nil)
    if err != nil {
    panic(err)
    }
    }

    Die Konsole zeigt:

    Visit this URL To Authenticate:
    http://localhost:7001/login/saml/authorize/admin/app-built-in?SAMLRequest=lFVbk6K8Fv0rFvNo2QR...
    Supply:
    SP ACS URL : http://localhost:6900/v1/_saml_callback
  3. Öffnen Sie die URL. Die Casdoor-Anmeldeseite erscheint.

    Casdoor sign-in page

  4. Melden Sie sich an. Das Programm gibt die SAML-Antwort aus.

    SAML response in the console

Siehe auch​