Authorization Service
The Authorization service hosts the Access Control Resources (ACR) for every ESS Pod resource and is responsible for managing/enforcing the Access Control Policies (ACP).
Authorization Service Endpoint
By default, the ESS Authorization Service runs from the following root URL:
https://authorization.<ESS Domain>
To change the root Authorization service URL, see INRUPT_AUTHORIZATION_BASE_URL
Authorization Service and Initial ACP Policies
When a Pod is created, like any other Pod resource, an ACR is also created for the Pod Root. The ACR is initialized with the default ACP policies for the Pod Owner and for Access Grant enablement:
Initial Pod Owner policies give the Pod Owner read and write access to the Pod. These policies also specify a client matcher as well if the Authorization Service’s configuration for the initial client allow list is set:
INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST
or if that is unset,
Using the value of the Pod owner’s WebID and an initial client allow list, ESS creates the initial policies of the form:
If allOf(AgentMatcher and ClientMatcher) evaluates to true, Then allow (Read and Write).
Specifically, ESS creates:
Policy 1 for the Pod Root: If the agent matches the Pod owner’s WebID, and if the client application’s Client ID has a match in the initial client allow list, allow Read and Write access.
Policy 2 for the Pod Root’s Initial Member Policies: If the agent matches the Pod owner’s WebID, and if the client application’s Client ID has a match in the initial client allow list, allow Read and Write access.
For more information on a Container’s Member Policies, see Member Policies
Disambiguation
Both Authorization Service and Pod Storage Service have a INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST
setting.
Only the Authorization Service setting affects which clients are allowed. The Pod Storage Service is for Discovery purposes only.
Initial Access Grant Enablement policies allow the use of Access Grants that grant read/write/append access to the Pod resources.
If allOf(VC Matcher) evaluates to true, Then allow (Read and Write and Append).
Specifically, ESS creates: Policy 3 for the Pod Root:If a presented VC matches the specified type, allow its use for
Read
,Write
, andAppend
access. Policy 4 for the Pod Root’s Initial Member Policies: If a presented VC matches the specified type, allow its use forRead
,Write
, andAppend
access. See alsoINRUPT_AUTHORIZATION_DEFAULT_ACR_ACCESS_GRANTS_ALLOWED_MODES
.
Important
The policies only enable the use of Access Grants for the allowed access modes. To determine the access for an agent using an access grant, ESS uses the intersection of:
The allowed access specified by the policy, and
The granted access specified in the Access Grant (for the resource specified in the Access Grant).
Configuration
As part of the installation process, Inrupt provides base Kustomize overlays and associated files that require deployment-specific configuration inputs.
The following configuration options are available for the service and may be set as part of updating the inputs for your deployment . The Inrupt-provided base Kustomize overlays may be using updated configuration values that differ from the default values.
Required
INRUPT_AUTHORIZATION_BASE_URL
The URI of the Authorization service.
INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST
Default: https://inrupt.com
Comma-delimited list of Client IDs that determine which applications are allowed to perform read and write operations on the Access Control Resources.
In addition, the authorization server uses INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST
to initialize the default access policies for a new Pod if INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST
is unset.
Important
The Authorization Service’s INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST
value must be managed with care. Only those applications with a high level of trust should be listed. This value should never be set to an empty list so the default value has been set to https://inrupt.com
to prevent this happening by mistake. It must be replaced during deployment.
See also:
INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST
configuration for the Pod service.
Kafka Configuration
INRUPT_KAFKA_AUDITV1EVENTSENCRYPTED_CIPHER_PASSWORD
The strong cipher key to use when running auditing with encrypted messages over the auditv1eventsencrypted
topic.
INRUPT_KAFKA_AUDITV1EVENTSPRODUCERENCRYPTED_CIPHER_PASSWORD
The strong cipher key to use when running auditing with encrypted messages over the auditv1eventsproducerencrypted
topic.
INRUPT_KAFKA_SOLIDACCESSCONTROLRESOURCE_CIPHER_PASSWORD
The symmetric key to use when encrypting messages (see MP_MESSAGING_OUTGOING_SOLIDACCESSCONTROLRESOURCE_VALUE_SERIALIZER
).
Warning Set to a strong password.
KAFKA_BOOTSTRAP_SERVERS
Default : localhost:9092
Comma-delimited list of Kafka broker servers for use by ESS services, including this service.
Setting KAFKA_BOOTSTRAP_SERVERS
configures ESS to use the same Kafka instances for all its Kafka message channels (e.g., solidresource
and auditv1out
message channels). This service uses the solidaccesscontrolresource
and auditv1out
message channels.
MP_MESSAGING_OUTGOING_SOLIDACCESSCONTROLRESOURCE_VALUE_SERIALIZER
Default : org.apache.kafka.common.serialization.StringSerializer
The serializer used for the notification messages the service sends to Kafka.
Supported values are:
org.apache.kafka.common.serialization.StringSerializer
When set to this value, notification messages sent to Kafka are unencrypted. Services that consume these messages will need to set theirMP_MESSAGING_INCOMING_SOLIDACCESSCONTROLRESOURCE_VALUE_DESERIALIZER
to the corresponding deserializer valueorg.apache.kafka.common.serialization.StringDeserializer
.com.inrupt.components.kafka.encryption.EncryptMessageSerializer
When set to this value, notification messages sent to Kafka are encrypted. Services that consume these encrypted messages will need to set theirMP_MESSAGING_INCOMING_SOLIDACCESSCONTROLRESOURCE_VALUE_DESERIALIZER
configuration to the corresponding deserializer valuecom.inrupt.components.kafka.encryption.DecryptMessageDeserializer
.
Optional
Configuration Logging
ESS services log their startup configuration.
INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW
Default : inrupt,mp.messaging
A comma-separated list of configuration property prefixes (case-sensitive) that determine which configurations are logged:
If the list is empty, NO configuration property is logged.
If a configuration property starts with a listed prefix ( case-sensitive ), the configuration property and its value are logged unless the configuration also matches a prefix in
INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY
(which acts as a filter onINRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW
list). As such, if the configuration matches prefix in bothINRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW
andINRUPT_LOGGING_CONFIGURATION_PREFIX_DENY
, theINRUPT_LOGGING_CONFIGURATION_PREFIX_DENY
takes precedence and the configuration is not logged. For example, ifinrupt.
is an allow prefix, butinrupt.kafka.
is a deny prefix, all configurations that start withinrupt.kafka.
are excluded from the logs.
When specifying the prefixes, you can specify the prefixes using one of two formats:
using dot notation (e.g.,
inrupt.foobar.
), orusing the MicroProfile Config environmental variables conversion value (e.g.,
INRUPT_FOOBAR_
).
Warning
Use the same format for both INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW
and INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY
.
For example, if you change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW
, change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY
as well.
INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY
Default : inrupt.kafka
A comma-separated list of configuration name prefixes (case-sensitive) that determines which configurations (that would otherwise match the INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW
) are not logged. That is, INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY
acts as a filter on INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW
. For example:
If
foobar.
is an allowed prefix, to suppressfoobar.private.<anything>
, you can specifyfoobar.private.
to the deny list.If
foobar.
is not an allowed prefix, no property starting withfoobar.
is logged. As such, you do not need to specifyfoobar.private
to the deny list.When specifying the prefixes, you can specify the prefixes using one of two formats:
using dot notation (e.g.,
inrupt.foobar.
), orusing the MicroProfile Config environmental variables conversion value (e.g.,
INRUPT_FOOBAR_
).
Warning
Use the same format for both INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW
and INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY
.
For example, if you change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW
, change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY
as well.
INRUPT_LOGGING_REDACTION_NAME_ACTION
Default : REPLACE
Type of the redaction to perform. Supported values are:
REPLACE
Default. Replaces the matching text with a specified replacement.
PLAIN
Leaves the matching field unprocessed. Only available if the redaction target is a field (i.e.,INRUPT_LOGGING_REDACTION_{NAME}_FIELD
).
DROP
Suppresses the matching field. Only available if the redaction target is a field (i.e.,INRUPT_LOGGING_REDACTION_{NAME}_FIELD
).
PRIORITIZE
Changes the log level of the matching message.
SHA256
Replaces the matching text with its hash.
If the action is
REPLACE
( default ), see alsoINRUPT_LOGGING_REDACTION_{NAME}_REPLACEMENT
.If the action is to
PRIORITIZE
, see alsoINRUPT_LOGGING_REDACTION_{NAME}_LEVEL
.
For more information on log redaction, see Logging Redaction
INRUPT_LOGGING_REDACTION_NAME_ENABLED
Default : true
A boolean that determines whether the redaction configurations with the specified INRUPT_LOGGING_REDACTION_{NAME}_
prefix is enabled.
For more information on log redaction, see Logging Redaction
INRUPT_LOGGING_REDACTION_NAME_EXCEPTION
Fully qualified name of the exception class to match in the log messages (includes inner exception). Configure to target an exception message class.
For more information on log redaction, see Logging Redaction
INRUPT_LOGGING_REDACTION_NAME_FIELD
Exact name of the field to match in the log messages. Configure to target a specific log message field for redaction.
For more information on log redaction, see Logging Redaction
INRUPT_LOGGING_REDACTION_NAME_PATTERN
A regex (see Java regex pattern) to match in the log messages. Configure to target log message text that matches a specified pattern.
For more information on log redaction, see Logging Redaction
INRUPT_LOGGING_REDACTION_NAME_REPLACEMENT
Replacement text to use if the INRUPT_LOGGING_REDACTION_{NAME}_ACTION
is REPLACE
.
If unspecified, defaults to REDACTED
.
For more information on log redaction, see Logging Redaction
Application-Defined Metadata Propagation
INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_ALLOW
A comma-separated list of application-defined properties that can be included in the associated audit events (unless specified in the corresponding INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_DENY
).
This configuration is case-sensitive to the propagated properties in the baggage.
See:
Manage Application-Defined Metadata Propagation to configure.
Application-Defined Metadata for more information.
INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_DENY
A comma-separated list of application-defined properties to exclude from the associated audit messages. This setting takes precedence over INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_ALLOW
.
This configuration is case-sensitive to the propagated properties in the baggage.
See:
Manage Application-Defined Metadata Propagation to configure.
Application-Defined Metadata for more information.
INRUPT_LOGGING_REQUEST_METADATA_ALLOW
A comma-separated list of application-defined properties that can be included in the associated log messages (unless specified in the corresponding INRUPT_LOGGING_REQUEST_METADATA_DENY
) .
This configuration is case-sensitive to the propagated properties in the baggage.
See:
Manage Application-Defined Metadata Propagation to configure.
Application-Defined Metadata for more information.
INRUPT_LOGGING_REQUEST_METADATA_DENY
A comma-separated list of application-defined properties to exclude from the associated log messages. This setting takes precedence over INRUPT_LOGGING_REQUEST_METADATA_ALLOW
.
This configuration is case-sensitive to the propagated properties in the baggage.
See:
Manage Application-Defined Metadata Propagation to configure.
Application-Defined Metadata for more information.
INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW
A comma-separated list of non-baggage request headers to add to the baggage (unless specified in the corresponding INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_DENY
); i.e., include these non-baggage request headers as application-defined properties.
The configuration is case-insensitive; i.e., the listed headers do not need to match the case of the client request headers. For example, a list that includes x-correlation-id
can match x-correlation-id
header, X-CoRrElAtIoN-Id
header, etc.
See:
Manage Application-Defined Metadata Propagation to configure.
Application-Defined Metadata for more information.
INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_DENY
A comma-separated list of non-baggage request headers to exclude from being added to the baggage; i.e., excludes these headers as application-defined properties. This setting takes precedence over INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW
.
The configuration is case-insensitive; i.e., the listed headers do not need to match the case of the client request headers. For example, a list that includes x-correlation-id
can match (and exclude) x-correlation-id
header, X-CoRrElAtIoN-Id
header, etc.
See:
Manage Application-Defined Metadata Propagation to configure.
Application-Defined Metadata for more information.
INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_OVERRIDES
A flag that determines ESS behavior when metadata property is defined both as a header and as a baggage entry:
If
true
ESS updates/overrides the baggage entry with the header value.If
false
(the default), ESS keeps the baggage entry.
For details, Duplicate Property Definition
INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_ALLOW
A comma-separated list of application-defined properties that can return as response headers (unless specified in the corresponding INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_DENY
) .
This configuration is case-sensitive to the propagated properties in the baggage.
See:
Manage Application-Defined Metadata Propagation to configure.
Application-Defined Metadata for more information.
INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_DENY
A comma-separated list of application-defined properties to exclude from returning as response headers. This setting takes precedence over INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_ALLOW
.
This configuration is case-sensitive to the propagated properties in the baggage.
See:
Manage Application-Defined Metadata Propagation to configure.
Application-Defined Metadata for more information.
Purge Configuration
The Authorization service contains user data, and as such it can be purged upon user request. See the Purger documentation for more information about the data being purged.
INRUPT_PURGE_BATCH_SIZ
Default : 100
The maximum number of access control records that the purge task will purge in each batch. This must be a non-zero, positive integer.
INRUPT_PURGE_CLEANUP_TASK_EVERY
Default : PT5H
Frequency at which a task goes through stored purge statuses to clear any which are beyond their retention window.
INRUPT_PURGE_IN_PROGRESS_TIMEOUT_SECONDS
Default : 120
Timeout after which an ongoing purge task is considered stale. Stale tasks are picked up by an ESS background process to be taken to completion. By keeping track of a purge task’s state (active or stale) the service can ensure that a purge which was started will eventually reach completion, even if the system is disrupted whilst the asynchronous purge process is ongoing.
INRUPT_PURGE_PROCESS_TASK_EVERY
Default : PT5M
Frequency at which an ESS background process goes through ongoing purges to pick up the incomplete stale ones. See INRUPT_PURGE_IN_PROGRESS_TIMEOUT_SECONDS
for additional details.
INRUPT_PURGE_STATUS_RETENTION_WINDOW
Default : P2D
Duration after which a purge task status will be cleared from storage. The purge task contains some Personally Identifying Data (such as the WebID), so ensuring it is cleared after a purge is required for compliance.
General
INRUPT_AUTHORIZATION_DEFAULT_ACR_ACCESS_GRANTS_ALLOWED_MODES
Default : read,write,append
Comma-delimited list of actions allowed when using Access Grants. This configuration is used to initialize the default access policies (specifically, the policy enabling the use of Access Grants) during Pod creation.
See also Enable Access Grant Usage (ACP)
INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST
Default :
Comma-delimited list of Client IDs used to initialize the default access policies (specifically, the client matchers) during Pod creation.
If INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST
is unset, the service uses the INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST
to initialize the policies.
Important
The option only takes effect during Pod creation. Changes to INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST
(or INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST
) has no impact on existing Pods.
To configure, see Set Initial Pod Clients Allow List
INRUPT_AUTHORIZATION_MAX_POD_COUNT
Default : 10
The maximum number of Pods owned by a specific WebID.
Important
The INRUPT_AUTHORIZATION_MAX_POD_COUNT
value must equal Pod Provisioning Services' INRUPT_STORAGE_MAX_PODS_PER_OWNER
value. When changing the INRUPT_AUTHORIZATION_MAX_POD_COUNT
value, ensure you also update INRUPT_STORAGE_MAX_PODS_PER_OWNER
to the same value.
INRUPT_JWT_ALLOWED_SIGNATURE_ALGORITHMS
Default : ES256
,
A comma-separated list that specifies the allowed encryption algorithms used to sign ID tokens.
INRUPT_JWT_ISSUER_ALLOW_LIST
A comma-separated list of trusted Solid-OIDC issuers (i.e., identity providers).
If unset, the service accepts all Solid-OIDC issuers with the exception of those in the
INRUPT_JWT_ISSUER_DENY_LIST
If set, the service accepts only those Solid-OIDC issuers in the list with the following exception:
If an issuer is in both
INRUPT_JWT_ISSUER_ALLOW_LIST
andINRUPT_JWT_ISSUER_DENY_LIST
, theINRUPT_JWT_ISSUER_DENY_LIST
supersedes theINRUPT_JWT_ISSUER_ALLOW_LIST
and the issuer is not accepted by ESS.
See also INRUPT_JWT_ISSUER_DENY_LIST
.
INRUPT_JWT_ISSUER_DENY_LIST
A comma-separated list of disallowed Solid-OIDC issuers.
If unset, the service accepts all Solid-OIDC issuers unless
INRUPT_JWT_ISSUER_ALLOW_LIST
is set, in which case, the service only accepts those in theINRUPT_JWT_ISSUER_ALLOW_LIST
.If set, the service disallows the Solid-OIDC issuers in the list. If
INRUPT_JWT_ISSUER_ALLOW_LIST
is also set, issuers not in theINRUPT_JWT_ISSUER_ALLOW_LIST
are also disallowed.
QUARKUS_GRPC_SERVER_PORT
The gRPC port of the Authorization Server.
QUARKUS_GRPC_SERVER_SSL_CERTIFICATE
Path to the server TLS/SSL certificate.
QUARKUS_GRPC_SERVER_SSL_KEY
Path to a server TLS/SSL certificate key file.
QUARKUS_GRPC_SERVER_SSL_TRUST_STORE
Trust store file to use.
QUARKUS_GRPC_SERVER_SSL_TRUST_STORE_PASSWORD
Password of the trust store file.
QUARKUS_LOG_LEVEL
Default : INFO
Logging level.
Additional Information
See also Quarkus Configuration Options
Last updated