Skip to content

Identity API Appsettings

Below is the documentation for the provided appsettings.json configuration file. This document provides explanations for each section in the configuration, assisting in understanding and managing your application settings.

Overview

This appsettings.json file includes configuration settings necessary for connecting to databases, managing scheduler jobs, interfacing with Azure, handling authentication, utilizing Event Hubs, and configuring logging with Serilog. These configurations support various aspects of an ASP.NET Core application.

1. ConnectionStrings

{
  "ConnectionStrings": {
    "DefaultConnection": "{Your connection string comes here}"
  }
}

Docker-compose form of environment variables.

environment:
  ConnectionStrings__DefaultConnection:"{Your connection string comes here}"
  • DefaultConnection: Placeholder for the database connection string used to connect the application to the database.

2. SchedulerJob

{
  "SchedulerJob": {
    "CleanUpOneTimeUsersDailyAtHour": 1
  }
}

Docker-compose form of environment variables.

environment:
  SchedulerJob__CleanUpOneTimeUsersDailyAtHour:"1"
  • CleanUpOneTimeUsersDailyAtHour: Specifies the hour at which the application runs a job to clean up one-time users, set here to run daily at 1 AM.

3. Storage

{
"Storage": {
  "Provider": "Azure",
  "Azure": {
    "ConnectionString": "{Your Azure connection string here}",
    "CDN": "{Your CDN URL here}",
    "SasToken": {
        "ExpireMinute": 360,
        "ExpireMinuteThreshold": 30
    }
  },
  "Amazon": {
    "BucketName": "{Your BucketName here}",
    "Region": "{Your Region here}",
    "CDN": "{Your CDN URL here}",
    "AccessKey":  "{Your AccessKey here}",
    "SecretKey": "{Your SecretKey here}",
    "CloudFrontKeyPairId": "{Your Key Pair Id here}",
    "CloudFrontPrivateKey": "-----BEGIN RSA PRIVATE KEY-----\n...3qltFR8=\n-----END RSA PRIVATE KEY-----\n",
    "SignedUrl": {
        "ExpireMinute": 360,
        "ExpireMinuteThreshold": 30
      }  },
  "PublishedContentFolder": "published-content",
  "MBTilerZipsFolder": "mbtiler-zips",
  "MapscaleCadsFolder": "mapscale-cads",
  "FeatureImagesFolder": "feature-images",
  "MBTilerFolder": "mbtiler",
  "MapscaleResultsFolder": "mapscale-results",
  "StylesWithContentsFolder": "style-with-map-metadata",
  "StylesFolder": "styles",
  "FilesFolder": "files",
  "CadToGeojsonFolder": "cad-to-geojson",
  "GeojsonToPngFolder": "geojson-to-png",
  "ImdfFolder": "imdf"
  } 
}

For containerized deployments, the Storage configuration can be provided using environment variables in docker-compose.yml.
Each nested property is represented with __ (double underscore) between hierarchy levels.

Example: Environment Variables

environment:
  Storage__Provider: "Azure"

  # Azure-specific settings
  Storage__Azure__ConnectionString: "..."
  Storage__Azure__CDN: "https://pointrcdnexample.blob.core.windows.net"
  Storage__Azure__SasToken__ExpireMinute: "360"
  Storage__Azure__SasToken__ExpireMinuteThreshold: "30"

  # Amazon-specific settings
  Storage__Amazon__BucketName: ""
  Storage__Amazon__Region: ""
  Storage__Amazon__CDN: ""
  Storage__Amazon__AccessKey: ""
  Storage__Amazon__SecretKey: ""
  Storage__Amazon__CloudFrontKeyPairId: ""
  Storage__Amazon__CloudFrontPrivateKey: ""
  Storage__Amazon__SignedUrl__ExpireMinute: "360"
  Storage__Amazon__SignedUrl__ExpireMinuteThreshold: "30"

  # Common folders
  Storage__PublishedContentFolder: "published-content"
  Storage__MBTilerZipsFolder: "mbtiler-zips"
  Storage__MapscaleCadsFolder: "mapscale-cads"
  Storage__FeatureImagesFolder: "feature-images"
  Storage__MBTilerFolder: "mbtiler"
  Storage__MapscaleResultsFolder: "mapscale-results"
  Storage__StylesWithContentsFolder: "style-with-map-metadata"
  Storage__StylesFolder: "styles"
  Storage__FilesFolder: "files"
  Storage__CadToGeojsonFolder: "cad-to-geojson"
  Storage__GeojsonToPngFolder: "geojson-to-png"
  Storage__ImdfFolder: "imdf"

