Configuration
Permify offers various options for configuring your Permify Server. Here is the example configuration YAML file with glossary below.
You can also find this example config file in Permify repo.
Configure Using Flags
Alternatively, you can set configuration options using flags when running the command. See all the configuration flags by running,
Configuration Using YAML File
Configuration Glossary
server | Server Configurations
server | Server Configurations
Definition
Server options to run Permify. (grpc
and http
available for now.)
Structure
Glossary
Required | Argument | Default | Description |
---|---|---|---|
[ ] | rate_limit | 100 | the maximum number of requests the server should handle per second. |
[x] | [ server_type ] | - | server option type can either be grpc or http . |
[ ] | enabled (for server type) | true | switch option for server. |
[x] | port | - | port that server run on. |
[x] | tls | - | transport layer security options. |
[ ] | enabled (for tls) | false | switch option for tls |
[ ] | cert | - | tls certificate path. |
[ ] | key | - | tls key path |
ENV
Argument | ENV | Type |
---|---|---|
rate_limit | PERMIFY_RATE_LIMIT | int |
grpc-port | PERMIFY_GRPC_PORT | string |
grpc-tls-enabled | PERMIFY_GRPC_TLS_ENABLED | boolean |
grpc-tls-key-path | PERMIFY_GRPC_TLS_KEY_PATH | string |
grpc-tls-cert-path | PERMIFY_GRPC_TLS_CERT_PATH | string |
http-enabled | PERMIFY_HTTP_ENABLED | boolean |
http-port | PERMIFY_HTTP_PORT | string |
http-tls-key-path | PERMIFY_HTTP_TLS_KEY_PATH | string |
http-tls-cert-path | PERMIFY_HTTP_TLS_CERT_PATH | string |
http-cors-allowed-origins | PERMIFY_HTTP_CORS_ALLOWED_ORIGINS | string array |
http-cors-allowed-headers | PERMIFY_HTTP_CORS_ALLOWED_HEADERS | string array |
logger | Logging Options
logger | Logging Options
Definition
Real time logs of authorization. Permify uses zerolog as a logger.
Structure
Glossary
Required | Argument | Default | Description |
---|---|---|---|
[x] | level | info | logger levels: error , warn , info , debug |
[x] | output | text | logger output: json , text |
ENV
Argument | ENV | Type |
---|---|---|
log-level | PERMIFY_LOG_LEVEL | string |
log-output | PERMIFY_LOG_OUTPUT | string |
authn | Server Authentication
authn | Server Authentication
Definition
You can choose to authenticate users to interact with Permify API.
There are 2 authentication method you can choose:
- Pre Shared Keys
- OpenID Connect
Pre Shared Keys
On this method, you must provide a pre shared keys in order to identify yourself.
Structure
Glossary
Required | Argument | Default | Description |
---|---|---|---|
[x] | method | - | Authentication method can be either oidc or preshared . |
[ ] | enabled | true | switch option authentication config |
[x] | keys | - | Private key/keys for server authentication. Permify does not provide this key, so it must be generated by the users. |
ENV
Argument | ENV | Type |
---|---|---|
authn-enabled | PERMIFY_AUTHN_ENABLED | boolean |
authn-method | PERMIFY_AUTHN_METHOD | string |
authn-preshared-keys | PERMIFY_AUTHN_PRESHARED_KEYS | string array |
OpenID Connect
Permify supports OpenID Connect (OIDC). OIDC provides an identity layer on top of OAuth 2.0 to address the shortcomings of using OAuth 2.0 for establishing identity.
With this authentication method, you be able to integrate your existing Identity Provider (IDP) to validate JSON Web Tokens (JWTs) using JSON Web Keys (JWKs). By doing so, only trusted tokens from the IDP will be accepted for authentication.
Structure
Glossary
Required | Argument | Default | Description |
---|---|---|---|
[x] | method | - | Authentication method can be either oidc or preshared . |
[ ] | enabled | false | Switch option to enable or disable authentication config. |
[x] | audience | - | The audience identifies the intended recipients of the token, typically the API or resource server. It ensures tokens are used only by the authorized party. |
[x] | issuer | - | This is the URL of the provider that is responsible for authenticating users. You will use this URL to discover information about the provider in step 1 of the authentication process. |
[x] | refresh_interval | 15m | The interval at which the authentication information should be refreshed to ensure that it remains valid and up-to-date. |
[x] | backoff_interval | 12s | The delay between retries when attempting to authenticate if the key is not found. The system will retry at intervals, which may vary, to avoid constant retry attempts. |
[x] | backoff_frequency | - | The duration to wait before retrying after a failed authentication attempt. This helps to manage the load on the authentication service by introducing a delay between retries, ensuring that repeated failures do not overwhelm the service or lead to excessive requests. This value should be configured according to the expected response times and reliability of the authentication provider. |
[x] | backoff_max_retries | 5 | The maximum number of retry attempts to make if key is not found. |
[x] | valid_methods | [“RS256”,“HS256”] | A list of accepted signing methods for tokens. This ensures that only tokens signed using one of the specified algorithms will be considered valid. |
ENV
Argument | ENV | Type |
---|---|---|
authn-enabled | PERMIFY_AUTHN_ENABLED | boolean |
authn-method | PERMIFY_AUTHN_METHOD | string |
authn-oidc-issuer | PERMIFY_AUTHN_OIDC_ISSUER | string |
authn-oidc-audience | PERMIFY_AUTHN_OIDC_AUDIENCE | string |
authn-oidc-refresh-interval | PERMIFY_AUTHN_OIDC_REFRESH_INTERVAL | duration |
authn-oidc-backoff-interval | PERMIFY_AUTHN_OIDC_BACKOFF_INTERVAL | duration |
authn-oidc-backoff-frequency | PERMIFY_AUTHN_OIDC_BACKOFF_FREQUENCY | duration |
authn-oidc-backoff-max-retries | PERMIFY_AUTHN_OIDC_BACKOFF_RETRIES | int |
authn-oidc-valid-methods | PERMIFY_AUTHN_OIDC_VALID_METHODS | string array |
tracer | Tracing Configurations
tracer | Tracing Configurations
Definition
Permify integrated with jaeger, otlp, signoz, and zipkin tacing tools to analyze performance and behavior of your authorization when using Permify.
Structure
Glossary
Required | Argument | Default | Description |
---|---|---|---|
[x] | exporter | - | Tracer exporter, the options are jaeger , otlp , signoz , and zipkin . |
[x] | endpoint | - | export uri for tracing data. |
[ ] | enabled | false | switch option for tracing. |
[ ] | urlpath | allows one to override the default URL path for otlp, used for sending traces. If unset, default (“/v1/traces”) will be used. | |
[ ] | insecure | false | Whether to use HTTP instead of HTTPs for exporting the traces. |
ENV
Argument | ENV | Type |
---|---|---|
tracer-enabled | PERMIFY_TRACER_ENABLED | boolean |
tracer-exporter | PERMIFY_TRACER_EXPORTER | string |
tracer-endpoint | PERMIFY_TRACER_ENDPOINT | string |
tracer-urlpath | PERMIFY_TRACER_URL_PATH | string |
tracer-insecure | PERMIFY_TRACER_INSECURE | boolean |
meter | Meter Configurations
meter | Meter Configurations
Definition
Configuration for observing metrics; check count, cache check count and session information; Permify version, hostname, os, arch.
Structure
Glossary
Required | Argument | Default | Description |
---|---|---|---|
[x] | exporter | - | otlp is default. |
[x] | endpoint | - | export uri for metric observation |
[ ] | enabled | true | switch option for meter tracing. |
ENV
Argument | ENV | Type |
---|---|---|
meter-enabled | PERMIFY_METER_ENABLED | boolean |
meter-exporter | PERMIFY_METER_EXPORTER | string |
meter-endpoint | PERMIFY_METER_ENDPOINT | string |
meter-urlpath | PERMIFY_METER_URL_PATH | string |
meter-insecure | PERMIFY_METER_INSECURE | boolean |
database | Database Configurations
database | Database Configurations
Definition
Configurations for the database that points out where your want to store your authorization data (relation tuples, audits, decision logs, authorization model)
Structure
Glossary
Required | Argument | Default | Description |
---|---|---|---|
[x] | engine | memory | Data source. Permify supports PostgreSQL('postgres' ) for now. Contact with us for your preferred database. |
[x] | uri | - | Uri of your data source. |
[ ] | auto_migrate | true | When its configured as false migrating flow won’t work. |
[ ] | max_open_connections | 20 | Configuration parameter determines the maximum number of concurrent connections to the database that are allowed. |
[ ] | max_idle_connections | 1 | Determines the maximum number of idle connections that can be held in the connection pool. |
[ ] | max_connection_lifetime | 300s | Determines the maximum lifetime of a connection in seconds. |
[ ] | max_connection_idle_time | 60s | Determines the maximum time in seconds that a connection can remain idle before it is closed. |
[ ] | enable (for garbage collection) | false | Switch option for garbage collection. |
[ ] | interval | 3m | Determines the run period of a Garbage Collection operation. |
[ ] | timeout | 3m | Sets the duration of the Garbage Collection timeout. |
[ ] | window | 720h | Determines how much backward cleaning the Garbage Collection process will perform. |
ENV
Argument | ENV | Type |
---|---|---|
database-engine | PERMIFY_DATABASE_ENGINE | string |
database-uri | PERMIFY_DATABASE_URI | string |
database-auto-migrate | PERMIFY_DATABASE_AUTO_MIGRATE | boolean |
database-max-open-connections | PERMIFY_DATABASE_MAX_OPEN_CONNECTIONS | int |
database-max-idle-connections | PERMIFY_DATABASE_MAX_IDLE_CONNECTIONS | int |
database-max-connection-lifetime | PERMIFY_DATABASE_MAX_CONNECTION_LIFETIME | duration |
database-max-connection-idle-time | PERMIFY_DATABASE_MAX_CONNECTION_IDLE_TIME | duration |
database-garbage-collection-enabled | PERMIFY_DATABASE_GARBAGE_COLLECTION_ENABLED | boolean |
database-garbage-collection-interval | PERMIFY_DATABASE_GARBAGE_COLLECTION_INTERVAL | duration |
database-garbage-collection-timeout | PERMIFY_DATABASE_GARBAGE_COLLECTION_TIMEOUT | duration |
database-garbage-collection-window | PERMIFY_DATABASE_GARBAGE_COLLECTION_WINDOW | duration |
service | Service Configurations
service | Service Configurations
Definition
Configurations for the permify service and how it should behave. You can configure the circuit breaker pattern, configuration watcher, and service specific options for permission and schema services (rate limiting, concurrency limiting, cache size).
Structure
Glossary
Required | Argument | Default | Description |
---|---|---|---|
[ ] | circuit_breaker | false | switch option to use the circuit breaker pattern. |
[ ] | watch | false | switch option for configuration watcher. |
[ ] | schema.cache.number_of_counters | 1_000 | number of counters for schema service. |
[ ] | schema.cache.max_cost | 10MiB | max cost for schema cache. |
[ ] | permission.bulk_limit | 100 | bulk operations limit for permission service. |
[ ] | permission.concurrency_limit | 100 | concurrency limit for permission service. |
[ ] | permission.cache.max_cost | 10MiB | max cost for permission service. |
ENV
Argument | ENV | Type |
---|---|---|
service-circuit-breaker | PERMIFY_SERVICE_CIRCUIT_BREAKER | boolean |
service-watch-enabled | PERMIFY_SERVICE_WATCH_ENABLED | boolean |
service-schema-cache-number-of-counters | PERMIFY_SERVICE_SCHEMA_CACHE_NUMBER_OF_COUNTERS | int |
service-schema-cache-max-cost | PERMIFY_SERVICE_SCHEMA_CACHE_MAX_COST | int |
service-permission-bulk-limit | PERMIFY_SERVICE_PERMISSION_BULK_LIMIT | int |
service-permission-concurrency-limit | PERMIFY_SERVICE_PERMISSION_CONCURRENCY_LIMIT | int |
service-permission-cache-max-cost | PERMIFY_SERVICE_PERMISSION_CACHE_MAX_COST | int |
profiler | Performance Profiler Configurations
profiler | Performance Profiler Configurations
Definition
pprof is a performance profiler for Go programs. It allows developers to analyze and understand the performance characteristics of their code by generating detailed profiles of program execution
Structure
Glossary
Required | Argument | Default | Description |
---|---|---|---|
[ ] | enabled | true | switch option for profiler. |
[x] | port | - | port that profiler runs on (default: 6060). |
ENV
Argument | ENV | Type |
---|---|---|
profiler-enabled | PERMIFY_PROFILER_ENABLED | boolean |
profiler-port | PERMIFY_PROFILER_PORT | string |
Distributed | Consistent hashing Configurations
Distributed | Consistent hashing Configurations
Definition
A consistent hashing ring ensures data distribution that minimizes reorganization when nodes are added or removed, improving scalability and performance in distributed systems.”
Structure
Glossary
Required | Argument | Default | Description |
---|---|---|---|
[x] | enabled | false | switch option for distributed. |
[] | address | - | address of the distributed service |
[] | port | 5000 | port on which the service is exposed |
ENV
Argument | ENV | Type |
---|---|---|
distributed-enabled | PERMIFY_DISTRIBUTED_ENABLED | boolean |
distributed-address | PERMIFY_DISTRIBUTED_ADDRESS | string |
distributed-port | PERMIFY_DISTRIBUTED_PORT | string |