45.8 Making Custom Classes Available

When Security Token Service does not support the token that you want to validate or issue out-of-the-box, a developer can write custom validation and issuance module classes.

You can apply the information when you have:

  • WS-Security User Name Token

  • WS-Trust Custom Token

  • Issuing Custom Token

Note:

You can also write a script that includes WebLogic Scripting Tool commands for any operation that you can accomplish through the console. For more information, see WLST Command Reference for WebLogic Server.

The following topics provide information about:

45.8.1 About Making Classes Available

After writing the custom token validation and/or issuance classes, you must add Custom Token Configuration to 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, *). See Figure 45-16.

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 45-16 New Custom Token Page

Description of Figure 45-16 follows
Description of "Figure 45-16 New Custom Token Page"

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

Table 45-14 New Custom Token Elements

Element Description

Token Type Name

The unique name you choose for this custom token. For example:

email_token

Note: After you save a new custom token configuration, you cannot edit this name.

Default Token URI

The URI for this custom token. This URI can then be used in the RST to request that a custom token of this type should be issued. For the example in this chapter, the value would be:

oracle.security.fed.sts.customtoken.email

XML Element Name

The name you decide on, which will be associated with the Token Type Name. For example:

email

If you specify email as the XML Element Name, each time the element name, email, appears in an incoming token it will be associated with the Token Type Name (in this case email_token).

Note: Minimally, you need either an XML Element Name or Binary Security Token Type.

Validation Classname

The name of the custom token validation class that you made available to Security Token Service. For example:

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

Note: Minimally, you need either an issuance class name or validation class name, depending on whether you want to issue or validate a custom token.

XML Element Namespace

The namespace of the custom token element name. For example:

http://email.example.com

Issuance Classname

The name of the custom token issuance class that you made available to Security Token Service. For example:

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

Note: Minimally, you need either an Issuance classname or Validation classname, depending on whether you want to issue or validate a custom token.

Binary Security Token Type

Enables the class to validate a custom token sent in as a BinarySecurityToken.

The ValueType of the BinarySecurityToken for this custom token. If Security Token Service receives a Binary Security Token with this ValueType, it will be forwarded to this custom token's Validation class for validation.

Validation Attributes

This section enables you to add (or remove) validation attributes. The table displays existing validation attributes, if any. For this example:

  • Attribute Name: testsetting

  • Attribute Type: String

Note: You will add a value to the attribute when creating a Token Validation Template.

Issuance Attributes

This section enables you to add (or remove) issuance attributes. The table displays the following information for existing issuance attributes.

  • Attribute Name: testsetting

  • Attribute Type: String

Note: You will add a value to the attribute when creating a Token Issuance Template.

Save

Click this button on the New Custom Tokens page to save your configuration information.

Cancel

Click this button to dismiss your configuration details.

Apply

Click this button to submit your changes.

Revert

Click this button to dismiss your changes.

45.8.1.1 Task Overview: Adding Custom Tokens for Custom Classes

You can add custom tokens for custom classes.

To add custom tokens:

  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 Table 45-14.
  3. Add the JAR to the OAM Server hosting Security Token Service and create a new custom token, as described in Managing Custom Tokens.

45.8.2 About Narrowing a Search for Custom Tokens

By default, all currently defined custom tokens are listed in the Search Results table. In custom token searches, wild cards are not allowed.

Figure 45-17 illustrates the Custom Tokens Search controls and Results table. These appear when you double-click the Custom Tokens node in the navigation tree.

Figure 45-17 Custom Tokens Search Page and Controls

Description of Figure 45-17 follows
Description of "Figure 45-17 Custom Tokens Search Page and Controls"

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

Table 45-15 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:

Up-Down Arrows

Controls affecting the ordering of items listed in the results table:

  • Ascending

  • Descending

45.8.3 Managing Custom Tokens

Users with valid Administrator credentials can 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.

45.8.3.1 Prerequisites for Managing Custom Tokens

See the developer creating the custom tokens and the Oracle Fusion Middleware Developer's Guide for Oracle Access Management for details about Writing a TokenIssuanceModule Class:

See "Making Custom Classes Available".

See "About Narrowing a Search for Custom Tokens".

45.8.3.2 Making Custom Classes Available

You can create a new Custom Token, find it and edit its configuration. From the Search Results table, you can delete a particular custom token.

To make custom classes available:

  1. Create and add the JAR containing your Issuance and Validation classes to the OAM Server hosting 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:

    1. In the Oracle Access Management Console, click Federation at the top of the window.

    2. Select Create Custom Token from the Create (+) drop-down menu in the Security Token Service section.

    3. Fill in the New Custom Token page with details for your custom classes.

      See Table 45-14.

    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 go to the following topic:

      See "Managing a Custom Security Token Service Configuration".

  3. Find Custom Tokens: In the Federation console, select Custom Tokens from the View menu in the Security Token Service section.

    1. Find All: Click the Search button and view the 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.

      See Table 45-14.

    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).