38.7 Using the Attribute Sharing Plug-in for the Attribute Query Service

Identity Federation provides an attribute sharing plug-in to enable Access Manager to request user attributes from an IdP.

In this interaction, the SP is an <AttributeQuery> requestor and the IdP is an <AttributeQuery> responder. The Attribute Sharing Plug-in depends on the Attribute Query Service, a request/response protocol transported using SOAP.

Note:

The Attribute Sharing Plug-in leverages the AttributeQuery requestor service to implement (a superset of) the X.509 Authentication Based Attribute Sharing Profile (XASP) in the context of Access Manager authentication flows.

Identity Federation (when configured as an SP) can send a SAML 2.0 <AttributeQuery> to the IdP in response to a SOAP call. The plug-in can be configured as a step in an Authentication Scheme. It can be invoked after authentication (by another plug-in) to fetch attributes for the authenticated user and set them into the Access Manager session. The following sections contain additional details.

38.7.1 Understanding the Plug-in and Query Service Design

Identity Federation must be configured as an SP to request user attributes from a remote IdP.

Figure 38-4 illustrates the design of the Attribute Sharing plug-in from a high level.

Figure 38-4 Attribute Sharing Plug-in Design

Description of Figure 38-4 follows
Description of "Figure 38-4 Attribute Sharing Plug-in Design"

The Attribute Sharing plug-in can be part of an Access Manager Custom Authentication Module and is invoked after a user has been authenticated. The Attribute Sharing plug-in will fetch the user attributes by invoking the Identity Federation Java API, setting the attributes into the Access Manager session and transforming the Java arguments into an Attribute Request that can be processed by the SP. The Identity Federation SP receives the Attribute Request (at an exposed SOAP endpoint), determines the attributes being requested and sends an (optionally) signed and encrypted SAML 2.0 <AttributeQuery> using the requested attribute names over a SOAP/HTTP/SSL channel to the IdP's Attribute Responder Service.

Note:

When invoking the Attribute Sharing plug-in, the framework will provide the following for inclusion in the <AttributeQuery>:

  • User ID of the authenticated user or SubjectDN if available

  • Partner ID user session attribute (available only if the Federation Authentication plug-in was used to authenticate user)

  • Tenant Name

  • IdP Name if the plug-in was created specifically for an IdP

The Attribute Responder Service (at the remote IdP) receives the <AttributeQuery>, decrypts it (verifying the signature if necessary) and determines (from its local policy) if the SP is authorized to request the attributes. If so, it retrieves the attributes from a user repository, constructs and (optionally) signs and encrypts an <Assertion> (with an <AttributeStatement> containing the attribute values) and returns a <Response> with the assertion to the SP. On receiving the <Response>, the SP decrypts the assertion, verifies (if necessary) its signature, extracts the attributes from the assertion and set the information in the Access Manager session. The following sections contain more details.

38.7.1.1 Using the SP Attribute Requester

The Attribute Requester Service processes the SOAP Attribute Request and returns a SOAP Attribute Response.

See Using the SOAP Endpoint.

The Attribute Request includes a SubjectDN and a list of other requested attributes and their values. The Attribute Requester Service identifies the IdP from which to fetch attributes by extracting one of the following (searched for in the order listed) from the request.

To use the SP Attribute Requester

  1. The partner/IdP name if the request comes from the Federation engine.
  2. The IdP configured in the plug-in used for authentication.
  3. The request's Subject DN to determine which IdP will get the query from the configured SubjectDN-IdP map. Map the SubjectDN from most specific (cn=Joe User,ou=Finance,o=Company,c=US) to least specific (c=US).
  4. The default IdP.

Following this discovery, the Attribute Requester Service retrieves the SOAP Attribute Responder Service endpoint URL from the IdP's metadata and creates a list of attributes to fetch by processing the attributes in the request through the Attribute Mapping profile.

Note:

Attribute Mapping profile specified for the target IdP will be used to change any incoming attribute names as well as add any attributes that are configured as send-with-sso (always requested) in the Attribute Mapping for this IdP.

A SAML Attribute Query is generated with the attribute list and sent to the IdP's SOAP endpoint. Once a response is received, the subject is verified and the each attribute is extracted from the Assertion, its value is found and both attribute and value are cached. Finally, an Attribute Response SOAP message is constructed and returned to the caller.

The following example represents a sample SOAP Attribute Request.

Sample SOAP Attribute Request

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <attrreq:AttributeRequest TargetIDP="adc.example.com"
          xmlns:attrreq="http://www.example.com/fed/ar/10gR3">
      <attrreq:Subject
         Format="oracle:security:nameid:format:emailaddress">alice@example.com
      </attrreq:Subject>
         <attrreq:Attribute Name="cn">
         </attrreq:Attribute>
      </attrreq:AttributeRequest>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The following example represents a sample SOAP attribute response.

