25.13 Introduction to Policy Responses for SSO

Each policy can optionally contain one or more authentication or authorization responses, or both. Responses are post-processing actions (obligations) to be carried out by the web agent.

Note:

There are no responses in Token Issuance Policies.

This section provides the following information:

25.13.1 Authentication and Authorization Policy Responses for SSO

Administrators can define responses that declare the actions that must be fulfilled after successful authentication or authorization. Authentication and authorization data is returned to the client (typically a Web Agent).

Policy responses enable the insertion of information into a session or application and the ability to withdraw the information at a later time to enable SSO. For instance, identity mappings can be inserted into the customer's application or actions can be carried out by the Agent or the application.

Depending on the responses specified for authentication or authorization success and failure, the user might be redirected to a specific URL, or user information might be passed on to other applications through a header variable or a cookie value.

Note:

Oracle Access Manager 10g provided data passage to (and between) applications only by redirecting to URLs in a specific sequence.

There are no default response provided. Figure 25-30 illustrates an Authorization Policy Response defined by an Administrator in the Oracle Access Management Console. Authorization responses can operate in conjunction with authorization conditions.

Figure 25-30 Authorization Policy Response in the Console

Description of "Figure 25-30 Authorization Policy Response in the Console"

Each response consists of two inputs (a type and an expression) and a single output (the value of the evaluated expression). The expression declares how the value should be constructed when the expression is processed. The response type defines the form of action to be taken with the value string.

The authentication policy determines the identity of the user. Each authentication policy requires an authentication scheme and responses (expressions).
The authorization policy determines whether the user has the right to access the resource. Each authorization policy requires authorization conditions and responses (expressions).

Response Guidelines

Cookie, Header, and Session responses are supported.
URL redirection can be set.
Response definitions are part of each policy. Response values can be literal strings or can contain additional embedded expressions that derive values from request, user, and session attributes.

Administrators set Responses in the Oracle Access Management Console, as described Table 25-25.

Table 25-25 Response Elements

Element	Description
Name	A unique name to distinguish this response from other responses that use the same mechanism (type).
Type	The mechanism used to convey the response. form of the action to be taken with the value string: HEADER (Header variables): Sets an HTTP request header for downstream applications using the defined value to dictate the action to be taken (such as the assertion of a User ID using a pre-defined HTTP header name). Another example gets the subscriber information (realm DN and so on) for OSSO and creates a response during the upgrade; a fresh OSSO Agent requires manual configuration. SESSION: Sets an attribute inside the user session by the client (to enable single sign-on) based on the defined session variable name and value. COOKIE: Sets a variable name and value (typically set by Web agents) inside the authentication session cookie to enable single sign-on. In cookie-less mode, Web-cache is currently used to store cookies from Webgate. However, in cookie-less mode, the end application does not have access to cookies and cannot use them. Asserted Attribute: With this type, Identity Assertion must be enabled for the policy to collect Assertion Attribute type responses when this policy is executed. The Name list provides valid identifiers from which to choose.
Value	The response expression, set as a variable. For more information, see "About the Policy Response Language".
Identity Assertion	Identity Assertion is required for ID propagation for any issued token from Access Manager that represents an end user (and possibly its Access Manager session). Security Token Service clients that are Web applications protected by Access Manager requesting tokens to gain proxy access to a Relying Party (ID Propagation use case) are required to pass an Access Manager Identity Assertion token that represents the end user. The Identity Assertion Token is generated and returned as a policy response (HTTP HEADER named "OAM_IDENTITY_ASSERTION", value as a SAML token) after a successful authentication. As you add each (non-Asserted Attribute Type) Response, you might be informed that `Identity Assertion has not been enabled for this policy....` Enable Identity Assertion to collect Assertion Attribute type responses when this policy is executed. See Also: "Scenario: Identity Propagation with the Access Manager Token" Authentication Policy Response for Identity Assertion by Webgate Using Identity Context

25.13.2 About the Policy Response Language

Access Manager authentication and authorization responses are defined using a very small, domain-specific language (DSL) with two main constructs.

Literal strings: For example: This is a valid expression
Variable references:
- Declared using a dollar sign prefix $
- Scoped to a namespace: $namespace.var_name
  
  Note:
  
  Certain variables include an attribute: $ns.name.attribute

25.13.3 Namespace and Variable Names for Policy Responses

With the namespace mechanism, the following variable types are to enable single sign-on:

Request: Information on the requested resource, the client making the request, and the policy matched during evaluation
Session: User session details
User: User details (user ID, group, and attribute information)

For details of each, see:

Table 25-26 Namespace Request Variables for Single Sign-On

Namespace	Description
agent_id	Name of the requesting agent
client_ip	IP address of the user browser
policy_appdomain	Name of the Application Domain holding the policy matched for the request
policy_eval_success_conditions	List of policy conditions that evaluated to true, separated by COLON or configured response separator
policy_eval_failure_conditions	List of policy conditions that evaluated to false, separated by COLON or configured response separator
policy_res	Resource host ID and URL pattern matched for the request
policy_name	Name of the specific policy matched for the request
res_host	Requested resource's hostname
res_port	Requested resource's port number
res_type	Requested resource's type
res_url	Requested resource URL path
res_complete_url	Requested resource URL path with query string

Table 25-27 Namespace Session Variables for Single Sign-On

Namespace	Description
attr	Reference to an arbitrary session attribute, the name of which is passed to us as a variable attribute. Its value has been bound to the session by executing a session response during a previous request.
authn_level	Current authentication level for the session
authn_scheme	Name of the authentication scheme executed to achieve the current authentication level
count	Session count for the user bound to this session
creation	Session creation time
expiration	Session expiration time

