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 follows
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

  1. Cookie, Header, and Session responses are supported.

  2. URL redirection can be set.

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

  • 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".

 

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:

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