Managing Users and Roles
This page discusses how to manage users, roles, and permissions in Stardog. See the section on Stardog’s Security Model to learn more about how security works in Stardog with respect to authentication and authorization.
Page Contents
- Setting Password Constraints
- Create a Role
- Grant Permissions to a Role
- Assign a Role to a User
- Create a User
- Grant Explicit Permissions to a User
- List a User and Role’s Permissions
- Enable/Disable User
- Change a User’s Password
- Delete a User
- Remove a Role from a User
- Delete a Role
- Using a Password File
Setting Password Constraints
To setup the constraints used to validate passwords when adding new users, configure the following settings in the stardog.properties
configuration file:
Property | Description | Default |
---|---|---|
password.length.min | Sets the password policy for the minimum length of user passwords, the value can’t be lower than password.length.min or greater than password.length.max . | 4 |
password.length.max | Sets the password policy for the maximum length of user passwords. | 1024 . |
password.regex | Sets the password policy of accepted chars in user passwords, via a Java regular expression. | [\w@#$%!&]+ |
Example stardog.properties
to set the minimum password length to 8 characters:
password.length.min=8
Create a Role
The following examples show how to create a role.
-
-
Create the role using the
role add
Stardog Admin CLI command:stardog-admin role add myRole
-
-
-
Navigate to the “Security” ( ) section in Studio.
-
Select the button in the “ROLES” pane:
-
Enter a name for the new role:
-
Grant Permissions to a Role
The following examples show how to grant permissions to a role.
-
-
Grant permissions to the role
myRole
such that it hasREAD
access overmyDatabase
using therole grant
Stardog Admin CLI command.stardog-admin role grant -n myRole -a read -o db:myDatabase
- Note how the target resource (
-o
argument) is specifieddb:myDatabase
. A particular resource is denoted byresource_type_prefix:name
. All resource type prefixes are documented in Resources. When adding permissions via the CLI, resources must be specified like this.
- Note how the target resource (
-
-
-
Navigate to the “Security” ( ) section of Studio.
-
Select the role in the “ROLES” pane you wish to add permissions to.
-
Select the “Add Permission” button in the top right of the window.
-
Grant a permission to the role. Remember, any action can be granted over any resource. See Actions and Resources for a description of all actions and resources. Below we grant the
myRole
roleREAD
access over the the databasemyDatabase
which has a resource type ofdb
.When adding permissions via Studio, you can omit the resource type prefix when entering the resource name/identifier. This is not the case when we grant permissions via the CLI.
-
Assign a Role to a User
The following examples show how to assign a role to a Stardog user.
-
-
Suppose you had a Stardog user named
bob
- you could assign him the rolemyRole
using theuser addrole
Stardog Admin CLI command:stardog-admin user addrole --role myRole bob
-
-
-
Navigate to the “Security” ( ) section of Studio.
-
To assign a role to an existing user, first select the user you wish to assign the role to in the “USERS” pane, and select the “Assign Role” button in the top right window:
-
Select the role you’d like to assign to the user:
-
Create a User
The following examples show how to create users in Stardog.
See Setting Password Constraints to modify the default password policy.
Only a user with superuser privileges can create other users with superuser privileges.
-
-
Create the new user with the
user add
Stardog Admin CLI command:stardog-admin user add bob
-
-
-
Navigate to the “Security” ( ) section of Studio.
-
Select the button in the “USERS” pane:
-
Enter a username and password for the the new user and click “Add”.
-
Grant Explicit Permissions to a User
The following examples show how to grant explicit permissions to Stardog users.
There is nothing inherently insecure about setting explicit permissions for individual users, however it is highly recommend managing user permissions by assigning users to roles such that you can easily update user permissions in batches.
-
-
Grant permissions to the user
bob
such that it hasWRITE
access overmyDatabase
using theuser grant
Stardog Admin CLI command:stardog-admin user grant -a write -o "db:myDatabase" bob
- Note how the target resource (
-o
argument) is specifieddb:myDatabase
. A particular resource is denoted byresource_type_prefix:name
. All resource type prefixes are documented in Resources. When adding permissions via the CLI, resources must be specified like this.
- Note how the target resource (
-
-
-
To add permissions to the newly created user, select a user in the “USERS” pane, and then select the “Add Explicit Permission” button.
-
Grant a permission to the user. Remember, any action can be granted over any resource. See Actions and Resources for a description of all actions and resources. Below we grant the user
bob
WRITE
access over the the databasemyDatabase
which has a resource type ofdb
. When we add permissions via Studio, we can omit the resource type prefix when entering the resource name/identifier. This is not the case when we grant permissions via the CLI.
-
List a User and Role’s Permissions
The following examples show how to list a user and role’s permissions.
-
From the CLI, use the
user permission
Stardog Admin CLI command like so to view a user’s effective permissions:$ stardog-admin user permission bob +---------------+---------------+-------------+--------+ | Resource Type | Resource Name | Permissions | Source | +---------------+---------------+-------------+--------+ | db | myDatabase | --R---- | myRole | | user | bob | --RW--- | [bob] | +---------------+---------------+-------------+--------+
You can see from this view that the user
bob
is able toread
from the databasemyDatabase
because he is assigned to the rolemyRole
.myRole
is the source of this permission.You can view the permissions granted to a role by using the
role permission
Stardog Admin CLI command.$ stardog-admin role permission myRole +---------------+---------------+-------------+ | Resource Type | Resource Name | Permissions | +---------------+---------------+-------------+ | db | myDatabase | --R---- | +---------------+---------------+-------------+
-
To see a user’s permissions in Stardog Studio, navigate to the “Security” ( ) section of Studio and select a user to inspect their permissions.
We see that user
bob
is assigned the rolemyRole
from this view. We can navigate to themyRole
role to inspect the permissions assigned to this role to obtainbob
’s effective permissions.
Enable/Disable User
The following examples show how to enable and disable users.
-
To enable or disable a user in Stardog from the CLI use the
user enable
anduser disable
Stardog Admin CLI commands respectively.stardog-admin user disable bob
stardog-admin user enable bob
-
To enable or disable a user in Stardog Studio, select the user you wish you wish to enable/disable in the “USERS” pane within the “Security” ( ) section. At the top right of the window, select the
•••
button and enable/disable the user.
Change a User’s Password
The following examples show how to change a user’s password.
-
To change a user’s password in Stardog from the CLI use the
user passwd
Stardog Admin CLI command.stardog-admin user passwd bob
-
To change a user’s password in Stardog Studio, select the user of interest in the “USERS” pane within the “Security” ( ) section. At the top right of the window, select the
•••
button and select “Change Password.
Delete a User
The following examples show how to delete a Stardog user.
-
To delete a user from the CLI use the
user remove
Stardog Admin CLI command.stardog-admin user remove bob
-
To delete a user in Stardog Studio, select the user you wish you wish to delete in the “USERS” pane within the “Security” ( ) tab. At the top right of the window, select the
•••
button and select “Delete User”.
Remove a Role from a User
The following examples show how to remove a role from a Stardog user.
-
To remove a role from a user from the CLI, use the
user removerole
Stardog Admin CLI command.stardog-admin user removerole --role myRole bob
-
To remove a role from a user in Stardog Studio, select the user of interest in the “USERS” pane within the “Security” ( ) section. Select the
X
on the role you wish to remove from the user.
Delete a Role
The following examples show how to delete a role.
If a role is currently assigned to a user, you must remove the role from the user before deleting it.
-
To delete a role from the CLI use the
role remove
Stardog Admin CLI command.stardog-admin role remove myRole
-
To delete a role in Stardog Studio, select the role you wish you wish to delete in the “ROLES” pane within the “Security” ( ) section. At the top right of the window, select the
•••
button and select “Delete Role”.
Using a Password File
To avoid putting passwords into scripts or environment variables, you can put them into a suitably secured password file. If no credentials are passed explicitly in CLI invocations, or you do not ask Stardog to prompt you for credentials interactively, then it will look for credentials in a password file.
- On a Unix system, Stardog will look for a file called
.sdpass
in the home directory of the user Stardog is running as; - On a Windows system, it will look for
sdpass.conf
inApplication Data\stardog
in the home directory of the user Stardog is running as.
If the file is not found in these locations, Stardog will look in the location provided by the stardog.passwd.file
system property.
This password file is different from the services.sdpass
file that lives within a server’s $STARDOG_HOME
directory. .sdpass
is for clients providing credentials to Stardog servers. services.sdpass
is for the Stardog server itself providing credentials to remote endpoints when performing federated queries via the SERVICE keyword. The formats of both of these files are the same.
Password File Format
The format of the password file is as follows:
- Any line that starts with a
#
is ignored -
Each line contains a single password in the format:
hostname:port:database:username:password
- Wildcards,
*
, are permitted for any field but the password field; colons and backslashes in fields are escaped with\
.
For example:
#this is my password file; there are no others like it and this one is mine anyway...
*:*:*:flannery:aNahthu8
*:*:summercamp:jemima:foh9Moaz
Of course you should secure this file carefully, making sure that only the user that Stardog runs as can read it.