Table 25-28 Namespace User Variables

Namespace	Description
attr.<attrName>	Value of user attribute attrName. If attrName is multivalued, list of values, separated by COLON or configured response separator.
groups	List of user's group membership, separated by COLON or configured response separator.
userid	The user ID
user.id_domain	The user's identity domain (essentially the same as the identity store)
guid	A unique identifier that locates the user entry in an Identity Store

25.13.4 About Constructing a Policy Response for SSO

This section is divided as follows:

25.13.4.1 Simple Responses

After deciding on the response type and determining which namespace and variable, you simply enter the response attributes in the Oracle Access Management Console.

A simple response might look like one of the several authorization responses shown in Figure 25-31.

Figure 25-31 Simple Response Samples

Description of "Figure 25-31 Simple Response Samples"

Simple responses stand alone. Each is preceded with the dollar sign ($), followed by the namespace, which is separated from the variable Value by a dot (.). For example:

$namespace1.var1

Table 25-29 illustrates several simple responses and a description of what each one returns.

Table 25-29 Simple Responses and Descriptions

Name	Type	Value (Simple $Namespace.Variable)	Returned Environment Variables and Values
oam_sessioncount	Header	$session.count	HTTP_OAM_SESSIONCOUNT integer
oam_userid	Header	$user.userid	HTTP_OAM_USERID name
oam_ipaddress	Header	$request.client_ip	HTTP_OAM_IPADDRESS nnn.nn.nn.nnn
oam_literal	Header	This is a response string.	HTTP_OAM_LITERAL This is a response string

25.13.4.2 Compound and Complex Responses

When crafting a compound or complex policy response, Administrators can combine literals and variables arbitrarily using braces { } to construct an expression. A colon (:) is used as a separator.

For example:

${namespace1.var1}:${namespace2.var2}

Literal String (LS): ${namespace1.var1}:${namespace2.var2}

LS: ${namespace1.var1}, LS:${namespace2.var2}

Figure 25-32 illustrates several complex responses defined by an Administrator. All are Header type responses, which set values in a header variable of an HTTP request for consumption by a downstream application.

Figure 25-32 Complex Response Sample

Description of "Figure 25-32 Complex Response Sample "

Table 25-30 describes the complex responses shown in Figure 25-32.

Table 25-30 Complex Responses

Name	Value	Returned Environment Variables and Values
oam_resinfo	Runtime resource: ${request.res_host}:${request.res_port}${request.res_url}	HTTP_OAM_RESINFO Runtime resource: myhost.domain.com:1234/cgi-bin/myres3
oam_clientinfo	Runtime client: Agent ID: ${request.agent_id}, Browser IP: $request.client_ip	HTTP_OAM_CLIENTINFO Runtime client: Agent ID: RREG_OAM, Browser IP: 123.45.67.891
oam_userinfo	${user.userid}'s groups: ${user.groups}, description: ${user.attr.description}	HTTP_OAM_USERINFO WebLogic's groups: Administrators, description: This user is the default Administrator
oam_sessioninfo	Session creation/expiration/count: ${session.creation}/${session.expiration}/${session.count}	HTTP_OAM_SESSIONINFO Session creation/expiration/count: Tue Oct 23 17:47:42 PST 2011/Wed Oct 24 01:47:42 PST 2011/7
oam_app_user	$user.userid	HTTP_OAM_USERID name

For more information, see "About Policy Response Processing".

25.13.4.3 Multi-Valued Responses

Access Manager 11g supports responses with multiple values. These can be multivalued user attribute responses, user's group membership responses and the like. For multivalued responses, Access Manager uses a COLON as the separator and a BACKSLASH as the escape character.

For example, if a user attribute genType has the values "Gold", "Platinum" and "Silver", the policy response for $user.attr.genType would be:

"Gold:Platinum:Silver"

If a COLON appears in any of the attribute values, it will be escaped with BACKSLASH. For example, for a user with group memberships as "Administrators", "Special:Users", the policy response for $user.groups would be

"Administrators:Special\:Users"

It is possible to change the default separator and escape character using the configurePolicyResponses(responseSeparator, responseEscapeChar) WLST command.

25.13.5 About Policy Response Processing

Policy response processing occurs during the authorization request for which the authentication responses are replayed. Variable references are filled with appropriate values to ensure that all variables have a value set, and can be set consistently with authorization values.

Processing a response expression is done through a series of steps:

Scanner/tokenizer
Parser
Interpreter

During interpretation, variable references are resolved to values. The result after processing is a simple String value, which is propagated to the Agent or saved within the session for future use.

Authentication success responses are saved and then "replayed" along with any authorization responses on the first applicable authorization request.

Authorization response expressions create the actions to be taken, depending on the evaluation of the expression: success, failure, or inconclusive.

Note:

Oracle Access Manager 10g exhibits the same behavior in the "authenticating Webgate" configuration. This is also employed by Access Manager 11g with 10g Webgates: The 10g Webgate always redirects to the Access Manager 11g credential collector which acts like the authenticating Webgate.

When referencing a variable, either the value is returned, or the following is returned:

NOT FOUND is returned if the variable is not set
NULL is returned if the variable is set to a null value

Note:

Verify the Responses.

Pass Through Without Processing:

A value that must be passed through without processing, can be identified using a \. For example:

\$1000

results in the value $1000 appearing in the returned value.

25.13.6 Assertion Claims and Processing

For details, see Using Identity Context.