JSON / REST Data Source

The JSON / REST data source is a small REST client. It is meant to provide a small but flexible interface to RESTful backends. It supports three methods:

  • Credential Management
  • Attribute fetching
  • Bucket access

It is not possible to manage accounts using the JSON / REST data source.

Note

JSON / REST data source supports multi-tenancy. Read more about multi-tenancy

Tip

For details on how to implement a backend for the JSON DAP see the developer documentation.

Configuration

The data source requires an http client configured with the trust settings needed to connect to the backend.

The full configuration reference can be found here.

Credential Management

The REST client can be configured to send either json or form encoded data, using either GET or POST. It is recommended to use POST as much as possible when sending credentials since the GET request’s URLs are subject to logging in gateways and proxies.

Listing 51 Example configuration of JSON credential data source
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<data-source>
    <id>CredentialDS</id>
    <json xmlns="https://curity.se/ns/conf/data-access/json">
        <web-service-client>
            <hostname>localhost</hostname>
            <port>7777</port>
            <context>/json-ds</context>
            <http-client>trustStoreHttpClient</http-client>
        </web-service-client>
    <credential-access>
        <url-path>/user</url-path>
        <backend-verifies-password>true</backend-verifies-password>
        <submit-as>post-as-json</submit-as>
        <username-parameter>username</username-parameter>
        <password-parameter>password</password-parameter>
      </credential-access>
    </json>
</data-source>

In the highlighted line the backend-verifies-password is set to true, this means that the backend performs password verification. If set to false the backend is expected to return the password and Curity’s credential manager will validate it.

The example above sets up the JSON data source for credential access. Important configuration is what to name the username and password parameters in the request. These can be configured to match the backend’s requirements.

Multi-Tenancy

When the JSON / REST data source is used in an authentication profile with a configured tenant ID, it is mandatory to set the tenant-id-parameter attribute or add the :tenantId placeholder in the url-path attribute.

Attribute Management

For attribute access similar configuration can be made or added to the existing data source:

Listing 52 Example configuration of JSON attribute data source
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<data-source>
    <id>CredentialDS</id>
    <json xmlns="https://curity.se/ns/conf/data-access/json">
        <web-service-client>
            <hostname>localhost</hostname>
            <port>7777</port>
            <context>/json-ds</context>
            <http-client>trustStoreHttpClient</http-client>
        </web-service-client>
        <attributes>
            <submit-as>get</submit-as>
            <parameter>
                <provide-as>query-parameter</provide-as>
                <username-parameter>subject</username-parameter>
            </parameter>
            <parameter-mappings>
                <parameter-mapping>
                    <parameter-name>parameter-orgid</parameter-name>
                    <use-value-of-attribute>orgid</use-value-of-attribute>
                </parameter-mapping>
                <parameter-mapping>
                    <parameter-name>parameter-token</parameter-name>
                    <use-value-of-attribute>attributes-token</use-value-of-attribute>
                </parameter-mapping>
            </parameter-mappings>
        </attributes>
    </json>
</data-source>

It is possible to submit the request using GET or POST methods, and the request body can contain JSON or URL-encoded form data, when applicable. Parameters can be included in headers, query-string or body. The exact behavior is controlled by how the subject is included in the request and by the value of the submit-as option.

If the data source is configured to include the subject in the URL path (url-path is used), the subject and tenant ID are always sent in the URL path and additional mapped parameters are sent according to the submit-as option:

submit-as Behavior
get Request uses GET. Additional parameters are sent in the query-string and the body is empty.
post-as-json Request uses POST. Additional parameters are sent as JSON object properties in the request body.
post-as-urlencoded-formdata Request uses POST. Additional parameters are sent as form parameters in the request body.

If the data source is configured to include the subject in the request in a different way (parameter is used), all parameters are sent according to the parameter/provide-as option (i.e. in the same way as the subject):

submit-as parameter/provide-as Behavior
get, post-as-json, post-as-urlencoded-formdata query-parameter Request uses GET or POST, respectively. All parameters are sent in the query-string and the body is empty.
get, post-as-json, post-as-urlencoded-formdata header-parameter Request uses GET or POST, respectively. All parameters are sent in request headers and the body is empty.
get request-default Request uses GET. All parameters are sent in the query-string and the body is empty.
post-as-json request-default Request uses POST. All parameters are sent as JSON object properties in the request body.
post-as-urlencoded-formdata request-default Request uses POST. All parameters are sent as form parameters in the request body.

Note that all mapped parameters are sent in the same location.

Multi-Tenancy

When the JSON / REST data source is used in an authentication profile with a configured tenant ID, it is mandatory to set the parameter/tenant-id-parameter attribute or add the :tenantId placeholder in the url-path attribute.

Bucket Access

For bucket access, there are three operations - fetch, store and clear - which can be configured individually.

Listing 53 Example configuration of JSON bucket data source (default values shown)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<data-source>
    <id>JsonDS</id>
    <json xmlns="https://curity.se/ns/conf/data-access/json">
        <web-service-client>
            <hostname>localhost</hostname>
            <port>7777</port>
            <context>/json-ds</context>
            <http-client>trustStoreHttpClient</http-client>
        </web-service-client>
        <buckets>
            <fetch>
                <method>get</method>
                <url>/buckets?subject=:subject&amp;purpose=:purpose</url>
            </fetch>
            <store>
                <method>put</method>
                <url>/buckets?subject=:subject&amp;purpose=:purpose</url>
            </store>
            <clear>
                <method>delete</method>
                <url>/buckets?subject=:subject&amp;purpose=:purpose</url>
            </clear>
        </buckets>
    </json>
</data-source>

Multi-Tenancy

When the JSON / REST data source is used in an authentication profile with a configured tenant ID, it is mandatory to add the :tenantId placeholder in the URLs of clear, fetch, store operations.