Skip to content

Authentication Policy

During the interactions with the Arrowhead Core and Support systems, all clients are required to prove their identity by providing appropriate identity info. The authentication can be done based on the given identity info.

Three authentication policies are offered: declared, certificate and outsourced.

The actual policy in force is depending on how the Core and Support systems are configured. See the authentication.policy configuration property under the general configurations.

Policies

declared

Applying the declared authentication policy results in no real identity verification taking place. The Core and Supports systems simply accept the identity provided by the application systems. This policy is not recommended for use in production environment.

Applicable to HTTP and MQTT interface protocols.

certificate

Applying the certificate authentication policy results in requiring client side system profile certificate being provided by the application systems. The issuer and the identity related content of the certificate are always verified during every interaction with the Arrowhead Core and Support systems.

Applicable to HTTP and MQTT interface protocols.

outsourced

Applying the outsourced authentication policy results in requiring the identity service being provided by a Core/Support system within the Local Cloud. This dedicated system can be the offical Authentication Core System or any third party solution that implements this service.

The actual credentials required to be authenticated and to join the Local Cloud always depend on the actual authentication method behind the identity service, but the outcome is always an identity token (and optionally an expiration time) that the authenticated system is required to use to prove its own identity when interacting with the Arrowhead Core and Support systems.

The interactions between the consumers and providers should never contain identity tokens in order to prevent any kind of identity theft. Identities should only be shared with the trusted Arrowhead Core and Support systems.

Applicable to HTTP and MQTT interface protocols.

Usage

HTTP

declared-http

The declared identity info is the unique system name itself that must be present in the HTTP Authorization request header according to the following scheme: 

Bearer SYSTEM//<system-name>

Example:

curl -X 'DELETE' \
  'http://localhost:8443/serviceregistry/system-discovery/revoke' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer SYSTEM//TemperatureConsumer1'

certificate-http

The certificate identity info is contained in the client certificate that must be attached to the HTTPS request.

Example:

curl -X 'DELETE' \
  'https://localhost:8443/serviceregistry/system-discovery/revoke' \
  -H 'accept: */*' \
  --cert my-cert.p12 --cert-type P12 --pass 123456

outsourced-http

The outsourced identity info is a string token generated by a dedicated Core or Support system and obtained as a result of a successful authentication attempt. This token must be present in the HTTP Authorization request header according to the following scheme: 

Bearer IDENTITY-TOKEN//<token>

Example:

curl -X 'DELETE' \
  'http://localhost:8443/serviceregistry/system-discovery/revoke' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer IDENTITY-TOKEN//3d7b084d-1259-4a04-8789-880b7da3a530'

MQTT

declared-mqtt

The declared identity info is the unique system name itself that must be present in the authentication field of the MqttRequestTemplate according to the following scheme: 

SYSTEM//<system-name>

Example:

Topic: arrowhead/serviceregistry/system-discovery/revoke

{
   "traceId":"abc123",
   "authentication":"SYSTEM//TemperatureConsumer1",
   "responseTopic":"my/response/topic",
   "qosRequirement":2

}

certificate-mqtt

The certificate identity info is contained by the client certificate that must be present in the authentication field of the MqttRequestTemplate where the PEM format of the certificate is expected as a Base64 encoded string.

Example:

Topic: arrowhead/serviceregistry/system-discovery/revoke

{
   "traceId":"abc123",
   "authentication":"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUgvVENDQmVXZ0...",
   "responseTopic":"my/response/topic",
   "qosRequirement":2

}

outsourced-mqtt

The outsourced identity info is a string token generated by a dedicated Core or Support system and obtained as a result of a successful authentication attempt. This token must be present in the authentication field of the MqttRequestTemplate according to the following scheme:

IDENTITY-TOKEN//<token>

Example:

Topic: arrowhead/serviceregistry/system-discovery/revoke

{
   "traceId":"abc123",
   "authentication":"IDENTITY-TOKEN//3d7b084d-1259-4a04-8789-880b7da3a530",
   "responseTopic":"my/response/topic",
   "qosRequirement":2

}

Management API

Management-level APIs serve to provide administrative, governance and oversight operations within a Core/Support system and therefore require elevated access controls. Every Core/Support system that offers management services has the configuration possibility for management access control. See the management.policy configuration property.

Three incremental policies are offered:

  • sysop-only, when the authenticated requester system has system-operator role that ensures overall management permission.
  • whitelist, sysop-only and when the authenticated requester system is whitelisted in the management.whitelist configuration property that ensures overall management permission.
  • authorization, sysop-only and whitelist and when the authenticated requester system has appropriate service permission according to the ConsumerAuthorization Core system.

System Operator

declared

In declared authentication policy the system-operator role can be assigned by naming the requester system as Sysop.

certificate

In certificate authentication policy the system-operator role can be assigned by issuing a certificate with operator profile.

outsourced

In outsourced authentication policy the requester system is considered as system-operator if the verify operation of the identity serivce results in a response where the sysop flag is true.