Claims Mapping

Configure how authenticated user claims are mapped to PostgreSQL context variables and function parameters.

Overview

This overview shows the claims-mapping subset of NpgsqlRest.AuthenticationOptions — see Authentication Options for the complete section with all defaults.

json

{
  "NpgsqlRest": {
    "AuthenticationOptions": {
      "UseUserContext": false,
      "ContextKeyClaimsMapping": {
        "request.user_id": "user_id",
        "request.user_name": "user_name",
        "request.user_roles": "user_roles"
      },
      "ClaimsJsonContextKey": null,
      "IpAddressContextKey": "request.ip_address",
      "UseUserParameters": false,
      "ParameterNameClaimsMapping": {
        "_user_id": "user_id",
        "_user_name": "user_name",
        "_user_roles": "user_roles"
      },
      "ClaimsJsonParameterName": "_user_claims",
      "IpAddressParameterName": "_ip_address"
    }
  }
}

User Context (PostgreSQL Context Variables)

Map authenticated user claims to PostgreSQL session context variables. Enable for specific endpoints using the user_context annotation, or enable globally with UseUserContext.

Setting	Type	Default	Description
UseUserContext	bool	false	Enable automatic claim-to-context mapping for all endpoints. Override per-endpoint with user_context annotation.
ContextKeyClaimsMapping	object	(see below)	Map of PostgreSQL context keys to claim names. Key is the context variable name, value is the claim type.
ClaimsJsonContextKey	string	null	Context key for all claims serialized as JSON, e.g. "request.user_claims". Disabled when null.
IpAddressContextKey	string	"request.ip_address"	Context key for client IP address.

Default Context Mapping

json

{
  "NpgsqlRest": {
    "AuthenticationOptions": {
      "ContextKeyClaimsMapping": {
        "request.user_id": "user_id",
        "request.user_name": "user_name",
        "request.user_roles": "user_roles"
      }
    }
  }
}

Custom Context Mapping Example

Map additional claims to custom context keys:

json

{
  "NpgsqlRest": {
    "AuthenticationOptions": {
      "ContextKeyClaimsMapping": {
        "request.user_id": "user_id",
        "request.user_name": "user_name",
        "request.user_roles": "user_roles",
        "request.user_email": "email",
        "request.tenant_id": "tenant_id"
      },
      "ClaimsJsonContextKey": "request.user_claims"
    }
  }
}

Access in PostgreSQL

sql

-- Access individual claims
select current_setting('request.user_id', true);
select current_setting('request.user_name', true);
select current_setting('request.user_roles', true);

-- Access client IP address
select current_setting('request.ip_address', true);

-- Access all claims as JSON (when ClaimsJsonContextKey is configured)
select current_setting('request.user_claims', true)::jsonb;

TIP

Always use true as the second parameter to current_setting() to avoid errors when the setting doesn't exist.

User Parameters

Map authenticated user claims to function parameters. Enable for specific endpoints using the user_parameters annotation, or enable globally with UseUserParameters.

Setting	Type	Default	Description
UseUserParameters	bool	false	Enable automatic claim-to-parameter mapping for all endpoints. Override per-endpoint with user_parameters annotation.
ParameterNameClaimsMapping	object	(see below)	Map of function parameter names to claim names. Key is the parameter name, value is the claim type.
ClaimsJsonParameterName	string	"_user_claims"	Parameter name that receives all claims serialized as JSON.
IpAddressParameterName	string	"_ip_address"	Parameter name that receives the client IP address.

Default Parameter Mapping

json

{
  "NpgsqlRest": {
    "AuthenticationOptions": {
      "ParameterNameClaimsMapping": {
        "_user_id": "user_id",
        "_user_name": "user_name",
        "_user_roles": "user_roles"
      }
    }
  }
}

Custom Parameter Mapping Example

Map additional claims to custom parameter names:

json

{
  "NpgsqlRest": {
    "AuthenticationOptions": {
      "ParameterNameClaimsMapping": {
        "_user_id": "user_id",
        "_user_name": "user_name",
        "_user_roles": "user_roles",
        "_email": "email",
        "_tenant": "tenant_id"
      },
      "ClaimsJsonParameterName": "_user_claims",
      "IpAddressParameterName": "_ip_address"
    }
  }
}

Example Function Using Parameters

sql

create function get_user_data(
    _user_id text,
    _user_name text,
    _user_roles text[],
    _ip_address text,
    _user_claims json
)
returns table (
    user_id int,
    user_name text,
    roles text[],
    ip text,
    all_claims json
)
language sql
begin atomic;
select
    _user_id::int,
    _user_name,
    _user_roles,
    _ip_address,
    _user_claims;
end;

comment on function get_user_data(text, text, text[], text, json) is '
@authorize
@user_params
';

Equivalent as a SQL file endpoint (sql/get-user-data.sql):

Named placeholders bind to the mapping by name — :_user_id matches the _user_id key of ParameterNameClaimsMapping, so no @param renames are needed (the @param :name type lines are Describe type hints only):

sql

/*
HTTP GET
@authorize
@user_params
@param :_user_id text
@param :_user_name text
@param :_user_roles text[]
@param :_ip_address text
@param :_user_claims json
*/
select
    :_user_id::int as user_id,
    :_user_name as user_name,
    :_user_roles as roles,
    :_ip_address as ip,
    :_user_claims as all_claims;

TIP

Parameters with default values can be used without authentication. When the user is authenticated, claim values override the defaults.

Complete Example

Configuration with user context and parameters enabled:

json

{
  "NpgsqlRest": {
    "AuthenticationOptions": {
      "UseUserContext": true,
      "ContextKeyClaimsMapping": {
        "request.user_id": "user_id",
        "request.user_name": "user_name",
        "request.user_roles": "user_roles"
      },
      "IpAddressContextKey": "request.ip_address",
      "UseUserParameters": true,
      "ParameterNameClaimsMapping": {
        "_user_id": "user_id",
        "_user_name": "user_name",
        "_user_roles": "user_roles"
      },
      "ClaimsJsonParameterName": "_user_claims",
      "IpAddressParameterName": "_ip_address"
    }
  }
}

Related

• Authentication Guide — the full walkthrough
• Authentication Options - Core authentication options (login/logout, password handling)
• Basic Auth Configuration - Configure HTTP Basic Authentication
• user_context annotation - Enable user context mapping per endpoint
• user_parameters annotation - Enable user parameters mapping per endpoint
• Comment Annotations Guide - How annotations work
• Configuration Guide - How configuration works

Next Steps

• Authentication Options - Configure login/logout and password handling
• Basic Auth Configuration - Configure Basic Authentication
• Authentication - Configure authentication methods (Cookie, Bearer Token, OAuth)

See Also

• USER_CONTEXT - Map claims to context variables
• USER_PARAMETERS - Map claims to function parameters