Explanation of Keys

Provider

  • Storage__Provider: Defines which provider is used (Azure or Amazon).

Azure Section

  • Storage__Azure__ConnectionString: The connection string used to access Azure Blob Storage services.
  • Storage__Azure__CDN: The URL for the Azure Content Delivery Network (CDN).

SasToken (Identity-specific)

  • Storage__Azure__SasToken__ExpireMinute (360): Defines the total validity duration of the SAS token in minutes. Here, 360 minutes = 6 hours.
  • Storage__Azure__SasToken__ExpireMinuteThreshold (30): If less than 30 minutes remain before token expiry, a new SAS token is generated proactively to avoid downtime.

Amazon Section

  • Storage__Amazon__BucketName: The name of the Amazon S3 bucket.
  • Storage__Amazon__Region: The AWS region where the bucket is hosted (e.g., eu-central-1).
  • Storage__Amazon__CDN: The URL for serving content via Amazon S3 or CloudFront.
  • Storage__Amazon__AccessKey: The AWS access key ID for authentication.
  • Storage__Amazon__SecretKey: The AWS secret key for authentication.
  • Storage__Amazon__CloudFrontKeyPairId: The CloudFront key pair ID used for generating signed URLs to restrict access to private content.
  • Storage__Amazon__CloudFrontPrivateKey: The RSA private key corresponding to the CloudFront key pair, used to sign URLs. This should be in PEM format with newlines represented as \n.
  • Storage__Amazon__SignedUrl__ExpireMinute (360): Defines the total validity duration of the signed URL in minutes. Here, 360 minutes = 6 hours.
  • Storage__Amazon__SignedUrl__ExpireMinuteThreshold (30): If less than 30 minutes remain before signed URL expiry, a new signed URL is generated proactively to avoid downtime.

Common Folder Paths

  • Storage__PublishedContentFolder: Stores published content.
  • Storage__MBTilerZipsFolder: Stores MBTiler zip files.
  • Storage__MapscaleCadsFolder: Stores CAD files for Mapscale.
  • Storage__FeatureImagesFolder: Stores feature-related images.
  • Storage__MBTilerFolder: Stores MBTiler output.
  • Storage__MapscaleResultsFolder: Stores Mapscale results.
  • Storage__StylesWithContentsFolder: Stores styles with metadata.
  • Storage__StylesFolder: Stores style files.
  • Storage__FilesFolder: General-purpose file storage.
  • Storage__CadToGeojsonFolder: Stores CAD → GeoJSON conversions.
  • Storage__GeojsonToPngFolder: Stores GeoJSON → PNG conversions.
  • Storage__ImdfFolder: Stores IMDF format files.

4. IdentityProviders

