Identity Provider Functions¶
Functions for managing identity providers -- creating, updating, enabling/disabling, querying, and validating provider capabilities. Identity providers represent external authentication systems (AzureAD, Google, LDAP, etc.) that can authenticate users and optionally supply group/role information for permission mapping.
Source: 024_functions_auth_provider.sql
See also: Identity Providers concept page for an overview of how providers integrate with the permission model.
Provider CRUD¶
auth.create_provider¶
Creates a new identity provider record with the given code and capability flags. The _provider_name is stored as a translation (not as a table column).
| Parameter | Type | Default | Description |
|---|---|---|---|
_created_by |
text | -- | Identifier of the user or system performing the action |
_user_id |
bigint | -- | ID of the user performing the action (used for permission check) |
_correlation_id |
text | -- | Correlation ID for tracing and audit logging |
_provider_code |
text | -- | Unique short code for the provider (e.g. 'azuread', 'google') |
_provider_name |
text | -- | Human-readable name for the provider (stored as a translation, not a table column) |
_is_active |
boolean | true |
Whether the provider is active and can be used for authentication |
_allows_group_mapping |
boolean | false |
Whether the provider supports mapping external groups to internal groups |
_allows_group_sync |
boolean | false |
Whether the provider supports full group synchronization (requires _allows_group_mapping to also be true) |
Returns: table(__provider_id integer) -- the newly created provider's ID.
Permission required: providers.create_provider
Journal event: 16001 (provider_created)
Source: 024_functions_auth_provider.sql:79
auth.update_provider¶
Updates an existing provider's code, active status, and capability flags. The _provider_name is upserted as a translation.
| Parameter | Type | Default | Description |
|---|---|---|---|
_updated_by |
text | -- | Identifier of the user or system performing the update |
_user_id |
bigint | -- | ID of the user performing the action (used for permission check) |
_correlation_id |
text | -- | Correlation ID for tracing and audit logging |
_provider_id |
integer | -- | ID of the provider to update |
_provider_code |
text | -- | New unique code for the provider |
_provider_name |
text | -- | New human-readable name (upserted as a translation, not a table column) |
_is_active |
boolean | true |
Whether the provider should be active |
_allows_group_mapping |
boolean | false |
Whether the provider supports group mapping |
_allows_group_sync |
boolean | false |
Whether the provider supports group sync |
Returns: table(__provider_id integer) -- the updated provider's ID.
Permission required: providers.update_provider
Journal event: 16002 (provider_updated)
Source: 024_functions_auth_provider.sql:121
auth.delete_provider¶
Deletes a provider by its code. This is a hard delete -- the provider record is permanently removed.
| Parameter | Type | Default | Description |
|---|---|---|---|
_deleted_by |
text | -- | Identifier of the user or system performing the deletion |
_user_id |
bigint | -- | ID of the user performing the action (used for permission check) |
_correlation_id |
text | -- | Correlation ID for tracing and audit logging |
_provider_code |
text | -- | Code of the provider to delete |
_tenant_id |
integer | 1 |
Tenant context |
Returns: table(__provider_id integer) -- the deleted provider's ID.
Permission required: providers.delete_provider
Journal event: 16003 (provider_deleted)
Warning
Deleting a provider will cascade to related records (user identities, group mappings). Consider using auth.disable_provider instead to preserve audit history.
Source: 024_functions_auth_provider.sql:162
Enable / Disable¶
auth.enable_provider¶
Sets a provider's is_active flag to true, allowing it to be used for authentication again.
| Parameter | Type | Default | Description |
|---|---|---|---|
_updated_by |
text | -- | Identifier of the user or system performing the action |
_user_id |
bigint | -- | ID of the user performing the action (used for permission check) |
_correlation_id |
text | -- | Correlation ID for tracing and audit logging |
_provider_code |
text | -- | Code of the provider to enable |
_tenant_id |
integer | 1 |
Tenant context |
Returns: table(__provider_id integer) -- the enabled provider's ID.
Permission required: providers.update_provider
Journal event: 16004 (provider_enabled)
Source: 024_functions_auth_provider.sql:192
auth.disable_provider¶
Sets a provider's is_active flag to false, preventing it from being used for authentication.
| Parameter | Type | Default | Description |
|---|---|---|---|
_updated_by |
text | -- | Identifier of the user or system performing the action |
_user_id |
bigint | -- | ID of the user performing the action (used for permission check) |
_correlation_id |
text | -- | Correlation ID for tracing and audit logging |
_provider_code |
text | -- | Code of the provider to disable |
_tenant_id |
integer | 1 |
Tenant context |
Returns: table(__provider_id integer) -- the disabled provider's ID.
Permission required: providers.update_provider
Journal event: 16005 (provider_disabled)
Source: 024_functions_auth_provider.sql:222
Ensure (Idempotent Create)¶
auth.ensure_provider¶
Creates a provider if it does not already exist (matched by _provider_code), or returns the existing provider's ID if it does. This is useful for application bootstrapping and seed scripts where you want idempotent setup.
| Parameter | Type | Default | Description |
|---|---|---|---|
_created_by |
text | -- | Identifier of the user or system performing the action |
_user_id |
bigint | -- | ID of the user performing the action (used for permission check if creating) |
_correlation_id |
text | -- | Correlation ID for tracing and audit logging |
_provider_code |
text | -- | Unique code for the provider |
_provider_name |
text | -- | Human-readable name, stored as a translation (used only when creating) |
_is_active |
boolean | true |
Whether the provider should be active (used only when creating) |
_allows_group_mapping |
boolean | false |
Whether the provider supports group mapping (used only when creating) |
_allows_group_sync |
boolean | false |
Whether the provider supports group sync (used only when creating) |
Returns: table(__provider_id integer, __is_new boolean) -- the provider's ID and whether it was newly created.
Permission required: providers.create_provider (only checked when creating a new provider; if the provider already exists, no permission check occurs)
Source: 024_functions_auth_provider.sql:51
Note
When the provider already exists, ensure_provider does not update the existing record's capability flags or translation -- it simply returns the existing ID with __is_new = false. If you need to update an existing provider, use auth.update_provider separately.
Query Functions¶
auth.get_providers¶
Returns a filtered, searchable list of all providers. All filter parameters are optional -- pass null (or omit) to skip a filter.
| Parameter | Type | Default | Description |
|---|---|---|---|
_user_id |
bigint | -- | ID of the user performing the action (used for permission check) |
_correlation_id |
text | -- | Correlation ID for tracing and audit logging |
_is_active |
boolean | null |
Filter by active status; null returns all |
_allows_group_mapping |
boolean | null |
Filter by group mapping capability; null returns all |
_allows_group_sync |
boolean | null |
Filter by group sync capability; null returns all |
_search |
text | null |
Case-insensitive substring search across provider code and translated name |
Returns: table(__provider_id integer, __code text, __name text, __is_active boolean, __allows_group_mapping boolean, __allows_group_sync boolean)
The __name column is resolved from the translation system (falls back to code when no translation exists).
Permission required: providers
Source: 024_functions_auth_provider.sql:279
auth.get_provider_users¶
Returns all users who have an identity linked to the specified provider.
| Parameter | Type | Default | Description |
|---|---|---|---|
_requested_by |
text | -- | Identifier of the user or system making the request |
_user_id |
bigint | -- | ID of the user performing the action (used for permission check) |
_correlation_id |
text | -- | Correlation ID for tracing and audit logging |
_provider_code |
text | -- | Code of the provider to query users for |
_tenant_id |
integer | 1 |
Tenant context |
Returns: table(__user_id bigint, __user_identity_id bigint, __username text, __display_name text)
Results are ordered by display_name.
Permission required: manage_provider.get_users
Source: 024_functions_auth_provider.sql:252
Validation Functions¶
These functions are used internally by other parts of the system to validate provider state and capabilities before performing operations. They raise exceptions when validation fails.
auth.validate_provider_is_active¶
Checks that the provider identified by _provider_code is active. Raises error 33010 / 52107 if the provider exists but is inactive.
| Parameter | Type | Default | Description |
|---|---|---|---|
_provider_code |
text | -- | Code of the provider to validate |
Returns: void
Permission required: None
Raises: 33010 -- "Provider (provider code: ...) is not in active state"
Source: 024_functions_auth_provider.sql:13
auth.validate_provider_allows_group_mapping¶
Checks that the provider identified by _provider_code has group mapping enabled. Raises error 33016 if the provider exists but does not allow group mapping.
| Parameter | Type | Default | Description |
|---|---|---|---|
_provider_code |
text | -- | Code of the provider to validate |
Returns: void
Permission required: None
Raises: 33016 -- "Provider does not allow group mapping"
Source: 024_functions_auth_provider.sql:27
auth.validate_provider_allows_group_sync¶
Checks that the provider identified by _provider_code has group synchronization enabled. Raises error 33017 if the provider exists but does not allow group sync.
| Parameter | Type | Default | Description |
|---|---|---|---|
_provider_code |
text | -- | Code of the provider to validate |
Returns: void
Permission required: None
Raises: 33017 -- "Provider does not allow group sync"
Source: 024_functions_auth_provider.sql:39
Provider Table Structure¶
For reference, the auth.provider table has the following columns:
| Column | Type | Default | Description |
|---|---|---|---|
provider_id |
integer | auto-generated identity | Primary key |
code |
text | -- | Unique provider code |
is_active |
boolean | true |
Whether the provider is active |
allows_group_mapping |
boolean | false |
Whether external group-to-internal-group mapping is enabled |
allows_group_sync |
boolean | false |
Whether full group synchronization is enabled |
created_at |
timestamptz | now() |
Creation timestamp |
created_by |
text | 'unknown' |
Creator identifier |
updated_at |
timestamptz | now() |
Last update timestamp |
updated_by |
text | 'unknown' |
Last updater identifier |
Note
The provider's display name is not stored in this table. It is managed through the translation system (public.translation with data_group = 'provider'). Functions like auth.get_providers resolve the name from translations at query time.
Constraint: provider_sync_requires_mapping -- allows_group_sync can only be true when allows_group_mapping is also true.
Source: 013_tables_auth.sql:13
Permission Summary¶
| Function | Required Permission |
|---|---|
auth.create_provider |
providers.create_provider |
auth.update_provider |
providers.update_provider |
auth.delete_provider |
providers.delete_provider |
auth.enable_provider |
providers.update_provider |
auth.disable_provider |
providers.update_provider |
auth.ensure_provider |
providers.create_provider (only when creating) |
auth.get_providers |
providers |
auth.get_provider_users |
manage_provider.get_users |
auth.validate_provider_is_active |
None |
auth.validate_provider_allows_group_mapping |
None |
auth.validate_provider_allows_group_sync |
None |