SAML 토큰 라이브러리 API
SAML 토큰 라이브러리 API(Application Programming Interface)는 SAML 토큰을 작성, 유효성 검증, 구문 분석 및 추출하는 데 사용할 수 있는 메소드를 제공합니다.
개요
SAML 버전 1.1 및 SAML 버전 2.0에 대한 라이브러리 구현은 holder-of-key (HoK), bearer 및 sender-vouches의 세 가지 유형의 제목 확인을 제공합니다. SAML 토큰 라이브러리 API를 사용하여 SAML HoK 또는 bearer 토큰의 속성을 작성, 유효성 검증 및 추출할 수 있습니다. 웹 서비스 SOAP 메시지로부터 SAML 토큰 전파도 논의됩니다. API의 사용을 보여주기 위한 샘플 코드가 제공됩니다.
SAML을 갖는 WebSphere® Application Server은 bearer 및 HoK 제목 확인을 지원하기 위한 기본 정책 세트를 제공합니다.
WSS API SAML 지원은 com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory 및 com.ibm.websphere.wssecurity.wssapi.trust.WSSTrustClient 인터페이스를 보완합니다. SAMLTokenFactory 및 WSSTrustClient 인터페이스는 com.ibm.websphere.wssecurity.wssapi.WSSFactory newSecurityToken() 메소드를 사용하여 생성된 SAMLToken을 처리할 수 있습니다. 반대로, SAMLTokenFactory를 통해 생성되거나 WSSTrustClient가 리턴한 SAMLToken을 WSS API에서 사용할 수 있습니다. 애플리케이션에서 사용할 API를 결정하는 것은 사용자의 특정 요구에 따라 다릅니다. WSS API SAML 지원은 웹 서비스 클라이언트 애플리케이션에 관한 한 SAMLTokenFactory 및 WSSTrustClient 인터페이스의 기능과 같은 기능을 제공한다는 의미에서 독립적입니다. SAMLTokenFactory 인터페이스에는 SAMLToken을 유효성 검증하고 인증된 SAMLToken을 나타내는 JAAS 주제를 작성할 수 있는 추가 기능이 있습니다. 이 유효성 검증은 웹 서비스 제공자 측에 유용합니다. SAMLToken을 이용할 애플리케이션을 개발하는 경우에는 SAMLTokenFactory 프로그래밍 인터페이스가 더 적합합니다.
토큰 작성 매개변수의 구성
토큰 작성 매개변수를 구성할 때 구성 정보가 요청하는 엔티티, 발행 엔티티 또는 수신 엔티티 중 하나에 관련됩니다. 이 예제에서 구성 정보는 요청 및 발행 엔티티에 대해 정의됩니다. 지원되는 주제 확인의 각 유형에 대해, SAML 토큰 라이브러리가 요청 엔티티에 대한 사전 구성된 속성을 제공합니다. 이들 속성은 WebSphere 런타임 환경에 의한 자체 발행 SAML 토큰의 작성 중에 사용됩니다. 자체 발행 SAML 토큰은 보안 토큰 서비스(STS)로부터 요청되는 것 대신 로컬로 생성되는 SAML 토큰입니다. 기본 매개변수에 대한 속성을 사용자 정의해야 하는 경우 RequesterConfig 매개변수를 사용하십시오. 자세한 정보는 SAMLTokenFactory API 주제의 RequesterConfig 매개변수에 대해 읽으십시오.
// Setup the requester's configuration information (parameters needed
// to create the token specified as configuration properties).
// in this case we are using the configuration information to create a
// SAML token that contains a symmetric holder of key subject
// confirmation.
RequesterConfig requesterData =
samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
// Set recipient's public key alias
// (in this example we use SOAPRecipient), so the provider can encrypt secret
// key for the receiving end.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
// Set the authentication method that took place. This is an optional
// parameter.
reqData.setAuthenticationMethod("Password");
// Set issuer information by instantiating a default ProviderConfig.
// See javadocs for the SAMLTokenFactory class on the details of the
// default values and how to modify them.
ProviderConfig samlIssuerCfg =
samlFactory.newDefaultProviderConfig("WebSphereSelfIssuer");
SAML 토큰 팩토리 인스턴스 작성
버전 1.1 또는 버전 2.0 중 하나인 SAML 토큰 유형을 지정하여 SAMLTokenFactory 클래스를 사용하십시오. SAML 토큰 작성을 위한 추가 매개변수를 설정하십시오.// Instantiate a token factory based on the version level of the token
// to use. In this example we use the SAML v1.1 token factory.
SAMLTokenFactory samlFactory =
SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
// Retrieve the caller subject or the runAsSubject (depending on your
// scenario) then use the Subject to get a CredentialConfig object
// using the SAML token library.
// This invocation requires the
// wssapi.SAMLTokenFactory.newCredentialConfig" Java Security
// permission.
CredentialConfig cred = samlFactory.newCredentialConfig(runAsSubject);
SAML 토큰 작성
// Now create the SAML token. This invocation requires the
// "wssapi.SAMLTokenFactory.newSAMLToken" Java Security permission.
SecurityToken samlToken =
samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
SAML 토큰 유효성 검증
비즈니스 서비스 같이 SAML 토큰을 수신하는 엔티티는 SAML 토큰 라이브러리 API를 사용하여 토큰을 사용하기 전에 유효성 검증할 수 있습니다. 예를 들어, 서비스는 요청자로부터 SAML 속성을 추출하기 전에 토큰을 유효성 검증해야 합니다. 기존 SAML 어설션 문서는 이용자의 구성 데이터를 사용하여 유효성 검증할 수 있습니다.ConsumerConfig consumerConfig = samlFactory.newConsumerConfig();
XMLStructure xml =
try {
SAMLToken token = samlFactory.newSAMLToken( consumerConfig, XMLStructure xml );
// token successfully validated
} catch(WSSException e){
// token failed validation
}
주제에 맵핑된 SAML 토큰 ID
SAML 토큰을 사용하여 주제를 작성할 수 있습니다. SAML 토큰의 이름 ID는 주제에 대한 프린시펄 이름을 얻기 위해 사용자 레지스트리의 사용자에 맵핑됩니다.Subject subject;
SAMLToken aSAMLToken = …;
try {
subject = samlFactory.newSubject(aSAMLToken);
} catch(WSSException e) {
}
구문 분석 어설션 요소
SAML 토큰의 수신인은 SAMLToken API를 사용하여 SAML 토큰으로부터 어설션 요소를 구문 분석 및 추출할 수 있으며, 이 API는 SAML 토큰 라이브러리 API에 포함되어 있습니다. 예를 들어, 토큰 작성 시간은 다음 코드를 사용하여 추출할 수 있습니다.Date dateCreated = samlToken.getSamlCreated();
String confirmationMethpo = samlToken.getConfirmationMethod();
String issuerName = samlToken.getSAMLIssuerName();
byte[] hokBytes = samlToken.getHolderOfKeyBytes();
모든 SAML API에 대한 자세한 정보는 SAMLToken 인터페이스에 대한 API 문서를 읽으십시오.
SAML 토큰 속성 추출
다음 코드 스니펫에서 보는 것처럼 SAMLToken API를 사용하여 시작하는 엔티티(서비스 요청자)로부터 SAML 속성을 추출하십시오.// Get all attributes
List<SAMLAttribute> allAttributes =
((SAMLToken) samlToken).getSAMLAttributes();
// Iterate over the attribute and process accordingly
Iterator<SAMLAttribute> iter = allAttributes.iterator();
while(iter.hasNext())
{
SAMLAttribute anAttribute = iter.next();
// Handle attributes
String attributeName = anAttribute.getName();
String[] attributeValues = anAttribute.getStringAttributeValue();
}
샘플 코드
샘플 코드는 앞에서 설명한 조작의 일부를 수행하기 위해 SAML 토큰 라이브러리 API를 사용하는 방법을 보여줍니다. SAML 특성 파일의 위치를 가리키는 JVM 특성이 이 코드 실행을 위한 전제조건입니다. SAML 특성 파일인 SAMLIssuerConfig.properties는 SAML 토큰의 발행자(제공자)와 관련된 구성 속성을 포함해야 합니다.셀 레벨에 대한 SAMLIssuerConfig.properties 파일의 기본 위치는 app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/sts입니다.
서버 레벨의 경우 기본 위치는 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;
// Import methods from the SAML token library
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 {
// Get an instance of the SAML v1.1 token factory
SAMLTokenFactory samlFactory = SAMLTokenFac
tory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
// Generate default requester data for a subject confirmation of
// type holder-of-key (secret key).
RequesterConfig requesterData =
samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
// Set the recipient's key alias, so that the issuer can encrypt
// the secret key for recipient as part of the subject confirmation.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
// Set the authentication method that took place.
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");
// Set the recipient's key alias so that token infomation such as
// the secret HoK can be encrypted by the issuer and decrypted by the
// recipient.
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");
// Print requester configuration items
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));
// Get an instance of the Credential config object
CredentialConfig cred = samlFactory.newCredentialConfig();
cred.setRequesterNameID("Alice");
// Set some user attributes
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);
// Get default provider configuration
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());
// Generate the SAML token
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());
// Create a Subject, mapping the name identifier in the token to a user
// in the user registry to obtain the Principal name
Subject subject = samlFactory.newSubject((SAMLToken)samlToken);
// Retrieve attributes from the token
List<SAMLAttribute> allAttributes =
((SAMLToken)samlToken).getSAMLAttributes();
// Iterate through the attributes and process accordingly
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();
}
}
}
샘플 코드 출력
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]