366 lines
7.6 KiB
Markdown
366 lines
7.6 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Auth Backend: RADIUS"
|
|
sidebar_current: "docs-auth-radius"
|
|
description: |-
|
|
The "radius" auth backend allows users to authenticate with Vault using an existing RADIUS server.
|
|
---
|
|
|
|
# Auth Backend: RADIUS
|
|
|
|
Name: `radius`
|
|
|
|
The "radius" auth backend allows users to authenticate with Vault using
|
|
an existing RADIUS server that accepts the PAP authentication scheme.
|
|
|
|
The mapping of users to Vault policies is managed by using the
|
|
`users/` path.
|
|
|
|
Optionally, a configurable set of policies can be granted to all users that
|
|
can successfully authenticate but are not registered in the `users/` path.
|
|
|
|
## Authentication
|
|
|
|
#### Via the CLI
|
|
|
|
```
|
|
$ vault auth -method=userpass -path=radius \
|
|
username=foo \
|
|
password=bar
|
|
```
|
|
|
|
#### Via the API
|
|
|
|
The endpoint for the login is `auth/radius/login/<username>`.
|
|
|
|
The password should be sent in the POST body encoded as JSON.
|
|
|
|
```shell
|
|
$ curl $VAULT_ADDR/v1/auth/radius/login/mitchellh \
|
|
-d '{ "password": "foo" }'
|
|
```
|
|
|
|
Alternatively a POST request can be made to `auth/radius/login/`
|
|
with both `username` and `password` sent in the POST body encoded as JSON.
|
|
|
|
The response will be in JSON. For example:
|
|
|
|
```javascript
|
|
{
|
|
"lease_id": "",
|
|
"renewable": false,
|
|
"lease_duration": 0,
|
|
"data": null,
|
|
"auth": {
|
|
"client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
|
|
"policies": [
|
|
"admins"
|
|
],
|
|
"metadata": {
|
|
"username": "mitchellh"
|
|
},
|
|
"lease_duration": 0,
|
|
"renewable": false
|
|
}
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
First, you must enable the RADIUS auth backend:
|
|
|
|
```
|
|
$ vault auth-enable radius
|
|
Successfully enabled 'radius' at 'radius'!
|
|
```
|
|
|
|
Now when you run `vault auth -methods`, the RADIUS backend is
|
|
available:
|
|
|
|
```
|
|
Path Type Description
|
|
token/ token token based credentials
|
|
radius/ radius
|
|
```
|
|
|
|
To use the radius auth backend, it must first be configured with connection
|
|
details for your RADIUS server.
|
|
The configuration options are detailed below in the API docs.
|
|
Configuration is written to `auth/radius/config`.
|
|
|
|
To use the "radius" auth backend, an operator must configure a
|
|
mapping between users and policies. An example is shown below.
|
|
Use `vault path-help` for more details.
|
|
|
|
```
|
|
$ vault write auth/radius/users/mitchellh \
|
|
policies=admins
|
|
...
|
|
```
|
|
|
|
The above creates a new mapping for user "mitchellh" that
|
|
will be associated with the "admins" policy.
|
|
|
|
Alternatively, Vault can assign a configurable set of policies to
|
|
any user that successfully authenticates with the RADIUS server but
|
|
has no explicit mapping in the `users/` path.
|
|
This is done through the `unregistered_user_policies` configuration parameter.
|
|
|
|
## API
|
|
|
|
### /auth/radius/config
|
|
#### POST
|
|
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Configures the connection parameters and shard secret used to communicate with RADIUS
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>POST</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/radius/config`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>
|
|
<span class="param">host</span>
|
|
<span class="param-flags">required</span>
|
|
The RADIUS server to connect to. Examples: `radius.myorg.com`, `127.0.0.1`
|
|
</li>
|
|
<li>
|
|
<span class="param">port</span>
|
|
<span class="param-flags">optional</span>
|
|
The UDP port where the RADIUS server is listening on. Defaults is 1812
|
|
</li>
|
|
<li>
|
|
<span class="param">secret</span>
|
|
<span class="param-flags">required</span>
|
|
The RADIUS shared secret
|
|
</li>
|
|
<li>
|
|
<span class="param">unregistered_user_policies</span>
|
|
<span class="param-flags">optional</span>
|
|
A Comma-Separated list of policies to be granted to unregistered users
|
|
</li>
|
|
<li>
|
|
<span class="param">dial_timeout</span>
|
|
<span class="param-flags">optional</span>
|
|
Number of second to wait for a backend connection before timing out. Defaults is 10
|
|
</li>
|
|
<li>
|
|
<span class="param">read_timeout</span>
|
|
<span class="param-flags">optional</span>
|
|
Number of second to wait for a backend response before timing out. Defaults is 10
|
|
</li>
|
|
<li>
|
|
<span class="param">nas_port</span>
|
|
<span class="param-flags">optional</span>
|
|
The NAS-Port attribute of the RADIUS request. Defaults is 10
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
### /auth/radius/users/[username]
|
|
#### POST
|
|
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Registers a new user and maps a set of policies to it.
|
|
This path honors the distinction between the `create` and `update` capabilities inside ACL policies.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>POST</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/radius/users/<username>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>
|
|
<span class="param">username</span>
|
|
<span class="param-flags">required</span>
|
|
Username for this user.
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
<dd>
|
|
<ul>
|
|
<li>
|
|
<span class="param">policies</span>
|
|
<span class="param-flags">optional</span>
|
|
Comma-separated list of policies.
|
|
If set to empty string, only the `default` policy will be applicable to the user.
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
#### GET
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Reads the properties of an existing username.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>GET</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/radius/users/[username]`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>
|
|
|
|
```javascript
|
|
{
|
|
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
|
|
"lease_id": "",
|
|
"lease_duration": 0,
|
|
"renewable": false,
|
|
"data": {
|
|
"policies": "default,dev"
|
|
},
|
|
"warnings": null
|
|
}
|
|
```
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
#### DELETE
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Deletes an existing username from the backend.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>DELETE</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/radius/users/[username]`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
### /auth/radius/login
|
|
### /auth/radius/login/[username]
|
|
#### POST
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Login with the username and password.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>POST</dd>
|
|
|
|
<dt>URLS</dt>
|
|
<dd>`/auth/radius/login`</dd>
|
|
<dd>`/auth/radius/login/[username]`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>
|
|
<span class="param">username</span>
|
|
<span class="param-flags">required</span>
|
|
Username for the authenticating user.
|
|
</li>
|
|
<li>
|
|
<span class="param">password</span>
|
|
<span class="param-flags">required</span>
|
|
Password for the authenticating user.
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>
|
|
|
|
```javascript
|
|
{
|
|
"lease_id": "",
|
|
"renewable": false,
|
|
"lease_duration": 0,
|
|
"data": null,
|
|
"warnings": null,
|
|
"auth": {
|
|
"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
|
|
"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
|
|
"policies": ["default"],
|
|
"metadata": {
|
|
"username": "vishal"
|
|
},
|
|
"lease_duration": 7200,
|
|
"renewable": true
|
|
}
|
|
}
|
|
```
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
### /auth/radius/users
|
|
#### LIST
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
List the users registered with the backend.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>LIST/GET</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/radius/users` (LIST) `/auth/radius/users?list=true` (GET)</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>
|
|
|
|
```javascript
|
|
[
|
|
"devuser",
|
|
"produser"
|
|
]
|
|
```
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
|