Configurations

These configurations are used to configure the UI for the Management UI, the management API and the runtime API. The configuration is done in the policyserver.json file. The following sections describe the different configurations available.

Root level configuration

{
    "PolicyServer": {
        "authority": "https://localhost:65471/",
        "demoMode": true,
}

Setting	Description
`authority`	Indicates the base address of PolicyServer UI host.
`demoMode`	If enabled the search api for both the users and roles will be activated with dummy auto-generated data just to show the feature.

Diagnostics

The Diagnostics section provides configuration options to help monitor and troubleshoot the system. It includes settings that control the level of logging for both the application startup and runtime operations. Specifically:

{
    "PolicyServer": {
        "diagnostics": {
            "enableStartupDiagnostics": true,
            "showMsJwtPiiDetails": true,
            "enableRequestLogging": true,
            "logRequestHeader": false
        },
}

Setting	Description
`enableStartupDiagnostics`	By default this option is turned off, when enabled, the application dump all the system configurations in the log.
`showMsJwtPiiDetails`	By default this option is turned off, when enabled the system display the Personally Identifiable Information (PII) in logs for the Microsoft IdentityModel library.
`enableRequestLogging`	By default this option is turned off, when enabled the system log all the http requests in the configured log.
`logRequestHeader`	By default this option is turned off, when enabled the system logs all the http request headers in the configured log.

Host

The Host configurations define how the PolicyServer UI host and its associated APIs (management and runtime) are enabled and secured. Key aspects include:

{
    "PolicyServer": {
        "host": {
            "uiEnabled": true,
            "managementApiEnabled": true,
            "runtimeApiEnabled": true,
        },
    }
}

Setting	Description
`uiEnabled`	Enables or disables the PolicyServer UI host.
`managementApiEnabled`	Enables or disables the management API.
`runtimeApiEnabled`	Enables or disables the runtime API.
`network`	Groups network-specific settings for pathing, reverse proxies, and HTTPS options.
`network.pathBase`	Specifies the base URL path (e.g., `/policyserver`) for routing incoming requests.
`network.allowAllReverseProxies`	Determines whether all reverse proxies are allowed or only specific ones.
`network.knownReverseProxies`	Lists the IP addresses of known reverse proxies that are explicitly allowed.
`network.knownReverseProxyNetworks`	Defines network ranges (using address and length) from which reverse proxies may be recognized.
`network.HttpsOptions`	Contains settings to enforce HTTPS, including HSTS configurations.
`network.HttpsOptions.preload`	Indicates if the HSTS policy should be preloaded by browsers.
`network.HttpsOptions.IncludeSubDomains`	Specifies whether the HSTS policy applies to all subdomains.
`network.HttpsOptions.MaxAgeInDays`	Sets the maximum age (in days) for which the HSTS policy is valid.
`network.HttpsOptions.ExcludedHosts`	Lists hosts that should be excluded from HTTPS redirection.
`network.HttpsOptions.HttpsPort`	Defines the port number to be used for HTTPS traffic.
`network.HttpsOptions.HttpsRedirectCode`	Specifies the HTTP status code to use for HTTPS redirection (e.g., 307).

Network

The Network section is responsible for configuring the network settings for the PolicyServer UI host. This includes settings for pathing, reverse proxies, and HTTPS options. The configuration is as follows:

{
    "PolicyServer": {
        "host": {
            "network": {
                "pathBase": "/policyserver",
                "allowAllReverseProxies": false,
                "knownReverseProxies": [],
                "knownReverseProxyNetworks": [
                {
                    "address": "192.168.0.0",
                    "length": 24
                }
                ],
                "HttpsOptions": {
                    "preload": true,
                    "IncludeSubDomains": true,
                    "MaxAgeInDays": 365,
                    "ExcludedHosts": [],
                    "HttpsPort": 5001,
                    "HttpsRedirectCode": 307
                }
            }
        },
    }
}

Setting	Description
`pathBase`	Specifies the base URL path (e.g., `/policyserver`) for routing incoming requests.
`allowAllReverseProxies`	Determines whether all reverse proxies are allowed or only specific ones.
`knownReverseProxies`	Lists the IP addresses of known reverse proxies that are explicitly allowed.
`knownReverseProxyNetworks`	Defines network ranges (using address and length) from which reverse proxies may be recognized.
`HttpsOptions`	Contains settings to enforce HTTPS, including HSTS configurations.
`HttpsOptions.preload`	Indicates if the HSTS policy should be preloaded by browsers.
`HttpsOptions.IncludeSubDomains`	Specifies whether the HSTS policy applies to all subdomains.
`HttpsOptions.MaxAgeInDays`	Sets the maximum age (in days) for which the HSTS policy is valid.
`HttpsOptions.ExcludedHosts`	Lists hosts that should be excluded from HTTPS redirection.
`HttpsOptions.HttpsPort`	Defines the port number to be used for HTTPS traffic.
`HttpsOptions.HttpsRedirectCode`	Specifies the HTTP status code to use for HTTPS redirection (e.g., 307).

Identity

The Identity section is responsible for configuring the authentication and authorization mechanisms for the PolicyServer UI host. This includes settings for local login, external token issuers, and single sign-on (SSO) options. The configuration is as follows:

{
    "PolicyServer": {
        "host": {
            "identity": {
                "enableLocalLogin": true,
                "externalTokenIssuer": {
                    "authority": "<external issuer authority>",

                    "RuntimeApiAudience": "<audience>",
                    "RuntimeApiScope": "<policyserver.runtime>",

                    "ManagementApiAudience": "<audience>",
                    "ManagementApiScope": "<policyserver.management>",

                    "RemoveSubjectIdForMachineClients": true,

                    "claimMappings": {
                        "ClientIdClaimTypes": [ "azp" ],
                        "SubClaimTypes": [ "azp" ],
                        "ScopeClaimTypes": [ "roles" ]
                    }
                },

                "sso": {
                    "federatedLogoutPrompt": true,
                    "openidconnect": {
                        "authority": "<external idp authority>",
                        "clientid": "<client id>",
                        "clientSecret": "<secret>",
                        "responseType": "code",
                        "responseMode": "query",
                        "scope": "openid profile roles",
                        "NameClaimType": "name",
                        "RoleClaimType": "role",
                        "SubClaimType": "sub",
                    }
                },

                "admins": [
                    {
                        "username": "<admin username>",
                        "password": "<password hash>",
                        "displayName": "<display name>"
                    }
                ],
                "runtimeClients": [
                    {
                        "clientId": "<runtime.client>",
                        "clientSecret": "<secret hash>"
                    }
                ],
                "managementClients": [
                    {
                        "clientId": "<management.client>",
                        "clientSecret": "<secret hash>"
                    }
                ]
            }
        },
    }
}

Identity Top-Level Configuration Attributes

The identity section contains top-level attribute that control the authentication and authorization mechanisms for the PolicyServer UI host. The configuration is as follows:

Setting	Description
`enableLocalLogin`	Enables or disables local login for the PolicyServer UI host, if enabled the admins in the admin array will be able log into the Managemnet UI using the passwords for the hashes configured.

External Token Issuer Configuration Attributes

The external token issuer configuration is used to set up an external identity provider for token issuance. This includes settings for the authority, audience, and scopes for both runtime and management APIs. The configuration is as follows:

Setting	Description
`authority`	Specifies the URL of the external token issuer.
`RuntimeApiAudience`	The audience for the runtime API.
`RuntimeApiScope`	The scope for the runtime API.
`ManagementApiAudience`	The audience for the management API.
`ManagementApiScope`	The scope for the management API.
`RemoveSubjectIdForMachineClients`	Determines if the subject ID should be omitted for machine clients.

Claim Mappings Sub-Attributes

These sub-attributes are used to specify the claim types for client ID, subject, and roles/scopes. They are defined within the claimMappings section of the external token issuer configuration.

Setting	Description
`ClientIdClaimTypes`	The claim types to be used for the client ID.
`SubClaimTypes`	The claim types to be used for the subject.
`ScopeClaimTypes`	The claim types to be used for roles/scopes.

SSO Configuration Attributes

The SSO configuration is used to set up single sign-on (SSO) capabilities for the PolicyServer UI host. This includes settings for federated logout and OpenID Connect parameters. The configuration is as follows:

Setting	Description
`federatedLogoutPrompt`	Controls the logout behavior when using SSO.
`openidconnect`	Contains settings for OpenID Connect configuration.
`openidconnect.authority`	Specifies the URL of the external identity provider.
`openidconnect.clientid`	The client identifier for authentication.
`openidconnect.clientSecret`	The client secret used for authentication.
`openidconnect.responseType`	The response type (e.g., “code”).
`openidconnect.responseMode`	The response mode (e.g., “query”).
`openidconnect.scope`	The requested scopes during authentication.
`openidconnect.NameClaimType`	The claim type used for the name.
`openidconnect.RoleClaimType`	The claim type used to represent roles.
`openidconnect.SubClaimType`	The claim type representing the subject.

Admins Configuration Attributes

The admins configuration is used to define local administrators for the PolicyServer UI host. This includes settings for the username, hashed password, and display name. The configuration is as follows:

Setting	Description
`username`	The administrator’s username.
`password`	The hashed password for the administrator.
`displayName`	The display name for the administrator.

Runtime Clients Configuration Attributes

The runtime clients configuration is used to define clients that can access the runtime API. This includes settings for the client ID and secret. The configuration is as follows:

Setting	Description
`clientId`	The client identifier for runtime API access.
`clientSecret`	The client secret or hash for runtime API access.

Management Clients Configuration Attributes

The management clients configuration is used to define clients that can access the management API. This includes settings for the client ID and secret. The configuration is as follows:

Setting	Description
`clientId`	The client identifier for management API access.
`clientSecret`	The client secret or hash for management API access.

UI

The UI section is responsible for configuring the user interface of the PolicyServer. This includes settings for pagination, management API URL, and support options. The configuration is as follows:

{
    "PolicyServer": {
        "ui": {
            "pageSize": 10,
            "managementApiUrl":  "",
            "pinTenantDescription": true,
            "support": {
                "disable": false,
                "hideLicense": false
            }
        },
    }
}

UI Configuration Attributes

Setting	Description
`pageSize`	Defines the number of items per page in the UI.
`managementApiUrl`	Specifies the URL for the management API used by the UI if different than the UI host.
`pinTenantDescription`	When enabled, the tenant description is pinned in the UI when selected.
`support`	Contains support-related configuration settings.

Support Configuration Attributes (UI Section)

Setting	Description
`disable`	When true, support options are disabled in the UI.
`hideLicense`	When true, license information is hidden from the UI.

Database

The Database section is responsible for configuring the database settings for PolicyServer. This includes settings for the database provider, connection string, caching, and database creation. The configuration is as follows:

{
    "PolicyServer": {
        "database": {
            "Provider": "<SQLite/SqlServer/PostgreSQL>",
            "ConnectionString": "<connection string>",
            "EnableCaching": true,
            "DisableOutputClause": true,
            "AutoCreateDatabase": true,
            "AutoSeedSampleData": true
        },
    }
}

Database Configuration Attributes

Setting	Description
`Provider`	Specifies the database provider (e.g., SQLite, SqlServer, or PostgreSQL).
`ConnectionString`	Defines the connection string used to connect to the database.
`EnableCaching`	Enables caching to improve performance.
`DisableOutputClause`	Disables the output clause, supporting EF breaking changes from version 7 and newer.
`AutoCreateDatabase`	Automatically creates the database if it does not exist.
`AutoSeedSampleData`	Automatically seeds sample data into the database.

Management

The Management section is responsible for configuring the management API settings for PolicyServer. This includes settings for token service authority, Swagger documentation, user and role search URLs, multi-tenancy, and data protection. The configuration is as follows:

{
    "PolicyServer": {
        "management": {
            "TokenServiceAuthority": "",
            "EnableSwagger": false,
            "userSearchUrl": "",
            "RoleSearchUrl": "",
            "EnableMultiTenancy": true,
            "AutoProvisionUnrecognizedTenants": true,
            "DefaultPageSize": 20,
            "DataProtection": {
                "CertificateFileName": "",
                "CertificateFilePassword": "",
                "CertificateThumbprint": "",
                "KeyVaultKeysUri": ""
            }
        },
    }
}

Management Configuration Attributes

The management section contains configuration attributes that control the behavior of the management API. The configuration is as follows:

Setting	Description
`TokenServiceAuthority`	Specifies the authority for the token service.
`EnableSwagger`	Enables or disables Swagger documentation for the management API.
`userSearchUrl`	Specifies the URL for user search functionality.
`RoleSearchUrl`	Specifies the URL for role search functionality.
`EnableMultiTenancy`	Enables or disables multi-tenancy support.
`AutoProvisionUnrecognizedTenants`	Automatically provisions unrecognized tenants.
`DefaultPageSize`	Sets the default page size for API responses.

Data Protection Configuration Attributes

The Data Protection section is responsible for configuring data protection settings for the management API. This includes settings for the certificate file name, password, thumbprint, and Key Vault keys URI. The configuration is as follows:

Setting	Description
`CertificateFileName`	Specifies the file name of the certificate used for data protection.
`CertificateFilePassword`	Specifies the password for the certificate file.
`CertificateThumbprint`	Specifies the thumbprint of the certificate used for data protection.
`KeyVaultKeysUri`	Specifies the URI for Key Vault keys used for data protection.

Runtime

The Runtime section is responsible for configuring the runtime API settings for PolicyServer. This includes settings for Swagger documentation, The configuration is as follows:

{
    "PolicyServer": {
        "runtime": {
            "EnableSwagger": false
        },
    }
}

Runtime Configuration Attributes

Setting	Description
`EnableSwagger`	Enables or disables Swagger documentation for the runtime API.

Azure AppConfig

The Azure AppConfig section is responsible for configuring the connection to Azure App Configuration. This includes settings for the connection string and label. The configuration is as follows:

{
    "PolicyServer": {
        "azureAppConfig": {
            "ConnectionString": "",
            "Label": ""
        },
    }
}

Azure AppConfig Configuration Attributes

Setting	Description
`ConnectionString`	Specifies the connection string for Azure App Configuration.
`Label`	Specifies the label for the configuration settings to support muliple environments.

Auditing

The Auditing section is responsible for configuring the auditing settings for PolicyServer. This includes settings for metadata, claims, and headers. The configuration is as follows:

{
    "PolicyServer": {
        "auditing": {
            "metadata": {
                "static": {
                "static1": "value1",
                "static2": "value2"
                },
                "claims": [
                {
                    "type": "ui",
                    "claimTypes": [
                    "sub",
                    "amr"
                    ]
                },
                {
                    "type": "api",
                    "claimTypes": [
                    "client_id",
                    "sub"
                    ]
                }
                ],
                "headers": [
                {
                    "name": "User-Agent"
                },
                {
                    "name": "CorrelationId",
                    "propagate": true
                }
                ]
            }
        }
    }
}

Auditing Configuration Attributes

Setting	Description
`metadata`	Contains metadata settings for auditing.
`static`	Contains static metadata key-value pairs.
`claims`	Contains claim settings for auditing.
`headers`	Contains header settings for auditing.