For more information and examples, please refer to the AuthN documentation.
AuthN is an AIS authorization server that can be deployed to manage user access to one or more AIS clusters.
All commands (except logout) send requests to AuthN URL defined in the AIS CLI configuration file.
Configuration can be overridden with environment variable AUTHN_URL, e.g., AUTHN_URL=http://10.0.0.20:52001 ais auth add ....
The CLI provides an easy way to manage users and to grant and revoke access permissions.
Only users with Admin role can manage AuthN server.
Every request to AuthN, except login and logout, requires a token.
The token is generated by the server after the user successfully logs in.
CLI automatically saves the received token to user's configuration directory and attaches it to every request.
When a token is revoked, AuthN notifies registered clusters, so they update their blacklists.
After successful login, the CLI saves the generated token to the user's configuration directory for future use and automatically passes it with every request to AuthN. For convenience, the CLI prints out the generated token so it can be copied and used with other clients.
$ ais auth login -p admin admin
Token(/home/ubuntu/.config/ais/auth.token):
eyJhbGciOiJIUuI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1ZSwiZThwaXJlcyI6IjIwMjAtMDYtMTFUMTY6MzU6MDAuODQyNzMzNjU1LTA3OjAwIiwidXNlcm5hbWUiOiJhZG1pbiJ9.ppyMR8EE37M9O9Kl9ybyB7CE0fq6hIwL3Sa-5OUea8IThe CLI supports loading a token from a custom location.
One possible usage is imitating the Linux sudo command.
First, a user logs into the AIStore cluster as an Admin and saves the token to some location.
Second, the user logs into AIStore as a regular user with default options.
The regular user's requests would then use that user's last generated token for all requests.
Then, when elevated privileges are needed, the user can specifying the path to the admin token.
$ # Generate a token and save it to a given location
$ ais auth login -p admin --file ./admin.token admin
Token saved to ./admin.token
$ # Log in as a regular user
$ ais auth login -p pass user
Token(/home/ubuntu/.config/ais/auth.token):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1Z...
$ # Create bucket as a regular user
$ ais bucket create ais://bck1
$ # Removing a user requires admin's token, pass a path to the token to CLI
$ AUTHN_TOKEN_FILE=./admin.token ais auth rm user tmpUser1When a user's token is compromised, the tokens should be revoked:
$ # Pass the token in the command line
$ ais auth rm token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1Z...
$ # Read the token from a file created by AIS CLI
$ ais auth rm token -f /home/user/user.tokenais auth add user [-p USER_PASS] USER_NAME [ROLE [ROLE...]]
Register the user and assign the list of roles to the user.
If the role is omitted, the new user does not have any permissions. It may be useful in case a user needs access to one or a few buckets. Instead of creating a new role just for the user, register a user with an empty role and grant permissions to the required buckets.
$ ais auth add user -p password user1
$ ais auth add user -p password user2 PowerUser
$ ais auth show user
NAME ROLES
admin Admin
user1 -
user2 PowerUserais auth update user [-p USER_PASS] USER_NAME [ROLE [ROLE...]]
Updates user password and list of roles. If the role list is omitted, the current
user role remains unchanged.
Changing the role for the built-in account admin is forbidden.
ais auth rm user USER_NAME
Remove an existing user. The built-in account admin cannot be removed.
ais auth show user [USER [-v]]
Displays the list of registered users.
$ ais auth show user
NAME ROLES
admin Admin
user1 Guest-clu1,Guest-clu2
user2 PowerUser-clu1By default, the user is displayed in short mode.
Option -v prints detailed info:
$ ais auth show user user1
NAME ROLES
user1 Guest-clu
$ ais auth show user user1 -v
Name test
Roles Guest-local
CLUSTER ID ALIAS PERMISSIONS
k5zAzdhbr clu GET,HEAD-OBJECT,HEAD-BUCKET,LIST-OBJECTSais auth add role CLUSTER_ID PERMISSION [PERMISSION...]
Creates a role and grants the list of permissions to the cluster.
CLUSTER_ID is either cluster ID or cluster alias.
PERMISSION can be a single compound permission(one of ro, rw, su) or a specific access permission.
$ # Create a role with read-write access to cluster data
$ ais auth add role rwRole clusterOne rw
$ ais auth show role rwRole -v
Role rwRole
Description
CLUSTER ID ALIAS PERMISSIONS
k5zAzdhbr clusterOne GET,HEAD-OBJECT,PUT,APPEND,DELETE-OBJECT,MOVE-OBJECT,HEAD-BUCKET,LIST-OBJECTS
$ # Grant specific permission to a role
$ ais auth add role specRole clusterOne GET HEAD-BUCKET LIST-OBJECT
$ ais auth show role specRole -v
Role specRole
Description
CLUSTER ID ALIAS PERMISSIONS
k5zAzdhbr clusterOne GET,HEAD-BUCKET,LIST-OBJECTSais auth show role [ROLE [-v]]
Displays existing roles in alphabetical order.
$ ais auth show role
ROLE DESCRIPTION
Admin AuthN administrator
BucketOwner Full access to buckets
Guest Read-only access to buckets
PowerUser Full access to clusterBy default, the role is displayed in short mode.
Option -v prints detailed info:
$ ais auth show role Guest-clu
ROLE DESCRIPTION
Guest-clu Read-only access to buckets of cluster k5zAzdhbr[local]
$ ais auth show role Guest-clu -v
Role Guest-local
Description Read-only access to buckets of cluster k5zAzdhbr[local]
CLUSTER ID ALIAS PERMISSIONS
k5zAzdhbr local GET,HEAD-OBJECT,HEAD-BUCKET,LIST-OBJECTSais auth login [-p USER_PASS] USER_NAME [--expire EXPIRATION_TIME]
Issue a token for a user.
After successful login, the user's token is saved to CLI configuration directory (typically ~/.config/ais/) with a filename auth.token.
Subsequent ais commands automatically load and use the token for requests to the AIS cluster.
The saved token can be used by other applications, like curl.
Please see AuthN documentation to read how to use AuthN API directly.
By default, the AuthN token expiration is 24 hours.
Use option -e or --expire to generate a token with custom expiration time.
$ # Generate a token that expires in 5 hours
$ ais auth login -p password username -e 5h
$ # Generate a token that never expires
$ ais auth login -p password username -e 0ais auth logout
Delete the user's token from a local machine. The token is not revoked, so it can be used by any application until it expires. To forbid using the token from any application, the token must be revoked manually in addition to logging out.
ais auth add cluster [ALIAS] [URL...]
If URL is omitted, CLI registers a cluster using its URL from CLI configuration or AIS_ENDPOINT variable.
When the URL list is defined, CLI tries to connect the cluster using the first URL from the list.
Register the cluster and assign the list of URLs for sending notifications.
A user may assign an alias to the cluster for convenience: AuthN commands accepts both cluster ID and alias in requests.
Alias must be a unique name. Alias is an arbitrary name, but it should not start with http.
In this case, CLI treats the alias as the URL.
On successful cluster registration, AuthN automatically creates a few predefined unique roles for the cluster: with full access, read-write access to all its buckets, and read-only access to the cluster. Please note that the role names include cluster's alias if it was defined. If the alias is omitted, AuthN adds cluster ID to a role name.
See full example in List registered clusters.
ais auth update cluster CLUSTER_ID [ALIAS] URL [URL...]
Replaces the list of URLs or changes alias for an existing cluster.
ais auth rm cluster CLUSTER_ID
Remove the existing cluster from the notification list.
ais auth show cluster
Display the list of the cluster that subscribe to AuthN notifications.
# register a cluster without an alias
$ ais auth add cluster http://172.0.10.10 http://10.0.10.10
# register a cluster with an alias and default URL
$ ais auth add cluster srv1
# check the list of the clusters
$ ais auth show cluster
CLUSTER ID ALIAS URLs
2xs35th89 http://172.0.10.10,http://10.0.10.10
78df35690 srv1 http://172.0.10.50
# check the list of generated roles. Note that for convenience,
# the role description includes both ID and alias if appropriate
$ ais auth show role
ROLE DESCRIPTION
Admin AuthN administrator
BucketOwner-2xs35th89 Full access to buckets of cluster 2xs35th89
BucketOwner-srv1 Full access to buckets of cluster 78df35690[srv1]
ClusterOwner-2xs35th89 Full access to cluster 2xs35th89
ClusterOwner-srv1 Full access to cluster 78df35690[srv1]
Guest-2xs35th89 Read-only access to buckets of cluster 2xs35th89
Guest-srv1 Read-only access to buckets of cluster 78df35690[srv1]ais auth show config [--json | PREFIX]
Display the AuthN server configuration in tabular or JSON format. In tabular output, the prefix filters only properties which names start with it.
$ ais auth show config auth.e
PROPERTY VALUE
auth.expiration_time 5h
$ ais auth show config --json
{
"path": "/home/ubuntu/.authn/authn.json",
"confdir": "/home/ubuntu/.authn",
"log": {
"dir": "/tmp/ais/authn/log",
"level": "3"
},
"net": {
"http": {
"port": 52001,
"use_https": false,
"server_crt": "server.crt",
"server_key": "server.key"
}
},
"auth": {
"secret": "aBitLongSecretKey",
"expiration_time": "5h"
},
"timeout": {
"default_timeout": "30s"
}
}
ais auth set config PROP VALUE [PROP VALUE...]
Update AuthN server configuration.
The command allows updating options that can be changed without AuthN server restart.
New property values can be defined either in PROPERTY VALUE or PROPERTY=VALUE form.
$ ais auth set config auth.
auth.expiration_time auth.secret
$ ais auth set config auth.expiration_time 4h
$ ais auth show config auth.e
PROPERTY VALUE
auth.expiration_time 4hDo not forget to update the secret on all clusters if you change AuthN secret. Otherwise, new tokens will be rejected by AIS clusters.