Authentication and access control

For quick getting-started (local-playground) session and in-depth overview, please refer to:

AIS AuthN documentation.

Note: AuthN is currently in beta.

User Account and Access management

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 AIS_AUTHN_URL, e.g., AIS_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 the 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 that they update their blacklists.

Token management

Generate a token for CLI

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.

1 $ ais auth login -p admin admin
2 Token(/home/ubuntu/.config/ais/cli/auth.token):

Generate a token to a file

The CLI supports loading a token from a custom location. One possible usage is imitating the Linux sudo command:

A user logs into the AIStore cluster as an Admin and saves the token to some location.
The user logs into AIStore as a regular user with default options. (A regular user’s requests would then use that last generated token for all requests).
When elevated privileges are needed, the user can specify the path to the admin token.

1 $ # Generate a token and save it to a given location
2 $ ais auth login -p admin --file ./admin.token admin
3 Token saved to ./admin.token
4 
5 $ # Log in as a regular user
6 $ ais auth login -p pass user
7 Token(/home/ubuntu/.config/ais/cli/auth.token)
8 
9 $ # Create bucket as a regular user
10 $ ais create ais://bck1
11 
12 $ # Removing a user requires admin's token, pass a path to the token to CLI
13 $ AIS_AUTHN_TOKEN_FILE=./admin.token ais auth rm user tmpUser1

Revoke a token

When a user’s token is compromised, the token should be revoked:

1 $ # Pass the token in the command line
2 $ ais auth rm token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6dHJ1Z...
3 
4 $ # Read the token from a file created by AIS CLI
5 $ ais auth rm token -f /home/user/user.token

Command List

Register new user

ais auth add user [-p USER_PASS] USER_NAME [ROLE [ROLE...]]

If the list of roles is not provided, the new user does not have any permissions.

Bucket access does not necessarily require creating a role. Instead, admin can register a user with an empty role and grant permissions to the required buckets.

Examples

1 $ ais auth add user -p password user1
2 $ ais auth add user -p password user2 PowerUser
3 $ ais auth show user
4 NAME    ROLES
5 admin   Admin
6 user1   -
7 user2   PowerUser

Update user

ais 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.

Unregister existing user

ais auth rm user USER_NAME

Remove an existing user. The built-in account admin cannot be removed.

List registered users

ais auth show user [USER [-v]]

Displays the list of registered users.

1 $ ais auth show user
2 NAME    ROLES
3 admin   Admin
4 user1   Guest-clu1,Guest-clu2
5 user2   PowerUser-clu1

By default, the user is displayed in short mode. Option -v prints detailed info:

1 $ ais auth show user user1
2 NAME    ROLES
3 user1   Guest-clu
4 
5 $ ais auth show user user1 -v
6 Name            test
7 Roles           Guest-local
8 CLUSTER ID      ALIAS   PERMISSIONS
9 k5zAzdhbr       clu     GET,HEAD-OBJECT,HEAD-BUCKET,LIST-OBJECTS

Add a new role

ais auth add role ROLE_ID PERMISSION [PERMISSION...] [--flags]

Creates a role and grants the list of permissions to the role.

Flag	Description	Argument
`--cluster`	Grants permissions to access and operate on a cluster (scope: cluster)	Cluster ID or alias
`--bucket`	Grants permissions to access and operate on a specific bucket (scope: bucket)	Bucket URI (provider and bucket name), e.g. `ais://imagenet`

If only --cluster is defined, the permissions are used as default ones to access every bucket in the cluster.

Note:

Flag --bucket always requires --cluster to be defined.
PERMISSION can be a single compound permission (one of ro, rw, su) or a specific access permission.

Examples:

1 # Create a role with read-write access to all buckets in the cluster
2 $ ais auth add role rwRole --cluster clusterOne rw
3 $ ais auth show role rwRole -v
4 Role            rwRole
5 Description
6 CLUSTER ID      ALIAS        PERMISSIONS
7 k5zAzdhbr       clusterOne   GET,HEAD-OBJECT,PUT,APPEND,DELETE-OBJECT,MOVE-OBJECT,HEAD-BUCKET,LIST-OBJECTS
8 
9 # Grant specific permission to a cluster-level role
10 $ ais auth add role specRole clusterOne GET HEAD-BUCKET LIST-OBJECT
11 $ ais auth show role specRole -v
12 Role            specRole
13 Description
14 CLUSTER ID      ALIAS        PERMISSIONS
15 k5zAzdhbr       clusterOne   GET,HEAD-BUCKET,LIST-OBJECTS

List existing roles

ais auth show role [ROLE]

Displays existing roles in alphabetical order.

Flags:

Flag	Type	Description
`-v`	`bool`	Enables verbose mode. In short mode only role names and their descriptions are displayed. In verbose mode, details about cluster and bucket permissions are shown as well. When `ROLE` is set, verbose mode enables automatically
`--cluster`	`string`	Comman-separated list of cluster IDs. Only roles that grants permissions to these clusters or buckets of these clusters are shown