Sample SOAP Attribute Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <soap:Envelope xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"  xmlns:ns2="http://www.w3.org/2005/08/addressing"  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"  xmlns:enc="http://www.w3.org/2001/04/xmlenc#"  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"  xmlns:wst14="http://docs.oasis-open.org/ws-sx/ws-trust/200802"  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"  xmlns:ic="http://schemas.xmlsoap.org/ws/2005/05/identity"  xmlns:mdext="urn:oasis:names:tc:SAML:metadata:extension"  xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"  xmlns:ns11="http://docs.oasis-open.org/ws-sx/ws-trust/200512"  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"  xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"  xmlns:ns14="urn:oasis:names:tc:SAML:2.0:assertion"  xmlns:xrds="xri://$xrds" xmlns:xrd="xri://$xrd*($v*2.0)"  xmlns:tns="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"  xmlns:ns18="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"  xmlns:ns19="urn:oasis:names:tc:SAML:1.0:protocol"  xmlns:ns20="http://www.w3.org/2003/05/soap-envelope"  xmlns:wsse11="http://docs.oasis-open.org/wss/
   oasis-wss-wssecurity-secext-1.1.xsd"  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"  xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
   oasis-200401-wss-wssecurity-utility-1.0.xsd"  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/
   oasis-200401-wss-wssecurity-secext-1.0.xsd"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xmlns:x500="urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500"  xmlns:orafed-arxs="http://www.oracle.com/fed/ar/10gR3/"  xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"  xmlns:ns31="urn:oasis:names:tc:SAML:profiles:v1metadata"  xmlns:ecp="urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp"> 
<soap:Body><orafed-arxs:AttributeResponse CacheFor="899"> <orafed-arxs:Status>Success</orafed-arxs:Status> <orafed-arxs:Subject Format="oracle:security:nameid:format:emailaddress">
   alice@example.com</orafed-arxs:Subject> <orafed-arxs:Attribute Name="cn"> <orafed-arxs:Value>alice</orafed-arxs:Value> </orafed-arxs:Attribute> </orafed-arxs:AttributeResponse></soap:Body></soap:Envelope>

38.7.1.2 Using the IdP Attribute Responder

The Identity Federation IdP Attribute Responder receives the SAML Attribute Query and returns a SAML response with an Attribute Statement that contains values for the requested attributes. The IdP first identifies the requester as an SP partner and then confirms that the user is in the user data store by searching on the NameId or SubjectDN value. It then uses the Attribute Mapping profile of the SP partner to retrieve values for each of the requested attributes. Finally, it constructs and returns a SAML response containing an Attribute Statement with attribute values.

Note:

The Attribute Responder uses the SP partner's Attribute Mapping profile to retrieve values. An empty value is returned for an attribute if there is no mapping present in the Attribute Mapping profile. If the value expression contains variables in the namespace of a session or request, this also evaluates to an empty string. Value Expressions in the Attribute Mapping Profile can only use variables in the namespace of user.attr to be evaluated correctly.

38.7.1.3 Using the SOAP Endpoint

The Attribute Requester Service on the SP exposes a SOAP interface for client requests. The SOAP service is available on the SP at the following URL:

http://<SP-managed-server>:<SP-port>/oamfed/ar/soap

38.7.2 Configuring for Attribute Sharing

Attribute Sharing Plug-in can optionally be provided with the configuration parameters.

Table 38-11 lists the Attribute Sharing Plug-in.

Table 38-11 Configuration Parameters for Attribute Sharing Plug-in

Parameter Description

NameIDValueAttribute

The name of the session attribute from which the user's nameID can be retrieved.

NameIDFormatAttribute

The name of the attribute that contains the value to be used as the nameID format.

AttributeAuthorityAttribute

The name of the attribute that contains the value used as the IdP to which the SP will send the <AttributeQuery>.

RequestedAttributes

This parameter can be used to specify attributes to be requested in the URL query format; for example, attr1&attr2&attr3=value1. In this case, attr1 and attr2 will be fetched but attr3 will be present in the response ONLY if one of its values is value1.

DefaultNameIDFormat

The nameID format to be used if it is undetermined from the other parameters and session attributes.

DefaultAttributeAuthority

The default IdP partner from whom to request the user's attributes.

The Attribute Sharing Plug-in can also access the attributes documented in Table 38-12. These attributes may be present in the Access Manager session during its operation.

Table 38-12 Session Attributes Accessible To Attribute Sharing Plug-in

Attribute Description

fed.partner

