Mapping

Mappings define the attributes that will be provided to the authorization engine and how to retrieve the corresponding values from the attribute source. A single attribute connector can have multiple mappings.

The contents of the Mapping section depend on the attribute connector type. Use the tabs below to see the steps for the appropriate type:

Table

1. From the Provided attribute dropdown, select the attribute to be fetched from the database.

   The dropdown contents are defined in the Dictionary.

2. In Table name, enter the database table name from which the target attribute value is fetched.

3. In Column name, enter the column name of the specified table from which the target attribute value is fetched.

4. Click Add key attribute to specify attributes that act as keys in the DB table and are required to determine and fetch the provided attributes' values.

   1. Select a Key attribute from the dropdown.
   2. Enter the corresponding Column name of the DB table for the key attribute.

   Repeat this step if you wish to add more key attributes.

   note

   Any key attribute added in the mapping should be different from the provided attribute.

   info

   If you wish to delete a key attribute, click the delete button next to it.

5. Optionally, add more mappings by clicking Add new mapping.

   Enter the required information following the instructions above.

SQL

1. From the Provided attribute dropdown, select the attribute to be fetched from the database.

   The dropdown contents are defined in the Dictionary.

2. In Query, enter the SQL query or stored procedure needed to fetch the attribute value from the database including one or more ? symbol(s).

   The ? symbol in your SQL query acts as a placeholder for any dynamic values that need to be supplied at runtime. Each ? represents a specific key attribute value that the query will use when executed.

   See the SQL queries and Stored procedures sections below for more details on composing SQL queries.

3. In Key attribute, select the required key attribute(s) to determine and fetch the provided attribute's value.

   Key attributes correspond directly to each ? placeholder used in your SQL query. This means for every ? in your query, you'll be prompted to select a Key attribute from the dropdown menu.

   note

   Your key attribute-related fields remain hidden until you enter a valid SQL query.

4. In Type, enter the corresponding SQL datatype of each key attribute.

5. Optionally, add more mappings by clicking Add new mapping.

   Enter the required information following the instructions above.

SQL queries

In most cases, the SQL attribute connector needs to utilize the values of other available attributes from the specific request context. You should denote these runtime-supplied attributes by using the ? symbol as the placeholder for the values in the SQL query. For example, below is an SQL query that looks for a username in the directory given the user_id value.

SELECT username FROM tbl_user WHERE user_id=?

note

SQL queries to retrieve attributes from SQL databases are passed without intervention to the database driver. As a result, you should ensure that they use the syntax specific to the SQL dialect employed by the database system.

Stored procedures

WIP

This section along with its subsection are still under development.

In addition to regular SQL queries, attribute mappings can also be created for stored procedures. Stored procedures are database specific subroutines that can be called with a number of input and output parameters.

A stored procedure with at least one output parameter can be used in an attribute mapping where the return values can be mapped to an attribute. Similarly, attributes can be used as input parameters for a stored procedure.

An example of a stored procedure is a subroutine that maps a user ID to a set of roles. In such a case, a subject-id attribute can be used as an input parameter, while a subject-roles attribute can be mapped to the stored procedure's output parameter.

Create an attribute mapping that uses a stored procedure as follows:

1. In the attributes table, select the attribute that is to hold the values of one of the stored procedure's output parameters.

2. Enter a call to the stored procedure in the Query field using the following syntax:

   {call proc(?,?)}

   where proc is the name of the stored procedure and each question mark is a parameter representing the use of an attribute. The number of parameters differs among stored procedures.

   The expression inside the curly braces follows JDBC syntax for calling stored procedures. It is also possible to use static values for parameters instead of using attributes, such as:

   {call proc(?,'string',42)}

3. After entering the call to the stored procedure, click outside the Query text box.

   This will update the Key Associations field with the information needed to complete the stored procedure configuration. The key association field will contain one row of configuration fields for each question mark encountered in the call-string.