{
  "IdentityProviders": {
    "Selected": "",
    "EntraIdClientCertificate": {
      "StsDiscoveryEndpoint": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
      "ClientId": "713fdc21-b059-477e-bc94-7b4ab31ed978",
      "TenantId": "2c0c586a-26dc-485d-a917-cebac9623a1a",
      "Scope": "api://{0}/access_as_user",
      "Redirect": "https://localhost:44345/HeatMap",
      "AuthenticationUrl": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
      "CertificateCheckMinute": 5,
      "TokenEmailField": "email"
    },
    "EntraIdClientSecret": {
      "StsDiscoveryEndpoint": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
      "ClientId": "713fdc21-b059-477e-bc94-7b4ab31ed978",
      "ClientSecret": "RT48Q~.Ayc5jK.fS3e8hcQx00gj-tbocBE2ycbkV",
      "TenantId": "2c0c586a-26dc-485d-a917-cebac9623a1a",
      "Scope": "api://{0}/access_as_user",
      "Redirect": "https://localhost:44345/HeatMap",
      "AuthenticationUrl": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
      "TokenEmailField": "email"
    },
    "Cisco": {
      "IdentityCertificateUrl": "",
      "IdentityCertificateHeaderKey": "",
      "IdentityCertificateHeaderValue": ""
    },
    "PingFederated": {
      "StsDiscoveryEndpoint": "",
      "ClientId": "",
      "RedirectUrl": "",
      "CodeVerifier": "",
      "TokenEndpoint": "",
      "Scope": "",
      "Username": "",
      "Password": "",
      "TokenFieldName": "",
      "TokenEmailField": "sub"
    }
  }
}

Docker-compose form of environment variables.

environment:
  IdentityProviders__Selected=""

  # EntraIdClientCertificate
  IdentityProviders__EntraIdClientCertificate__StsDiscoveryEndpoint="https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration"
  IdentityProviders__EntraIdClientCertificate__ClientId="{Your ClientId here}"
  IdentityProviders__EntraIdClientCertificate__TenantId="{Your TenantId here}"
  IdentityProviders__EntraIdClientCertificate__Scope="{Your Scope here}"
  IdentityProviders__EntraIdClientCertificate__Redirect="{Your Redirect URL here}"
  IdentityProviders__EntraIdClientCertificate__AuthenticationUrl="https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token"
  IdentityProviders__EntraIdClientCertificate__CertificateCheckMinute="5"
  IdentityProviders__EntraIdClientCertificate__TokenEmailField="email"

  # EntraIdClientSecret
  IdentityProviders__EntraIdClientSecret__StsDiscoveryEndpoint="https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration"
  IdentityProviders__EntraIdClientSecret__ClientId="{Your ClientId here}"
  IdentityProviders__EntraIdClientSecret__ClientSecret="{Your ClientSecret here}"
  IdentityProviders__EntraIdClientSecret__TenantId="{Your TenantId here}"
  IdentityProviders__EntraIdClientSecret__Scope="{Your Scope here}"
  IdentityProviders__EntraIdClientSecret__Redirect="{Your Redirect URL here}"
  IdentityProviders__EntraIdClientSecret__AuthenticationUrl="https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token"
  IdentityProviders__EntraIdClientSecret__TokenEmailField="email"

  # Cisco
  IdentityProviders__Cisco__IdentityCertificateUrl=""
  IdentityProviders__Cisco__IdentityCertificateHeaderKey=""
  IdentityProviders__Cisco__IdentityCertificateHeaderValue=""

  # PingFederated
  IdentityProviders__PingFederated__StsDiscoveryEndpoint=""
  IdentityProviders__PingFederated__ClientId=""
  IdentityProviders__PingFederated__RedirectUrl=""
  IdentityProviders__PingFederated__CodeVerifier=""
  IdentityProviders__PingFederated__TokenEndpoint=""
  IdentityProviders__PingFederated__Scope=""
  IdentityProviders__PingFederated__Username=""
  IdentityProviders__PingFederated__Password=""
  IdentityProviders__PingFederated__TokenFieldName=""
  IdentityProviders__PingFederated__TokenEmailField=""

IdentityProviders:

  • Selected: Determines the currently active identity provider. It is currently unset.
    • EntraIdClientCertificate
    • EntraIdClientSecret
    • Cisco
    • PingFederated

