Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Access Resource Protected by Oracle Access Manager Assertion

Last update August 22, 2018

The Access Resource Protected by Oracle Access Manager assertion delegates authentication and authorization to an Oracle Access Manager 10g or 11g server. It also populates context variables with the values and attributes set for the action on Authorization Rules (on the OAM server).

You can control whether the obSSO cookie is excluded in the outbound request and set its contents in a custom context variable.

Separate Installation Required

For instructions on how to install this assertion, see Install the Oracle Access Manager Assertion. Once installed, this assertion is available from both the Access Control and Custom Assertions palettes.

Note: During an Oracle Access Manager session, if the username in the session token does not match the username in the HTTP request, then the assertion fails during authentication validation.

Context Variables Created by This Assertion

The Access Resource Protected by Oracle Access Manager assertion sets the following context variables with details of the verification.

Variable Description
${<prefix>.actions.type} A multivalued context variable that returns all action types.
${<prefix>.actions.<type>.names}  A multivalued context variable that returns all names related to a certain type, specified by "<type>".
${<prefix>.actions.<type>.<name>}  Returns a values or attribute related to a certain type and name, specified by "<type>" and "<name>".
oam.ssoCookie

Returns the content of the SSO Cookie.
"oam.ssoCookie" is the default variable name and can be changed via the assertion properties.

oam.ssoCookie.name Returns the name of the OAM SSO cookie.
oam.ssoCookie.value Returns the session token of the OAM SSO Cookie.

The default variable prefix is oamResponse. This can be changed in the assertion properties.

Certificate Authentication

The Access Resource Protected by OAM assertion can authenticate a user via a TLS or SSL Client X.509 certificate from a HTTP request or a context variable, depending on how the Oracle Access Manager is configured.

Authentication via Certificate

If the Oracle Access Manager is configured to authenticate via certificate:

  1. This custom assertion will first attempt to extract the certificate from the context variable oracleAccessManager.ssl.clientCertificate.base64. This variable can be set by previous assertions in a policy.
  2. If the variable is not defined, the custom assertion will attempt to retrieve the certificate from the HTTP request.
  3. If no certificate can be found, authentication fails even if a username/password is presented.

Authentication via Username/Password

If the Oracle Access Manager is configured to authenticate via username/password:

  1. The custom assertion will use the provided username/password for authentication. If a certificate is also present, it is not used for authentication.
  2. If no username/password is supplied, authentication fails even if a certificate is presented.

