4 Writing Oracle Security Token Service Module Classes

4.2.1 About Writing a TokenValidatorModule Class

The Oracle Security Token Service Validation module class implements the oracle.security.fed.sts.token.tpe.TokenValidatorModule interface. The following properties can be fetched from the TokenContext during the validation process:

• XML_TOKEN: The bytes of the XML message that contains the token that must be validated.

• BST_VALUE_TYPE: If the custom token is sent as a Binary Security Token, this will contain the Binary Security Token value type.

• BST_ENCODING: If the token is sent as a Binary Security Token, this will contain the encoding.

• BST_CONTENT: If the token is sent as a Binary Security Token, this will contain the Binary Security Token content.

• TOKEN_ELEMENT: If the token is not a binary security token and does not have a jaxb representation in the Oracle Security Token Service internal classes, this will contain the XML element or custom JAXB class representing the token.

• XML_DOM: This is the DOM representation of the incoming message. This will be present only if a DOM object was created as a part of Oracle Security Token Service processing thus far.

The token should be validated using the information in the properties in the TokenContext and a TokenResult should be returned. The following properties can be set on a TokenResult object to return information to Oracle Security Token Service:

• TPE_RESULT_FAILURE_CODE: The failure code if there was a failure.

• TPE_RESULT_FAILURE_STRING: A string describing the failure.

• Any other properties that are set in the result are available in the context to be used for token mapping. Usually, validators set STS_SUBJECT_ID property to the name ID and use this to map to a user record.

See the following figures contain examples for the full implementation of EmailTokenValidatorModuleImplforBinary.java:

• Figure 4-1, "Part 1: EmailTokenValidatorModuleImplforBinary.java"

• Figure 4-2, "Part 2: EmailTokenValidatorModuleImplforBinary.java"

Figure 4-1 Part 1: EmailTokenValidatorModuleImplforBinary.java

Figure 4-2 Part 2: EmailTokenValidatorModuleImplforBinary.java

The following overview outlines development highlights for this module class.

Development highlights: Writing a TokenValidatorModule class

1. Implement the init(Map options) method, called when the TokenValidatorModule is initialized. The init method is passed in a map containing the parameters defined in the validation template.

2. Implement the validate(TokenContext context) method, called when a particular incoming custom token must be validated.

   1. Fetch token information from the properties in the TokenContext object.

   2. Validate the token and return a TokenResult object:

      On Success, return:

      TokenResultImpl result = new TokenResultImpl(0, TokenResult.SUCCESS, token);
      

      On Failure, return:

      TokenResultImpl result = new TokenResultImpl(0, TokenResult.FAILURE, token);
      result.setTokenProperty("TPE_RESULT_FAILURE_CODE", failureCode);
      result.setTokenProperty("TPE_RESULT_FAILURE_STRING", "validation failed");
         
      

   3. Confirm the validated token result returns the NameId in the token and any attributes that are parsed from the token, in the following format:

      result.setTokenProperty(TPEConstants.NAMEID_VALUE, emailAddress);
      
       //attributes
      List attributeList = new ArrayList();
      Return any other properties that should be available in the context for :  
      token mapping and issuance by setting the properties on the result
      result.setTokenProperty(name, value);
      Return any other properties that should be available in the context for 
      token mapping and issuance by setting the properties on the result as 
      follows: result.setTokenProperty(name, value);
      emailAttribute.put(TPEConstants.SAML_ATTRIBUTE_NAMESPACE, null);
      List attributeValues = new ArrayList();
      attributeValues.add(emailAddress);
      emailAttribute.put(TPEConstants.SAML_ATTRIBUTE_VALUES, attributeValues);
      attributeList.add(emailAttribute);
      result.setTokenProperty(TPEConstants.TOKEN_ATTRIBUTES, attributeList); 
      
      

4.2.2 Writing a TokenValidatorModule Class

Perform the following tasks to write a custom TokenValidatorModule class.

Task overview: Writing a TokenValidatorModule class

1. Develop your own module class while referring to:

   • Section 4.2.1, "About Writing a TokenValidatorModule Class"

   • Oracle Security Token Service Java API Reference

2. Proceed as needed:

   • Section 4.3, "Writing a TokenIssuanceModule Class"

   • Section 4.4, "Making Custom Classes Available"

4.3.1 About Writing a TokenIssuanceModule Class

