APIs da Biblioteca de Tokens SAML
As interfaces de programação de aplicativos (APIs) da biblioteca de tokens SAML fornecem métodos que podem ser usados para criar, validar, analisar e extrair tokens SAML.
Visão geral
A implementação da biblioteca para o SAML Versão 1.1 e o SAML Versão 2.0 fornece três tipos de confirmação de objeto: holder-of-key (HoK), transmissão e sender-vouches. É possível usar as APIs da biblioteca de tokens SAML para criar, validar e extrair os atributos de um token SAML HoK ou de transmissão. A propagação de token SAML a partir de mensagens SOAP de serviços da Web também é discutida. O código de amostra é fornecido para demonstrar o uso das APIs.
O WebSphere Application Server com o SAML fornece conjuntos de política padrão para suportar a confirmação de assunto de transmissão e de Hok.
O suporte do WSS API SAML complementa as interfaces com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory e com.ibm.websphere.wssecurity.wssapi.trust.WSSTrustClient. Os SAMLTokens que são gerados usando o método com.ibm.websphere.wssecurity.wssapi.WSSFactory newSecurityToken() podem ser processados pelas interfaces de programação SAMLTokenFactory e WSSTrustClient. Por outro lado, os SAMLTokens que são gerados pelo SAMLTokenFactory ou retornados pelo WSSTrustClient podem ser usados no WSS API. Decidir qual API será usada no seu aplicativo depende das suas necessidades específicas. O suporte do WSS API SAML é autocontido no sentido em que ele fornece uma funcionalidade equivalente à funcionalidade das interfaces SAMLTokenFactory e WSSTrustClient até o ponto em que os aplicativos clientes de serviços da Web forem interessados. A interface SAMLTokenFactory possui funções adicionais para validar os SAMLTokens e para criar o Assunto JAAS que representa SAMLTokens autenticados. Essa validação é útil para o lado do provedor de serviços da Web. Quando desenvolver seus aplicativos para consumir os SAMLTokens, a interface de programação SAMLTokenFactory será a mais adequada.
Configuração de Parâmetros de Criação de Token
Ao configurar os parâmetros de criação de token, as informações de configuração estão relacionadas à entidade solicitante, à entidade de emissão ou à entidade de recebimento. Neste exemplo, as informações de configuração são definidas para as entidades solicitante e de emissão. Para cada tipo de confirmação de assunto suportada, a biblioteca de tokens SAML fornece atributos pré-configurados para a entidade solicitante. Esses atributos são usados durante a criação do token SAML autoemitidos pelo ambiente de tempo de execução do WebSphere. Um token SAML autoemitido é aquele que é gerado localmente, e não aquele que é solicitado a partir de um Security Token Service (STS). Se precisar customizar os atributos para um parâmetro padrão, use o parâmetro RequesterConfig. Para obter informações adicionais, leia sobre o parâmetro RequesterConfig no tópico API SAMLTokenFactory.
// Configurar as informações de configuração do solicitante (parâmetros necessários
// para criar o token especificado como propriedades de configuração).
// neste caso, estamos usando as informações de configuração para criar
// um token SAML que contém uma confirmação de objeto holder of key
// simétrica.
RequesterConfig requesterData =
samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
// Configurar o alias de chave pública do destinatário
// (neste exemplo, usamos SOAPRecipient), portanto, o provedor pode criptografar a
// chave secreta para a extremidade de recebimento.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
// Configurar o método de autenticação ocorrido. Este é um parâmetro
// opcional.
reqData.setAuthenticationMethod("Password");
// Configurar informações do emissor, instanciando um ProviderConfig padrão.
// Consulte os javadocs para a classe SAMLTokenFactory sobre os detalhes dos
// valores-padrão e como modificá-los.
ProviderConfig samlIssuerCfg =
samlFactory.newDefaultProviderConfig("WebSphereSelfIssuer");
Criação de Instância de Factory de Token SAML
Use a classe SAMLTokenFactory, especificando o tipo de token SAML, Versão 1.1 ou Versão 2.0. Configurar parâmetros adicionais para criar o token SAML.// Instanciar um factory de token com base no nível de versão do token
// a ser usado. Neste exemplo, usamos o factory de token SAML v1.1.
SAMLTokenFactory samlFactory =
SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
// Recuperar o objeto responsável pela chamada ou o runAsSubject (dependendo de
// seu cenário), em seguida, usar o Subject para obter um objeto CredentialConfig
// usando a biblioteca de tokens SAML.
// Esta chamada requer
// a permissão de Segurança Java
// wssapi.SAMLTokenFactory.newCredentialConfig".
CredentialConfig cred = samlFactory.newCredentialConfig(runAsSubject);
Criação de Token SAML
// Agora crie o token SAML. Esta chamada requer a permissão
// de Segurança Java "wssapi.SAMLTokenFactory.newSAMLToken".
SecurityToken samlToken =
samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
Validação de Token SAML
Uma entidade que recebe um token SAML, como um serviço de negócios, pode usar a API da biblioteca de tokens SAML para validar o token antes de usá-lo. Por exemplo, o serviço precisa validar o token antes de extrair os atributos SAML do solicitante. Um documento de asserção SAML existente pode ser validado usando os dados de configuração do consumidor.ConsumerConfig consumerConfig = samlFactory.newConsumerConfig();
XMLStructure xml =
try {
SAMLToken token = samlFactory.newSAMLToken( consumerConfig, XMLStructure xml );
// token validado com êxito
} catch(WSSException e) {
// falha na validação do token
}
Identidade de Token SAML Mapeada para um Objeto
Um token SAML pode ser usado para criar um objeto. O identificador de nome no token SAML é mapeado para um usuário no registro do usuário para obter o nome do principal para o objeto.Subject subject;
SAMLToken aSAMLToken = …;
try {
subject = samlFactory.newSubject(aSAMLToken);
} catch(WSSException e) {
}
Analisar Elementos de Asserção
O destinatário de um token SAML pode analisar e extrair elementos de asserção do token SAML usando as APIs SAMLToken, que estão incluídas na API da biblioteca de tokens SAML. Por exemplo, o tempo de criação de token pode ser extraído usando este código:Date dateCreated = samlToken.getSamlCreated();
String confirmationMethpo = samlToken.getConfirmationMethod();
String issuerName = samlToken.getSAMLIssuerName();
byte[] hokBytes = samlToken.getHolderOfKeyBytes();
Para obter informações adicionais sobre todas as APIs SAML, leia a documentação da API para a interface SAMLToken.
Extração de Atributos de Token SAML
Extraia atributos SAML da entidade inicial (solicitante de serviços) usando a API SAMLToken, conforme mostrado nos seguintes fragmentos de código.// Obter todos os atributos
List<SAMLAttribute> allAttributes =
((SAMLToken) samlToken).getSAMLAttributes();
// Iterar sobre o atributo e o processo de forma apropriada
Iterator<SAMLAttribute> iter = allAttributes.iterator();
while ( iter.hasNext() )
{
SAMLAttribute anAttribute = iter.next();
// Manipular atributos
String attributeName = anAttribute.getName();
String[] attributeValues = anAttribute.getStringAttributeValue();
}
Código de Amostra
O código de amostra demonstra como usar as APIs da biblioteca de tokens SAML para executar algumas das operações descritas anteriormente. Uma propriedade JVM que aponta para o local do arquivo de propriedades SAML é um pré-requisito para executar esse código. O arquivo de propriedades SAML, SAMLIssuerConfig.properties, deve conter atributos de configuração relacionados ao emissor (provedor) do token SAML.O local padrão do arquivo SAMLIssuerConfig.properties para o nível de célula é: app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/sts.
Para o nível do servidor, o local padrão é: app_server_root/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 da biblioteca de tokens 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 {
// Obter uma instância do factory de token SAML v1.1
SAMLTokenFactory samlFactory = SAMLTokenFac
tory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
// Gerar dados do solicitante padrão para uma confirmação de objeto de
// tipo holder-of-key (chave secreta).
RequesterConfig requesterData =
samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
// Configurar o alias de chave do destinatário, para que o emissor possa criptografar
// a chave secreta para o destinatário como parte da confirmação de objeto.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
// Configurar o método de autenticação ocorrido.
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");
// Configurar o alias de chave do destinatário para que informações do token, como
// o HoK secreto, possam ser criptografadas pelo emissor e decriptografadas pelo
// destinatário.
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 itens de configuração do 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));
// Obter uma instância do objeto de configuração Credencial
CredentialConfig cred = samlFactory.newCredentialConfig();
cred.setRequesterNameID("Alice");
// Configurar alguns atributos do usuário
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);
// Obter configuração do provedor padrão
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());
// Gerar o token 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());
// Criar um Subject, mapeando o identificador de nome no token para um usuário
// no registro do usuário para obter o nome do Principal
Subject subject = samlFactory.newSubject((SAMLToken)samlToken);
// Recuperar atributos do token
List<SAMLAttribute> allAttributes =
((SAMLToken)samlToken).getSAMLAttributes();
// Iterar por meio dos atributos e processar de forma apropriada
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();
}
}
}
Saída de Código de Amostra
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]