34 Managing Templates, Endpoints, and Policies

This chapter provides the following information for Security Token Service.

• Prerequisites

• Introduction

• Searching for an Existing Template

• Managing Token Issuance Templates

• Managing Token Validation Templates

• Managing Security Token Service Endpoints

• Managing Token Issuance Policies, Conditions, and Rules

• Managing TokenServiceRP Type Resources

• Making Custom Classes Available

• Managing a Custom Security Token Service Configuration

34.1 Prerequisites

Security Token Service must be enabled on the Available Services page, as described in "Enabling and Disabling Security Token Service".

34.2 Introduction

Security Token Service supports control of who can access WSPs by defining Application Domains that provide access to resources based on policies. Application domains identify Web Services, along with authorization rules that determine who can request a security token based on the WSPs.

The following functionality is established by Trust Issuance Policies, which can be managed through Application Domain under the Policy Configuration tab of the Oracle Access Management Console.

• Resource of type TokenServiceRP representing Relying Parties or Web Service Providers.

• Token Issuance Policy defining a policy for a set of resources of type TokenServiceRP.

• Condition defining the identities of the clients that are allowed or denied issuance of tokens for the resources listed in the policy. The clients can either be Requester Partners or User from the Default Identity Store.

Security Token Service supports the creation of Relying Party Partner, representing a remote Web Service Provider that will be the consumer of a security token issued by Security Token Service.

For each Relying Party Partner, it is possible to define URLs that will be mapped to the partner, so that WS-Addressing endpoint specified in a WS-Trust Request can be mapped to an Security Token Service Relying Party Partner.

At runtime, when a client requests a token to be issued, Security Token Service will evaluate the Trust Issuance Policies to determine whether or not the token can be issued:

• The client will be identified either as a Requester Partner or as an end user

• If an AppliesTo element was present in the WS-Trust Request and was mapped to a Relying Party Partner, then the TokenServiceRP resource for the Trust Issuance Policy evaluation will be the Partner ID of that Security Token Service Relying Partner.

• If an AppliesTo element was present in the WS-Trust Request and could not be mapped to a Relying Party Partner, then the TokenServiceRP resource for the Trust Issuance Policy evaluation will be the UnknownRP defined in the Access Manager Application Domain.

• If an AppliesTo element was missing in the WS-Trust Request, then the TokenServiceRP resource for the Trust Issuance Policy evaluation will be the MissingRP defined in the Access Manager Application Domain.

Security Token Service requires the following items (at a minimum) to process a request and issue a token based on an incoming request (RST):

• EndPoints

• One Issuance Template

• One Validation Template

• One Requester Partner Profile that contains the token

• One Relying Party Partner Profile

Note:

Partners might need to be provisioned.

An LDAP server is required for the Security Token Service to map the Username token that references the user to an LDAP User record, and then use that record to populate the outgoing token. Partners might need to be provisioned before they are available.

34.3 Searching for an Existing Template

All defined template names appear in the Search Results Table when you open either the Token Validation Template or Token Issuance Template node. To quickly find a specific template or set of templates, you can use the Search controls.

This section explains the controls you can use to refine your search, which are similar whether you are searching for a Token Validation Template or a Token Issuance Template. It includes the following topics:

• About Template Search Controls

• Searching For a Template

34.3.1 About Template Search Controls

The following figures show the search pages where you will see many similarities:

• Figure 34-1, "Validation Templates Search Controls"

• Figure 34-2, "Issuance Template Search Controls"

Figure 34-1 Validation Templates Search Controls

Description of "Figure 34-1 Validation Templates Search Controls"

Figure 34-2 Issuance Template Search Controls

Description of "Figure 34-2 Issuance Template Search Controls"

Table 34-1 describes the controls available to refine a template search. Unless explicitly stated, all elements are available for both Validation and Issuance Template searches.

Table 34-1 Search Validation Template

Element	Description
Match	Choose All to search for a template that matches all your specifications. Choose Any to search for a template that matches at least one of your specifications.
Search Operations List	A list of operations from which you choose one to help refine your search.
... Template Name	Choose an operation from the list and enter information in the field to help refine your search.
Description	Refine your search using the optional description field.
Token Protocol Validation Template only	Choose the token protocol from those listed: WS-Trust WS-Security
Token type	Choose the token type. Both standard and custom token types are included. Username: Consumption and Creation X.509: Consumption SAML: Consumption & Creation OAM 11g: Consumption using the OBO (on behalf of) field Kerberos: Consumption Custom: Consumption the OBO (on behalf of) field and Creation
Search	Initiates the Search function using criteria in the form.
Reset	Resets the Search form with defaults only.
Add Fields	A list of additional items you can add as search criteria.
Search Results Table	Itemizes the results of your search based on choices in the View menu, described later in this table.
Actions menu Shown: Actions for Validation Template	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 ... Template: Click the New ... Template button at the top of the Search page, or select New ... Template from the menu, or click the + button above the table. Edit: Click a name in the Results Table, or select Edit from the Actions menu, or click the Edit (pencil) 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 Results Table and either select Delete from the Actions menu, or click the Delete (X) command button above the table.
View menu Validation Template only	A list from which you can identify which information to display in the results table.
View menu Issuance Template only	A list from which you can identify which information to display in the results table.
	Controls you can choose to define the order of items listed in the results table: Ascending Descending

34.3.2 Searching For a Template

Users with valid Administrator credentials can use the following procedure to use search controls to locate a specific template or set of templates. For example, to locate all templates of a certain token type you can simply choose the type of token. To refine the search further to all templates of a specific token type and name.

When performing these steps, fill in as much or as little as you want. Skip any steps that do not apply to you.

See Also:

"About Template Search Controls"

To search for a template

1. From the System Configuration tab, expand the Secure Token Services Settings section.

2. In the navigation tree, open the desired Template node. For example: Token Validation Templates.

3. Edit Search Criteria (Table 34-1). For example:

   • Match: All

   • Name: contains em

   • Token Type: equals Username

4. Click Search, review results, and click the one you want to open.

34.4 Managing Token Issuance Templates

An issuance template contains rules on how a token will be created and is specific to a token type. Each issuance template indicates Signing and Encryption and also contains Attribute Name, Value Mapping, and Filtering settings to be sent as part of the token.

This section provides the following information:

• About Managing Token Issuance Templates

• Managing a Token Issuance Template

34.4.1 About Managing Token Issuance Templates

Each Token Issuance Template indicates how to construct a token. In other words, which signing or encryption to use when constructing a token. Each Token Issuance Template also defines the attributes mapping and filtering rules to be applied to the attributes that will be included in the outgoing token. However, Issuance Templates do not list the attributes that will be sent in the outgoing token: these are defined in the Relying Party Partner Profile.