Note: some roles include “global” permissions - it is roles which are not bound to all clusters. You can create such role by omitting --cluster flag while adding or updating a role. To list “global” roles, pass a list which contains an empty cluster ID. List that contains only “global” cluster ID is ",". E.g, ais auth show role --cluster=,.

1 $ ais auth show role
2 ROLE            DESCRIPTION
3 Admin           AuthN administrator
4 BucketOwner     Full access to buckets
5 Guest           Read-only access to buckets
6 PowerUser       Full access to cluster

By default, the role is displayed in short mode. Option -v prints detailed info:

1 $ ais auth show role
2 ROLE            DESCRIPTION
3 Guest-clu       Read-only access to buckets of cluster k5zAzdhbr[local]
4 
5 $ ais auth show role -v
6 Role            Guest-local
7 Description     Read-only access to buckets of cluster k5zAzdhbr[local]
8 CLUSTER ID      ALIAS   PERMISSIONS
9 k5zAzdhbr       local   GET,HEAD-OBJECT,HEAD-BUCKET,LIST-OBJECTS

Show all, global, and a single cluster roles:

1 $ ais auth show role -v
2 Role              Admin
3 Description       AuthN administrator
4 
5 Role              role1
6 Description
7 CLUSTER ID        ALIAS    PERMISSIONS
8                            GET,HEAD-OBJECT,HEAD-BUCKET,LIST-OBJECTS,LIST-BUCKETS
9 
10 Role              role2
11 Description
12 CLUSTER ID        ALIAS    PERMISSIONS
13 wRF7CDVbN         clu-tst  GET,HEAD-OBJECT,HEAD-BUCKET,LIST- OBJECTS,LIST-BUCKETS
14 
15 Role              role3
16 Description
17 CLUSTER ID        ALIAS    PERMISSIONS
18 wRF7CDVbN         clu-tst  GET,HEAD-OBJECT,LIST-OBJECTS
19 
20 $ ais auth show role --cluster=clu-tst
21 ROLE      DESCRIPTION
22 role2
23 role3
24 
25 $ ais auth show role --cluster=,
26 ROLE      DESCRIPTION
27 role1

Log in to AIS cluster

ais 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/cli/) under auth.token filename.

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 for 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.

1 $ # Generate a token that expires in 5 hours
2 $ ais auth login -p password username -e 5h
3 
4 $ # Generate a token that never expires
5 $ ais auth login -p password username -e 0

Log out

ais 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.

Register new cluster

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.

Update existing cluster

ais auth update cluster CLUSTER_ID [ALIAS] URL [URL...]

Replaces the list of URLs or changes alias for an existing cluster.

Unregister existing cluster

ais auth rm cluster CLUSTER_ID

Remove the existing cluster from the notification list.

List registered clusters

ais auth show cluster

Display the list of the cluster that subscribe to AuthN notifications.

1 # register a cluster without an alias
2 $ ais auth add cluster http://172.0.10.10 http://10.0.10.10
3 
4 # register a cluster with an alias and default URL
5 $ ais auth add cluster srv1
6 
7 # check the list of the clusters
8 $ ais auth show cluster
9 CLUSTER ID      ALIAS   URLs
10 2xs35th89               http://172.0.10.10,http://10.0.10.10
11 78df35690       srv1    http://172.0.10.50
12 
13 # check the list of generated roles. Note that for convenience,
14 # the role description includes both ID and alias if appropriate
15 $ ais auth show role
16 ROLE                    DESCRIPTION
17 Admin                   AuthN administrator
18 BucketOwner-2xs35th89   Full access to buckets of cluster 2xs35th89
19 BucketOwner-srv1        Full access to buckets of cluster 78df35690[srv1]
20 ClusterOwner-2xs35th89  Full access to cluster 2xs35th89
21 ClusterOwner-srv1       Full access to cluster 78df35690[srv1]
22 Guest-2xs35th89         Read-only access to buckets of cluster 2xs35th89
23 Guest-srv1              Read-only access to buckets of cluster 78df35690[srv1]

Show AuthN server configuration

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.

1 $ ais auth show config auth.e
2 PROPERTY                 VALUE
3 auth.expiration_time     5h
4 
5 $ ais auth show config --json
6 {
7     "path": "/home/ubuntu/.authn/authn.json",
8     "confdir": "/home/ubuntu/.authn",
9     "log": {
10         "dir": "/tmp/ais/authn/log",
11         "level": "3"
12     },
13     "net": {
14         "http": {
15             "port": 52001,
16             "use_https": false,
17             "server_crt": "server.crt",
18             "server_key": "server.key"
19         }
20     },
21     "auth": {
22         "secret": "aBitLongSecretKey",
23         "expiration_time": "5h"
24     },
25     "timeout": {
26         "default_timeout": "30s"
27     }
28 }

Change AuthN server configuration

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.

1 $ ais auth set config auth.
2 auth.expiration_time  auth.secret
3 
4 $ ais auth set config auth.expiration_time 4h
5 $ ais auth show config auth.e
6 PROPERTY                 VALUE
7 auth.expiration_time     4h

Do not forget to update the secret on all clusters if you change AuthN secret. Otherwise, new tokens will be rejected by AIS clusters.

Table of contents