Using the Assertion

  1. Do one of the following:
    • To add the assertion to the policy development window, drag and drop the assertion from the palette into the policy window.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. Right-click Access Resource Protected By Oracle Access Manager in the policy window and select Oracle Access Manager Protected Resource. The properties dialog appears.
  3. Configure the properties as follows:

    Setting Description
    Protected Resource

    Enter the full name of the resource being protected. This should be in the format:

    //<host>:<port><resource_URL>

    Where:

    • <host> is the hostname of the server that is servicing <resource_URL>
    • <port> is the port number on the server (optional)
    • <resource_URL> is the resource being serviced; this resource definition should follow the guidelines set by Oracle Access Manager

    You can also specify a context variable that contains the resource.

    Note the following:

    • The <host> and <port> must be defined in one of the host identifiers via the OAM Admin Console.
    • The <resource_URL> must be defined in one of the Resources in the Application Domains via OAM Admin Console.
    • The <host> does not need to be an actual hostname, as long as it is defined in a host identifier via the OAM Admin Console.
    Type

    Enter the type of the resource. This can be a built-in type, such as HTTP or EJB, or a custom type defined through the Access System Console. For custom resource types, custom operations are defined using the Oracle Access Manager system console when the resource type is defined.

    You can also specify a context variable that contains the type.

    Default: HTTP

    Method

    Enter the action to be performed against the protected resource, as dictated by the resource type. Examples are GET and POST for HTTP resources, and EXECUTE for EJB resources. For custom resources, operations are defined through the Access System Console when the resource type is defined.

    You can also specify a context variable that contains the method.

    Response Variable Prefix

    Enter a prefix that will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent the variables from overwriting each other when multiple instances of this assertion appear in a policy.

    Default prefix: oamResponse

    For an explanation of the validation messages displayed, see Context Variable Validation.

    Set Location IP Address This is the IP address of the client. By default (pre-v8.3 behavior), this assertion uses the IP address from the inbound request in the user session parameters. If you need to override this IP address (for example, to use the address of the Gateway on which this custom assertion is installed), select the check box and enter the IP address in the adjacent box. You may reference context variables.
    Skip Validation

    This assertion compares the IP address of the client against the address that is stored in the session token. The assertion fails if they differ.

    The Gateway compares addresses by default. Select this check box to skip the IP comparison.

    When should I skip IP comparison?

    If you encounter unexpected failures with this assertion, skipping the validation may resolve the issue. Examples of when to skip:

    - You receive the message "Rejected session from cookie due to location IP address changed"

    - You receive the message: "Illegal Group Reference”

    - This assertion is called more than once in a policy and the IP address changed, resulting in an unexpected failure.

    Get Session Token from 

    Choose the source to obtain the session cookie: from the Inbound Request message or from the specified Context Variable. This variable may be entered with or without the wrapper: "${ }".
    The default is to use the inbound request.

    Note: The context variable must not contain the reserved names of ObSSOCookie= or obSSOCookie=.

    Save SSO cookie in context variable:

    Specify a context variable to save the SSO cookie and value, including all specified cookie attributes.

    Default: oam.ssoCookie

    You can access specific cookie information using these suffixes:

    • <variable>.name: Returns the name of the OAM SSO cookie.
    • <variable>.value: Returns the value of the OAM SSO cookie.
    Omit SSO cookie in Outbound Request

    Select this check box to exclude the ObSSOCookie from the outbound request. Tip: You can exclude the cookie to avoid certain problems. For example, this assertion is used to authenticate and authorize consumer access to a service, but the CA API Gateway needs to identify itself with a different set of credentials to an OAM-protected service endpoint.

    Clear this check box to not exclude the cookie in the outbound request.

    Note: Clearing the check box does not guarantee that the outbound request will contain an SSO Cookie or an updated SSO cookie.

    Tip: To ensure that the outbound request contains an SSO Cookie, use either the Manage Transport Properties/Headers Assertion or the Route via HTTP(S) Assertion to add the cookie using the oam.ssoCookie context variable.

    Omit SSO cookie in Outbound Response When this custom assertion finishes executing, the ObSSOCookie is automatically included in the HTTP response header. Select this check box to exclude the cookie from the response.
    Set cookie attributes

    Select this check box to set the cookie attributes.

    • Domain: Enter the domain for which the cookie is valid (optional).
    • Path: Type the full path that specifies the subset of URLs to which this cookie applies (optional).
    • Expiry: Enter the lifetime of the cookie, in seconds (optional). A negative value indicates that the cookie is not stored persistently and will be deleted when the browser is closed. The default is -1,which the cookie will persist until the browser is closed.
    • Version: Enter the required version of the state management specifications to which the cookie conforms. The default is 0, which means the cookie is using the Netscape cookie format. Any other versions (for example, 1+) mean that the cookie is using the RFC 2109 cookie format.
    • Comment: Enter any comments (optional). Note: As cookies can contain private information about a user, the Cookie attribute allows an origin server to document its intended use of a cookie. You can then inspect the information to decide whether to initiate or continue a session with this cookie.
    HTTP only

    Select this check box to direct browsers to use cookies via the HTTP or HTTP(S) protocols. This setting is the default.

    Clear this check box to allow browsers to use cookies via other protocols.

    Secure

    Select this check box to direct browsers to use cookies only via encrypted/secure connections.

    Clear this check box to allow browsers to use cookies in unsecured connections.

    Note: The values used are determined by the configuration of the Oracle Access Manager System.

  4. Click [OK].

When a successful authorization call is made to Oracle Access Manager using this assertion, the obSSOCookie is added to the response HTTP header (unless suppressed). If the cookie is available in the request HTTP header on subsequent calls to the CA API Gateway policy using the Access Resource Protected by Oracle Access Manager assertion, the cookie will be used as the authorization credentials for the user.

When a user is authenticated by the Access Resource Protected by Oracle Access Manager assertion, the authorization action information is made available in the policy using the context variables created by this assertion.

Note: Failed authorization action information still requires a user to be authenticated, but not authorized to access the specified resource.
Was this helpful?

Please log in to post comments.

  1. Francois Lascelles
    2018-08-20 08:17

    It appears that the separate licensing requirement suggested in Note above is an error and that the gateway license entitles the licensee to use this assertion without an additional license. Incorrect statement: "The Access Resource Protected by Oracle Access Manager Assertion is a custom assertion that requires separate licensing and installation." in the doc above

    1. Carl Lum
      2018-08-21 03:20

      Thanks for letting me know, Franco. I'll remove that note.