BASIC_AUTH_REALM

Set the HTTP Basic Authentication realm name.

Keywords

basic_authentication_realm, basic_auth_realm, realm

Syntax

realm = <realm-name>
basic_auth_realm = <realm-name>

• realm-name: The realm name displayed in the browser's authentication dialog and included in the WWW-Authenticate response header.

Default Value

If not specified, the default realm is NpgsqlRest.

Examples

Set Realm Name

create function protected_api()
returns json
language sql
as $$select '{"data": "secret"}'::json$$;

comment on function protected_api() is '
HTTP GET
basic_auth admin_user hashed_password_here
realm = MyApplication
';

When authentication fails, the response header will be:

WWW-Authenticate: Basic realm="MyApplication"

Alternative Keyword

comment on function admin_area() is '
HTTP GET
basic_auth admin hashed_password_here
basic_auth_realm = Admin Area
';

With Challenge Command

create function secure_endpoint(
    _user_claims json
)
returns text
language sql as $$
select _user_claims;
$$;

comment on function secure_endpoint(json) is '
basic_auth
challenge_command = select * from validate_user($1, $2, $3, $4, $5)
realm = SecureZone
user_params
';

The realm value (SecureZone) is passed as the 4th parameter ($4) to the challenge command.

Behavior

• Sets the realm parameter in the WWW-Authenticate response header when authentication fails.
• The realm helps browsers identify which set of credentials to use for a given protected resource.
• Different realms can have different sets of valid credentials.
• The realm name is displayed in browser authentication dialogs, helping users identify which credentials to enter.
• When using challenge_command, the realm value is passed as the 4th parameter to the validation function.

Realm Resolution Order

The realm is determined in the following order:

1. Endpoint-specific realm annotation (highest priority)
2. Global BasicAuth.Realm configuration option
3. Default value: NpgsqlRest

Related

• Authentication Options configuration - Configure global Basic Auth realm
• Comment Annotations Guide - How annotations work
• Configuration Guide - How configuration works

Related Annotations

• BASIC_AUTH - Enable Basic Authentication
• BASIC_AUTH_COMMAND - Set validation function for custom authentication logic