If Federation was used to authenticate the user, this value is used to determine the IdP used. The same IdP would then be used for Attribute Sharing.

fed.nameidformat

If Federation was used to authenticate the user, the value of this attribute is used to determine the NameID format.

fed.nameidvalue

If Federation was used to authenticate the user, the value of this attribute is used to determine the NameID of the user. If present in the session, it will be used as the DN to locate the user in the SP's identity store.

KEY_USERNAME_DN

If this value is present, it will be used as the DN to locate the user in the SP's identity store.

The following sections have additional details on parameters and how they determine how the Attribute Sharing process.

38.7.2.1 NameID

This is the name identifier of the user for whom the SP is requesting attributes.

To determine the NameID, the following searches will be conducted in order.

In the Attribute Sharing plug-in

  1. If the NameIDValueAttribute is specified, retrieve the value of the specified attribute from the session and use it as the NameID.

  2. If NameIDValueAttribute is not specified, use the value of fed.nameidvalue for the NameID.

  3. If undetermined by the above, the Attribute Sharing Plug-in will invoke the Federation Engine with a null/empty NameID and the UserID (specified in the KEY_USERNAME_DN session attribute) is sent to the SP Attribute Requester.

In the Attribute Requester (SP)

  1. If the NameID is in the Request, use its value for the user's nameID.

  2. If a NameID is undetermined but a UserID is present (which occurs when invoking the Authentication Plug-in), retrieve the value of the defaultattrrequestnameiduserattribute attribute (found in the SP configuration for this IdP) and use it as the NameID.

  3. When using SAML 2.0 only: If a NameID is not determined and SSO is configured for Simple NameID mapping, use the nameiduserattribute attribute (found in the SP configuration for this IdP). For example, if the value of this attribute is $user.attr.mail, extract the name of the user from this attribute and use it as the NameID.

  4. If a NameID is still undetermined, an error is thrown.

38.7.2.2 NameID Format

This is the format of the user's NameID.

To determine the NameID format, the following searches will be conducted in order. In the Attribute Sharing plug-in

  1. If the NameIDFormatAttribute parameter is specified, retrieve the value of the specified attribute and use it as the NameID format.

    See Table 38-11.

  2. Use the value of the fed.nameidformat attribute as the NameID format.

    See Table 38-12..

  3. Use the value of the DefaultNameIDFormat as the NameID format.

    See Table 38-11.

  4. If NameID Format is still undetermined, the Attribute Sharing plug-in will invoke Federation with a null/empty NameID Format.

In the Attribute Requester (SP)

  1. Use the NameID Format specified in the request.

  2. Use the value of the defaultattrrequestnameidformat attribute (found in the SP configuration for this IdP).

  3. When using SAML 2.0 only: If the NameID Format is still undetermined, use the value of the defaultauthnrequestnameidformat attribute (found in the SP configuration for this IdP).

  4. If a NameID Format is still undetermined, an error is thrown.

38.7.2.3 IdP

This is the IdP partner to which the attribute request should be sent.

To determine the IdP partner, the following searches will be conducted in order. In the Attribute Sharing plug-in

  1. If the AttributeAuthorityAttribute as specified, retrieve its value and use it as the IdP name.

    See Table 38-11.

  2. Use the value of the fed.partner attribute as the IdP name.

    See Table 38-12.

  3. Use the value of the DefaultAttributeAuthority parameter as the IdP name.

    See Table 38-11.

  4. If the IdP is still undetermined, the Attribute Sharing plug-in will invoke Federation with a null/empty NameID Format.

In the Attribute Requester (SP)

  1. Use the IdP name included with the request sent to the Attribute Sharing plugin.

  2. When using x509 only: look up the dn-idp mapping to determine the IdP for this user DN.

  3. Use the value of the defaultattrauthority attribute (found in the SP configuration).

  4. Use the value of the defaultssoidp attribute (found in the SP configuration).

  5. If an IdP name is still undetermined, an error is thrown.

38.7.2.4 RequestedAttributes

These are the attributes to be requested from the Attribute Authority.

To determine the attributes, the following searches will be conducted in order. In the Attribute Sharing plug-in

If the RequestedAttributes parameter is defined, use the attributes specified. If none are specified, no attributes are sent.

See Table 38-11.

In the Attribute Requester (SP)

  1. If the RequestedAttributes parameter is defined, use the attributes specified.

    See Table 38-11.

  2. Append (or add) attributes to the request from partner(send-with-sso) attribute in the IdP partner profile.

In the Attribute Responder (IdP)

  1. If the <AttributeQuery> from the SP contains requests for specific attribute values, return values for those attributes.

  2. If no attribute values are requested, return any attributes specified as Always Send (send-with-sso) in the SP attribute profile configuration.