skilja/authorizationservice repository overview

⁠Quick reference

• Maintained by:
  Skilja GmbH⁠

• Where to get help:
  The Partner Portal⁠ or via email [email protected]⁠⁠

⁠Supported tags and Versioning

The container uses the following pattern for different versions:

• <major>.<minor>.<patch>.<revision> points to a specific version
• <major>.<minor>.<patch> points to a specific patch level
• <major>.<minor> always points to the newest patch level, and is guaranteed to be compatible with all previous containers of the same <major>.<minor> version.
• latest points to the latest version that exists. It may not be compatible with the current database if the major or minor version changes, and also can require additional setup or migration steps.

For easily getting the latest security and bug fixes, we recommend to pull a <major>.<minor> version, for example:
docker pull skilja/authorizationservice:4.0

Images that host a .NET service are based on mcr.microsoft.com/dotnet/aspnet:8.0. All images can run as root-less containers.

The most recent images are :

• 4.0.2⁠

⁠What is the Authorization Server?

The Skilja Authorization Server allows you to achieve single sign-on (SSO) for Vinna, its components, external clients and the Tegra⁠ products⁠.

The following samples won´t explain the product in full. If you are not familiar with terms like IDP or certificates please check the Partner Portal⁠ for the full documentation.

⁠How to use this image

The following sample shows how to run the Authorization Server with a minimum of configuration: (No statistics, no reverse proxy, no full fledged database)

1. Create the envfile.txt with the needed environment variables and accept the EULA

# to accept the EULA, set this to y
ACCEPT_EULA=n
AS_ConnectionStrings__sqlite=Data Source=/data/auth.db
AS_Service__DatabaseProvider=sqlite
AS_Service__AutomaticDatabaseMigration=true
AS_Service__AllowRestarts=true
AS_Service__AuthCertificates__Style=persisted
AS_Service__AuthCertificates__Autocreate=true
AS_Service__AuthCertificates__AutocreatedCertificateNotAfterDays= 20000
AS_Service__AuthCertificates__EncryptionCertificates__0__Path=/data/oidc_enc_cert
AS_Service__AuthCertificates__SigningCertificates__0__Path=/data/oidc_sign_cert
AS_Service__DataProtection__PersistKeysInDatabase=true
AS_Service__DataProtection__Autocreate=true
AS_Service__DataProtection__AutocreatedCertificateNotAfterDays= 20000
AS_Service__DataProtection__ProtectKeysFile=/data/data_protection_cert

2. Pull and start the Authorization Server:
Ensure that your mapped path has enough rights.

docker pull skilja/authorizationservice 
docker run -p 8080:8080 -v ./_data:/data -d --env-file envfile.txt skilja/authorizationservice