The EmailTokenIssuerModuleImpl.java class should implement the oracle.security.fed.sts.token.tpe.TokenIssuerModule interface and attributes in the TokenContext.

See Figure 4-3 for an example. The overview that follows outlines development highlights for this module class.

Figure 4-3 EmailTokenIssuerModuleImpl.java 

Development highlights: Writing a TokenIssuanceModule class

1. Implement the public void init(Map options)throws TokenProcessingException method.

   The init() method is called when the issuer module is initialized. The init method is passed a map contain the parameters defined in the issuance template.

2. Implement the public TokenResult issue(TokenContext context) throws TokenProcessingException method.

   This method is called when a custom outgoing token must be created.

   1. Create, within the issue method, the token using the attributes in the issuance template and the attributes passed in the TokenContext. Attributes in the TokenContext are accessed in the following way:

      List attributes = (List)context.getOtherProperties().get(TPEConstants.TOKEN_ATTRIBUTES);
      String emailAddress = null;
      HashMap attributes = (HashMap)context.getOtherProperties().get("STS_TOKEN_ATTRIBUTES");        
      Object valueObj = attributes.get("mail"); //valuesObj will be a list if mail has more than 1 value;
      if(attributes != null)
      attrIter = attributes.iterator();
      if(attrIter != null){
      HashMap attributes = (HashMap)context.getOtherProperties().get("STS_TOKEN_      
      ATTRIBUTES");  
      Object valueObj = attributes.get("mail"); //valuesObj will be a list if
      mail has more than 1 value.
      Map<String, Object> attribute = attrIter.next();
      String attributeName = (String)attribute.get(TPEConstants.SAML_ATTRIBUTE_NAME);
      if("mail".equals(attributeName)){
      {Object valuesObj = attribute.get(TPEConstants.SAML_ATTRIBUTE_VALUES); if(valuesObj instanceof List) { Iterator iter = ((List)valuesObj).iterator(); while(iter.hasNext())
      {Object valueObj = iter.next(); if(valueObj instanceof String)
      
      }
      }else if(valuesObj instanceof String)
      Unknown macro: { emailAddress = (String)valuesObj; } 
      }
      

   2. Create a result object and set the bytes of the token and the Document Object Model (DOM) representation of the token (only if the DOM representation was created during the processing in this class):

      token.setTokenDocument(null);--> if you have a doc object that can be reuse.d set it here
      token.setTokenBytes(tokenBytes);
      TokenResult result = new TokenResultImpl(0, TokenResult.SUCCESS, token); 
      

   3. Set the key identifier information into the token properties, as follows:

      Map resultMap = new HashMap();
         resultMap.put("STS_KEY_IDENTIFIER_VALUE", emailAddress);
         resultMap.put("STS_KEY_IDENTIFIER_VALUE_TYPE", "EmailAddress");
         result.setTokenProperties(resultMap);
      

4.3.2 Writing a TokenIssuanceModule Class

Task overview: Writing an Issuance Module class

1. Write the issuance module class as you refer to Section 4.3.1, "About Writing a TokenIssuanceModule Class" and Oracle Security Token Service Java API Reference.

2. Proceed to Section 4.4, "Making Custom Classes Available"

4.4.1 About Making Classes Available

After writing the custom token validation and/or issuance classes, you must add Custom Token Configuration to Oracle Security Token Service to indicate when and how these classes should be used.

On the New Custom Token page only the Token Type Name is required (identified with an asterisk, *), as shown in Figure 4-4. Not all elements apply to all custom tokens. However, if you submit information that is incomplete, a dialog box appears to identify what is missing.

Figure 4-4 New Custom Token Page

After successful submission of new custom token details, the saved page is available for editing as shown in Figure 4-5.

Figure 4-5 Custom Token Definition: email

For the custom token, you must decide on the XML Element Name, XML Element Namespace, Binary Security Token Type, and so on. Table 4-1 describes the elements on a Custom Token page based on the examples in this chapter.

email_token

oracle.security.fed.sts.customtoken.email

email

oracle.security.fed.sts.tpe.providers.email.EmailTokenValidatorModuleImpl

http://email.example.com

oracle.security.fed.sts.tpe.providers.email.EmailTokenIssuerModuleImpl

Task overview: Adding custom tokens for custom classes

1. Create a JAR file containing only your custom TokenIssuerModule or TokenValidatorModule classes (or both). No XML metadata or manifest is needed.

2. Review information in Figure 4-5 and Table 4-1.

3. Add the JAR to the OAM Server hosting Oracle Security Token Service and create a new custom token, as described in Section 4.4.3, "Managing Custom Tokens".

4.4.2 About Narrowing a Search for Custom Tokens

Figure 4-6 illustrates the Custom Tokens Search controls and Results table. These appear when you double-click the Custom Tokens node in the navigation tree. By default, all currently defined custom tokens are listed when the Search Results table is displayed.

Figure 4-6 Custom Tokens Search Page and Controls

Table 4-2 describes the Custom Tokens Search elements and controls. No wild cards (*) are allowed in Custom Token searches.

Table 4-2 Custom Tokens Search Elements and Controls

Element	Description
Default Token URI	The URI that was defined for the custom token. You can enter the entire URI or only part of it. For instance, if you enter "ai" the Search Results table will display all custom tokens defined with a token URI that includes the letters "ai". Note: Wild cards are not allowed in Custom Token searches.
Search	Initiates the Search function using criteria provided in the form.
Reset	Resets the Search form with defaults only.
Search Results	Provides the results of your search based on your choices in the View menu.
Actions menu	Provides the following functions that can be performed on a selection in the results table: Note: Actions menu functions mirror command buttons above the results table. For example: New Custom Token: Click the New Custom Token button at the top of the Search page, or select New Custom Token from the menu, or click the + button above the table. Edit: Double-click a name in the Token Type Name column of the Search Results table, or select Edit from the Actions menu, or click the Edit (pencil icon) command button above the Results Table. Create Like: Select the desired row in the table and either select Create Like from the Actions menu, or click the Create Like command button above the table Remove: Select the desired row in the table and either select Delete from the Actions menu, or click the Delete (X) command button above the table.
View menu	Provides functions you can use to display various information in the results table:
	Controls affecting the ordering of items listed in the results table: Ascending Descending

4.4.3 Managing Custom Tokens

Users with valid administrator credentials can use the procedure in this section to manage custom tokens for custom Token Module classes.

The following procedure includes steps to add, edit, and delete custom tokens or attributes of a custom token. Skip any steps that you do not need.

Prerequisites

Writing a TokenValidatorModule Class

Writing a TokenIssuanceModule Class

To make custom classes available

1. Create and add the JAR containing your Issuance and Validation classes to the OAM Server hosting Oracle Security Token Service using one of these methods:

   • Add the custom token jar and the sts-common.jar that is available in DOMAIN_HOME/config/fmwconfig/mbeans/oam to the Managed Server classpath by editing the startup script.

   • Add the custom token jar and the sts-common.jar that is available in DOMAIN_HOME/config/fmwconfig/mbeans/oam to the DOMAIN_HOME/lib directory to automatically add these jars to the Managed Server classpath.

   • Restart the OAM Server.

2. New Custom Token: From the Oracle Access Suite System Configuration tab, open the Security Token Services section and:

   1. Double-click the Custom Tokens node to open the page.

   2. Click the New Custom Token button.

   3. Fill in the New Custom Token page with details for your custom classes (Table 4-1).

   4. Click Save and dismiss the confirmation window (or click Cancel to dismiss the page without submitting it).

   5. Close the page (or edit as described in Step 4).

   6. Proceed to Step 4, if needed, or to Section 4.5, "Managing a Custom Oracle Security Token Service Configuration".

3. Find Custom Tokens: From the Security Token Service section of the System Configuration tab:

   1. Find All: Double-click the Custom Tokens node to display a results table with all custom tokens listed.

   2. Narrow the Search: Enter some or all characters in the desired Default Token URI, click the Search Button, and review the results table.

   3. Reset the Search Form: Click the Reset button.

4. Edit Custom Token Configuration: Start with the saved page you just created.

   Alternatively: Use Step 3 to find the desired Custom Token, then double-click the name in the Search Results table to open the page.

   1. In the named Custom Token page, click the appropriate field and edit as needed.

   2. Add Attributes: Click the Add (+) icon for the Attributes table, enter the Attribute Name and an Attribute Type (Table 4-1).

   3. Remove Attributes: From the Attributes table, click the row containing the attribute to remove, click the Delete (X) icon for the table, and dismiss the Confirmation window.

   4. Apply Changes: Click the Apply button at the top of the page to submit changes.

5. Remove a Custom Token:

   1. Click the desired name in the Search Results table to select the item to remove.

   2. From the Actions menu, click Delete (or click the Delete (X) command button above the table.

   3. Click the Delete button in the Confirmation window (or click No to cancel the operation).

4.5.1 Creating the Validation Template

Users with valid Oracle Access Manager administrator credentials can perform the following task to create a Validation Template with a Token Protocol of Webservice Trust to map the token to the requester.

The template in this example can be used for the module classes described earlier in this chapter. Full implementation details are shown in the following figures. As you review these, notice how specifications for this template reference the module class code:

• Figure 4-7, "General Details: email-wstrust-valid-temp"

• Figure 4-8, "Token Mapping: email-wstrust-valid-temp"

Figure 4-7 General Details: email-wstrust-valid-temp

Figure 4-8 Token Mapping: email-wstrust-valid-temp

See Also:

Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service

To create the validation template for the custom module classes

1. Display the list of existing Token Validation Templates.

   
   Oracle Access Suite
   System Configuration
   Security Token Services
   Token Validation Templates
   

2. Click the New Validation Template button in the upper-right corner (or click the Add (+) command button above the Search Results table).

3. General: Set the following for use with the custom token.

   Validation Template Name: email-wstrust-valid-temp

   Token Protocol: Webservice Trust

   Token Type: email

   Default Partner Profile: requester-profile

   Custom Validation Attributes: testsetting: hello

4. Token Mapping: Set the following for use with the custom token in this chapter.

   Check the box beside Map Token To User (to enable it).

   Check the box beside Enable Simple User Mapping and enter:

   
   User Token Attribute: STS_SUBJECT_ID
   Datastore Attribute: mail
   

5. Click Save and dismiss the confirmation window.

6. Proceed to "Creating the Issuance Template for a Custom Token".

4.5.2 Creating the Issuance Template for a Custom Token

This is a server side configuration. Users with valid Oracle Access Manager administrator credentials can perform the following task to create a Token Issuance Template.

Each Token Issuance Template indicates how to construct a token, and which signing or encryption to use when constructing a token. Each Token Issuance Template also defines the attributes to be sent as part of the outbound token for mapping, and filtering data. However, Issuance Templates do not list mapping or filtering rules, which are defined in the Relying Party Partner Profile.

The template in this example can be used for the email custom token described earlier in this chapter. Implementation details are shown in the following figures, and described in the accompanying procedure. As you review these, notice how specifications for this template reference the module class code:

• Figure 4-9, "General Details: email-issuance-temp"

• Figure 4-10, "Issuance Properties: email-issuance-temp"

Figure 4-9 General Details: email-issuance-temp

When you have a custom token type deployed, the Issuance Properties are tailored to accommodate the custom token. For instance, the custom email token type was chosen for the issuance template show in Figure 4-10.

Figure 4-10 Issuance Properties: email-issuance-temp

This procedure produces a companion Issuance Template for the custom module classes in this chapter. For the example:

• Ignore the Token Encryption Algorithm, which is not used for the custom token type: email.

• Fill in a value for the Custom Token Attribute, which is populated from the custom token code.

See Also:

Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service

To create the Issuance Template for the custom module classes

1. Go to the list of existing Token Issuance Templates.

   
   Oracle Access Suite
   System Configuration
   Security Token Services
   Token Issuance Templates
   

2. New Token Issuance Template:

   1. Click the New Issuance Template button in the upper-right corner (or click the Add (+) command button above the Search Results table).

   2. General: Set the following for use with the custom token in this chapter.

      
      Issuance Template Name: email-issuance-temp
      Token Type: email
      

   3. Click Save and dismiss the confirmation window (or click Cancel without saving).

   4. Issuance Properties: Set the following for use with the custom token in this chapter.

      
      Custom Token Attribute Value: world
      

   5. Click Apply and dismiss the confirmation window (or click Revert without saving it).

   6. Close the definition (or edit it as described in Step 4).

3. Edit a Template: Start with the saved page you just created.

   Alternatively: Use Step 3 to find the desired template and click the name in the Search Results table to display the definition.

   1. Edit details as needed.

   2. Click the Apply button at the top of the page to submit changes (or Revert to undo your changes).

4.5.3 Adding the Custom Token to a Requester Profile

You can either edit an existing requester profile to add your custom token to the Token Type Configuration table, or create a new requester profile to use with the custom token. Either way, configure:

• Token Type: email (your custom token)

• Validation Template: email-wstrust-valid-temp

Prerequisites

Your Custom Token and Validation Template must be defined.

To create or edit a requester profile for the custom token

1. From the Oracle Access Suite System Configuration tab, open the Security Token Services section.

2. In the navigation tree, open the Partner Profiles node and double-click the Requestor Profiles node to display a list of existing profiles

3. Existing Profile:

   1. In the Search Results table of the Requester Profiles page, click the name of the desired profiles.

   2. Token and Attributes: Fill in the following details for the custom token in this chapter and then click the Save button at the top of the page.

      
      Token type: email
      Validation Template: email-wstrust-valid-temp
      

   3. Click Save, dismiss the confirmation window, and close the page (or click Cancel to dismiss the page without submitting it).

   4. Proceed to Section 4.5.4, "Adding the Custom Token to the Relying Party Profile".

4. New Profile: Click the New Requester Profile button to display the New Partner Profile page where you enter details:

   1. General: Fill in the following details for the custom token in this chapter and then click the Next button at the top of the page.

      
      Profile ID: unique_requesterprofile_name
      Default Relying Party Profile: unique_relyingparty_name
      

   2. Add Token Type Configuration: Fill in the following details for the custom token in this chapter and then click the Save button at the top of the page.

      
      Token type: email
      Validation Template: email-wstrust-valid-temp
      

   3. Proceed to Section 4.5.4, "Adding the Custom Token to the Relying Party Profile".

4.5.4 Adding the Custom Token to the Relying Party Profile

You can either edit an existing Relying Party profile, or create a new one to issue the custom token by default, and refer to the Issuance Template and related information. Either way, configure:

• Default token to issue: email (your custom token)

• Issuance Template: email-issuance-temp

Prerequisites

Your Custom Token and Issuance Template must be defined.

To edit the requester profile for the custom module classes

1. From the Oracle Access Suite System Configuration tab, open the Security Token Services section.

2. In the navigation tree, open the Partner Profiles node and double-click the Relying Party Profiles node to display a list of existing profiles.

3. Existing Profile:

   1. In the Search Results table of the Relying Party Profiles page, click the name of the desired profile.

   2. Click the Token and Attributes tab.

   3. Token Type Configuration: Click the Add (+) button above the Token Type Configuration table and enter the following details:

      
      Token type: email
      Issuance Template: email-issuance-temp
      

   4. Attributes: Click the Add (+) button above the Attributes table and define the following:

      
      Attribute name: mail
      Store Type: Userstore
      Include in Token: (check to enable)
      Encryption (leave blank)
      Value (leave blank)
      

   5. Click Apply, dismiss the confirmation window, and close the page (or click Cancel to dismiss the page without submitting it).

4. New Profile: Click the New Relying Party Profile button to display the New Partner Profile page where you enter details:

   1. General: Fill in the following details for the custom token in this chapter and then click the Next button at the top of the page.

      
      Profile ID: unique_relyingparty-name
      Default Token: email
      

   2. Click the Token and Attributes tab and perform Steps 2c and 2d, then click Apply.

4.5.5 Mapping the Token to a Requestor

If you don't have a Username Validation Template (username-wss-valid-template), use the Oracle Access Suite to create one to map the token to the requester.

Validation Template Name: username-wss-valid-template

Token Type: Username

Proceed to Section 4.5.6, "Creating an /wssuser EndPoint"

4.5.6 Creating an /wssuser EndPoint

Prerequisites

"Mapping the Token to a Requestor"

To create an endpoint

1. From the Oracle Access Suite System Configuration tab, open the Security Token Services section.

2. Double-click the Endpoints node to display a list of existing Endpoints.

3. New Endpoint:

   1. Click the Add (+) button above the table (or choose New Endpoint from the Actions menu).

   2. Enter the new Endpoint URI: /wssuser

   3. Choose the Oracle WSM policy: sts/wss_username_service_policy

   4. Choose the Validation Template: username-wss-validation-template.

   5. Click Apply to submit the definition and dismiss the confirmation window (or click Revert to dismiss the page without submitting it).

   6. Close the page.