API de biblioteca de señales SAML
Las interfaces de programación de aplicaciones (API) de biblioteca de señales SAML proporcionan métodos que se pueden utilizar para crear, validar, analizar y extraer señales SAML.
Visión general
La implementación de biblioteca para SAML Versión 1.1 y SAML Versión 2.0 proporciona tres tipos de confirmación de sujeto: HoK(holder-of-key), bearer y sender-vouches. Puede utilizar las API de biblioteca de señales SAML para crear, validar y extraer los atributos de la señal HoK o bearer de SAML. También se describe la propagación de señales SAML desde los mensajes SOAP de servicios web. Se proporciona código de ejemplo para ofrecer una demostración del uso de las API.
WebSphere Application Server con SAML proporciona conjuntos de políticas predeterminadas para admitir la confirmación de sujetos bearer y HoK.
El soporte de SAML de la API de WSS complementa las interfaces com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory y com.ibm.websphere.wssecurity.wssapi.trust.WSSTrustClient. Las interfaces de programación SAMLTokenFactory y WSSTrustClient procesan las SAMLTokens que se generan mediante el método com.ibm.websphere.wssecurity.wssapi.WSSFactory newSecurityToken(). A la inversa, las SAMLTokens que se generan mediante SAMLTokenFactory o que se devuelven de WSSTrustClient pueden utilizarse en la API de WSS. La determinación de qué API utilizar en la aplicación depende de sus necesidades específicas. El soporte SAML de la API de WSS es completo en el sentido de que proporciona funcionalidad equivalente a la de las interfaces SAMLTokenFactory y WSSTrustClient en lo que respecta a las aplicaciones cliente de servicios web. La interfaz SAMLTokenFactory tiene funciones adicionales para validar las SAMLTokens y para crear el asunto JAAS que representa las SAMLTokens autenticadas. Esta validación es útil en el proveedor de servicios web. Al desarrollar aplicaciones para consumir SAMLTokens, la interfaz de programación de SAMLTokenFactory es más adecuada para usted.
Configuración de los parámetros de creación de señales
Cuando se configuran los parámetros de creación de señales, la información de configuración tiene que ver con la entidad solicitante, la entidad emisora o la entidad receptora. En este ejemplo, la información de configuración se define para las entidades solicitante y emisora. Para cada tipo de confirmación de sujetos admitida, la biblioteca de señales SAML proporciona atributos preconfigurados para la entidad solicitante. Estos atributos se utilizan durante la creación de la señal SAML autoemitida por el entorno de ejecución de WebSphere. Una señal SAML autoemitida es la que se genera de forma local, en lugar de la que se solicita de un servicio de señales de seguridad (STS). Si tiene que personalizar los atributos de un parámetro predeterminado, utilice el parámetro RequesterConfig. Para obtener más información consulte la información sobre el parámetro RequesterConfig en el tema de la API SAMLTokenFactory.
// Configurar la información de configuración del solicitante (parámetros necesarios
// para crear la señal especificada como propiedades de configuración).
// En este caso utilizaremos la información de configuración para crear una
// señal SAML que contenga un contenedor simétrico de confirmación
// de sujetos de clave.
RequesterConfig requesterData =
samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
// Establecer el alias de clave pública del destinatario
// (en este ejemplo utilizamos SOAPRecipient), de este modo el proveedor puede cifrar la clave
// secreta del extremo receptor.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
// Establecer el método de autenticación que se ha aplicado. Es un parámetro
// opcional. reqData.setAuthenticationMethod("Password");
// Establecer la información de emisor instanciando un ProviderConfig predeterminado.
// Consulte los javadocs de la clase SAMLTokenFactory en los detalles de los
// valores predeterminados y cómo modificarlos.
ProviderConfig samlIssuerCfg =
samlFactory.newDefaultProviderConfig("WebSphereSelfIssuer");
Creación de instancias de fábrica de señales SAML
Utilice la clase SAMLTokenFactory, que especifica el tipo de señal SAML, ya sea de la Versión 1.1 o de la Versión 2.0. Establezca parámetros adicionales para crear la señal SAML.// Instanciar una fábrica de señales según el nivel de versión de la señal
// que se debe utilizar. En este ejemplo utilizamos la fábrica de señales SAML v1.1.
SAMLTokenFactory samlFactory =
SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
// Recuperar el sujeto de llamante o runAsSubject (en función de la
// situación de ejemplo) y, a continuación, utilizar el sujeto para obtener un objeto CredentialConfig
// mediante la biblioteca de señales SAML.
// Esta información exige el permiso de seguridad
// wssapi.SAMLTokenFactory.newCredentialConfig"
// de Java.
CredentialConfig cred = samlFactory.newCredentialConfig(runAsSubject);
Creación de señales SAML
// Ahora crear la señal SAML. Esta invocación exige el
// permiso de seguridad Java "wssapi.SAMLTokenFactory.newSAMLToken".
SecurityToken samlToken =
samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
Validación de señales SAML
Una entidad que recibe una señal SAML, como un servicio empresarial, puede utilizar la API de biblioteca de señales SAML para validar la señal antes de utilizarla. Por ejemplo, el servicio tiene que validar la señal antes de extraer los atributos SAML del solicitante. Un documento de aserción SAML existente se puede validar mediante los datos de configuración del consumidor.ConsumerConfig consumerConfig = samlFactory.newConsumerConfig();
XMLStructure xml =
try {
SAMLToken token = samlFactory.newSAMLToken( consumerConfig, XMLStructure xml );
// La señal se ha validado satisfactoriamente
} catch(WSSException e) {
// La señal ha fallado la validación.
}
Identidad de señal SAML correlacionada con un sujeto
Las señales SAML se pueden utilizar para crear un sujeto. El identificador de nombre de la señal SAML se correlaciona con un usuario del registro de usuarios para obtener el nombre de principal del sujeto.Subject subject;
SAMLToken aSAMLToken = …;
try {
subject = samlFactory.newSubject(aSAMLToken);
} catch(WSSException e) {
}
Análisis de elementos de aserción
El destinatario de una señal SAML puede analizar y extraer elementos de aserción de la señal SAML mediante las API SAMLToken, que se incluyen en la API de la biblioteca de señales SAML. Por ejemplo, con este código se puede extraer la hora de creación de la señal:Date dateCreated = samlToken.getSamlCreated();
String confirmationMethpo = samlToken.getConfirmationMethod();
String issuerName = samlToken.getSAMLIssuerName();
byte[] hokBytes = samlToken.getHolderOfKeyBytes();
Para obtener más información acerca de las API de SAML, consulte la documentación de las API para la interfaz SAMLToken.
Extracción de atributos de señal SAML
Extraiga los atributos SAML de la entidad de inicio (solicitante de servicio) mediante la API SAMLToken, como se muestra en los fragmentos de código siguientes.// Obtener todos los atributos
List<SAMLAttribute> allAttributes =
((SAMLToken) samlToken).getSAMLAttributes();
// Iterar sobre el atributo y el proceso en consonancia
Iterator<SAMLAttribute> iter = allAttributes.iterator();
while(iter.hasNext())
{
SAMLAttribute anAttribute = iter.next();
// Manejar atributos
String attributeName = anAttribute.getName();
String[] attributeValues = anAttribute.getStringAttributeValue();
}
Código de ejemplo
El código de ejemplo muestra cómo utilizar las API de la biblioteca de señales SAML para realizar algunas de las operaciones que se describían anteriormente. Una propiedad de JVM que apunta a la ubicación del archivo de propiedades SAML es un requisito previo para ejecutar este código. El archivo de propiedades de SAML, SAMLIssuerConfig.properties, debe contener los atributos de configuración relacionados con el emisor (proveedor) de la señal SAML.La ubicación predeterminada del archivo SAMLIssuerConfig.properties para el nivel de célula es: raíz_servidor_aplicaciones/profiles/$PROFILE/config/cells/$CELLNAME/sts.
Para el nivel de servidor, la ubicación predeterminada es: raíz_servidor_aplicaciones/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME.
IssuerURI=WebSphere
TimeToLive=3600000
KeyStorePath=c:/samlsample/saml-provider.jceks
KeyStoreType=jceks
KeyStorePassword=myissuerstorepass
KeyAlias=samlissuer
KeyName=CN=SAMLIssuer, O=IBM, C=US
KeyPassword=xxxxxxxxx
TrustStorePath=c:/samlsample/saml-provider.jceks
TrustStoreType=jceks
TrustStorePassword=yyyyyyyy
package samlsample;
import java.util.List;
import java.util.Iterator;
import java.util.ArrayList;
import javax.security.auth.Subject;
// Importar métodos de la biblioteca de señales SAML
import com.ibm.wsspi.wssecurity.saml.data.SAMLAttribute;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLToken;
import com.ibm.wsspi.wssecurity.saml.config.ProviderConfig;
import com.ibm.wsspi.wssecurity.saml.config.RequesterConfig;
import com.ibm.wsspi.wssecurity.saml.config.CredentialConfig;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory;
import com.ibm.websphere.wssecurity.wssapi.token.SecurityToken;
import com.ibm.wsspi.wssecurity.core.token.config.RequesterConfiguration;
public class SamlAPIsample {
public void testSAMLTokenLibrary() throws Exception {
try {
// Obtener una instancia de la fábrica de señales SAML v1.1
SAMLTokenFactory samlFactory = SAMLTokenFac
tory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
// Generar los datos de solicitante para una confirmación de sujetos de
// tipo holder-of-key (clave secreta).
RequesterConfig requesterData =
samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
// Establecer el alias de la clave del destinatario, de modo que el emisor puede cifrar
// la clave secreta para el destinatario como parte de la confirmación de sujetos.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
// Establecer el método de autenticación que se ha aplicado.
requesterData.setAuthenticationMethod("Password");
System.out.println("default holder of key confirmation key type is: "+
Requester
Data.getRSTTProperties().get(RequesterConfiguration.RSTT.KEYTYPE));
Requester
Data.getRSTTProperties().put(RequesterConfiguration.RSTT.KEYTYPE,
"http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey");
requesterData.getRSTTProperties().put(
RequesterConfiguration.RSTT.APPLIESTO_ADDRESS,
"http://localhost:9080");
requesterData.setConfirmationMethod("holder-of-key");
// Establecer el alias de clave del destinatario para que la información de señal como
// el HoK secreto la pueda cifrar el emisor y descifrar el
// destinatario.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
requesterData.setAuthenticationMethod("Password");
requesterData.getRSTTProperties().put(
RequesterConfiguration.RSTT.ENCRYPTIONALGORITHM,
"http://www.w3.org/2001/04/xmlenc#aes128-cbc");
requester
Data.getRSTTProperties().put(RequesterConfiguration.RSTT.TOKENTYPE,
"http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-
1.1#SAMLV1.1");
requesterData.setRequesterIPAddress("9.53.52.65");
// Imprimir los elementos de configuración del solicitante
System.out.println("authentication method for requester is: "+
requesterData.getAuthenticationMethod());
System.out.println("confirmation method for requester is: "+
requesterData.getConfirmationMethod());
System.out.println("key alias for requester is: "+
requesterData.getKeyAliasForRequester());
System.out.println("key alias for recipient as set in requester config is "+
requesterData.getKeyAliasForAppliesTo());
System.out.println("holder of key confirmation key type is: "+
Requester
Data.getRSTTProperties().get(RequesterConfiguration.RSTT.KEYTYPE));
// Obtener una instancia del objeto de configuración Credential.
CredentialConfig cred = samlFactory.newCredentialConfig();
cred.setRequesterNameID("Alice");
// Establecer ciertos atributos de usuario
ArrayList<SAMLAttribute> userAttrs = new ArrayList<SAMLAttribute>();
SAMLAttribute anAttribute = new SAMLAttribute("EmployeeInfo",
new String[] {"GreenRoofing","JohnDoe", "19XY981245"},
null, "WebSphere Namespace", null, "JohnDoeInfo " );
userAttrs.add(anAttribute);
cred.setSAMLAttributes(userAttrs);
// Obtener la configuración de proveedor predeterminada
ProviderConfig samlIssuerCfg =
samlFactory.newDefaultProviderConfig("WebSphereSelfIssuer");
System.out.println("time to live from the default provider config: "+
samlIssuerCfg.getTimeToLive());
System.out.println("keyStore path from default provider config: "+
samlIssuerCfg.getKeyStoreConfig().getPath());
System.out.println("keyStore type from default provider config: "+
samlIssuerCfg.getKeyStoreConfig().getType());
System.out.println("key alias from default provider config: "+
samlIssuerCfg.getKeyInformationConfig().getAlias());
// Generar la señal SAML
SecurityToken samlToken =
samlFactory.newSAMLToken(cred, requesterData, samlIssuerCfg);
System.out.println("token's creation Date is:
"+((SAMLToken)samlToken).getSamlCreated().toString());
System.out.println("token's expiration Date is:
"+((SAMLToken)samlToken).getSamlExpires().toString());
System.out.println("token's subject confirmation method is:
"+((SAMLToken)samlToken).getConfirmationMethod());
// Crear un sujeto correlacionando el identificador de nombre de la señal con un usuario
// del registro de usuarios para obtener el nombre de principal
Subject subject = samlFactory.newSubject((SAMLToken)samlToken);
// Recuperar los atributos de la señal
List<SAMLAttribute> allAttributes =
((SAMLToken)samlToken).getSAMLAttributes();
// Iterar a través de los atributos y el proceso en consonancia
Iterator<SAMLAttribute> iter = allAttributes.iterator();
while (iter.hasNext()) {
SAMLAttribute attribute = iter.next();
String attributeName = attribute.getName();
String[] attributeValues = attribute.getStringAttributeValue();
System.out.println("attribute name = "+ attributeName +
" attribute value = ["+
attributeValues[0]+ ",
"+attributeValues[1]+ ", "+
attributeValues[2]+"]");
}
} catch(Exception e) {
e.printStackTrace();
}
}
}
Salida de código de ejemplo
default holder of key confirmation key type is: http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
authentication method for requester is: Password
confirmation method for requester is: holder-of-key
key alias for requester is: null
key alias for recipient as set in requester config is SOAPRecipient
holder of key confirmation key type is: http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
time to live from the default provider config: 3600000
keyStore path from default provider config: C:/saml/samlsample/saml-provider.jceks
keyStore type from default provider config: jceks
key alias from default provider config: samlissuer
token's creation Date is: Mon Sep 14 15:49:00 CDT 2009
token's expiration Date is: Mon Sep 14 16:49:00 CDT 2009
token's subject confirmation method is: urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
attribute name = EmployeeInfo attribute value = [GreenRoofing, JohnDoe, 19XY981245]