4. Enter the correct input/output information for every parameter ? symbol in the stored procedure call-string as described in the [In/out parameters](#Inout parameters) section below.

5. Submit the mapping by clicking Apply.

In/out parameters

As a stored procedure can have any number of input and output parameters, the attribute mapping needs to be informed which parameters are input, which are output, and which of the output parameters is to be used for the attribute in the mapping.

The Source attribute and Result field depend on the parameter type (input or output). The Result is a checkbox that must be set for exactly one output parameter (type OUT or INOUT) since this is the parameter returning the values that will be set for the target XACML attribute. The parameter types and Source attributes are described in the following table.

Parameter type	Description	Source attribute
IN	Inputs data to the stored procedure. The actual data will be taken from an attribute set in the Source attribute field.	Set to the attribute whose value is to be used as input data for the stored procedure parameter.
OUT	An output parameter from the stored procedure, whose return value can be used for the attribute mapping.	Not applicable.
INOUT	A stored procedure parameter that works both as input and output.	Set to the attribute whose value is to be used as input data for the stored procedure parameter. Note that the values of an attribute used as a source attribute for an INOUT parameter will not be altered.

The Type field is always the datatype of the stored procedure parameter in the target database. While the Type drop-down menu provides a list of common SQL datatypes, an integer value can be entered so that other JDBC-supported datatypes (such as -10 for an Oracle cursor) can be used. Refer to your vendor documentation for a list of valid values.

note

Compatibility between the database type of the result stored procedure output parameter and the XACML datatype of the target XACML attribute is not checked or ensured. The Attribute Finder will simply convert the string representation of the result to the target attribute.

LDAP

1. From the Provided attribute dropdown, select the attribute to be fetched from the LDAP server.

   The dropdown contents are defined in the Dictionary.

2. In Search selection, enter the LDAP attribute name that will return the value of the corresponding provided attribute.

3. From the Search scope dropdown, select the depth of the LDAP search. The following options are available:

   • ONELEVEL_SCOPE - Searches only the level immediately below the base distinguished name (DN).
   • OBJECT_SCOPE - Searches only the level specified by the base DN and none of its child entries.
   • SUBTREE_SCOPE - Searches the subtree below the base DN and also includes the base DN level.

4. In Search base, enter the topmost DN or starting point in the directory to conduct the search.

   The search base can be static, that is a fixed node, or dynamic in which case it will depend on attribute values in the request. A dynamic search base is created by inserting one or more ? symbols in the search base DN. Each ? symbol is substituted for the value of a specified attribute. See the Dynamic search base section below for details.

   In case of a dynamic search base, for each ? symbol a Key attribute dropdown displays.

   1. From the Key attribute dropdown, select the source attribute to replace the ? symbol in the dynamic search base.
   2. Repeat if more than one key attributes are required.

5. In Search filter, enter the LDAP attribute and value that will be used to filter the result set.

   Values used in the query are denoted by a ? symbol. For each ? symbol a Key attribute dropdown displays. See the Search filters section below for details.

   1. From the Key attribute dropdown, select the source attribute to replace the ? symbol in the search filter.
   2. Repeat if more than one key attributes are required.

6. Optionally, add more mappings by clicking Add new mapping.

   Enter the required information following the instructions above.

Dynamic search base

A dynamic LDAP search base can change depending on the value of one or more attributes from the request context or from any configured attribute that can be fetched by means of an Attribute Finder.

A dynamic search base is constructed by inserting one or more ? symbols in the DN string wherever substitution for an attribute value is needed. As soon as a ? symbol is entered in the search base string, a corresponding key mapping field is added in the search base key associations table.

A key attribute has to be selected for each ? symbol.

Search filters

The attribute connector will typically need to use the values of other attributes from the specific request context in order to search for the value of a target attribute. These attributes can be made available either in the request itself or by another search. These runtime-supplied values filter the full result set into the specific value of the target attribute.

HTTP

1. From the Provided attribute dropdown, select or type an attribute to be provided from the dictionary.

   info

   This option allows you to specify which attribute(s) the HTTP Attribute Connector should retrieve from the HTTP endpoint. These attributes represent specific pieces of data that the web service will return, typically in JSON or XML format. You can define multiple mappings by clicking + Add new mapping.

2. In Content type, enter the expected format of the web service response, such as application/json or application/xml.

3. From the Payload template dropdown, select a payload template type.

   The following options are available:

   • LITERAL - This option allows you to directly input the payload content in a predefined format, such as JSON, into the UI.
   • LOCATION - This option allows you to specify the file path to a JSON file that contains the payload template.
   • NONE - This option allows you to proceed without defining a payload template, leaving it unset.

4. Select LITERAL to define and manage the payload directly within the configuration:

   1. Enter the payload directly in the Payload field.

      You can include variable placeholders, such as {"city": "@var1", "country": "@var2"}.

   2. If the payload includes variable placeholders, define the corresponding key attributes. Select the appropriate keys from the dropdown menu in the Key attribute field(s). These key attributes ensure that the placeholders are dynamically replaced with the correct values during execution.

5. Select LOCATION to manage the payload externally:

   1. Enter an absolute or relative path to the payload file in the Payload path field. To use a relative path, check the Relative classpath checkbox on the right.

      info

      The payload file's content can include placeholder variables, for example @var1, @var2, that are dynamically replaced with the corresponding key attribute values during execution.

   2. Click Add Key attribute to define one or more key attributes corresponding to the variables' placeholders defined in the payload file's content.

   3. Enter a name in the Variable name field. For example @var1.

   4. Select a key attribute from the dropdown menu in the Key attribute field to map it to the corresponding variable.

note

Make sure that the payload content has the correct syntax.

note

Every variable name must be preceded by the @ symbol. Variable names must only consist of alphanumeric characters and/or underscores (_).

XML parser

1. From the Provided attribute dropdown, select the attribute to be fetched from the attribute source.

   The dropdown contents are defined in the Dictionary.

2. In XPath, enter the XPath expression specifying values to be collected from the XML source.

   You can include parameters into the expression using placeholder variables in the format ##index##, where "index" denotes a number beginning at 1. For example, /users/##1##/role/text().

3. In the Key attribute dropdown, select a key attribute to map it to the corresponding variable.

4. Optionally, select the Collate values checkbox to combine multiple values found from the XPath search into a single value, instead of presenting them as individual entries.

5. If Collate values is checked, specify the separator between collated values using the Delimiter dropdown.

   Select one of the predefined separators or add your own.

JSON parser

1. From the Provided attribute dropdown, select the attribute to be fetched from the attribute source.

   The dropdown contents are defined in the Dictionary.

2. In JSONPath, enter the JSONPath expression specifying values to be collected from the JSON source.

   You can include parameters into the expression using placeholder variables in the format ##index##, where "index" denotes a number beginning at 1. For example, $.authorizations[?(@.id=='##1##')].status.

3. In the Key attribute dropdown, select a key attribute to map it to the corresponding variable.

4. Optionally, select the Collate values checkbox to combine multiple values found from the XPath search into a single value, instead of presenting them as individual entries.

5. If Collate values is checked, specify the separator between collated values using the Delimiter dropdown.

   Select one of the predefined separators or add your own.

JWT parser

1. From the Provided attribute dropdown, select the attribute to be fetched from the attribute source.

   The dropdown contents are defined in the Dictionary.

2. In Claim, enter the JWT claim associated with the provided attribute.

Proceed to Connection/Section