Home Getting Started Installation & Setup Development & Integration Deployment & Operations Data Management Technical Support Platform Updates

DocsDeployment & OperationsOperating Stardogmanaging users and roles

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.

<details open markdown="block"> <summary> Page Contents </summary> 1. TOC </details>

Setting Password Constraints

To set up 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 has READ access over myDatabase using the role grant Stardog Admin CLI command:
```
stardog-admin role grant -n myRole -a read -o db:myDatabase
```
- Note how the target resource (-o argument) is specified db:myDatabase. A particular resource is denoted by resource_type_prefix:name. All resource type prefixes are documented in Resources. When adding permissions via the CLI, resources must be specified like this.
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 role READ access over the the database myDatabase, which has a resource type of db.

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 role myRole using the user 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 to manage user permissions by assigning users to roles so you can update user permissions in batches.

Grant permissions to the user bob such that it has WRITE access over myDatabase using the user grant Stardog Admin CLI command:
```
stardog-admin user grant -a write -o "db:myDatabase" bob
```
- Note how the target resource (-o argument) is specified db:myDatabase. A particular resource is denoted by resource_type_prefix:name. All resource type prefixes are documented in Resources. When adding permissions via the CLI, resources must be specified like this.
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 database myDatabase, which has a resource type of db. 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 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----     |
+---------------+---------------+-------------+

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.

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 and user disable Stardog Admin CLI commands, respectively:

stardog-admin user enable bob

stardog-admin user disable 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 in Application 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 a password file
*:*:*:flannery:aNahthu8
*:*:summercamp:jemima:foh9Moaz

Secure this file carefully, making sure only the user Stardog runs as can read it.