EntraIdClientSecret (Microsoft Entra ID):

  • Selected: Must be set to EntraIdClientSecret for this type.
  • StsDiscoveryEndpoint: OpenID Connect metadata endpoint.
  • Authority: Token endpoint with {0} replaced by your Tenant ID.
  • TenantID: Directory (tenant) identifier.
  • ClientID: Azure-registered application's ID.
  • ClientSecret: Secret key for authentication.
  • Scope: Requested permissions (e.g. api://{0}/access_as_user).
  • RedirectUrl: Post-authentication redirect.
  • TokenEmailField: Field name used to extract email from the token. (e.g. email)

EntraIdClientCertificate (Microsoft Entra ID):

  • Selected: Must be EntraIdClientCertificate.
  • StsDiscoveryEndpoint: OpenID Connect metadata endpoint.
  • Authority: Token endpoint with {0} replaced by your Tenant ID.
  • TenantID: Directory (tenant) identifier.
  • ClientID: Azure-registered application's ID.
  • Scope: Requested permissions (e.g. api://{0}/access_as_user).
  • RedirectUrl: Post-authentication redirect.
  • CertificateCheckMinute: Optional frequency (in minutes) to check and refresh the client certificate.
  • TokenEmailField: Field name used to extract email from the token. (e.g. email)

NOTE: * This flow uses client assertion via certificate instead of a client secret for improved security.

Cisco:

  • Selected: Must be Cisco.
  • IdentityCertificateUrl: URL for identity certificate validation or retrieval (if applicable).
  • IdentityCertificateHeaderKey: HTTP header used to pass identity information.
  • IdentityCertificateHeaderValue: Expected value of the identity header (optional or dynamic).

PingFederated (Ping Federate With Basic Auth):

  • IdentityProvider: Must be PingFederate.
  • StsDiscoveryEndpoint: OpenID Connect metadata endpoint.
  • TokenEndpoint: Endpoint to exchange authorization code for access token.
  • ClientID: PingFederate-registered application's ID.
  • RedirectUrl: Post-authentication redirect.
  • Username: Username for basic authentication.
  • Password: Password for basic authentication.
  • CodeVerifier: Your code verifier code.
  • TokenFieldName: Specifies which field to use as the access token in the response.
  • TokenEmailField: Email claim name in the token. (e.g. sub)

PingFederated (Ping Federate With PKCE):

  • Selected: Must be PingFederated.
  • StsDiscoveryEndpoint: OpenID Connect metadata endpoint.
  • TokenEndpoint: Endpoint to exchange authorization code for access token.
  • ClientID: PingFederate-registered application's ID.
  • RedirectUrl: Post-authentication redirect.
  • CodeVerifier: Your code verifier code.
  • Scope: Requested permissions (e.g. openid profile).
  • TokenFieldName: Specifies which field to use as the access token in the response.
  • TokenEmailField: Email claim name in the token. (e.g. sub)

5. Auth

{
  "Auth": {
    "DashboardUrl": "{Your DashboardUrl here}",
    "ClientCriticalAccessSecret": "{Your ClientCriticalAccessSecret here}",
    "JWT": {
      "RefreshTokenExpireMinutes": 1440,
      "TokenExpireMinutes": 120,
      "PointrClientSecret": "{Your JWT client secret here}",
      "IssuerGatewayUrl": "{Your IssuerGatewayUrl here}"
    },
    "MinimumPasswordLength": 0
  }
}

Docker-compose form of environment variables.

environment:
  Auth__DashboardUrl: "{Your DashboardUrl here}"
  Auth__ClientCriticalAccessSecret: "{Your ClientCriticalAccessSecret here}"
  Auth__JWT__RefreshTokenExpireMinutes: "1440"
  Auth__JWT__TokenExpireMinutes: "120"
  Auth__JWT__PointrClientSecret: "{Your JWT client secret here}"
  Auth__JWT__IssuerGatewayUrl: "{Your IssuerGatewayUrl here}"
  Auth__MinimumPasswordLength: "0"
  • DashboardUrl: The URL for the application's dashboard.
  • ClientCriticalAccessSecret: A secret for accessing critical client-level features.
  • JWT: JSON Web Token-related settings.
    • RefreshTokenExpireMinutes: Token refresh expiration period (1440 minutes).
    • TokenExpireMinutes: Access token expiration period (120 minutes).
    • PointrClientSecret: Secret key for generating JWT.
    • IssuerGatewayUrl: URL for the JWT issuer gateway.
  • MinimumPasswordLength: Configures minimum password length required (set to 0 here).

6. EventHub

{
  "EventHub": {
    "ServiceUrl": "https://{0}.servicebus.windows.net/{1}",
    "SasPrimaryKey": "",
    "SbName": "sendeventstest",
    "EhName": "sdkanalyticstest"
  }
}

Docker-compose form of environment variables.

environment:
  EventHub__ServiceUrl: "https://{0}.servicebus.windows.net/{1}"
  EventHub__SasPrimaryKey: ""
  EventHub__SbName: "sendeventstest"
  EventHub__EhName: "sdkanalyticstest"
  • ServiceUrl: Format string URL for connecting to Azure Event Hub services.
  • SasPrimaryKey: Primary key for SAS authentication (currently left empty).
  • SbName: Service Bus namespace used.
  • EhName: Event Hub name utilized for analytics.

7. Serilog

{
  "Serilog": {
    "Using": [ "Serilog.Sinks.Console" ],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Information",
        "System": "Information",
        "Microsoft.EntityFrameworkCore.Database.Command": "Warning",
        "Microsoft.AspNetCore.Mvc.Infrastructure.ObjectResultExecutor": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "Elasticsearch",
        "Args": {
          "nodeUris": "",
          "basicAuthUsername": "",
          "basicAuthPassword": "",
          "apiKey": "",
          "indexFormat": "apilogs-{logType}",
          "autoRegisterTemplate": true,
          "autoRegisterTemplateVersion": "ESv8",
          "emitEventFailure": "WriteToSelfLog"
        }
      },
      {
        "Name": "Console",
        "Args": {
          "theme": "Serilog.Sinks.SystemConsole.Themes.SystemConsoleTheme::Literate, Serilog.Sinks.Console",
          "outputTemplate": "[{Level} {@Timestamp:yyyy-MM-dd HH:mm:ss}] [Message: {Message} {Exception}]{NewLine}"
        }
      },
      {
        "Name": "CustomFile",
        "Args": {
          "path": "logs/log-.txt"
        }
      }
    ],
    "Enrich": ["FromLogContext", "WithMachineName", "WithProcessId", "WithThreadId"],
    "Destructure": [
      {
        "Name": "ToMaximumDepth",
        "Args": { "maximumDestructuringDepth": 20 }
      },
      {
        "Name": "ToMaximumStringLength",
        "Args": { "maximumStringLength": 5000 }
      },
      {
        "Name": "ToMaximumCollectionCount",
        "Args": { "maximumCollectionCount": 20 }
      }
    ],
    "Properties": {
      "Application": "Pointr.Microservice.Identity.API",
      "AllowedMethods": ""
    }
  }
}

