| name | shortname | status | editor |
|---|---|---|---|
Endpoint and Client Authentication Protocol |
16/ECAP |
draft |
Andrew Kokhanovskyi <ak@kaaiot.io> |
Endpoint and Client Authentication Protocol (ECAP) is designed for authentication services to provide endpoints and clients authentication and identification interface to other services in the Kaa platform.
ECAP complies with the Inter-Service Messaging guidelines.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
The following terms and definitions are used in this RFC.
-
Authentication provider service (provider): service that exposes ECAP to other services for endpoint and client authentication.
-
Authentication consumer service (consumer): service that uses ECAP interface exposed by a provider to authenticate endpoints and clients.
Endpoint token validation request message is a targeted message that consumer sends to provider to make sure that the endpoint is allowed to connect and to resolve the endpoint ID.
The consumer MUST send endpoint token validation request messages using the following NATS subject:
kaa.v1.service.{provider-service-instance-name}.ecap.ep-token-request
The consumer MUST include NATS replyTo field to handle the response.
It is RECOMMENDED to follow the subject format described in 3/ISM session affinity section:
kaa.v1.replica.{consumer-service-replica-id}.ecap.ep-token-response
Endpoint token validation request message payload MUST be an Avro-encoded object with the following schema (0016-endpoint-token-validation-request.avsc):
{
"namespace":"org.kaaproject.ipc.ecap.gen.v1",
"name":"EndpointTokenValidationRequest",
"type":"record",
"doc":"EP token validation request message",
"fields":[
{
"name":"correlationId",
"type":"string",
"doc":"Message ID primarily used to track message processing across services"
},
{
"name":"timestamp",
"type":"long",
"doc":"Message creation UNIX timestamp in milliseconds"
},
{
"name":"timeout",
"type":"long",
"default":0,
"doc":"Amount of milliseconds (since the timestamp) until the message expires. Value of 0 is reserved to indicate no expiration."
},
{
"name":"appName",
"type":"string",
"doc":"Application name of the endpoint, for which the token validation is requested"
},
{
"name":"token",
"type":"string",
"doc":"Endpoint token to validate"
}
]
}Endpoint token validation response message MUST be sent by provider in response to an endpoint token validation request message.
Provider MUST publish endpoint token validation response message to the subject provided in the NATS replyTo field of the request.
Endpoint token validation response message payload MUST be an Avro-encoded object with the following schema (0016-endpoint-token-validation-response.avsc):
{
"namespace":"org.kaaproject.ipc.ecap.gen.v1",
"name":"EndpointTokenValidationResponse",
"type":"record",
"doc":"EP token validation response message",
"fields":[
{
"name":"correlationId",
"type":"string",
"doc":"Message ID primarily used to track message processing across services"
},
{
"name":"timestamp",
"type":"long",
"doc":"Message creation UNIX timestamp in milliseconds"
},
{
"name":"timeout",
"type":"long",
"default":0,
"doc":"Amount of milliseconds (since the timestamp) until the message expires. Value of 0 is reserved to indicate no expiration."
},
{
"name":"tokenId",
"type":[
"string",
"null"
],
"doc":"ID of the resolved token. May be null in case token is not found."
},
{
"name":"endpointId",
"type":[
"string",
"null"
],
"doc":"Identifier of the endpoint resolved by the provided token. May be null in case token is not found."
},
{
"name":"statusCode",
"type":"int",
"doc":"HTTP status code of the request processing"
},
{
"name":"reasonPhrase",
"type":[
"null",
"string"
],
"default":null,
"doc":"Human-readable status reason phrase"
}
]
}Endpoint token status transition request message is a targeted message that consumer sends to provider to transit a token status.
The consumer MUST send endpoint token status transition request messages using the following NATS subject:
kaa.v1.service.{provider-service-instance-name}.ecap.ep-token-status-transition-request
The consumer MUST include NATS replyTo field to handle the response.
It is RECOMMENDED to follow the subject format described in 3/ISM session affinity section:
kaa.v1.replica.{consumer-service-replica-id}.ecap.ep-token-status-transition-response
Endpoint token status transition request message payload MUST be an Avro-encoded object with the following schema (0016-endpoint-token-status-transition-request.avsc):
{
"namespace":"org.kaaproject.ipc.ecap.gen.v1",
"name":"EndpointTokenStatusTransitionRequest",
"type":"record",
"doc":"EP token status transition request message",
"fields":[
{
"name":"correlationId",
"type":"string",
"doc":"Message ID primarily used to track message processing across services"
},
{
"name":"timestamp",
"type":"long",
"doc":"Message creation UNIX timestamp in milliseconds"
},
{
"name":"timeout",
"type":"long",
"default":0,
"doc":"Amount of milliseconds (since the timestamp) until the message expires. Value of 0 is reserved to indicate no expiration."
},
{
"name":"appName",
"type":"string",
"doc":"Application name of the endpoint, for which the token status transition is requested"
},
{
"name":"token",
"type":"string",
"doc":"Endpoint token which status to transit"
},
{
"name":"targetStatus",
"type":"string",
"doc":"Target status to transit endpoint token to"
}
]
}Endpoint token status transition response message MUST be sent by provider in response to an endpoint token status transition request message.
Provider MUST publish endpoint token status transition response message to the subject provided in the NATS replyTo field of the request.
Endpoint token status transition response message payload MUST be an Avro-encoded object with the following schema (0016-endpoint-token-status-transition-response.avsc):
{
"namespace":"org.kaaproject.ipc.ecap.gen.v1",
"name":"EndpointTokenStatusTransitionResponse",
"type":"record",
"doc":"EP token status transition response message",
"fields":[
{
"name":"correlationId",
"type":"string",
"doc":"Message ID primarily used to track message processing across services"
},
{
"name":"timestamp",
"type":"long",
"doc":"Message creation UNIX timestamp in milliseconds"
},
{
"name":"timeout",
"type":"long",
"default":0,
"doc":"Amount of milliseconds (since the timestamp) until the message expires. Value of 0 is reserved to indicate no expiration."
},
{
"name":"statusCode",
"type":"int",
"doc":"HTTP status code of the request processing"
},
{
"name":"reasonPhrase",
"type":[
"null",
"string"
],
"default":null,
"doc":"Human-readable status reason phrase"
}
]
}Provider MUST publish endpoint token revoked event whenever one or more previously valid endpoint tokens become unusable for endpoint identification. On receipt of this event consumers MUST take immediate measures for terminating active endpoint communication sessions where listed tokens are used for endpoint identification.
Endpoint token revoked event is a broadcast message with endpoint target entity type, token event group, and revoked event type.
Providers MUST use the following NATS subject format for endpoint token revoked events:
kaa.v1.events.{originator-service-instance-name}.endpoint.token.revoked
Endpoint token revoked event message payload MUST be an Avro-encoded object with the following schema (0016-endpoint-token-revoked.avsc):
{
"namespace":"org.kaaproject.ipc.ecap.gen.v1",
"name":"EndpointTokenRevokedEvent",
"type":"record",
"doc":"Endpoint token revoked event",
"fields":[
{
"name":"correlationId",
"type":"string",
"doc":"Message ID primarily used to track message processing across services"
},
{
"name":"timestamp",
"type":"long",
"doc":"Message creation UNIX timestamp in milliseconds"
},
{
"name":"timeout",
"type":"long",
"default":0,
"doc":"Amount of milliseconds since the timestamp until the message expires. Value of 0 is reserved to indicate no expiration."
},
{
"name":"appName",
"type":"string",
"doc":"Application name of the endpoint, for which tokens are revoked"
},
{
"name":"endpointId",
"type":"string",
"doc":"Identifier of the endpoint associated with revoked tokens"
},
{
"name":"tokenIds",
"type":{
"type":"array",
"items":"string"
},
"doc":"List of revoked endpoint token IDs"
},
{
"name":"originatorReplicaId",
"type":"string",
"doc":"Identifier of the service replica that generated the event"
}
]
}Client username and password validation request message is a targeted message that consumer sends to provider to make sure that the client is allowed to connect and to resolve the client ID.
The consumer MUST send client username and password validation request messages using the following NATS subject:
kaa.v1.service.{provider-service-instance-name}.ecap.client-username-password-request
The consumer MUST include NATS replyTo field to handle the response.
It is RECOMMENDED to follow the subject format described in 3/ISM session affinity section:
kaa.v1.replica.{consumer-service-replica-id}.ecap.client-username-password-response
Client username and password validation request message payload MUST be an Avro-encoded object with the following schema (0016-client-username-password-validation-request.avsc):
{
"namespace":"org.kaaproject.ipc.ecap.gen.v1",
"name":"ClientUsernamePasswordValidationRequest",
"type":"record",
"doc":"Client username/password combination validation request message",
"fields":[
{
"name":"correlationId",
"type":"string",
"doc":"Message ID primarily used to track message processing across services"
},
{
"name":"timestamp",
"type":"long",
"doc":"Message creation UNIX timestamp in milliseconds"
},
{
"name":"timeout",
"type":"long",
"default":0,
"doc":"Amount of milliseconds (since the timestamp) until the message expires. Value of 0 is reserved to indicate no expiration."
},
{
"name":"username",
"type":[
"string",
"null"
],
"doc":"Client's username for validation"
},
{
"name":"password",
"type":[
"string",
"null"
],
"doc":"Client's password for validation"
}
]
}Client username and password validation response message MUST be sent by provider in response to a client username and password validation request message.
Provider MUST publish client username and password validation response message to the subject provided in the NATS replyTo field of the request.
Client username and password validation response message payload MUST be an Avro-encoded object with the following schema (0016-client-username-password-validation-response.avsc):
{
"namespace":"org.kaaproject.ipc.ecap.gen.v1",
"name":"ClientUsernamePasswordValidationResponse",
"type":"record",
"doc":"Client username/password combination validation response message",
"fields":[
{
"name":"correlationId",
"type":"string",
"doc":"Message ID primarily used to track message processing across services"
},
{
"name":"timestamp",
"type":"long",
"doc":"Message creation UNIX timestamp in milliseconds"
},
{
"name":"timeout",
"type":"long",
"default":0,
"doc":"Amount of milliseconds (since the timestamp) until the message expires. Value of 0 is reserved to indicate no expiration."
},
{
"name":"credentialId",
"type":[
"string",
"null"
],
"doc":"ID of the credential resolved by provided username/password combination. May be null in case the combination is not found."
},
{
"name":"clientId",
"type":[
"string",
"null"
],
"doc":"ID of the client resolved by provided username/password combination. May be null in case the combination is not found or no client ID is known to provider."
},
{
"name":"statusCode",
"type":"int",
"doc":"HTTP status code of the request processing"
},
{
"name":"reasonPhrase",
"type":[
"null",
"string"
],
"default":null,
"doc":"Human-readable status reason phrase"
}
]
}Client certificate validation request message is a targeted message that consumer sends to provider to make sure that the client is allowed to connect and to resolve the client ID. Provider does not perform standard certificate verification (signature, authority, expiration, etc.). Consumer MUST perform such verification prior to sending a client certificate validation request to provider.
The consumer MUST send client certificate validation request messages using the following NATS subject:
kaa.v1.service.{provider-service-instance-name}.ecap.client-certificate-request
The consumer MUST include NATS replyTo field to handle the response.
It is RECOMMENDED to follow the subject format described in 3/ISM session affinity section:
kaa.v1.replica.{consumer-service-replica-id}.ecap.client-certificate-response
Client certificate validation request message payload MUST be an Avro-encoded object with the following schema (0016-client-certificate-validation-request.avsc):
{
"namespace":"org.kaaproject.ipc.ecap.gen.v1",
"name":"ClientCertificateValidationRequest",
"type":"record",
"doc":"Client certificate validation request message",
"fields":[
{
"name":"correlationId",
"type":"string",
"doc":"Message ID primarily used to track message processing across services"
},
{
"name":"timestamp",
"type":"long",
"doc":"Message creation UNIX timestamp in milliseconds"
},
{
"name":"timeout",
"type":"long",
"default":0,
"doc":"Amount of milliseconds (since the timestamp) until the message expires. Value of 0 is reserved to indicate no expiration."
},
{
"name":"issuer",
"type":"string",
"doc":"Issuer field of the client's certificate"
},
{
"name":"serialNumber",
"type":"string",
"doc":"Serial number of the client's certificate, base 10 encoded"
}
]
}Client certificate validation response message MUST be sent by provider in response to an client certificate validation request message.
Provider MUST publish client certificate validation response message to the subject provided in the NATS replyTo field of the request.
Client certificate validation response message payload MUST be an Avro-encoded object with the following schema (0016-client-certificate-validation-response.avsc):
{
"namespace":"org.kaaproject.ipc.ecap.gen.v1",
"name":"ClientCertificateValidationResponse",
"type":"record",
"doc":"Client certificate validation response message",
"fields":[
{
"name":"correlationId",
"type":"string",
"doc":"Message ID primarily used to track message processing across services"
},
{
"name":"timestamp",
"type":"long",
"doc":"Message creation UNIX timestamp in milliseconds"
},
{
"name":"timeout",
"type":"long",
"default":0,
"doc":"Amount of milliseconds (since the timestamp) until the message expires. Value of 0 is reserved to indicate no expiration."
},
{
"name":"credentialId",
"type":[
"string",
"null"
],
"doc":"ID of the credential resolved by provided certificate fields. May be null in case certificate is not found."
},
{
"name":"clientId",
"type":[
"string",
"null"
],
"doc":"ID of the client resolved by provided certificate fields. May be null in case certificate is not found or no client ID is known to provider."
},
{
"name":"statusCode",
"type":"int",
"doc":"HTTP status code of the request processing"
},
{
"name":"reasonPhrase",
"type":[
"null",
"string"
],
"default":null,
"doc":"Human-readable status reason phrase"
}
]
}Provider MUST publish client credential revoked event whenever previously valid client credential becomes unusable for client authentication. On receipt of this event consumers MUST take immediate measures for terminating active communication sessions with the specified client.
Client credential revoked event is a broadcast message with client target entity type, credential event group, and revoked event type.
Providers MUST use the following NATS subject format for client credential revoked events:
kaa.v1.events.{originator-service-instance-name}.client.credential.revoked
Client credential revoked event message payload MUST be an Avro-encoded object with the following schema (0016-client-credential-revoked.avsc):
{
"namespace":"org.kaaproject.ipc.ecap.gen.v1",
"name":"ClientCredentialRevokedEvent",
"type":"record",
"doc":"Client credential revoked event",
"fields":[
{
"name":"correlationId",
"type":"string",
"doc":"Message ID primarily used to track message processing across services"
},
{
"name":"timestamp",
"type":"long",
"doc":"Message creation UNIX timestamp in milliseconds"
},
{
"name":"timeout",
"type":"long",
"default":0,
"doc":"Amount of milliseconds since the timestamp until the message expires. Value of 0 is reserved to indicate no expiration."
},
{
"name":"credentialId",
"type":"string",
"doc":"Identifier of the revoked credential"
},
{
"name":"originatorReplicaId",
"type":"string",
"doc":"Identifier of the service replica that generated the event"
}
]
}