Configuration: Authentication & Authorization

RavenDB comes with a built-in authentication functionality and it supports two types of authentication:

• Windows Authentication
• OAuth Authentication

Appropriate authentication type is chosen by examining incoming request headers. By default all actions except read-only are being authenticated. To determine which actions will be authenticated, please refer to Raven/AnonymousAccess configuration setting.

Security system - OSS vs commercial use

The authentication feature is available only in commercial use of RavenDB. You will be able to enable it if you provide a valid commercial license to your database instance. For an open-source software the only available setting is Raven/AnonymousAccess = Admin, which means that no authentication is required. Then any user will have all administrative permissions. An attempt to setup authentication for a database working under AGPL license will result in an exception thrown by a server.

In order to prevent security issues in commercial systems related to a temporary lack of a valid license (e.g. if it just expired), RavenDB stores info about a last seen valid license. This way despite the fact that the license is temporary invalid, the authentication will be still working.

Windows Authentication

When action (request) needs to be authenticated and no other authentication method is detected, then the Windows Authentication is chosen. Worth noting is that all /admin endpoint requests are processed using this method.

By default only admins and backup operator users have access to all databases. Other users and groups don't have any access to resources, but this can be easily changed by editing the Raven/Authorization/WindowsSettings document in the system database. The document consists of list of users and groups that contain the list of accessible databases.

{
	"RequiredGroups": [],
	"RequiredUsers": [
		{
			"Name": "IIS AppPool\\DefaultAppPool",
			"Enabled": true,
			"Databases": [
				{
					"Admin": false,
					"TenantId": "Northwind",
					"ReadOnly": true
				}
			]
		}
	]
}

Above example gives a read-only access to Northwind to IIS AppPool\DefaultAppPool. Similar effect can be achieved using the Studio and editing system database settings.

Allow to login by using an account with a blank password

By default Windows Authentication does not allow to use an account that has a blank password. However, if you really need this, you can disable this Windows security policy using:

Raven.Server.exe /allow-blank-password-use

It will disable the following policy Limit local account use of blank passwords to console logon only on your Windows machine. In order to revert your changes you can use:

Raven.Server.exe /deny-blank-password-use

to get back into the default setting.

OAuth Authentication

Second supported authentication type is an OAuth authentication and to simplify the process, we have introduced the API key authentication described below.

Example - API keys

To authenticate the user by using API keys we need to create a document with Raven/ApiKeys/key_name as a key and ApiKeyDefinition as a content on the system database.

store
	.DatabaseCommands
	.Put(
		"Raven/ApiKeys/sample",
		null,
		RavenJObject.FromObject(new ApiKeyDefinition
		{
			Name = "sample",
			Secret = "ThisIsMySecret",
			Enabled = true,
			Databases = new List<ResourceAccess>
			        {
				        new ResourceAccess {TenantId = "*"},
				        new ResourceAccess {TenantId = Constants.SystemDatabase},
			        }
		}), new RavenJObject());

Now, to perform any actions against specified database (system database must be declared explicitly), we need to provide the API key.

DocumentStore store = new DocumentStore
{
	ApiKey = "sample/ThisIsMySecret",
	Url = "http://localhost:8080/"
};

Debugging authentication issues

To grant the ability to resolve authentication issues, we have introduced /debug/user-info endpoint that will return information about current authenticated user and that can be accessed by executing the following code:

RavenJToken json = store
	.JsonRequestFactory
	.CreateHttpJsonRequest(new CreateHttpJsonRequestParams(null, store.Url + "/debug/user-info", "GET", store.DatabaseCommands.PrimaryCredentials, store.Conventions))
	.ReadResponseJson();

The returned results vary on the current authentication type:

• Anonymous

{
    "Remark": "Using anonymous user"
}

• Windows Authentication with full access to all databases:

{
    "Remark": "Using windows auth",
	"User": "RavenUser",
	"IsAdmin": "True"
}

• Windows Authentication with restricted access:

{
    "Remark": "Using windows auth",
	"User": "RavenUser",
	"IsAdmin": "False",
	"AdminDatabases": [],
    "ReadOnlyDatabases": [ "ReadOnlyNorthwind" ],
    "ReadWriteDatabases": [ "ReadWriteNorthwind" ]
}

• OAuth Authentication:

{
    "Remark": "Using OAuth",
	"User": "RavenUser",
	"IsAdmin": "False",
	"TokenBody": "<token_here>"
}