# IAM.AUTH

> Log the connection in through an LDAP directory, an OpenID Connect token, or an ACL user.

URL: https://docs.hotkv.com/commands/iam-auth/

```
IAM.AUTH ldap username password
IAM.AUTH oidc username|- token
IAM.AUTH local username password
```

- Group: IAM
- Complexity: O(1) for local, otherwise the time the directory or the identity provider takes
- HotKV Cloud: not available
- On-Premise: requires the enterprise-iam license feature

`IAM.AUTH` logs the connection in. Like `AUTH` it can be sent before the
connection is authenticated, which is the point of it, and it needs no
permission. If the connection was already logged in through IAM, the new login
replaces the old session.

| Source | What is checked |
| --- | --- |
| `ldap` | `password` is the user's password in the LDAP directory (`iam.ldap.*`). The connection waits while the directory is asked, and other clients are served meanwhile |
| `oidc` | `token` is a signed token from the identity provider (`iam.oidc.*`). `username` is `-`, or the name the token must carry |
| `local` | The same check as [AUTH](https://docs.hotkv.com/commands/auth/index.md): an ACL user and its password. The connection stays that ACL user; the session only shows in [IAM.SESSION.LIST](https://docs.hotkv.com/commands/iam-session-list/index.md) |

For `ldap` and `oidc` the login gets the roles given to its user name, to
`ldap:name` or `oidc:name`, and to its groups
([IAM.USER.ASSIGN](https://docs.hotkv.com/commands/iam-user-assign/index.md)), and the connection runs as the
identity `ldap:name#id` or `oidc:name#id`: it can run what those roles allow, on
their keys, and nothing else. A login with no role is refused. An `oidc` session
ends, and its connection is closed, when the token's `exp` passes. See
[Roles and single sign-on](https://docs.hotkv.com/operate/iam/index.md) for the setup and for what is checked
in a token.

`password` and `token` are never shown by `SLOWLOG` or `MONITOR`. Failed logins
are in [ACL LOG](https://docs.hotkv.com/commands/acl-log/index.md). An address that fails
`iam.max-login-failures` logins (10 by default) in a minute is turned away for the
rest of it.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Logged in | Integer: the session ID | Integer: the session ID |
| Wrong password, wrong token, unknown user, or a source that is down | Error `WRONGPASS invalid username-password pair or user is disabled.` | Same error |
| The login is right but has no role | Error `NOPERM this user has no role: ask an administrator to assign one` | Same error |
| Too many failed logins from the address | Error `ERR too many failed logins from this address: try again in a minute` | Same error |
| Too many logins waiting on the directory or provider | Error `BUSY logins are waiting on the directory or the identity provider: try again` | Same error |
| LDAP or OIDC login is not set up | Error `ERR ldap login is not set up on this server (see iam.ldap.* settings)` | Same error |
| Any other source | Error `ERR unknown auth source, expected local, ldap or oidc` | Same error |
| No license that includes `enterprise-iam` | Error `NOLICENSE enterprise-iam requires a HotKV license. Contact sales@hotkv.com` | Same error |

## Examples

```
127.0.0.1:6379> IAM.AUTH ldap alice alice-password
(integer) 7
127.0.0.1:6379> ACL WHOAMI
"ldap:alice#7"
127.0.0.1:6379> IAM.AUTH oidc - eyJhbGciOiJSUzI1NiIs...
(integer) 8
127.0.0.1:6379> IAM.AUTH oidc - garbage
(error) WRONGPASS invalid username-password pair or user is disabled.
```

## Compatibility

HotKV-only command. `AUTH username password` also logs in an LDAP user, when the
ACL has no user of that name.

## See also

[AUTH](https://docs.hotkv.com/commands/auth/index.md), [IAM.SESSION.LIST](https://docs.hotkv.com/commands/iam-session-list/index.md),
[IAM.USER.ASSIGN](https://docs.hotkv.com/commands/iam-user-assign/index.md)