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 in Stardog Studio and the CLI.
Stardog Studio
-
Navigate to the “Security” ( ) section in Studio.
-
Select the button in the “ROLES” pane:
-
Enter a name for the new role:
CLI
-
Create the role using the
role add
Stardog Admin CLI command:$ stardog-admin role add myRole Successfully added role myRole.
Grant Permissions to a Role
The following examples show how to grant permissions to a role via Stardog Studio and the CLI.
Stardog Studio
-
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.
CLI
-
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 Successfully granted the permission.
- 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 (
Assign a Role to a User
The following examples show how to assign a role to a Stardog user via Stardog Studio and the CLI.
Stardog Studio
-
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:
CLI
-
Suppose we had a Stardog user named
bob
- we could assign him the rolemyRole
using theuser addrole
Stardog Admin CLI command:$ stardog-admin user addrole --role myRole bob Role myRole has been successfully assigned to user bob.
Create a User
In the following examples, we show how to create users in Stardog via Stardog Studio and the CLI.
Stardog Studio
-
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”.
The default password policy can be modified. See Setting Password Constraints for more information.
CLI
-
Create the new user with the
user add
Stardog Admin CLI command:$ stardog-admin user add bob New password for user bob: Confirm new password for user bob: Successfully created user bob.
Grant Explicit Permissions to a User
In the following examples, we show how to grant explicit permissions to Stardog users via Stardog Studio and the CLI.
There is nothing inherently insecure about setting explicit permissions for individual users, however we highly recommend managing user permissions by assigning users to roles such that you can easily update user permissions in batches.
Stardog Studio
-
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.
CLI
-
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 Successfully granted the permission.
- 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 (
List a User and Role’s Permissions
You can use easily view a user’s permissions via Stardog Studio and the CLI.
Stardog Studio
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 role myRole
from this view. We can navigate to the myRole
role to inspect the permissions assigned to this role to obtain bob
’s effective permissions.
CLI
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 to read
from the database myDatabase
because he is assigned to the role myRole
. 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---- |
+---------------+---------------+-------------+
Enable/Disable User
The following examples show how to enable and disable users via Stardog Studio and the CLI.
Stardog Studio
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.
CLI
To enable or disable a user in Stardog from the CLI use the user enable
and user disable
Stardog Admin CLI commands respectively.
$ stardog-admin user disable bob
User bob has been successfully disabled.
$ stardog-admin user enable bob
User bob has been successfully enabled.
Change a User’s Password
The following examples show how to change a user’s password via Stardog Studio and the CLI.
Stardog Studio
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.
CLI
To change a user’s password in Stardog from the CLI use the user passwd
Stardog Admin CLI command.
$ stardog-admin user passwd bob
New password for user bob:
Confirm new password for user bob:
Password changed successfully for user bob.
Delete a User
The following examples show how to delete a user via Stardog Studio and the CLI.
Stardog Studio
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”.
CLI
To delete a user from the CLI use the user remove
Stardog Admin CLI command.
$ stardog-admin user remove bob
Successfully dropped user bob.
Remove a Role from a User
The following examples show how to remove a role from a Stardog user via Stardog Studio and the CLI.
Stardog Studio
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.
CLI
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
Role myRole has been successfully unassigned from user bob.
Delete a Role
The following examples show how to delete a role via Stardog Studio and the CLI.
If a role is currently assigned to a user, you must remove the role from the user before deleting it.
Stardog Studio
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”.
CLI
To delete a role from the CLI use the role remove
Stardog Admin CLI command.
$ stardog-admin role remove myRole
Successfully dropped role myRole.
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.
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.