Token Issuance Template details which will differ depending on your chosen token type. Table 34-2 describes where to find more information.

Table 34-2 Issuance Template Requirements

Topic	Figures and Tables
General Details	Figure 34-3, Table 34-3
Issuance Properties: Username Tokens	Figure 34-4, Table 34-4
Issuance Properties: SAML Tokens	Figure 34-5, Table 34-6
Security: SAML Tokens	Figure 34-6, Table 34-6
Attribute Mapping: SAML Tokens	Figure 34-9, Table 34-7

General Details

Figure 34-3 shows the New Issuance Template page with defaults showing. Unless explicitly stated, General information is the same regardless of the Token Type you choose. For more information, see Table 34-3. After you fill in General information and click Save, you cannot return and edit the template name or token type.

Figure 34-3 Issuance Template: General Details and Defaults

Description of "Figure 34-3 Issuance Template: General Details and Defaults"

Table 34-3 Issuance Template: General Details

Elements	Description
Issuance Template Name	Enter a unique name for this template.
Description	Optional.
Token Type	Choose a standard (or custom, if any) token type from those listed.
SAML, Username, and Custom Token Types
Send Encrypted Token	Click to enable token encryption.
Token Encryption Algorithm	When token encryption is enabled, choose a Token Encryption Algorithm from those listed.

Issuance Properties: Username Token Type

If the token type is Username, the Issuance Properties shown in Figure 34-4 are needed for a Username token type template.

Figure 34-4 Issuance Properties: Username Token Type

Description of "Figure 34-4 Issuance Properties: Username Token Type"

Table 34-4 describes the Issuance Properties for the Username token type.

Table 34-4 Issuance Properties: Username Token Type

Element	Description
Name Identifier User Attribute	Attribute to be used to populate the Username element in the Username Token.
Name Identifier User Attribute Store	Choose the user attribute store type: Userstore Context Note: If the Attribute Store is the Userstore, LDAP is used to retrieve the attribute from the user record. If the Attribute Store is context, data from the incoming token is used as the attribute source.
Password Attribute	Attribute to be used to populate the Password element in the Username Token.
Password Attribute Store	Choose the password attribute store type: Userstore Context Note: If the Attribute Store is the Userstore, LDAP is used to retrieve the attribute from the user record. If the Attribute Store is context, data from the incoming token is used as the attribute source.
Include Nonce	Indicates whether or not a Nonce made of random data should be included in the Username token. Default: Disabled
Include Timestamp	Indicates whether or not a the Created element should be included in the Username token. Default: Disabled

Issuance Properties: SAML Token Types

SAML 1.1 and 2.0 token types require the issuance properties illustrated in Figure 34-5.

Note:

These issuance properties differ from those for Username token type.

Figure 34-5 Issuance Properties: SAML Token Types

Description of "Figure 34-5 Issuance Properties: SAML Token Types"

Table 34-5 describes all Issuance Properties by token type. Only SAML token types require issuance properties.

Table 34-5 Issuance Properties: SAML Token Types

Element	Description
Assertion Issuer	Specifies the identifier representing the issuer of the assertion. This string is used to represent this Security Token Service as the issuer of the assertion.
Name Identifier Format	Choose a format from the list and then enter the details in the text field.
Name Identifier Qualifier	Contains the string that will be set as the Name Identifier Qualifier.
Name Identifier User Attribute	References the attribute that will be used to populate the value of the Name Identifier.
Name Identifier User Attribute Store	Userstore Context Note: If the Attribute Store is the Userstore, LDAP is used to retrieve the attribute from the user record. If the Attribute Store is context, data from the incoming token is used as the attribute source.
Include Authentication Statement	Indicates whether or not a SAML Authentication Statement should be included in the Assertion. Default: Disabled Note: An authentication operation is required for a statement of this type to be included. An authentication statement will be included if the incoming token contained some authentication data and that those were validated (for example, the incoming SAML Assertion contains an authentication statement, or a Username Token contains credentials that were validated).
Include Attribute Statement	Indicates whether or not a SAML Attribute Statement will be included in the outgoing Assertion. A statement of this type will be included only if this flag is set to true and if at least one attribute is included in the outgoing Assertion. Default: Enabled Note: the RP PP will determine which attributes need to be included in an outgoing token.
Validity Period	Specify the length of time (in seconds) that the token will be valid. Default: 3600 (seconds)

Security Details: SAML Tokens

Only SAML token types require Security Details, as shown in Figure 34-6 and described in Table 34-6.

Figure 34-6 Security Details: SAML Tokens

Description of "Figure 34-6 Security Details: SAML Tokens"

Table 34-6 Security Details: SAML Tokens

Elements	Description
Signing And Encryption	Indicates whether or not the Assertion will be signed using the Key referenced by the Signing Keystore Access Template ID field.
Sign Assertion	Indicates whether or not the signing certificate will be included in the Assertion. Default: Enabled
Include Certificate in Signature	Default: Enabled
Signing Keystore Access Template Id	References the key to be used to sign assertions created with this issuance template. The key templates are defined in the Security Token Service Settings section.
Subject Confirmation
Default Subject Confirmation Method	Indicates which Subject Confirmation Method will be used by default, if the requester did not specify a method in the WS-Trust request. Possible values are: Bearer Holder of Key with Public Key Holder of Key with Symmetric Key Sender Vouches
Compute Holder-of-Key Symmetric Key	Default: Enabled Indicates whether or not Security Token Service will generate random data when creating the Secret Key for the Holder of Key Symmetric Key data. If true, the server will generate the secret key if the client did not specify entropy. Otherwise it will derive the key from the client and server entropy If false, the client entropy will be used as the secret key
Encrypt RSTR Proof Token	Indicates whether or not the Proof Token must be encrypted when returning the server entropy or secret key to the requester in the WS-Trust response, when the Subject Confirmation method is Holder of Key with Symmetric Key Default: Disabled
Holder-of-Key Symmetric Key Generation Algorithm	Indicates the symmetric key generation algorithm to use to create the secret key when the Subject Confirmation method is Holder of Key with Symmetric Key:

Attribute Mapping: SAML Tokens

When the token type is SAML 1.1 or 2.0, it is possible to define attribute mapping and filter rules that will be applied to the attributes included in the Assertion.

There are three different rules:

• Attribute name mapping where the local name of an attribute can be changed to another value. For example, givenname can be changed to firstname.

• Attribute value mapping where the local value of an attribute can be translated to another value. For example, President to CEO.