3.Now connect to the WebUI (http://localhost:8080⁠), login with the temp user and setup your IDP. In order to have a secure auth code flow you should also configure a reverse proxy that takes care of SSL/TLS.
For more information about the temporary user visit the Environment Variables section External Identity Provider⁠ below

⁠... via [docker-compose] (extended setup with reverse proxy )

Example docker-compose.yml for skilja/authorizationservice:

# This docker compose sample must be adjusted.For example, any external hostnames that are not found via docker's DNS must be explicitly added to the docker container's DNS. Here, we set the {{authserver}}s URL `auth.contoso.com` to the IP `172.22.32.1`. The mounted volumes paths can be adjusted for your environment. Finally, all .env files and the config.json files for the websites must be adjusted for your environment.

# This example uses traefik (https://traefik.io/traefik/) as a load balancer.
# Experience with traefik is recommended should you chose to use this sample as is.
# However, other load balancers can be used as well.

# The shown traefik setup requires the following additional configuration files : traefik.yml, tls.yml and your SSL certificate.

# If you have already a reverse proxy running or want to configure the reverse proxy via it´s Web UI, please remove everything traefik related.

services:
  traefik:
    image: traefik:v3.2
    ports:
      # - "8080:80"
      # - "8081:443"
      - "8100:8100" # the http endpoint
      - "8200:8200" # the https endpoint - and the port under that auth.docker.localhost is reachable
      - "8080:8080"  # Traefik dashboard
    command:
      - "--configFile=/etc/traefik/traefik.yml" # static config file
    volumes:
      - type: bind
        source: ./traefik.yml
        target: /traefik.yml
      - /var/run/docker.sock:/var/run/docker.sock
      - ./certs:/etc/traefik/certs # ssl certificates
      - ./traefik:/config # dynamic config files

  auth:
    image: skilja/authorizationservice:4.0
    deploy:
      replicas: 1
    ports:
      - 8080
    labels:
      - traefik.enable=true
      - traefik.http.routers.dt.rule=Host(`auth.docker.localhost`) # routes requests to host auth.docker.localhost to this image
      # The next line routes requests to host+path docker.localhost/auth/* to this image - Ensure AS_Service__PathBase is configured correctly
      # - traefik.http.routers.auth.rule=Host(`docker.localhost`) && PathPrefix(`/auth`)
      - traefik.http.routers.dt.tls=true # we want this service only reachable via https (traefik does SSL offloading)
      - traefik.http.routers.dt.entrypoints=websecure # we bind to the websecure port
      - traefik.http.services.auth.loadbalancer.server.port=8080 # this could be omitted if we have only 1 open port
    environment:
      ACCEPT_EULA: n # to accept the EULA, set this to y
      # AS_Service__PathBase: /auth # uncomment this line if the reverse proxy routes requests to ~:8080/auth instead of ~:8080/
      AS_ConnectionStrings__sqlite: "Data Source=/data/auth.db"
      AS_Service__DatabaseProvider: "sqlite"
      AS_Service__AutomaticDatabaseMigration: true
      AS_Service__AllowRestarts: true
      AS_Service__AuthCertificates__Style: "persisted"
      AS_Service__AuthCertificates__Autocreate: true
      AS_Service__AuthCertificates__AutocreatedCertificateNotAfterDays: 20000
      AS_Service__AuthCertificates__EncryptionCertificates__0__Path: /data/oidc_enc_cert
      AS_Service__AuthCertificates__SigningCertificates__0__Path: /data/oidc_sign_cert
      AS_Service__DataProtection__PersistKeysInDatabase: true
      AS_Service__DataProtection__Autocreate: true
      AS_Service__DataProtection__AutocreatedCertificateNotAfterDays: 20000
      AS_Service__DataProtection__ProtectKeysFile: /data/data_protection_cert
    volumes:
      - ./_data:/data
    extra_hosts:
      - "dbServer:172.22.32.1"

Run docker compose up, wait for it to initialize completely, and visit auth.docker.localhost ( your configured URL) to check if everything is running.

⁠Environment Variables

The Authorization Server image uses several environment variables, of which some are required others are optional. The following environment variables are provided.

All Skilja containers require accepting the End User license agreement (EULA)⁠ .

• ACCEPT_EULA:
  Set to y to accept the End User License Agreement.
• AS_Service__DisableHttpsRequirement:
  Is set to false in the docker container by default. If you explicitly want to require HTTPS, then set this to true.
• AS_Service_PathBase: When the container is hosted behind a load balancer and is reached on a sub path like https://my.server.com/auth, you have to specify the path base to /auth. The container always hosts its application directly on the port :8080, and does not know that /auth belongs to its URL. The leading slash on the path base is required.

⁠Logging Configuration

The Authorization Server writes logs to the standard output and/or to a log file. Log files are rotated each day and after they 4MB. For both outputs you can decide if you want a human readable format (unstructured), or structured logs in Compact Log Event Format (CLEF)⁠. More logging configuration options are in the documentation on the Partner Portal⁠.

• AS_Serilog__LevelSwitches__controlSwitch:
  Default log level:
  Information
• AS_Service__Logging__FileFormatsCompactJson:
  Use compact JSON format for file logging. This is useful if you use other logging providers and feed them with docker's console output:
  false
• AS_Service__Logging__HttpRequestLoggingIncludesQuery:
  Include query parameters in HTTP request logging. Note that this can include sensitive data:
  false

⁠Reverse Proxy Configuration

Proxy'ing works by default. Options for fine tuning are in the documentation on the Partner Portal⁠.

⁠Database Connection

The database can either be initialized automatically upon container startup, or via the use of the database scripts.

• AS_Service__AutomaticDatabaseMigration:
  Automatically migrates the configured database if set to true.
• AS_ConnectionStrings__mssql:
  Connection string for an MSSQL database: Data Source=localhost;Initial Catalog=auth;Integrated Security=True;DatabaseSchema=dbo
• AS_ConnectionStrings__postgresql:
  Connection string for a PostgreSQL database: Server=127.0.0.1;Port=5432;Database=auth;Userid=postgres;Password=postgres;Pooling=false;MinPoolSize=1;MaxPoolSize=20;Timeout=15;SslMode=Disable;
• AS_ConnectionStrings__oracle:
  Connection string for an Oracle database: Data Source=localhost:1521/orcl.docker.internal;User Id=\"C##auth_user\";Password=password
• AS_Service__DatabaseProvider:
  Supported database provider:
  mssql, postgresql, oracle

⁠OIDC Certificates

These certificates are required for the Authorization Server's OIDC features. Signing certificates are used to protect against tampering. For example, ID-tokens are signed with this certificate. Encryption certificates are used to ensure that the content of tokens cannot be read by malicious parties.

We recommend that you let the container create these certificates automatically. Alternatively, you have to create appropriate certificates with the appropriate key usage flags for data encipherment and digital signatures.

• AS_Service__AuthCertificates__Style: Set to Persisted to use locally stored certificates for signing and encrypting authentication tickets and identity tokens. Without Persisted, multiple instances of the Authorization Server are not supported. Can be set to Ephemeral for temporary and non-scaled deployments.
• AS_Service__AuthCertificates__Autocreate: If set to true and the provided certificate files do not exist, pfx certificates are automatically created. Ensure that the directory is writable when you mount it via volume.
• AS_Service__AuthCertificates__AutocreatedCertificateNotAfterDays: The expiration date that is set for automatically generated certificates. Set it to a large value, for example, 20000, if you do not care for certificate rotation. If you want to use more complex certificate rotation, set it to a lower value and ensure you update the environment variables periodically.
• AS_Service__AuthCertificates__EncryptionCertificates__0__Path: The path of the encryption certificate file, used for encrypting authentication tickets. We suggest to mount volumes to /data, so that /data/oidc_enc_cert is a reasonable value.
• AS_Service__AuthCertificates__EncryptionCertificates__0__Password: The password used for the pfx certificate
• AS_Service__AuthCertificates__SigningCertificates__0__Path: The path of the signing certificate file, used for signing identity tokens. We suggest to mount volumes to /data, so that /data/oidc_sign_cert is a reasonable value.
• AS_Service__AuthCertificates__SigningCertificates__0__Password: The password used for the pfx certificate

In case you use certificate rotation, you must add the old and expired certificates to the EncryptionCertificates and SingingCertificates as well. Use __1__, __2__, and so forth for additional certificate elements in the list.

⁠Data Protection Certificates

Sensitive information, like client secrets or identity provider configurations are encrypted at rest. These certificates are used to create the keys that encrypt such data.

We recommend to let the container automatically create these certificates for you. Ensure that you back them up after creation, since you cannot access encrypted data without them. Alternatively, you can provide those certificates yourself.

• AS_Service__DataProtection__PersistKeysInDatabase:
  If you want to scale the Authorization Server, you must set this to true. In that case, symmetric keys for encryption are stored in the database (encrypted at rest).
• AS_Service__DataProtection__Autocreate:
  If set to true and the provided certificate file does not exist, a pfx certificate is automatically created. Ensure that the directory is writable when you mount it via volume.
• AS_Service__DataProtection__AutocreatedCertificateNotAfterDays:
  The expiration date that is set for automatically generated certificates. Set it to a large value, for example, 20000, if you do not care for certificate rotation. If you want to use more complex certificate rotation, set it to a lower value and ensure you update the environment variables periodically.
• AS_Service__DataProtection__ProtectKeysFile:
  The path of the certificate used to encrypt the symmetric keys that are used for data protection. We suggest to mount volumes to /data, so that /data/data_protection_cert is a reasonable value.
• AS_Service__DataProtection__ProtectKeysPassword:
  The password used for the ProtectKeysFile pfx certificate
• AS_Service__DataProtection__UnprotectionCertificates__0__Path:
  For certificate rotation, specify the previous certificate's location here
• AS_Service__DataProtection__UnprotectionCertificates__0__Password:
  For certificate rotation, specify the previous certificate's password here
• AS_Service__DataProtection__UnprotectionCertificates__1__Path:
  For certificate rotation, specify the previous certificate's location here
• AS_Service__DataProtection__UnprotectionCertificates__1__Password:
  For certificate rotation, specify the previous certificate's password here

In case you use certificate rotation, you must add the old and expired certificates to the UnprotectionCertificates. Use __1__, __2__, and so forth for additional certificate elements in the list.

⁠External Identity Provider

A docker container must use an external identity provider such as EntraID, Keycloak, or any other provider that supports OIDC. You cannot use LDAP or NTLM/Kerberos authentication for user logins. An example configuration for the identity provider configuration is documented here⁠. the Partner Portal⁠

To configure a docker setup initially, you can either user a setup-user login or provide a configuration file. If no external IDP configuration is provided, any user logging in with password 1234 is administrator and able to configure the service. You can also provide a IDP configuration file, that immediately sets up the external IDP:

• AS_Service__AuthenticationProviderSource__Filepath:
  The path of the identity provider settings file.

Please read section Identity Provider Configuration Settings⁠ for an example configuration file.

⁠Admin Client Creation

If an admin client is required by other software installations, one can be automatically created when starting a new Docker container (container that has no other clients defined yet). Other software installations require the admin client if they automatically register their clients without user interaction. To trigger automatic creation, you must set the following environment variables:

• AS_Service__CreateAdminClientID:
  Admin client ID
• AS_Service__CreateAdminClientSecret:
  Admin client secret

⁠Metrics Configuration

The Authorization Servers support sending metrics to an Open Telemetry⁠ collector. The metrics can then be collected by Prometheus, and displayed with Grafana. Other metrics tools are also available for this - the service is agnostic to what is being used.

• AS_Service__Metrics__OtlpEndpoint: "http://otel-collector:4317" If you want to export metrics to the OpenTelemetry collector, you must specify the OpenTelemetry collector endpoint
• AS_Service__Metrics__AspNetCoreMetricsEnabled: "true" If set to true, ASP.NET Core metrics are exported to the OpenTelemetry collector. Currently, these are the only supported metrics.

⁠Folders

We recommend to mount a data volume to /data for providing files to the Authorization Server , or to provide a location to create certificates into.

⁠Handling Secrets

In a container environment, secrets are not encrypted anymore. Instead, they are stored verbatim in a text file that can only be accessed by those that may read it. To use a secret for a configuration setting in the services, store the configuration setting's value in a file. The file is then added as a secret to the docker compose file.

To set a configuration setting to the file content, the file must be mounted as AS_SECRETS_<configuration setting>. For example, connection string can be defined with file AS_SECRETS_ConnectionStrings__mssql. The services expect that the files are mounted by the container manager to /run/secrets/<filename>. Secrets that are mounted elsewhere are not found.

Settings where secrets can be helpful:

• ConnectionStrings__<database provider>
• Service__AuthCertificates__EncryptionCertificates__<index>__Password
• Service__AuthCertificates__SigningCertificates__<index>__Password
• Service__DataProtection__ProtectKeysPassword
• Service__DataProtection__UnprotectionCertificates__<index>__Password

⁠Identity Provider Configuration Settings Documentation

The IDP can be configured via Web UI or JSON. Since we are limited in text length here, please refer to the 'Identity Provider Configuration Settings Documentation' within the Authorization Server Installation Guide. Obtainable at the Partner Portal⁠

This documentation explains all settings used in the sample JSON configuration. An example JSON with explanations⁠ is at the end of this section.

On docker or Linux systems, the username and password dialog is always disabled. Currently, Windows logins or LDAP are not supported.

⁠Top-Level Properties

• defaultProvider (string)
  Specifies the default authentication provider to use. When set, authentication challenges automatically redirect to this provider.
• providers (array)
  A list of identity providers configured for authentication. Each provider in the list should follow the IdentityProvider structure (detailed below).
• discoveryIntervalSeconds (integer)
  Defines how often backend services check for new roles. Default value is 1800 seconds (30 minutes).
• autoCollect (boolean)
  Indicates whether roles should be automatically collected from any authenticated external identity provider. Default is true.

⁠Provider-Level Properties (IdentityProvider)

Each provider in the providers array represents an external identity provider (IDP) and includes the following properties:

• isEnabled (boolean)
  Indicates whether the identity provider is enabled. Defaults to true. If you specify multiple providers, all but 1 must be set to "isEnabled": false.
• name (string)
  The name of the identity provider, e.g., EntraID.
• authority (string)
  The URL of the external authority for authentication, e.g., https://login.microsoftonline.com/....
• metadataAddress (string, nullable)
  The discovery endpoint URL for OpenID Connect configuration. If not provided, defaults to authority/.well-known/openid-configuration.
• roleDiscoveryUrl (string, nullable)
  Used to discover roles from the external identity provider. Defaults are known for specific IDP types, such as EntraID.
• disableAutomaticRoleDisovery (boolean)
  Disables automatic fetching of roles from this provider. Defaults to false.
• idpType (IdpType enum)
  Specifies the type of the identity provider. Valid values include:
  • EntraID for Microsoft Azure's identity platform.
  • Keycloak for the Keycloak IAM solution.
  • Custom for other OpenID Connect-compatible providers.
• clientId (string)
  The client ID used to authenticate with the external provider.
• clientSecret (string)
  The client secret used to authenticate with the external provider.
• requireHttpsMetadata (boolean)
  Indicates whether HTTPS is required for metadata endpoints. Defaults to false.
• nameClaimType (string)
  The claim type used to identify the user's name. Default is name.
• roleClaimType (string)
  The claim type used to identify user roles. Default is roles.
• usernameClaimType (string)
  The claim type used for the username, uniquely identifying the user. Default is preferred_username.
• getClaimsFromUserInfoEndpoint (boolean)
  Determines whether to fetch additional claims from the user info endpoint after authentication. Defaults to true.
• scopes (array of strings)
  Specifies the scopes to request during authentication. If not set, defaults to openid and profile. Example: ["profile"].

⁠Claim Mapping (ClaimMappings)

Defines custom claim mappings for specific users or groups.

• mappings (array of TargetMap)
  An array of mappings that transform source claims into target claims. Each mapping consists of:
  • sourceType (string)
    The type of the source claim (e.g., preferred_username). Defaults to the provider’s role claim type if empty.
  • sourceValues (array of strings)
    A list of specific claim values to match (e.g., ["[email protected]"]).
  • targetType (string)
    The type of the target claim (e.g., roles). Defaults to the provider’s role claim type if empty.
  • targetValue (string)
    The value assigned to the target claim (e.g., administrator).

⁠Example JSON with Explanations

{
  "discoveryIntervalSeconds": 1800,
  "autoCollect": true,
  "providers": [
    {
      "isEnabled": true,
      "name": "EntraID",
      "authority": "https://login.microsoftonline.com/9ea0740e-56b9-47b8-8770-ff323817e219/v2.0/",
      "metadataAddress": null,
      "roleDiscoveryUrl": null,
      "disableAutomaticRoleDisovery": false,
      "idpType": "EntraID",
      "clientId": "cf848065-5123-4466-901c-719567baf0f5",
      "clientSecret": "a4c49b37-c5d6-4fcf-bc11-7489f3340e78",
      "requireHttpsMetadata": false,
      "nameClaimType": "name",
      "roleClaimType": "roles",
      "usernameClaimType": "preferred_username",
      "getClaimsFromUserInfoEndpoint": true,
      "scopes": ["profile"],
      "claimMap": {
        "mappings": [
          {
            "sourceType": "preferred_username",
            "sourceValues": ["[email protected]"],
            "targetType": "",
            "targetValue": "administrator"
          }
        ]
      }
    }
  ]
}

• isEnabled: Only 1 provider may be enabled at the same time. Must be set to true on 1 provider.
• providers: Contains a single provider configuration for EntraID.
  Most important are the properties authority, clientId, and clientSecret.
  A mapping is required unless you assign the role administrator to at least one user.
• scopes: Limited to profile to reduce requested claims.
• claimMap: Maps specific usernames to the administrator role.