THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
| Table of Contents |
|---|
Status
Current state: Under Discussion Accepted
Discussion thread: here
JIRA: none yet
| Jira | ||||||
|---|---|---|---|---|---|---|
|
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).
...
As part of the KIP-500 effort to remove Kafka's ZooKeeper dependency, we need a broker-side API to alter these settings.
Public Interfaces
...
describeUserScramCredentials
listScramUsers describeUserScramCredentials will list describe the currently configured SCRAM usersuser credentials. For security reasons, it will not list their passwords.
| Code Block | ||
|---|---|---|
| ||
public enum ScramMechanism {
UNKNOWN(0),
HMACSCRAM_SHA_256(1),
HMACSCRAM_SHA_512(2);
private final byte type;
private ScramMechanism(byte type) {final String mechanismName;
public static ScramMechanism fromType(byte this.type) = type;{
}
}
public class ScramMechanismInfo {
// etc...
private final ScramMechanism mechanism; }
privatepublic finalstatic int iterations;
}
public class ScramUserListing {
ScramMechanism fromMechanismName(String mechanismName) {
private final String name;
private final List<ScramMechanismInfo> infos;
// etc...
}
public class ListScramUsersOptions extends AbstractOptions<ListScramUsersOptions>public { }
default ListScramUsersResult listScramUsersString mechanismName() {
return listScramUsers(new ListScramUsersOptions());
// etc...
}
ListScramUsersResult listScramUsers(ListScramUsersOptions options);
public classbyte ListScramUsersResulttype() {
public KafkaFuture<Map<String, ScramUserListing>> all();
} |
listScramUsers will be implemented by a new RPC.
// etc...
}
private ScramMechanism(byte type) {
// etc...
}
}
public class ScramCredentialInfo {
private final ScramMechanism mechanism;
private final int iterations;
}
public class UserScramCredentialsDescription {
private final String name;
private final List<ScramCredentialInfo> infos;
}
public class DescribeScramUserCredentialsOptions extends AbstractOptions<DescribeScramUserCredentialsOptions> { }
// interface Admin: Describe all users.
default DescribeScramUserCredentialsResult describeScramUserCredentials() {
return describeScramUserCredentials(null);
}
// interface Admin: Describe indicated users (null or empty implies all).
default DescribeScramUserCredentialsResult describeScramUserCredentials(List<String> users) {
return describeScramUserCredentials(users, new DescribeScramUserCredentialsOptions());
}
// interface Admin
DescribeScramUserCredentialsResult describeScramUserCredentials(List<String> users, DescribeScramUserCredentialsOptions options);
public class DescribeScramUserCredentialsResult {
// completes successfully only if users() does and every described user does
public KafkaFuture<Map<String, UserScramCredentialsDescription>> all();
// completes successfully if request was authorized and the list of users described is determined
public KafkaFuture<List<String>> users();
// completes successfully if the individual user is described successfully
public KafkaFuture<UserScramCredentialsDescription> description(String userName)
} |
describeScramUserCredentials will be implemented by a new RPC.
| Code Block |
|---|
{
"apiKey": 50,
"type": "request",
"name": "DescribeUserScramCredentialsRequest",
"validVersions": "0",
"flexibleVersions": "0+",
"fields": [
|
| Code Block |
{ "apiKey": 50, "type": "request", "name": "ListScramUsersRequest", "validVersions": "0", "flexibleVersions": "0+", "fields": [ ] } { "apiKey": 50, "type": "response", "name": "ListScramUsersResponse", "validVersions": "0", "flexibleVersions": "0+", "fields": [ { "name": "Error", "type": "int16", "versions": "0+", "about": "The message-level error code." }, { "name": "ErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+", "about": "The message-level error message." }, { "name": "Users", "type": "[]ScramUser", "versions": "0+", "about": "The SCRAM users.", "fields": [ { "name": "Name", "type": "string", "versions": "0+", "about": "The user name." }, { "name": "MechanismInfos", "type": "ScramUserMechanismInfo", "versions": "0+", "about": "The user name." }, { "name": "Mechanism", "type": "int8", "versions": "0+", "about": "The SCRAM mechanism." }, { "name": "IterationsUsers", "type": "int32[]UserName", "versions": "0+", "nullableVersions": "0+", "about": "The users numberto ofdescribe, iterationsor usednull/empty into thedescribe SCRAMall mechanismusers." }, "fields": [ { "name": "SaltName", "type": "bytesstring", "versions": "0+", "about": "The passworduser saltname." }, ]} ] } { "apiKey": 50, {"type": "response", "name": "StoredKeyDescribeUserScramCredentialsResponse", "typevalidVersions": "byte0", "versionsflexibleVersions": "0+", "fields": [ "about": "The hashed client key." }, { { "name": "ServerKeyThrottleTimeMs", "type": "byteint32", "versions": "0+", "about": "The hashedduration serverin key." } } ]} ] } |
It will require ALTER permissions on the CLUSTER resource. It will return CLUSTER_AUTHORIZATION_FAILED if the user has insufficient permissions.
It will be will be sent to the controller, and will return NOT_CONTROLLER if the receiving broker is not the controller.
AlterScramUsers
alterScramUsers will delete, create, or change SCRAM users.
Deletions are done by user name.
Alterations will create the given user if it doesn't exist, or alter it if it does.
| Code Block |
|---|
public class ScramUserDeletion { private final String user; } public class ScramCredential { private final ScramMechanismInfo info; private final byte[] salt; private final byte[] password; // There will be one constructor that randomly generates a salt, and one that accepts a pre-defined salt. } public class ScramUserAlteration { private final String user; private final List<ScramCredential> credentials; public ScramCredentialAlteration(String user, List<ScramCredential> credentials) {milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." }, { "name": "ErrorCode", "type": "int16", "versions": "0+", "about": "The message-level error code, 0 except for user authorization or infrastructure issues." }, { "name": "ErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+", "about": "The message-level error message, if any." }, { "name": "Results", "type": "[]DescribeUserScramCredentialsResult", "versions": "0+", "about": "The results for descriptions, one per user.", "fields": [ { this.user = user; "name": "User", "type": "string", "versions": "0+", this.credentials = credentials; } "about": "The user name." }, public String user() { "name": "ErrorCode", return user; "type": "int16", "versions": "0+", } "about": "The publicuser-level List<ScramCredential> credentials() {error code." }, { return credentials; } } public class AlterScramUsersOptions extends AbstractOptions<AlterScramUsersOptions> {} default AlterScramUsersResult alterScramUsers(List<ScramUserDeletion> deletions"name": "ErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+", "about": "The user-level error message, if any." }, { "name": "CredentialInfos", "type": "[]CredentialInfo", "versions": "0+", "about": "The mechanism and related information associated with the user's SCRAM List<ScramUserAlteration> alterations) { credentials.", "fields": [ return alterScramUsers(deletions, alterations, new AlterScramUsersOptions()); } AlterScramUsersResult alterScramUsers(List<ScramUserDeletion> deletions, { "name": "Mechanism", "type": "int8", "versions": "0+", "about": "The SCRAM mechanism." }, { "name": "Iterations", "type": "int32", "versions": "0+", List<ScramUserAlteration> alterations, AlterScramUsersOptions options); public class AlterScramCredentialsResult { public KafkaFuture<Void> all(); public Map<String, KafkaFuture<Void>> results(); } |
The AlterScramUsersRequest and AlterScreamUsersResponse implement the new API.
"about": "The number of iterations used in the SCRAM credential." }]}
]}
]
}
|
It will require DESCRIBE permissions on the CLUSTER resource. It will return CLUSTER_AUTHORIZATION_FAILED if the user has insufficient permissions.
It will return RESOURCE_NOT_FOUND if a user is requested to be described but that user does not exist/has no credentials. Note that DescribeScramUserCredentialsResult will not consider such a username to be part of its users() result list, and this RESOURCE_NOT_FOUND error by itself will not prevent the future returned by all() from completing successfully.
It will return DUPLICATE_RESOURCE if a user is requested to be described twice. Note that DescribeScramUserCredentialsResult will consider such a username to be part of its users() result list, and this will cause the future returned by all() to complete exceptionally.
AlterScramUserCredentials
alterScramUserCredentials will create or change SCRAM user credentials.
Alterations will create the given user credential if it doesn't exist, or alter it if it does.
| Code Block |
|---|
public abstract class UserScramCredentialAlteration {
private final String user;
}
public class UserScramCredentialUpsertion extends UserScramCredentialAlteration {
private final ScramCredentialInfo info;
private final byte[] salt;
private final byte[] password;
// There will be one constructor that randomly generates a salt, and one that accepts a pre-defined salt.
}
public class UserScramCredentialDeletion extends UserScramCredentialAlteration {
private final ScramMechanism mechanism;
}
public class AlterScramUserCredentialsOptions extends AbstractOptions<AlterScramUserCredentialsOptions> {}
// interface Admin
default AlterScramUserCredentialsResult alterScramUserCredentials(List<UserScramCredentialAlteration> alterations) {
return alterScramUserCredentials( alterations, new AlterScramUserCredentialsOptions());
}
// interface Admin
AlterScramUserCredentialsResult alterScramUserCredentials(List<UserScramCredentialAlteration> alterations,
AlterScramUserCredentialsOptions options);
public class AlterUserScramCredentialsResult {
public Map<String, KafkaFuture<Void>> values();
public KafkaFuture<Void> all(); // completes successfully only if everything in values() does
} |
If any of the operations associated with a single user can't be done, none of the operations will be done. On the other hand, operations could succeed for one user but fail for another, different user.
If a user doesn't exist and we add a credential for them, they will be created. If a user exists and we remove their last credential, they will be deleted.
The AlterScramUserCredentialsRequest and AlterScramUserCredentialsResponse implement the new API.
| Code Block | ||
|---|---|---|
| ||
{
"apiKey": 51,
"type": "request",
"name": "AlterUserScramCredentialsRequest",
"validVersions": "0",
"flexibleVersions": "0+",
"fields": [
{ "name": "Deletions", "type": "[]ScramCredentialDeletion", "versions": "0+",
"about": "The SCRAM credentials to remove.", "fields": [
{ "name": "Name", "type": "string", "versions | ||
| Code Block | ||
| ||
{ "apiKey": 51, "type": "response", "name": "AlterScramUsersRequest", "validVersions": "0", "flexibleVersions": "0+", "fieldsabout": [ "The user name." }, { "name": "DeletionsMechanism", "type": "[]ScramUserDeletionint8", "versions": "0+", "about": "The SCRAM users to removemechanism.", "fields": [ } ]}, { "name": "NameUpsertions", "type": "string[]ScramCredentialUpsertion", "versions": "0+", "about": "The SCRAM credentials userto name." } ]}, update/insert.", "fields": [ { "name": "AlterationsName", "type": "[]ScramUserAlterationstring", "versions": "0+", "about": "The SCRAM users to alteruser name.", "fields": [ }, { "name": "NameMechanism", "type": "stringint8", "versions": "0+", "about": "The userSCRAM namemechanism." }, { "name": "CredentialsIterations", "type": "ScramCredentialint32", "versions": "0+", "about": "The SCRAMnumber credentialsof to configureiterations." }, { "name": "MechanismSalt", "type": "int8bytes", "versions": "0+", "about": "The SCRAM mechanismA random salt generated by the client." }, { "name": "IterationsSaltedPassword", "type": "int32bytes", "versions": "0+", "about": "The number of iterations, or -1 to use the server default "The salted password." }, ]} {] } { "nameapiKey": "Salt"51, "type": "bytesresponse", "versionsname": "0+", AlterUserScramCredentialsResponse", "aboutvalidVersions": "A random salt generated by the client." }"0", "flexibleVersions": "0+", "fields": [ { "name": "SaltedPasswordThrottleTimeMs", "type": "bytesint32", "versions": "0+", ", "about": "The duration saltedin password." } ]} ]} ] } { "apiKey": 51, milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." }, { "name": "Results", "type": "response[]AlterUserScramCredentialsResult", "nameversions": "AlterScramUsersResponse0+", "validVersionsabout": "0"The results for deletions and alterations, "flexibleVersions": "0+", one per affected user.", "fields": [ { "name": "ResultsUser", "type": "[]AlterScramUsersResultstring", "versions": "0+", "about": "The results for removals, followed by the results for alterations.", "fields": [ user name." }, { "name": "ErrorCode", "type": "int8int16", "versions": "0+", "about": "The error code." }, { "name": "ErrorStringErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+", "about": "The error message, if any." } ]} ] } |
An addition A removal or alteration will return INVALIDUNACCEPTABLE_REQUEST CREDENTIAL if an empty user name is passed, or an invalid number of iterations , or a duplicate user name. Note that if the number of iterations is set to -1, the server-side default will be used(less than the minimum required for the mechanism or more than a hard-coded max of 16,384) is passed.
DUPLICATE_RESOURCE will be returned if a user appears as both an upsertion and a deletion in the same request.
UNSUPPORTED_SASL_MECHANISM will be returned if the broker does not recognize the requested SASL mechanism.
A removal will return a new an error code, RESOURCE_NOT_FOUND, if it was instructed to delete a user, but that user was not foundcredential that did not exist.
The RPC will require ALTER on CLUSTER. It will return CLUSTER_AUTHORIZATION_FAILED if the user has insufficient permissions.
It will be will be sent to the controller , and will return NOT_CONTROLLER if the receiving broker is not the controller.
...