# IAM.USER.ASSIGN

> Give a role to a user name, to the users of one source, or to a group.

URL: https://docs.hotkv.com/commands/iam-user-assign/

```
IAM.USER.ASSIGN principal role
```

- Group: IAM
- Complexity: O(1)
- HotKV Cloud: not available
- On-Premise: requires the enterprise-iam license feature

`IAM.USER.ASSIGN` gives a role to a principal. A login gets every role given to
any of its principals, so a login that is in three groups can have the roles of
all three. Giving a role a principal already has changes nothing. The change is
the same on every node of a cluster, is saved with the data, and applies to open
sessions at once.

`principal` is one of:

| Form | Matches |
| --- | --- |
| `alice` | The user of that name, whichever way they logged in |
| `ldap:alice`, `oidc:alice` | The user, only through that source |
| `group:name` | Everyone the directory or the token lists in that group, by its name or by its full DN (`group:ops` and `group:cn=ops,ou=groups,dc=example,dc=com` both match the group `cn=ops,ou=groups,dc=example,dc=com`) |

Names are matched exactly as they are typed at login, including case. The
principal does not have to exist anywhere yet, and is 1 to 1024 characters. See
[Roles and single sign-on](https://docs.hotkv.com/operate/iam/index.md).

## Return value

Simple string `OK` in RESP2 and RESP3, or one of these errors:

| Case | Error |
| --- | --- |
| No such role | `ERR role not found` |
| An empty principal, or one over 1024 characters | `ERR a user name, ldap:name, oidc:name or group:name is 1 to 1024 characters` |
| No license that includes `enterprise-iam` | `NOLICENSE enterprise-iam requires a HotKV license. Contact sales@hotkv.com` |

## Examples

```
127.0.0.1:6379> IAM.USER.ASSIGN alice app
OK
127.0.0.1:6379> IAM.USER.ASSIGN group:developers app
OK
127.0.0.1:6379> IAM.USER.ASSIGN "group:cn=ops,ou=groups,dc=example,dc=com" admin
OK
127.0.0.1:6379> IAM.USER.ASSIGN oidc:bob reporting
OK
127.0.0.1:6379> IAM.USER.ASSIGN alice nosuch
(error) ERR role not found
```

## Compatibility

HotKV-only command.

## See also

[IAM.USER.UNASSIGN](https://docs.hotkv.com/commands/iam-user-unassign/index.md), [IAM.USER.LIST](https://docs.hotkv.com/commands/iam-user-list/index.md),
[IAM.ROLE.CREATE](https://docs.hotkv.com/commands/iam-role-create/index.md)