Docker-compose form of environment variables.

environment:
  Serilog__Using__0: "Serilog.Sinks.Console"
  Serilog__MinimumLevel__Default: "Information"
  Serilog__MinimumLevel__Override__Microsoft: "Information"
  Serilog__MinimumLevel__Override__System: "Information"
  Serilog__MinimumLevel__Override__Microsoft.EntityFrameworkCore.Database.Command: "Warning"
  Serilog__MinimumLevel__Override__Microsoft.AspNetCore.Mvc.Infrastructure.ObjectResultExecutor: "Warning"
  Serilog__WriteTo__0__Name: "Elasticsearch"
  Serilog__WriteTo__0__Args__nodeUris: "{Your Elasticsearch URL comes here}"
  Serilog__WriteTo__0__Args__basicAuthUsername: "{Your Elasticsearch username comes here}"
  Serilog__WriteTo__0__Args__basicAuthPassword: "{Your Elasticsearch password comes here}"
  Serilog__WriteTo__0__Args__apiKey: "{Your Elasticsearch API key comes here (optional)}"
  Serilog__WriteTo__0__Args__indexFormat: "apilogs-{logType}"
  Serilog__WriteTo__0__Args__autoRegisterTemplate: "true"
  Serilog__WriteTo__0__Args__autoRegisterTemplateVersion: "ESv8"
  Serilog__WriteTo__0__Args__emitEventFailure: "WriteToSelfLog"
  Serilog__WriteTo__1__Name: "Console"
  Serilog__WriteTo__1__Args__theme: "Serilog.Sinks.SystemConsole.Themes.SystemConsoleTheme::Literate, Serilog.Sinks.Console"
  Serilog__WriteTo__1__Args__outputTemplate: "[{Level} {@Timestamp:yyyy-MM-dd HH:mm:ss}] [Message: {Message} {Exception}]{NewLine}"
  Serilog__WriteTo__2__Name: "CustomFile"
  Serilog__WriteTo__2__Args__path: "logs/log-.txt"
  Serilog__Enrich__0: "FromLogContext"
  Serilog__Enrich__1: "WithMachineName"
  Serilog__Enrich__2: "WithProcessId"
  Serilog__Enrich__3: "WithThreadId"
  Serilog__Destructure__0__Name: "ToMaximumDepth"
  Serilog__Destructure__0__Args__maximumDestructuringDepth: "20"
  Serilog__Destructure__1__Name: "ToMaximumStringLength"
  Serilog__Destructure__1__Args__maximumStringLength: "5000"
  Serilog__Destructure__2__Name: "ToMaximumCollectionCount"
  Serilog__Destructure__2__Args__maximumCollectionCount: "20"
  Serilog__Properties__Application: "Pointr.Microservice.Identity.API"
  Serilog__Properties__AllowedMethods: ""
  • Using: Specifies the Serilog sinks in use, such as "Serilog.Sinks.Console" for console logging.
  • MinimumLevel: Sets the minimum logging level to Information, with specific overrides available for Microsoft and System namespaces.
  • WriteTo: Defines where log output is sent. This configuration includes:
  • Elasticsearch: Sends logs to Elasticsearch with configurable authentication and indexing options.
  • Console: Outputs logs to the console with a custom theme and template.
  • CustomFile: Writes logs to a file at logs/log-.txt.
  • Enrich: Adds contextual data to logs, such as machine name, process ID, and thread ID.
  • Destructure: Configures destructuring with limits on depth (20), string length (5000), and collection count (20) to manage log size and detail.
  • Properties: Additional properties to include in every log, like specifying the application name and allowed methods.

