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.

Estas seções discutem a criação de um token SAML usando as APIs da biblioteca de tokens SAML:
  1. Configuração de Parâmetros de Criação de Token
  2. Criação de Instância de Factory de Token SAML
  3. Criação de Token SAML
  4. Código de Amostra
A API SAMLTokenFactory é a principal interface de programação da biblioteca de tokens SAML. SAMLTokenFactory suporta a criação, análise e validação de tokens SAML 1.1 e SAML 2.0. Usando a API SAMLTokenFactory, você pode criar objetos de configuração ProviderConfid, RequesterConfig e ConsumerConfig para definir as características do token SAML necessárias. Leia a documentação da API para obter detalhes adicionais.
É possível executar operações adicionais em um token SAML após sua criação, incluindo:
Nota: A partir do WebSphere Application Server Release 8 é possível usar a classe com.ibm.websphere.wssecurity.wssapi.token.SAMLToken na interface de programação de aplicativos (API) do Web Services Security (WSS). Quando não houver nenhum problema de confusão, o termo SAMLToken será usado em vez de usar o nome completo do pacote. É possível usar a API do WSS para solicitar o processamento do SAMLToken a partir de um Security Token Service (STS) externo, para propagar SAMLTokens nas mensagens de solicitação SOAP e para usar uma chave simétrica ou assimétrica identificada pelos SAMLTokens para proteger mensagens SOAP.

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.

Primeiro, configure as informações de configuração do solicitante:
// 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();
Em seguida, configure o alias de chave pública do destinatário e, opcionalmente, o método de autenticação:
// 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"); 
Em seguida, configure os atributos de configuração do emissor:
// 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.
Use a classe SAMLTokenFactory com o tipo de 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);
Configure parâmetros adicionais no objeto CredentialConfig usando o objeto responsável pela chamada ou o runAsSubject:
// 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

Crie o token SAML usando o factory de token:
// 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.
O seguinte código da API valida o token:
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();
Extraia o nome do emissor de token e o método de confirmação da seguinte forma:
String confirmationMethpo = samlToken.getConfirmationMethod();
String issuerName = samlToken.getSAMLIssuerName();
Se o método de confirmação de objeto extraído for retornado como confirmação holder-of-key, você poderá usar a seguinte API para recuperar os bytes para o material da chave:
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]

Ícone que indica o tipo de tópico Tópico de Referência



Ícone de registro de data e hora Última atualização: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=rwbs_libraryapisaml
Nome do arquivo: rwbs_libraryapisaml.html