• Attribute value filtering where the local value of an attribute can be filtered so it is not included in the outgoing assertion. For example, some sensitive attribute values could be removed while others would be issued.

See Also:

Token Mapping attributes in Figure 34-9 and Table 34-11.

Table 34-7 Issuance Template: Attribute Mapping, SAML Token

Element	Description
Attribute Name Mapping	Defines an optional mapping between the local name of an attribute, and the name used to reference this attribute in the assertion. The mapping is optional. If an attribute does not have a mapping defined, then its local name will be used, and the namespace will be set to urn:oracle:security:fed:attrnamespace for SAML 1.1 Assertions or the format will be set to urn:oasis:names:tc:SAML:2.0:attrname-format:basic for SAML 2.0 Assertions. External Attribute: Contains the externam name of the attribute as it will appear in the Assertion. Local Attribute: Contains the local name of the attribute. Format of Namespace: Contains an optional Format or Namespace. If missing, the namespace will be set to urn:oracle:security:fed:attrnamespace for SAML 1.1 Assertions or the format will be set to urn:oasis:names:tc:SAML:2.0:attrname-format:basic for SAML 2.0 Assertions.
Attribute Value Mapping	Defines an optional value mapping for an attribute that will be included in the Assertion. Note: this attribute value mapping applies to an Attribute Name mapping. In order to define an attribute mapping for an attribute, it is required to first define an attribute name mapping for that attribute. External Attribute: Contains the value that should be included in the Assertion, if the local attribute value matches the Local Attribute/Local Null fields. Local Attribute: Contains the local value of the attribute. External Null: Indicates if the value to be included in the Assertion should be null, if the local value of the attribute matches the Local Attribute/Local Null fields. Local Null: Represents a null local value. Ignore Case: Indicates whether or not Security Token Service should ignore case when comparing the attribute value to the Local Attribute field.
Attribute Value Filters	Defines an optional value filtering for an attribute that will be included in the Assertion. Note: This attribute value filtering applies to an Attribute Name mapping. In order to define an attribute filtering for an attribute, it is required to first define an attribute name mapping for that attribute. Condition: Contains the condition associated with the expression to determine whether or not the attribute value should be filtered. The possible values are described in "Attribute Value Condition Filters". Expression: Contains data that will be used to evaluate the filtering rule. Ignore Case: Indicates whether or not Security Token Service should ignore case when comparing the attribute value to the expression field.

Attribute Value Condition Filters

This optional value filtering applies to an Attribute Name mapping and will be included in the Assertion. To define an attribute filtering for an attribute, you must first define an attribute name mapping for that attribute. The Condition is associated with the expression to determine whether or not the attribute value should be filtered. The possible Condition values are:

• regexp: the expression will contain a regular expression, and if it evaluates to true, the attribute value will be filtered.

• equals: if the attribute value matches the data contained in the expression field, then it will be filtered.

• not-equals: if the attribute value does not match the data contained in the expression field, then it will be filtered.

• not-equals: if the attribute value does not match the data contained in the expression field, then it will be filtered.

• endswith: if the attribute value ends with the data contained in the expression field, then it will be filtered.

• contains: if the attribute value contains an occurrence of the data contained in the expression field, then it will be filtered.

• not-contains: if the attribute value does not contains any occurrence of the data contained in the expression field, then it will be filtered.

• equals-null: if the attribute value is null, then it will be filtered.

• not-equals-null: if the attribute value is not null, then it will be filtered.

34.4.2 Managing a Token Issuance Template

Users with valid Oracle Access Management Administrator credentials can use this procedure as a guide when developing a new Token Issuance Template (or editing an existing template) Skip any steps that do not apply to you.

The following procedure describes how to create a new Token Issuance Template for a Security Assertion Markup Language (SAML) token.

Prerequisites

Confirm that the desired LDAP Identity Store is registered with and configured as the Default Store.

See Also:

• About Managing Token Issuance Templates

• Searching for an Existing Template

To create a new token Issuance template

1. Display the list of existing Token Issuance Templates.

   
   Oracle Access Management Console
   System Configuration
   Security Token Service
   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: Define general information for this template and see:

      Table 34-3, "Issuance Template: General Details"

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

   4. Username Token Type: Define issuance parameters for this template and see:

      Table 34-4, "Issuance Properties: Username Token Type"

   5. SAML Token Type: Define parameters for this template and see:

      Table 34-5, "Issuance Properties: SAML Token Types"

      Table 34-6, "Security Details: SAML Tokens"

      Table 34-7, "Issuance Template: Attribute Mapping, SAML Token"

   6. Click Apply (or click Revert without saving it).

   7. Close the definition.

3. Find an Existing Template: From the Security Token Service section of the System Configuration tab:

   1. Find All: Double-click the Token Issuance Templates node and review the results table.

   2. Narrow the Search: Specify your search criteria (Table 34-1), click the Search Button, and review the results table.

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

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

5. Remove a Template:

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

34.5 Managing Token Validation Templates

A validation template is used to validate an incoming token and, optionally, map the incoming token to either a Requester Partner or a user record:

• For OnBehalfOf use cases, a WS-Trust Validation Template must be present.

• For validating an Assertion, one Issuing Authority Partner Profile must be present.

The Security Token Service Endpoint is linked to a WSS Validation Template that indicates how to validate the token in the WSS header and how to map the token and binding data to a Requester.

This section provides the following topics.

• About Managing Token Validation Templates

• Managing Token Validation Templates

34.5.1 About Managing Token Validation Templates

A Security Token Service Endpoint is always mapped with a WS-Security Validation Template that indicates how to map the request to a requester entry or to a user:

• If mapping is required and no match is found, processing will fail.

• If no mapping is required, a default requester partner profile will be used.

• In either case, a requester partner profile is retrieved.

• If a mapping is performed to a user record, a default requester partner profile will be used.

• If a mapping is performed to a requester partner entry, the requester partner profile for this partner will be used.

A validation template determines the token validation rules:

• Whether or not to validate and map the incoming token.

• The mapping rules to be used if mapping is enabled.

A validation template is specific to a token type and specific to a protocol as described in Table 34-8.

Table 34-8 Validation Template Protocols

Protocol	Description
WS-Security	Validates only WS-Security Tokens: Possible Mapping actions: no action, map binding data to partner, map incoming token to partner, map incoming token to user and binding data to partner, map incoming token to user Token Types supported: SAML 1.1, SAML 2.0, Username X.509, Kerberos, None. When you toggle the Token Protocol from WS-Trust to WS-Security, options in the Token Type list do not change. However, the required "Default Partner Profile" list appears from which you must choose one profile for WS-Security.
WS-Trust	Validates only Tokens included in OBO (on behalf of) field of the RST (request): Possible Mapping actions: none, map incoming token to user Token Types supported: SAML 1.1, SAML 2.0, Username, X.509, Kerberos, OAM, Custom.