Important Notes:

  • Elasticsearch authentication: API Key is preferred if available, otherwise Basic Auth (username/password) is used for connection.

  • The WriteTo array allows multiple sinks to be configured simultaneously, enabling logs to be sent to console, file, and Elasticsearch at the same time.

  • If the required configuration parameters for a sink are not provided, that sink will be silently skipped and no logs will be sent to it.

Notes:

This documentation is designed to make the configuration more comprehensible and guide you in making necessary adjustments where needed. It includes explanations of what each setting is for and important considerations when making changes.

8. Logging Details

Logged Activities

  • API Requests: Every incoming HTTP request is intercepted and logged by the ActivityMiddleware.
  • Authentication: Specialized logging occurs for auth/token endpoints to track token generation (masked for security).

Logged Data Fields

  • Ip: Client IP address.
  • HttpMethod: The HTTP verb (GET, POST, etc.).
  • EndPoint: The request URL path (e.g., /identity/users).
  • Method: The controller action display name.
  • AuthenticationType: Typically "Bearer".
  • ClientIdentifier: Extracted from the route parameters if present.
  • UserId: Extracted from the JWT token userId claim.
  • StatusCode: The HTTP response status code (e.g., 200, 400).
  • ExecutionTimeMs: Total duration of the request processing in milliseconds.

Note: Request and Response bodies are disabled by default to protect sensitive identity data and optimize memory.