Skip to content

user-parameters.md

Latest commit

 

History

History
180 lines (149 loc) · 4.37 KB

user-parameters.md

File metadata and controls

180 lines (149 loc) · 4.37 KB
Raw
outline
2
3
title USER_PARAMETERS Annotation
titleTemplate NpgsqlRest
description Pass authenticated user claims as PostgreSQL function parameters. Inject user ID, roles, and custom claims into SQL functions.
head
meta
name content
keywords
npgsqlrest user parameters, user claims parameters, inject user id, function user parameter, authenticated user sql
meta
property content
og:title
NpgsqlRest USER_PARAMETERS Annotation
meta
property content
og:description
Pass user claims as function parameters for authenticated endpoints.
meta
property content
og:type
article

USER_PARAMETERS

::: info Also known as user_params (with or without @ prefix) :::

Enable passing user claims as function parameters for the endpoint.

Syntax

@user_parameters
@user_params

Examples

Basic User Parameters

create function get_user_params(
    _user_id text,
    _user_name text,
    _user_roles text[]
)
returns table (
    user_id int,
    user_name text,
    user_roles text[]
)
language sql
begin atomic;
select
    _user_id::int,
    _user_name,
    _user_roles;
end;

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

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

/*
HTTP GET
@authorize
@user_params
@param $1 user_id text
@param $2 user_name text
@param $3 user_roles text[]
*/
select $1::int as user_id, $2 as user_name, $3 as user_roles;

With Default Values (for unauthenticated access)

create function get_user_params_optional(
    _user_id text = null,
    _user_name text = 'anonymous',
    _user_roles text[] = array[]::text[]
)
returns table (
    user_id int,
    user_name text,
    user_roles text[]
)
language sql
begin atomic;
select
    _user_id::int,
    _user_name,
    _user_roles;
end;

comment on function get_user_params_optional(text, text, text[]) is '
@user_params
';

Access All Claims as JSON

create function get_user_ip_and_full_claims(
    _ip_address text,
    _user_claims json
)
returns table (
    ip_address text,
    user_claims json
)
language sql
begin atomic;
select
    _ip_address,
    _user_claims;
end;

comment on function get_user_ip_and_full_claims(text, json) is '
@authorize
@user_params
';

Combined with User Context

comment on function user_profile() is
'HTTP GET
@authorize
@user_context
@user_parameters';

Behavior

  • Automatically injects user claim values into matching function parameters before execution
  • Parameters are matched by name according to ParameterNameClaimsMapping configuration
  • Default behavior for all endpoints can be configured via UseUserParameters
  • Parameters with default values work without authentication; claim values override defaults when authenticated
  • Parameters not found in claims use their default values or null
  • Claim values are always passed as text type. For multi-value claims (like roles), values are passed as text[]. PostgreSQL handles type coercion to your parameter types.

Default Parameter Mapping

Parameter Name Claim Description
_user_id user_id User identifier
_user_name user_name Username
_user_roles user_roles User roles (array)
_ip_address - Client IP address
_user_claims - All claims serialized as JSON

Differences from USER_CONTEXT

Feature USER_PARAMETERS USER_CONTEXT
Access method Function parameters current_setting()
Works without auth Yes (with defaults) Yes (returns empty)
Type safety PostgreSQL enforced Manual casting required
Performance Slightly faster Slightly slower

Related

Related Annotations

  • USER_CONTEXT - Access user claims via PostgreSQL session context variables
  • AUTHORIZE - Require authentication

See Also