com.ibm.websphere.wssecurity.wssapi.token
Class SAMLTokenFactory
- java.lang.Object
com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory
- public abstract class SAMLTokenFactory
- extends java.lang.Object
This API is used for the creation of SAML security tokens conforming the SAML v1.1
and SAML v2.0 standards (both versions of the token are supported). Subject confirmation can be based
on holder of key (symmetric or public key) or bearer. Users can create and validate tokens or use
them to authenticate the token holder.
Code snippet that are shown below demonstrate how to use this API to generate and validate SAML tokens
as defined in:
OASIS Web Services Security:SAML Token Profile 1.1.
In those sample codes, it is assumed that the ProviderConfig instance is created from a JVM system property,
com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath, in a java client environment.
This JVM property specifies a property file that contains default value of ProviderConfig object.
In the Application Server runtime environment, default value of ProviderConfig object is defined by a
an SAMLIssuerConfig.properties file under the cell level or server level config directory.
- $CELL/sts/SAMLIssuerConfig.properties
- $SERVER/SAMLIssuerConfig.properties
- Sample code of generating SAMLToken for SAML V1.1 Symmetric holder-of-Key assertion from Subject
-
SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11); // 1. Create RequesterConfig object. RequesterConfig reqData = samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig(); // Set recipient's key alias, so the secret key could be encrypted for the recipient. reqData.setKeyAliasForAppliesTo("SOAPRecipient"); // Set authentication method that the requester was authenticated with. This is an optional parameter. reqData.setAuthenticationMethod("Password"); // 2. Create CredentialConfig object. // This step assumes that an SAMLToken exists in a RunAsSubject. You can use WSSUbject API to get RunAsSubject.. // This method allows SAMLTokenFactory copies SAMLToken's NameID or NameIdentifier and Attributes to the new SAMLToken. // If there were no SAMLToken in the RunAsSubject, a new SAMLToken is created using the user security identity from // the WSPrincipal object in the RunAsSubject. CredentialConfig cred = samlFactory.newCredentialConfig(runAsSubject); // 3. Create ProviderConfig object which specifies key store for SAML signing and encryption, expiration time, and issuer logical name. // Make sure the JVM system property com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath is set in a java client environment, // or the default SAMLIssuerConfig.properties file is updated in the Application Server runtime environment. ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig("Issuer name is WebSphere server"); SecurityToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
- Sample code of generating SAMLToken for SAML V2.0 Bearer assertion from Subject
-
SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV20Token11); // 1. Create RequesterConfig object. RequesterConfig reqData = samlFactory.newBearerTokenGenerateConfig(); // 2. Create CredentialConfig object. // This step assumes an SAMLToken existing in an RunAsSubject, and you first get an RunAsSubject. // This method call will allow SAMLTokenFactory to copy existing SAML NameID and attributes in RunAsSubject to new SAMLToken. // If there were no SAMLToken in the RunAsSubject, a new SAMLToken is created using the user security identity from // the WSPrincipal object in the RunAsSubject. CredentialConfig cred = samlFactory.newCredentialConfig(runAsSubject); // 3. Create ProviderConfig object which specifies key store for SAML signing and encryption, expiration time, and issuer logical name. // Make sure the JVM system property com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath is set in a java client environment, // or the default SAMLIssuerConfig.properties is updated in the Application Server runtime environment. ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig("Issuer name is WebSphere server"); SecurityToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg); // Get SAML assertion in XML form. OMElement samlXML = ((OMStructure)samlToken.getXML()).getNode();
- Sample code of generating SAMLToken for SAML V2.0 Bearer assertion
-
SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV20Token11); // 1. Create RequesterConfig object. RequesterConfig reqData = samlFactory.newBearerTokenGenerateConfig(); // Set Authentication method that the requester was authenticated with. This is an optional parameter. reqData.setAuthenticationMethod("Password"); // 2. Create CredentialConfig object which contains NameID and Attributes Assertion. CredentialConfig cred = samlFactory.newCredentialConfig(); // Create SAMLNameID object for SAMLTokenFactory to generate NameID or NameIdentifier assertion. SAMLNameID samlNameId = new SAMLNameID("alice@websphere", "urn:oasis:names:tc:SAML:1.0:assertion#emailAddress", null, null, null); cred.setSAMLNameID(samlNameId); // Create SAMLAttribute object for SAMLTokenFactory to generate Attribute assertion. SAMLAttribute sattribute = new SAMLAttribute("Address", new String[] {"Austin, Texas"}, null, "IBM WebSphere namespace", null, null); ArrayList
al = new ArrayList (); al.add(sattribute); sattribute = new SAMLAttribute("Membership", new String[] {"Blue team", "Green Team"}, null, null, null, null ); al.add(sattribute); cred.setSAMLAttributes(al); // 3. Create ProviderConfig object which specifies key store for SAML signing and encryption, expiration time, and issuer logic name. // Make sure the JVM system property com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath is set in a java client environment, // or the default SAMLIssuerConfig.properties is updated in the Application Server runtime environment. ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig("WebSphere Self Issuer"); SecurityToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
- Sample code of generating SAMLToken from SAML XMLStructure or InputStream
-
SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11); // Create ConsumerConfig object for SAML validation and parsing. ConsumerConfig samlConsumerCfg = samlFactory.newConsumerConfig(); // The following method calls are required if SAML tokens or embedded Keys are encrypted. KeyStoreConfig tsc = SAMLTokenFactory.newKeyStoreConfig( "jceks", "recipient.jceks","storepass"); samlConsumerCfg.setTrustStoreConfig(tsc); // Use one of the following statement to create SAMLToken. SAMLToken samlTokenFromXML = samlFactory.newSAMLToken(samlConsumerCfg, samlXml); //samlXml is SAML in XMLStructure format. SAMLToken samlTokenFromInputStream = samlFactory.newSAMLToken(samlConsumerCfg, samlInputStream ); // samlInputStream is SAML in InputStream.
Field Summary
Modifier and Type | Field and Description |
---|---|
|
GET_NEWCREDENTIALCONFIG_PERM
|
|
GET_NEWSAMLTOKEN_PERM
|
|
GET_NEWSUBJECT_PERM
|
|
WssSamlV11Token11
This is the key used by SAMLTokenFactory to create an instance of
the SAML Version 1.1 token factory.
|
|
WssSamlV20Token11
This is the key used by SAMLTokenFactory to create an instance of
the SAML Version 2.0 token factory.
|
Constructor Summary
Constructor and Description |
---|
SAMLTokenFactory()
|
Method Summary
Modifier and Type | Method and Description |
---|---|
|
getInstance(java.lang.String valueType)
Return a
SAMLTokenFactory implementation that supports the specified token type (v1.1 or v2.0).
|
|
newAsymmetricHolderOfKeyTokenGenerateConfig()
Create a default
RequesterConfig object that encapsulates attributes
relating to the entity requesting a SAML token.
|
|
newBearerTokenGenerateConfig()
Create a default
RequesterConfig object that encapsulates attributes
relating to the entity requesting a SAML token that will contain
bearer type of subject confirmation.
|
|
newConsumerConfig()
Create an empty ConsumerConfig to validate, decrypt, and parse SAMLAssertion.
|
|
newCredentialConfig()
Create a
CredentialConfig that encapsulates two main attributes:
a SAML Name Identifier for the requester
a SAML list of attributes for the requester
|
|
newCredentialConfig(javax.security.auth.Subject subject)
Create a
CredentialConfig that encapsulates the identity of the requester
and possibly its attributes.
|
|
newDefaultProviderConfig(java.lang.String stsUri)
Create a default
ProviderConfig that encapsulates configuration attributes
for the SAML token issuer .
|
|
newKeyStoreConfig(java.lang.String ksRef)
Create a
KeyStoreConfig that encapsulates
KeyStore configuration attributes.
|
|
newKeyStoreConfig(java.lang.String type,java.lang.String path,java.lang.String password)
Create a
KeyStoreConfig that encapsulates
KeyStore configuration attributes.
|
|
newSAMLToken(com.ibm.wsspi.wssecurity.saml.config.ConsumerConfig consumer,java.io.InputStream in)
Create a
SAMLToken object based on an inputStream for a SAML XML document.
|
|
newSAMLToken(com.ibm.wsspi.wssecurity.saml.config.ConsumerConfig consumer,XMLStructure xml)
Create a
SAMLToken object based on an existing SAML XML document.
|
|
newSAMLToken(com.ibm.wsspi.wssecurity.saml.config.CredentialConfig cred,com.ibm.wsspi.wssecurity.saml.config.RequesterConfig request,com.ibm.wsspi.wssecurity.saml.config.ProviderConfig providerConfig)
Create a
SAMLToken object based on the passed in parameters that include the
CredentialConfig, the RequesterConfig and the ProviderConfig objects (see the methods above for content details).
|
|
newSAMLToken(javax.security.auth.Subject subject,com.ibm.wsspi.wssecurity.saml.config.RequesterConfig request,com.ibm.wsspi.wssecurity.saml.config.ProviderConfig providerConfig)
Create a
SAMLToken object based on the passed in parameters that include a JAAS Subject
and configuration objects for the requester and provider (see the methods above for content details).
|
|
newSenderVouchesTokenGenerateConfig()
Create a
RequesterConfig .
|
|
newSubject(SAMLToken aSAMLToken)
Create a JAAS subject based on
SAMLToken object principal name which is basically
the NameId or NameIdentifier attribute in SAML Assertion Specification.
|
|
newSymmetricHolderOfKeyTokenGenerateConfig()
Create a default
RequesterConfig object that encapsulates attributes
relating to the entity requesting a SAML token.
|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail
GET_NEWCREDENTIALCONFIG_PERM
- public static final java.security.SecurityPermission GET_NEWCREDENTIALCONFIG_PERM
GET_NEWSAMLTOKEN_PERM
- public static final java.security.SecurityPermission GET_NEWSAMLTOKEN_PERM
GET_NEWSUBJECT_PERM
- public static final java.security.SecurityPermission GET_NEWSUBJECT_PERM
WssSamlV11Token11
- public static final java.lang.String WssSamlV11Token11
WssSamlV20Token11
- public static final java.lang.String WssSamlV20Token11
This is the key used by SAMLTokenFactory to create an instance of the SAML Version 2.0 token factory. It is defined in the Web Services Security SAML Token Profile 1.1.
Constructor Detail
SAMLTokenFactory
- public SAMLTokenFactory()
Method Detail
getInstance
- public static SAMLTokenFactory getInstance( java.lang.String valueType)
- throws WSSException
SAMLTokenFactory
implementation that supports the specified token type (v1.1 or v2.0).
valueType
- a string that specifies the version level for the token. It can only have either of these values:
- SAMLTokenFactory.WssSamlV11Token11 for SAML 1.1
- SAMLTokenFactory.WssSamlV20Token11 for SAML 2.0
SAMLTokenFactory
implementation that support the specified token type. WSSException
- if there is no SAMLTokenFactory
class that
supports the specified token type. newBearerTokenGenerateConfig
- public abstract com.ibm.wsspi.wssecurity.saml.config.RequesterConfig newBearerTokenGenerateConfig( )
RequesterConfig
object that encapsulates attributes
relating to the entity requesting a SAML token that will contain
bearer type of subject confirmation. These attributes include:
- subject confirmation type of bearer
- version of the token to be requested (v1.1 or v2.0) for the respective token factory.
RequesterConfig
object to build Bearer confirmation SAML assertion. RequesterConfig
newSenderVouchesTokenGenerateConfig
- public abstract com.ibm.wsspi.wssecurity.saml.config.RequesterConfig newSenderVouchesTokenGenerateConfig( )
RequesterConfig
.
RequesterConfig
object to build a SAML assertion that contains
Sender-Vouches as a subject confirmation. The main attributes encapsulated by this object are:
- subject confirmation type of sender-vouches
- version of the token to be requested (v1.1 or v2.0) for the respective token factory.
WSSException
RequesterConfig
newSymmetricHolderOfKeyTokenGenerateConfig
- public abstract com.ibm.wsspi.wssecurity.saml.config.RequesterConfig newSymmetricHolderOfKeyTokenGenerateConfig( )
RequesterConfig
object that encapsulates attributes
relating to the entity requesting a SAML token. This object will contain
holder of key type of subject confirmation using a secret key. It mainly contains these attributes:
- subject confirmation type of holder-of-key
- key type of symmetric (secret)
- version of the token to be requested (v1.1 or v2.0) for the respective token factory.
RequesterConfig
object to build Holder-of-Key SAML assertion with SymmetricKey KeyType. RequesterConfig
newAsymmetricHolderOfKeyTokenGenerateConfig
- public abstract com.ibm.wsspi.wssecurity.saml.config.RequesterConfig newAsymmetricHolderOfKeyTokenGenerateConfig( )
RequesterConfig
object that encapsulates attributes
relating to the entity requesting a SAML token. This object will contain
holder of key type of subject confirmation using a public key. It mainly contains these attributes:
- subject confirmation type of holder-of-key
- key type of asymmetric (public)
- version of the token to be requested (v1.1 or v2.0) for the respective token factory.
RequesterConfig
object to build Holder-of-Key SAML assertion with asymmetricKey KeyType. RequesterConfig
newCredentialConfig
- public abstract com.ibm.wsspi.wssecurity.saml.config.CredentialConfig newCredentialConfig( javax.security.auth.Subject subject)
- throws WSSException
CredentialConfig
that encapsulates the identity of the requester
and possibly its attributes. This object is created in preparation for using the SAML
token creation methods (see below).
This method requires the SecurityPermission("wssapi.SAMLTokenFactory.newCredentialConfig") Java Security permission.
subject
- containing the principal name and possibly attributes of the requester. CredentialConfig
object that could be used to create SAML assertion.
The CredentialConfig is populated with the Name Identifier of the requester and possibly SAML attributes
that may exist on the SAML token that is extracted off of the Private Credential list
of the subject.
If subject is null, this method will return null. WSSException
CredentialConfig
newCredentialConfig
- public abstract com.ibm.wsspi.wssecurity.saml.config.CredentialConfig newCredentialConfig( )
- throws WSSException
CredentialConfig
that encapsulates two main attributes:
- a SAML Name Identifier for the requester
- a SAML list of attributes for the requester
CredentialConfig
object that can be used to populate the NameID and the attributes
for a requester when creating a SAML token (see below). WSSException
how to use setter methods to populate the returned object.
newDefaultProviderConfig
- public abstract com.ibm.wsspi.wssecurity.saml.config.ProviderConfig newDefaultProviderConfig( java.lang.String stsUri)
- throws WSSException
ProviderConfig
that encapsulates configuration attributes
for the SAML token issuer .
stsUri
- is a String that represents SAML issuer in an SAML Assertion.
In this case of WebSphere self issued tokens, this parameter can assume any value; e.g.
WebSphereSelfIssuer. ProviderConfig
that encapsulates the following attributes:
- the URI for the issuer from the passed input parameter. This can default to the string WebSphere.
- time to live for the token expiration. Defaults to 3600000 milliseconds or 2 hours.
- a KeyStoreConfig object encapsulating the key store info for the issuer including: the location, password, and type. For example in a WebSphere installation, one can set the type to PKCS12 and point to the keyStore: $WAS_HOME/profiles/$PROFILE/etc/ws-security/samples/WssIP.pfx
- a trust store configuration possibly containing the public key certificate for the recipient. Both issuer keyStore
and trustStore are used to protect the SAML token as well as for the generation
of holder-of-key data in the SAML assertion (see token creation API below). Configuration items for the
trustStore include: type, password, and location. For example in a WebSphere installation one might set the type to PKCS12 and point to the trustStore:
$WAS_HOME/profiles/$PROFILE/etc/ws-security/samples/wssipkey.p12
In order to change the configuration parameters for the provider in the WebSphere environment you need to edit: $WAS_HOME/profiles/$PROFILE/config/cells/$CELLNAME/sts/SAMLIssuerConfig.properties for the cell level. At the server level: $WAS_HOME/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME/SAMLIssuerConfig.properties
- a KeyInformationConfig object encapsulating key store info for the issuer that includes: the key alias, password and key name.
WSSException
newKeyStoreConfig
- public static com.ibm.wsspi.wssecurity.core.config.KeyStoreConfig newKeyStoreConfig( java.lang.String type,
- java.lang.String path,
- java.lang.String password)
- throws WSSException
KeyStoreConfig
that encapsulates
KeyStore configuration attributes. For example in a WebSphere installation,
one can set the type to JKS and point to the keyStore using
parameter strings like the following:
"JKS, "$WAS_HOME/profiles/$PROFILE/etc/ws-security/samples/dsig-sender.ks", "sampleapp"
type
- is a String that represents type of KeyStore path
- is a String that represents the KeyStore file name password
- is a String that represents the KeyStore password KeyStoreConfig
that
encapsulates the following attributes: the type, location,
and password. WSSException
KeyStoreConfig
newKeyStoreConfig
- public static com.ibm.wsspi.wssecurity.core.config.KeyStoreConfig newKeyStoreConfig( java.lang.String ksRef)
- throws WSSException
KeyStoreConfig
that encapsulates
KeyStore configuration attributes. For example in a WebSphere
installation, one can use a reference to the default keystore
with a parameter string like:
"name=NodeDefaultKeyStore managementScope=(cell):sampleNode01Cell:(node):sampleNode01"
ksRef
- is a String that represents KeyStore reference name KeyStoreConfig
that
encapsulates the KeyStore reference name. WSSException
KeyStoreConfig
newSAMLToken
- public abstract SAMLToken newSAMLToken( javax.security.auth.Subject subject,
- com.ibm.wsspi.wssecurity.saml.config.RequesterConfig request,
- com.ibm.wsspi.wssecurity.saml.config.ProviderConfig providerConfig)
- throws WSSException
SAMLToken
object based on the passed in parameters that include a JAAS Subject
and configuration objects for the requester and provider (see the methods above for content details).
This method will copy the contents from the original SAML Token, if one exists in the Subject, to the new SAML token.
NameId or NameIdentifier, SAML Attributes, and AuthenticationMethod are copied to the new SAML Token.
The new SAML Token namespace, issuer, signing certificate,
confirmation method and encryption key, timestamp, and lifetime are determined by the ProviderConfig and RequesterConfig parameters.
When the Subject does not contain an existing SAMLToken object, this method will create a new SAML Token using
the WSPrincipal name as the NameId or NameIdentifier. No other attribute will be copied from the Subject to the new SAMLToken when there
was no SAML token in the Subject parameter.
Use the newSAMLToken( CredentialConfig cred, RequesterConfig request, ProviderConfig providerConfig )
method if you need to add SAML Attributes in the new SAMLToken
.
This method requires the SecurityPermission("wssapi.SAMLTokenFactory.newSAMLToken") Java Security permission.
subject
- is mapped to NameIdentifier and attributes in an SAML Assertion. request
- contains data that describes what kind of assertion should be created. providerConfig
- describes issuer, like Signing KeyInfo and Encryption KeyInfo. SAMLToken
which can then be bound to a secure service request. WSSException
- if required key and certificate cannot be found,
or upon other configuration problems. ProviderConfig
,
RequesterConfig
newSAMLToken
- public abstract SAMLToken newSAMLToken( com.ibm.wsspi.wssecurity.saml.config.CredentialConfig cred,
- com.ibm.wsspi.wssecurity.saml.config.RequesterConfig request,
- com.ibm.wsspi.wssecurity.saml.config.ProviderConfig providerConfig)
- throws WSSException
SAMLToken
object based on the passed in parameters that include the
CredentialConfig, the RequesterConfig and the ProviderConfig objects (see the methods above for content details).
This method requires the SecurityPermission("wssapi.SAMLTokenFactory.newSAMLToken") Java Security permission.
cred
- contains principal and attributes that will be included in SAML Assertion. request
- contains data that describes what kind of assertion should be created. providerConfig
- describes issuer, like Signing KeyInfo and Encryption KeyInfo. SAMLToken
WSSException
- if the specified SAMLToken class cannot be found,
or required key and certificate cannot be found, or upon other configuration problems. ProviderConfig
,
RequesterConfig
,
CredentialConfig
newSAMLToken
- public abstract SAMLToken newSAMLToken( com.ibm.wsspi.wssecurity.saml.config.ConsumerConfig consumer,
- XMLStructure xml)
- throws WSSException
SAMLToken
object based on an existing SAML XML document.
This method can be used to validate the xml structure representing the SAML token.
consumer
- contains key information associated with the recipient of the token.
This info is used to verify and/or decrypt the SAML XML document. xml
- is an SAML XML document. SAMLToken
. That can be used to initiate service requests. WSSException
- if key and certificate information cannot be found, or upon other configuration problems. ConsumerConfig
newSAMLToken
- public abstract SAMLToken newSAMLToken( com.ibm.wsspi.wssecurity.saml.config.ConsumerConfig consumer,
- java.io.InputStream in)
- throws WSSException
SAMLToken
object based on an inputStream for a SAML XML document.
This method may be used to validate the inputStream representing the SAML token.
consumer
- contains key information associated with the recipient of the token.
This info is used to verify and/or decrypt the SAML XML document. in
- an inputStream corresponding to a serialized SAML token. The programmer is
responsible for closing of the stream accordingly. SAMLToken
. That can be used to initiate service requests. WSSException
- if key and certificate information cannot be found, or upon other configuration problems. ConsumerConfig
newSubject
- public abstract javax.security.auth.Subject newSubject( SAMLToken aSAMLToken)
- throws WSSException
SAMLToken
object principal name which is basically
the NameId or NameIdentifier attribute in SAML Assertion Specification.
This method looks up user security name and group membership data from the configured user registry using the
SAMLToken
principal name. The SAMLToken
object will be added to the Subject PrivateCredentials
.
None of the individual SAMLToken
attributes will be copied into the new subject.
The lifetime of the new subject is determined by the LTPA timeout configuration.
The subject lifetime is independent from the SAMLToken
lifetime.
This method requires the SecurityPermission("wssapi.SAMLTokenFactory.newSubject") Java Security permission.
aSAMLToken
- that contains a named principal and attributes. WSSException
.
newConsumerConfig
- public abstract com.ibm.wsspi.wssecurity.saml.config.ConsumerConfig newConsumerConfig( )
- throws WSSException
-
- throws WSSException
. for how set the
consumer's keyStore as well as trustStore information on the newly created ComsumerConfig
object.
This is the key used by SAMLTokenFactory to create an instance of the SAML Version 1.1 token factory. It is defined in the Web Services Security SAML Token Profile 1.1.