Verwenden Sie die API
der SAML-Bibliothek, um ein SAML-Sender-Vouches-Token
zu erstellen, das die Bestätigungsmethode
"sender-vouches" enthält. Die Bestätigungsmethode "sender-vouches" wird verwendet, wenn ein Server die Clientidentität
oder das Verhalten des Clients weitergeben muss.
Informationen zu diesem Vorgang
Wenn die
SAML-Funktion in einem WebSphere-Server installiert ist, wird die API der SAML-Bibliothek bereitgestellt.
Verwenden Sie die Bibliothek, um
ein SAML-Sender-Vouches-Token
zu erstellen. Mit der API der
SAML-Bibliothek können Sie erforderliche SAML-Konfigurationsobjekte erstellen und
anschließend mit diesen Konfigurationsobjekten ein SAML-Sender-Vouches-Token
generieren.
Vorgehensweise
- Erstellen Sie eine Instanz der
"SAMLTokenFactory" und verwenden Sie dabei
die SAML-Tokenversion als Parameter.
- Verwenden Sie die folgende Codezeile, um die Methode zu importieren:
import com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory;
- Verwenden Sie je nach Tokenversion eine der folgenden Codezeilen,
um die Instanz zu erstellen.
- Nachdem Sie die Instanz erstellt haben, wird
die "SAMLTokenFactory" verwendet, um eine Instanz des Objekts
"RequesterConfig" zu erstellen, die entsprechend den Authentifizierungsvoraussetzungen des Requesters
festlegt, wie das Token generiert wird. Verwenden Sie diese Codezeile, um
die Instanz des Objekts "RequesterConfig" für das Sender-Vouches-Token
zu erstellen:
RequesterConfig reqData = samlFactory.newSenderVouchesTokenGenerateConfig();
Die
Standardinstanz von "RequestConfig" reicht aus, um ein einfaches Sender-Vouches-Token
zu generieren.
Durch Anpassen der "RequestConfig"-Instanz können
aber weitere Zusicherungen in das SAML-Token aufgenommen werden.
Um beispielsweise Informationen zur Kennwortauthentifizierung in das Token aufzunehmen, verwenden Sie
die Methode "setAuthenticationMethod":
reqData.setAuthenticationMethod(“password”);
Die
Trust-Validierung
für eine Zusicherung des Typs
"sender-vouches" obliegt dem Sender, nicht dem Aussteller. Daher ist das Element "Enveloped-Signature" in der Zusicherung nicht erforderlich.
Um das Element "Enveloped-Signature" aus der SAML-Zusicherung
zu entfernen, verwenden Sie die Methode
"setAssertionSignatureRequired" wie im folgenden Beispiel:
reqData.setAssertionSignatureRequired(false);
- Erstellen Sie mit der API
"SAMLTokenFactory" eine Instanz des Objekts
"ProviderConfig", die den Tokenaussteller beschreibt.
Die "ProviderConfig"-Instanz legt den
SAML-Ausstellernamen sowie Informationen zu Keystore und Truststore fest,
die den Schlüssel für die SAML-Verschlüsselung und -Signatur angeben. Die
"ProviderConfig"-Instanz wird mit Eigenschaftswerten aus einer Eigenschaftendatei erstellt.
Die Eigenschaftendatei gibt den Standardwert des
Objekts "ProviderConfig" an.
In einer
Java™-Clientumgebung wird diese
Eigenschaftendatei von der JVM-Systemeigenschaft
"com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath" definiert.
In der Laufzeitumgebung von
WebSphere Application Server lautet der Name der
Eigenschaftendatei "SAMLIssuerConfig.properties".
Die Datei kann sich entweder unter dem Konfigurationsverzeichnis auf Serverebene oder
unter dem Verzeichnis auf Zellenebene (in dieser Reihenfolge) befinden.
Das folgende Beispiel gilt für den Pfad auf Serverebene:
Stammverzeichnis_des_Anwendungsservers/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME/SAMLIssuerConfig.properties
Das folgende Beispiel gilt für den Pfad auf Zellenebene:
Stammverzeichnis_des_Anwendungsservers/profiles/$PROFILE/config/cells/$CELLNAME/sts/SAMLIssuerConfig.properties
Die
JVM-Systemeigenschaft
"com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath" wird ignoriert, wenn die
Eigenschaft in der Serverlaufzeitumgebung definiert wird.
Eine ausführliche Beschreibung aller Eigenschaften finden Sie in den Informationen zur Konfiguration eines SAML-Tokens während der Tokenerstellung.
Verwenden Sie die folgende Codezeile, um
eine Instanz des Objekts "ProviderConfig"
zu erstellen:
ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(“Name_des_Ausstellers”);
Der Name des Ausstellers ist optional.
Wenn der Name des Ausstellers angegeben wird, erscheint er in der SAML-Zusicherung.
Wird der Name des Ausstellers nicht angegeben,
wird ein Standardname für den Aussteller aus
der Datei "SAMLIssuerConfig.properties" verwendet.
- Optional: Wenn Sie ein neues SAML-Token erstellen, verwendet die
"SAMLTokenFactory" entweder ein JAAS-Subjekt (Java Authentication and Authorization Service)
oder eine
"CredentialConfig"-Instanz, um das neue SAML-Token zu füllen. Wenn ein
JAAS-Subjekt verwendet werden soll, um das Token zu füllen, rufen Sie die API
"com.ibm.websphere.security.auth.WSSubject
getCallerSubject()" oder die
API "getRunAsSubject()" auf, um ein JAAS-Subjekt zu erhalten, das den
anfordernden Client darstellt, oder die Identität des Ausführungs-Threads.
- Wenn Sie das JAAS-Subjekt verwenden, um ein neues
SAML-Token zu erstellen, durchsucht die API
"SAMLTokenFactory" die "PrivateCredentials"-Subjektliste nach
einem "SAMLToken"-Objekt.
Wenn ein
"SAMLToken"-Objekt existiert, werden
die Objekte
"NameId" oder "NameIdentifier" in das neue SAML-Token kopiert.
Außerdem kopiert die
"SAMLTokenFactory" die SAML-Attribute und die Methode
"AuthenticationMethod" aus dem vorhandenen SAML-Token in das neue SAML-Token.
Das neue SAML-Token enthält einen neuen Namen des Ausstellers, neue
Signaturzertifikate, die Bestätigungsmethode, neue Schlüsselinformationen
("KeyInfo") für die Bestätigungsmethode
"holder-of-key" und neue Bedingungen des Typs
"NotBefore" und "NotOnAfter". Diese Tokeneinstellungen werden von Konfigurationsparametern
in den Objekten "ProviderConfig" und
"RequesterConfig" festgelegt.
Wenn im Subjekt kein
"SAMLToken"-Objekt existiert, wird nur der Principal-Name
"WSPrincipal" aus dem Subjekt in das neue SAML-Token kopiert.
Keine anderen Attribute im Subjekt werden in das neue SAML-Token kopiert.
Auf die gleiche Weise werden der Name des Ausstellers, das Signaturzertifikat, die
Bestätigungsmethode, Schlüsselinformationen ("KeyInfo") für
"holder-of-key" und die Bedingungen
"NotBefore" und "NotOnAfter" von den Konfigurationsparametern in den Objekten
"ProviderConfig" und "RequesterConfig" bestimmt.
Alternativ dazu können Sie die
Methode "RunAsSubject" für den Ausführungs-Thread verwenden, um das SAML-Token zu erstellen.
Bei Verwendung dieser Methode sollten Sie das JAAS-Subjekt
bzw. das Objekt
"CredentialConfig"
nicht an die "SAMLTokenFactory" übergeben, um das SAML-Token zu erstellen.
Statt dessen wird der Inhalt des vorhandenen
SAML-Tokens wie bereits beschrieben in das neue
SAML-Token kopiert.
- Eine weitere Methode zum Erstellen eines SAML-Tokens besteht darin,
unter Verwendung des Objekts "CredentialConfig" die SAML-Namens-ID ("NameID") und -Attribute
programmgesteuert zu füllen.
Diese Methode sollte in folgenden Situationen verwendet werden:
- In das neue SAML-Token müssen angepasste SAML-Attribute aufgenommen werden.
- Das SAML-Token wird nicht mit der
"SAMLTokenFactory" erstellt, damit es aus einem JAAS-Subjekt automatisch gefüllt wird, sondern das SAML-Token wird manuell erstellt.
- Im Subjekt ist kein SAML-Token vorhanden.
- Es ist kein JAAS-Subjekt verfügbar.
- Verwenden Sie die folgende Codezeile, um ein
"CredentialConfig"-Objekt ohne Verwendung des
JAAS-Subjekts zu erstellen:
CredentialConfig cred = samlFactory.newCredentialConfig ();
Für dieses
"CredentialConfig"-Objekt wird kein Anfangswert bereitgestellt, daher müssen Sie
das Objekt mit Setter-Methoden füllen.
- Zum Füllen der
"NameIdentifier" oder "NameID" für SAML verwenden Sie die folgende Codezeile:
cred.setRequesterNameID("beliebiger Name");
Der Wert
des an die Methode "setRequesterNameID()" übergebenen
Parameters
wird im SAML-Token
als Name des Principals verwendet.
Der Name wird in Zusicherungen als "NameIdentifier" in einem SAML-Token der
Version 1.1 oder als "NameId" im SAML-Token der Version 2.0 angezeigt. Wenn der Wert des mit der Methode "setRequesterNameID()" übergebenen Parameters
z. B. Alice ist, wird in einem SAML-Token
der Version 1.1 die folgende Zusicherung generiert: <saml:NameIdentifier>Alice</saml:NameIdentifier>
In einem SAML-Token
der Version 2.0 wird die folgende Zusicherung generiert:
<saml2:NameID>Alice</saml2:NameID>
- Verwenden Sie folgenden Code, um
SAML-Attribute in den Abschnitt
<AttributeStatement> einer Zusicherung aufzunehmen:
SAMLAttribute samlAttribute = new SAMLAttribute("email" /* Name*/, new String[] {"joe@websphere"}
/*Attributwerte*/, null, "IBM WebSphere-Namespace" /* Namespace*/, "E-Mail-Adresse" /* Format*/, "joe" /*aussagekräftiger Name*/);
ArrayList<SAMLAttribute> al = new ArrayList<SAMLAttribute>();
al.add(samlAttribute)
sattribute = new SAMLAttribute("Membership", new String[] {"Super users", "Gold membership"}, null, null /* format*/, null, null );
al.add(samlAttribute );
cred.setSAMLAttributes(al);
Dieser Beispielcode generiert die folgenden <Attribute>-Zusicherungen:
<saml:Attribute AttributeName="email" NameFormat="email" AttributeNamespace="IBM WebSphere namespace">
<saml:AttributeValue>joe@websphere</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute AttributeName="Membership">
<saml:AttributeValue>Super users</saml:AttributeValue><saml:AttributeValue>Gold membership</saml:AttributeValue>
</saml:Attribute>
- Erstellen Sie mit der folgenden Codezeile
ein SAML-Sender-Vouches-Token:
SAMLToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
Für diese
Methode ist die Java-Sicherheitsberechtigung
"wssapi.SAMLTokenFactory.newSAMLToken" erforderlich.
Im Abschnitt mit den Beispielen finden Sie vollständige Codebeispiele, die die Codezeilen aus
den vorherigen Schritten enthalten:
Beispiel
Verwenden Sie diesen Beispielcode, um ein SAML-Sender-Vouches-Token
der Version 1.1 aus dem Subjekt zu erstellen:
SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11)
RequesterConfig reqData = samlFactory.newSenderVouchesTokenGenerateConfig();
ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(“WebSphere Server”);
Subject subject = com.ibm.websphere.security.auth.WSSubject.getRunAsSubject();
SAMLToken samlToken = samlFactory.newSAMLToken(subject, reqData, samlIssuerCfg);
Verwenden Sie diesen Beispielcode, um ein SAML-Sender-Vouches-Token
der Version 1.1 ohne Verwendung des Subjekts zu erstellen:
SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
RequesterConfig reqData = samlFactory.newSenderVouchesTokenGenerateConfig();
reqData.setAuthenticationMethod("Password"); //Authentifizierungsmethode für die Zusicherung
ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(Self issuer);
CredentialConfig cred = samlFactory.newCredentialConfig ();
cred.setRequesterNameID("Alice"); // NameIdentifier für SAML
//SAML-Attribute:
SAMLAttribute attribute = new SAMLAttribute
("email" /* Name*/, new String[] {"joe@websphere"}
/*Attributwerte in String*/,null
/*Attributwerte in XML */, "WebSphere" /* Namespace*/, "E-Mail-Adresse" /* Format*/, "joe" /*aussagekräftiger_Name */);
ArrayList<SAMLAttribute> al = new ArrayList<SAMLAttribute>();
al.add(attribute);
attribute = new SAMLAttribute("Membership", new String[] {"Super users", "Mein Team"}, null, null, null, null );
al.add(attribute);
cred.setSAMLAttributes(al);
SAMLToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);