A validation template mapping rules determines how the incoming data is mapped to a user or a partner, using data from the incoming token:

• Username for Username Token

• UserID for Kerberos Token

• NameID and attributes for SAML Token

• DN Components for X.509 Token

• Attributes from a Custom

Mapping is performed as follows:

• Simple mapping: one incoming attribute matched against one user record attributes

• Complex LDAP query: LDAP query with placeholders for incoming data (e.g.: (&(sn=%lastname%)(mail=%email%))

• NameID Mapping table for SAML Token

Figure 34-7 illustrates default General details on the New Validation Template page.

Figure 34-7 New Validation Template page: General Page Defaults

Description of "Figure 34-7 New Validation Template page: General Page Defaults"

Table 34-9 describes the elements on the New Validation Template, General page.

Table 34-9 New Validation Template: General Details

Element	Description
Back	Click this button to return to the previous page.
Next	Click this button to proceed to the next page.
Cancel	Click this button to dismiss the page.
Validation Template Name	The name you choose for this template. For example: email-wstrust-valid-temp
Description	Optional.
Token Protocol	The type of Validation Template to be created. Type can be either: WS-Trust: This template will be used to validate and map tokens included in the OnBehalfOf element of the WS-Trust request. WS-Security: This template will be used to validate and map tokens located in the Security SOAP Header of the incoming message
Token Type	A list of in-bound token types from which you choose the one to use for this template. The token type options depends on the protocol type: WS-Trust: SAML 1.1, SAML 2.0, Username, X.509, Kerberos, OAM, Custom WS-Security: SAML 1.1, SAML 2.0, Username, X,509, Kerberos, None
Default Partner Profile	Only applies to WS-Security Validation Template References the default requester partner profile to use, in case the incoming request is not mapped to a requester partner. For example, if the request is mapped to a user instead. A requester partner profiles contains settings that are used during the request processing. If the incoming request was mapped to a requester partner, then the partner profile for that requester will be retrieved and used as the requester partner profile
Timestamp Lifespan	Applies only to Username and SAML Validation Templates. It determines the validity time of a Token (for Username Token, only if it contains a Created element indicating the instant it was created). Default: 1000 (seconds)
Authentication Details	Specific to username token validation template.
Enable Credential Validation	Check this box to enable validation using credentials contained in the username token. When enabled, Security Token Service will validate the username and the password elements contained in the username token, using the specified validation source. Note: password digest as defined in the Username Token WS-Security Profile is not supported in this release. See Also: Table 34-10, "New Validation Template: Authentication Details"

Figure 34-8 illustrates the General details page when Enable Credential Validation is checked and, as a result, the Authentication Details section of the page is visible with its default values. This is specific to username token validation.

Figure 34-8 New Validation Template: General Authentication Details

Description of "Figure 34-8 New Validation Template: General Authentication Details"

Table 34-10 describes Authentication related details that are available when you choose Enable Credential Validation.

Table 34-10 New Validation Template: Authentication Details

Element	Description
Validation Source	A list from which you can choose a credential validation sources There are four types of validation sources when validating the credentials contained in a username token: LDAP: a standalone LDAP server will be used to validate the credentials. The connection information will need to be entered Embedded LDAP: the LDAP server embedded in the WebLogic server will be used to validate the credentials. No information is required. Userstore: the default User Identity Store configured in the Common Configuration -> Data Sources will be used to validate the credentials. No information is required in this validation template screen Partner: the credentials will be verified against the username/password information entered in the Requester Partner entries. Note: When selected, the Token Mapping configuration section is disabled, because the token will have been mapped to a requester partner after the credentials validation operation.
LDAP URL	The URL of the LDAP server.
Admin User	The username of an account used to perform lookups in the LDAP server.
Admin Password	The password of an account used to perform lookups in the LDAP server.
Base DN	The Base search DN used when looking up user records.
Enable HA	Indicates whether or not the LDAP server is in HA mode, fronted by a load balancer.
Person Object Class	The person object class associated with the user records.
Unique Id	The attribute of the user record containing the user unique identifier data.In most cases, is identical to the Credential ID field.
Credential Id	The attribute of the user record containing the username data. This field will be used to lookup user records, based on the username.
Maximum Connections	The maximum number of concurrent opened LDAP connections Default: 50
Connection Wait Timeout	Maximum amount of time to wait when opening a new connection. Default: 5000 (seconds)
Connection Inactivity Timeout	Maximum amount of inactivity time for an LDAP connection, before closing it. Default: 5000 (seconds)
Connection Read Timeout	Maximum number of concurrent opened LDAP connections. Default: 5000 (seconds)

Token Mapping

The Token Mapping section indicates the following:

• If an incoming token needs to be mapped.

• If the incoming token needs to be mapped, what kind of mapping is done. For example, mapping token to user, mapping token to partner, and so on.

• How the mapping is done. For example, by mapping a token attribute to a partner/user attribute, or by using an LDAP query involving several token attributes.

Mapping rules determine how the incoming data is mapped to a user or a partner. The following data of the incoming token is used:

• Username for UNT

• UserID for Kerberos

• NameID and attributes for SAML

• DN Components for X.509

• Attributes from custom

Mapping is performed using the following:

• Simple mapping: One incoming attribute matched against one user record attributes.

• Complex LDAP query: An LDAP query with placeholders for incoming data. For example, (&(sn=%lastname%)(mail=%email%))

• A NameID Mapping table for SAML

Following are several Token Mapping Examples for a new Validation Template:

• Figure 34-9, "Token Mapping: SAML2 WS-Security Validation Template"

• Figure 34-10, "Token Mapping, username-wstrust-validation-template"

• Figure 34-11, "Token Mapping: x509-wss-validation-template"

Figure 34-9 shows the mapping configuration settings required for Security Token Service to map the token to a user record, by matching the NameID value to user records that have a matching attribute, based on the NameID format:

• Enable Map Token to User

• Enable Simple User Mapping

• Disable Attribute Based User Mapping

Figure 34-9 Token Mapping: SAML2 WS-Security Validation Template

Description of "Figure 34-9 Token Mapping: SAML2 WS-Security Validation Template"

Figure 34-10 shows the mapping configuration settings required for Security Token Service to map the token to a user record by matching the username element of the Username token to a user record that has a matching uid. The required settings are:

• Enable Map Token to User

• Enable Simple User Mapping

• Datastore Attribute set to uid

• Disable Attribute Based User Mapping

Figure 34-10 Token Mapping, username-wstrust-validation-template

Description of "Figure 34-10 Token Mapping, username-wstrust-validation-template"

Figure 34-11 shows the mapping configuration settings required for Security Token Service to map the token to a requester partner entry by matching the Subject DN of the certificate to a Requester Partner that has a match on SSL Client Cert DN Identification attribute. The required settings are:

• Map Token to Partner

• Disable Simple User Mapping

• Disable Attribute Based User Mapping

• Enable Simple Partner Mapping

Figure 34-11 Token Mapping: x509-wss-validation-template

Description of "Figure 34-11 Token Mapping: x509-wss-validation-template"

Not all elements apply to all token types and token protocols. The elements that you must define will vary.

Table 34-11 describes the token mapping elements for validation templates.

Table 34-11 New Validation Template: Token Mapping

Element	Description
Map Token to	WS-Security Validation Template: Map Token to list <empty>: no token mapping operation will occur Map token to Partner: The token will be mapped to a requester partner Map Token to User and map binding data to Partner: The token will be mapped to a user, and binding data (such as SSL Client Cert DN or HTTP Basic Auth Username) will be used to map the HTTP request to a requester partner Map token to User: The token will be mapped to a user - - - - - - - - - - WS-Trust Validation Template: Map Token to User Check the box to enable (or clear the checkbox to disable).
Enable Simple User Mapping	Simple user mapping consists of mapping the incoming token to a user record by using a single token attribute and matching it against a single user record attribute. WS-Security Validation Template: Only Username, SAML Assertion, Kerberos. and X.509. WS-Trust Validation Template: Username, SAML Assertion, Kerberos, X.509, OAM and custom token. The layout is different, depending on the token type of this validation template: Username Token: Datastore attribute references the user record attribute that will be matched against the username element of the username token. SAML Assertion: User Token attribute references an attribute from the incoming token that will be matched against the Datastore attribute (defined below) of a user record. The values can be STS_SUBJECT_ID for the NameID Value, or the name of an Attribute contained in the Assertion's AttributeStatement. In the Token Mapping section of a SAML Validation template, the User Token Attribute will either be the NameID selected from the drop down or a SAML Attribute name entered in the text field. Datastore attribute references the user record attribute that will be matched against the User token attribute referenced above. In the Token Mapping section of a SAML Validation template, the Datastore Attribute is the name of the directory attribute that will be used for the LDAP matching query. Kerberos: User Token attribute references an attribute from the incoming token that will be matched against the Datastore attribute (defined below) of a user record. The User Token Attribute can be specified by selecting one of the pre-populated attribute (Kerberos Principal, Kerberos Principal Primary or Kerberos Principal No Domain) or by entering a specific value. Datastore attribute references the user record attribute that will be matched against the User token attribute referenced above. X.509: User Token attribute references an attribute from the incoming token that will be matched against the Datastore attribute (defined below) of a user record. The User Token Attribute can be specified by selecting one of the pre-populated attribute (Subject DN, Common Name, Country Name, State or Province Name, Locality Name, Organizational Name, Organizational Unit Name or Domain Component) or by entering a specific value (which can be set to STS_X509_### by replacing ### with the upper case X.500 component name, for example STS_X509_CN to reference the common name component of the certificate subject). Datastore attribute references the user record attribute that will be matched against the User token attribute referenced above. OAM: Datastore attribute references the user record attribute that will be matched against the username element of the username token. Should be the user ID attribute defined in the Default User Identity Store. Custom: User Token attribute references an attribute from the incoming token that will be matched against the Datastore attribute (defined below) of a user record. The possible values are the names of the attribute returned by the custom token validation module. Datastore attribute references the user record attribute that will be matched against the User token attribute referenced above.
Enable User Name Identifier Mapping	When enabled, define the following: WSS and WS-Trust Validation Templates will contain the same section for the Name Identifier mapping settings. A NameID user mapping operation consists of mapping the incoming SAML Assertion to a user record by mapping the NameID Value to a single user record attribute, based on the NameID format When enabled, Security Token Service evaluates the NameID format, and based on the Name Identifier mapping table which user record attribute should be matched against the Name ID value contained in the Assertion. The Name Identifier mapping table holds the user record attributes to be used for the mapping operation. It contains standard NameID formats, but it can be customized to define custom Name ID formats. To add custom NameID format, click the add button on the Name Identifier mapping table, and enter the custom URI. To set an attribute for a specific NameID format to be used for mapping operation, set the user record attribute on the line for that format.
Enable Attribute Based User Mapping	WSS Validation Template: only Username, SAML Assertion, Kerberos and X.509. WS-Trust Validation Template: only Username, SAML Assertion, Kerberos, X.509 and custom token An Attribute Based User Mapping operation consists of mapping the incoming token to a user record by using an LDAP query and token attributes. The format of the LDAP query defines the mapping rule and specifies the token attributes to be used by their names, surrounded by the percent (%) character. For example, an LDAP query that will map a token based on two token attributes (firstname and lastname) would be (&(sn=%lastname)(givenname=%firstname%)). The possible token attributes depend on the token type. Username Token STS_SUBJECT_ID is the only available token attribute containing the username element of the Username token. SAML Assertion STS_SUBJECT_ID contains the NameID Value. STS_NAMEID_FORMAT contains the NameID Format STS_NAMEID_QUALIFIER contains the NameID Qualifier STS_SAML_ASSERTION_ISSUER contains the Issuer of the Assertion Attributes present in the Assertion's AttributeStatement Kerberos STS_KERBEROS_PRINCIPAL_SHORT contains the Kerberos Principal attribute. STS_KERBEROS_PRINCIPAL_FULL contains the Kerberos Principal Primary attribute STS_KERBEROS_PRINCIPAL_NODOMAIN contains the Kerberos Principal No Domain attribute X.509 STS_SUBJECT_ID contains the Subject DN. STS_X509_CN contains the Common Name STS_X509_C contains the Country Name STS_X509_ST contains the State or Province Name STS_X509_L contains the Locality Name STS_X509_O contains the Organizational Name STS_X509_OU contains the Organizational Unit Name STS_X509_DC contains the Domain Component Custom Token The possible values are the names of the attribute returned by the custom token validation module.
Enable Simple Partner Mapping	Only for WSS Validation Template and for the following token types: Username, SAML Assertion, Kerberos, and X.509. A simple partner mapping operation consists of mapping the incoming token to a partner requester by using a single token attribute and matching it against a partner identification attributes. The layout is different, depending on the token type of this validation template Username Token Partner Datastore attribute references the partner identification attribute that will be matched against the username element of the username token. SAML Assertion Partner Token attribute references an attribute from the incoming token that will be matched against the Partner Datastore attribute (defined below) of a Requester Partner. The values can be STS_SUBJECT_ID for the NameID Value, or the name of an Attribute contained in the Assertion's AttributeStatement. Partner Datastore attribute references the partner identification attribute that will be matched against the Partner token attribute referenced above Kerberos Partner Token attribute references an attribute from the incoming token that will be matched against the Partner Datastore attribute (defined below) of a requester partner. The Partner Token Attribute can be specified by selecting one of the pre-populated attribute (Kerberos Principal, Kerberos Principal Primary or Kerberos Principal No Domain) or by entering a specific value. Partner Datastore attribute references the partner identification attribute that will be matched against the Partner token attribute referenced above X.509 Partner Token attribute references an attribute from the incoming token that will be matched against the Partner Datastore attribute (defined below) of a requester partner. The Partner Token Attribute can be specified by selecting one of the pre-populated attribute (Subject DN, Common Name, Country Name, State or Province Name, Locality Name, Organizational Name, Organizational Unit Name or Domain Component) or by entering a specific value (which can be set to STS_X509_### by replacing ### with the upper case X.500 component name, for example STS_X509_CN to reference the common name component of the certificate subject). Partner Datastore attribute references the partner identification attribute that will be matched against the Partner token attribute referenced above.
Enable Partner Name Identifier Mapping	When enabled, defines the following only for WSS Validation Template and for SAML token types: A NameID user mapping operation consists of mapping the incoming SAML Assertion to a user record by mapping the NameID Value to a single requester partner identification attribute, based on the NameID format. When enabled, Security Token Service will evaluate the NameID format, and based on the Name Identifier mapping table which partner identification attribute should be matched against the Name ID value contained in the Assertion. The Name Identifier mapping table holds the requester partner identification attributes to be used for the mapping operation. It contains standard NameID formats, but it can be customized to define custom Name ID formats. To add custom NameID format, click the Add button on the Name Identifier mapping table, and enter the custom URI. To set an attribute for a specific NameID format to be used for mapping operation, set the requester partner identification attribute on the line for that format.

34.5.2 Managing Token Validation Templates

This is a server side configuration. A default Token Validation Template exists. Users with valid Administrator credentials can use can use the procedure in this section to add, find, edit, or delete token validation templates. Skip any steps that you do not need.

The Security Token Service Endpoint must be linked to a WS Security Validation Template that indicates:

• how to validate the token in the Webservice Security header

• how to map the token and binding data to a Requester

The information here can be applied when you want to validate the following:

• WS-Security tokens present in the SOAP Header, of type: Username, SAML 1.1, SAML 2.0, X.509 and Kerberos.

• WS-Trust tokens present in the OnBehalfOf element or in the ValidateTarget element of the WS-Trust request, of type: Username, SAML 1.1, SAML 2.0, X.509, Kerberos, OAM Session Propagation Token and custom tokens.

The following procedure includes several examples of input following specific parameters. Also, a brief translation appears within parentheses (). For instance: Name (username-token): email-wstrust-valid-temp. Values in your environment will be different.

Prerequisites

See Also:

• "About Managing Token Validation Templates"

• "Searching for an Existing Template"

To manage token validation templates

1. Locate and open the desired Token Validation Template as described in "Searching For a Template".

2. New Token Validation Template:

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

   2. General: Define parameters for this template (Table 34-9). For example:

      
      Name (username-token): email-wstrust-valid-temp
      Token Protocol (WS-Security for token protocol): Webservice
      Token Type (username): email
      Default Partner Profile: requester-profile
      

   3. Authentication: Enable Credential Validation for this template, if needed, and provide details (Table 34-10). If the token type is username, enable credential validation if needed for this template and provide the details.

   4. Token Mapping: Specify preferences for this template based on your token type (Table 34-11).

   5. Click Save and dismiss the confirmation window (or click Cancel 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.

   1. Edit the template definition as needed.

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

4. Remove a Token Validation Template:

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

34.6 Managing Security Token Service Endpoints

An endpoint is a Web Service published by Security Token Service where clients can send WS-Trust requests over SOAP. An endpoint is:

• Protected by a WS Security Policy.

• Bound to WSS Validation Template that will indicate how to validate the security token and how to map it.

• Specific to a token type, namely, the one specified in the WSS Validation Template.

Note:

The WS-Security policy protecting the endpoint must be compatible with the WSS Validation Template bound to the endpoint.

An endpoint is a Web Service endpoint published by Security Token Service and protected by OWSM Agent. An endpoint is bound to:

• A WS-Security policy that will determine the WSS requirements in terms of message protection and security tokens

• A WSS Validation template that will indicate how the request will be processed, how the security token will be validated.

This section provides the following information:

• About Managing Endpoints

• Managing EndPoints

34.6.1 About Managing Endpoints

Security Token Service Endpoint definitions consist of three categories, as shown in Figure 34-12.

Figure 34-12 Endpoints Page

Description of "Figure 34-12 Endpoints Page"

Table 34-12 describes the required Endpoints categories.

Table 34-12 Endpoints Page

Elements	Description
Endpoint URI	The path to the Endpoint, relative to the Security Token Service base URL The Security Token Service base URL is /sts.
Policy URI	Choose from a listing of Oracle WSM policies the one used to protect this Endpoint. Oracle Access Management Administrators can add a new custom policy to the available listing.To show this newly created Policy URI in the endpoints table list, use the following wlst command to update the owsmpolicies map: putStringProperty("/stsglobal/owsmpolicies/<index>", "<newcustom_policypath>) For example: putStringProperty("/stsglobal/owsmpolicies/31", "sts/newcustom_policy")
Validation Template ID	Choose from a listing of Validation Template names to identify one for use with this Endpoint.

Once an Endpoint is created, you can remove it but you cannot edit the definition.

34.6.2 Managing EndPoints

Users with valid Oracle Access Management Administrator credentials can perform the following task to add, edit, or remove an Endpoint.

Prerequisites

Creating a Token Validation Template to reference

To create or delete an endpoint

1. From the Oracle Access Management Console System Configuration tab, open the Security Token Service section.

2. Open the Endpoints node to display a list of existing Endpoints.

3. New Endpoint: see Table 34-12 and

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

   2. Enter the new Endpoint URI.

   3. Choose one of the Oracle WSM policies to protect this Endpoint.

   4. Choose the Validation Template to use with this Endpoint.

   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.

4. Remove Endpoint:

   1. Highlight a row in the Endpoints table and click the Delete (X) button (or choose Delete Selected from the Actions menu).

   2. Confirm removal (or cancel the removal).

34.7 Managing Token Issuance Policies, Conditions, and Rules

This section provides the following topics:

• About Token Issuance Policies

• About Managing Token Issuance Conditions and Rules

• Managing Token Issuance Policies and Conditions

34.7.1 About Token Issuance Policies

A Token Issuance Policy defines the rules under which a token can be issued for a resource (Relying Party Partner) based on the client's identity, with the client either being a Requester Partner or an end user. If a Requester is NOT present, it is assumed that the User (represented by the on-behalf-of (OBO) token or WSS Token) is trying to access the RelyingParty.

When issuing a token, Security Token Service will determine for which Relying Party that token is created, and it will then evaluate if the client is authorized to request the token for that Relying Party. In order to issue a token, a Token Issuance Policy must be created with the resource involved in the operation, and with possibly a condition. At runtime if the policy evaluation is successful, the token will be issued.

You can add Conditions, Rules, and Responses to this Token Issuance Policy.

34.7.2 About Managing Token Issuance Conditions and Rules

The Token Issuance Policy allows the Administrator to define conditions along with "Allow" and "Deny" rules for the policy. Each Token Issuance Policy can contain one or more conditions, and rules that determine whether access to the requested resource should be granted or denied:

• An Allow type rule specifies who is authorized to access a protected resource.

  Only partners and users listed in the Condition are granted access; everyone else is denied access to the resource.

• A Deny type rule specifies explicitly who is denied access to the protected resource.

  Only partners and users listed in the Condition are denied access; everyone else is granted access to the resource.

Note:

When adding User conditions, the identity store from which the users are to be chosen can be selected from a list. Ensure that you choose the Default User Identity Store, which is the only one used by Security Token Service.

Managing Token Issuance Conditions is similar to managing Authorization Conditions and Rules. Figure 34-4 shows the Conditions tab of a Token Issuance Policy.

Figure 34-13 Token Issuance Policies and Conditions

Description of "Figure 34-13 Token Issuance Policies and Conditions"

Table 34-13 describes the Token Issuance Condition requirements.

See Also:

Part IX, "Managing Oracle Access Management Mobile and Social" for details about Adding a Token Issuance Policy for Mobile and Social Authentication Service

Table 34-13 Conditions tab: Token Issuance Policy

Element	Description
Summary tab
Name	A unique name for this Token Issuance Policy.
Description	Optional.
Conditions tab	Table 17-18 describes elements and controls on the Conditions tab.
Class	Only Token Requester Identity is allowed for Token Issuance Policy conditions. You choose this in the Add Condition dialog box.
Rules tab	Table 17-29 describes the elements and controls on the Rules tab for Simple Mode evaluations. Table 17-30 describes the elements on the Rule tab in Expression mode.
Condition Details
Add	Choose from the following populations: Add Identities: This choice opens a Search window where you can set the Store Name, Choose an Entity Type (All, User, or Group), and Provide an Entity Name. You then choose one or more results from those listed and click Add Selected to populate the condition. Add Partners: This choice opens a Search window where you can locate specific partners to populate the condition. Enter your search criteria (or click the arrow key beside the field to find all partners), then choose one or more results and click Add Selected to populate the condition.
Entity Name	The name of the User or Group, as defined in the selected User Identity Store.
Entity Type	The type of entity you want to locate during a search to add identifies to the condition: User, or Group.
Store Name	Choose the name of the User Identity Store to search for users or groups to populate the condition. Remember, Security Token Service uses only the Default Identity Store.

34.7.3 Managing Token Issuance Policies and Conditions

Users with valid Administrator credentials can use the following procedure to add a Token Issuance Policy and Conditions to an Application Domain. When adding resources to this policy, you might want to add the UnknownRP and MissingRP resources.

Prerequisites

The Application Domain must already exist.

Note:

You can add Token Issuance Policies to the IAM Suite Application Domain.

To manage Token Issuance Policies and conditions

1. Locate the desired domain as described in "Searching for an Existing Application Domain".

2. On the individual Application Domain page, click Token Issuance Policies tab.

3. Create a Token Issuance Policy:

   1. In the desired domain, click the Token Issuance Policies tab and then click the Create Token Issuance Policy button to open a fresh page.

   2. On the Summary page, enter a unique name and optional description.

4. Add Resources: This step presumes that the resource has been defined in the Application Domain and is ready to be added to policies.

   1. Click the Resources tab.

   2. Click the Add (+) button.

   3. Click the Search button to display a list of defined resources you can add.

   4. Click the desired resource in the results table, then click Add Selected.

   5. Repeat as needed to add any other resources to this policy.

5. Add Conditions to a Policy: The only types available are Token Requester Identity or True.

   1. Click the Conditions tab, then click the Add button on the Conditions tab to display the Add Condition window.

   2. Enter a unique name for this condition in the dialog box.

   3. Choose Token Requester Identity from the Type list.

   4. Click Add Selected.

   5. Proceed with Step 5 to add details for Token Requestor Identity. Otherwise, skip to Step 6.

6. Add Conditions Details:

   1. Click the Condition name to display Conditions: Details.

   2. From the Selected Identities table, click the Add button and choose either:

      Add Partners: In the Search field, enter criteria (or click the arrow key beside the field to find all partners); click one or more results then click Add Selected to populate the condition.

      Add Identities: Select the Store Name, select the desired Identity Type, enter search criteria and click the Search button; choose one or more results and click Add Selected to populate the condition.

   3. Click the Save button on the Condition Details panel.

7. Add Rules: Perform these steps to Allow or Deny access based on your Conditions.

   1. Click the Rules tab.

   2. Check the Rule Mode: Simple or Expression.

   3. Expression Mode: Build your expression by entering operators (Table 17-31) and choosing and inserting conditions (Table 17-30).

   4. Simple Mode: Click to Match either All or Any of the selected conditions, then using arrows for Allow (or Deny) Rule, move desired conditions from the Available Conditions column into the Selected Conditions column.

8. Click Apply and then close the Confirmation window.

9. Find (or Add) TokenServiceRP Resources in the Application Domain: See "Managing TokenServiceRP Type Resources".

34.8 Managing TokenServiceRP Type Resources

A Token Issuance Policy defines the rules under which a token can be issued for a resource (Relying Party Partner) based on the client's identity, with the client either being a Requester Partner or an end user.

When issuing a token, Security Token Service will determine for which Relying Party that token is created, and it will then evaluate if the client is authorized to request the token for that Relying Party.

Note:

To issue a token, a Token Issuance Policy must be created with the resource involved in the operation and, possibly, with a condition. At run time if the policy evaluation is successful, the token will be issued.

The resource(s) in a policy can be:

• A TokenServiceRP type resource represents resources for, and is based on, the Token Service Relying Party (required for Mobile and Social REST clients).

  See Also:

  Part IX, "Managing Oracle Access Management Mobile and Social" for details about Configuring Access Manager for Mobile and Social Authentication Service

• The pre-existing UnknownRP resource which is needed when Security Token Service is not able to map the Service URL referenced in the AppliesTo element of the WS-Trust request to an Security Token Service Relying Party Partner entry.

• The pre-existing MissingRP resource which is needed when the AppliesTo element of the WS-Trust request is missing.

Note:

Both the MissingRP and UnknownRP are defined in the IAM Suite Application Domain.

A resource of type TokenServiceRP, Figure 34-14, represents an Security Token Service Relying Party Partner defined in the Security Token Service Partner Store.

Figure 34-14 Pre-defined Resource Type: TokenServiceRP

Description of "Figure 34-14 Pre-defined Resource Type: TokenServiceRP "

Resources of type TokenServiceRP are used in Token Issuance Policies, which are evaluated when Security Token Service issues tokens at run time. This is a predefined resource type, which cannot be deleted. However, additional operations can be created, edited or deleted as needed. Predefined operations are shown with a lock icon.

For more information, see:

• About Managing TokenServiceRP Type Resources in Access Manager

• Managing TokenServiceRP Type Resources in Application Domains

34.8.1 About Managing TokenServiceRP Type Resources in Access Manager

Use the Search controls for the Application Domain to locate resources of a specific type within the domain. Figure 34-15 shows the search controls for the IAM Suite resources. Resource Type TokenServiceRP is the search criteria. The Search Results table lists all resources of this type within the Application Domain.

Figure 34-15 Search: Resource Type TokenServiceRP in Application Domain

Description of "Figure 34-15 Search: Resource Type TokenServiceRP in Application Domain"

The TokenServiceRP resources in this domain include those provided out of the box, and described earlier:

• UnknownRP resource

• MissingRP resource

34.8.2 Managing TokenServiceRP Type Resources in Application Domains

Users with valid Administrator credentials can use the following procedure to add TokenServiceRP resources to an Application Domain.

Note:

• If AppliesTo is present in the RST but the requester could not be mapped, use the TokenServiceRP:UnknownRP resource.

• If AppliesTo is not present, use TokenServiceRP:MissingRP, otherwise select the appropriate resource.

See Also:

"About Managing TokenServiceRP Type Resources in Access Manager"

To manage TokenServiceRP Resources

1. Locate the desired Application Domain as described in "Searching for an Existing Application Domain".

2. Add TokenServiceRP Resource to the Application Domain:

   1. Click the New Resource button on the Application Domain Search page.

   2. Specify the Resource Type as TokenServiceRP.

   3. Enter a Resource URL that is the Relying Party ID for whom the token issuance policy will be defined.

   4. Click the Apply button at the top of the page to submit this and dismiss the confirmation window.

   5. See Also: "Defining Resources in an Application Domain".

3. Find TokenServiceRP Resources:

   1. In the desired Application Domain, open the Resources tab to display the Search controls.

   2. From the Resource Type, choose TokenServiceRP, and click Search.

   3. Review the Search Results table and click a name to open the Resource Definition.

34.9 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. This section describes how to make custom classes available using the console.

The information here can be applied 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 Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

This section provides the following topics:

• About Making Classes Available

• About Narrowing a Search for Custom Tokens

• Managing Custom Tokens

34.9.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, *), as shown in Figure 34-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 34-16 New Custom Token Page

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

Figure 34-17 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 34-14 describes the elements on a Custom Token page based on the examples in this chapter.

Table 34-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.

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 34-17 and Table 34-14.

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

34.9.2 About Narrowing a Search for Custom Tokens

Figure 34-18 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 34-18 Custom Tokens Search Page and Controls

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

Table 34-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:
	Controls affecting the ordering of items listed in the results table: Ascending Descending

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

Refer to the developer creating the custom tokens and the Oracle Fusion Middleware Developer's Guide for Oracle Access Management for details about:

Writing a TokenValidatorModule Class

Writing a TokenIssuanceModule Class

See Also:

• "Making Custom Classes Available"

• "About Narrowing a Search for Custom Tokens"

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: From the Oracle Access Management Console System Configuration tab, open the Security Token Service section and:

   1. Open the Custom Tokens node to open the Search controls.

   2. Click the New Custom Token button.

   3. Fill in the New Custom Token page with details for your custom classes (Table 34-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 to "Managing a Custom Security Token Service Configuration".

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

   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 (Table 34-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).

34.10 Managing a Custom Security Token Service Configuration

This tasks consists of the following procedures:

• Creating the Validation Template

• Creating the Issuance Template for a Custom Token

• Adding the Custom Token to a Requester Profile

• Adding the Custom Token to the Relying Party Profile

• Mapping the Token to a Requestor

• Creating an /wssuser EndPoint

34.10.1 Creating the Validation Template

Users with valid Oracle Access Management 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 34-19, "General Details: email-wstrust-valid-temp"

• Figure 34-20, "Token Mapping: email-wstrust-valid-temp"

Figure 34-19 General Details: email-wstrust-valid-temp

Figure 34-20 Token Mapping: email-wstrust-valid-temp

To create the validation template for the custom module classes

1. Display the list of existing Token Validation Templates.

   
   Oracle Access Management Console
   System Configuration
   Security Token Service
   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".

34.10.2 Creating the Issuance Template for a Custom Token

This is a server side configuration. Users with valid Oracle Access Management 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 34-21, "General Details: email-issuance-temp"

• Figure 34-22, "Issuance Properties: email-issuance-temp"

Figure 34-21 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 34-22.

Figure 34-22 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 Management

To create the Issuance Template for the custom module classes

1. Find existing Token Issuance Templates.:

   
   System Configuration
   Security Token Service
   Token Issuance Templates
   Search button (with or without filling in search criteria)
   

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: Find the desired template, edit details, and click Apply.

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

34.10.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 Management Console System Configuration tab, open the Security Token Service 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 "Adding the Custom Token to a Requester 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 "Adding the Custom Token to a Requester Profile".

34.10.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 Management Console System Configuration tab, open the Security Token Service 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.

34.10.5 Mapping the Token to a Requestor

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

Validation Template Name: username-wss-valid-template

Token Type: Username

Proceed to "Creating an /wssuser EndPoint"

34.10.6 Creating an /wssuser EndPoint

Prerequisites

Mapping the Token to a Requestor

To create an endpoint

1. From the Oracle Access Management Console System Configuration tab, open the Security Token Service 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.