mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-02-06 20:32:06 -05:00
7d193c78dd
We return UUIDs for the token not the actually token hash since at least OpenCloud 2.0.0 Related: #1832
140 lines
4.8 KiB
Markdown
140 lines
4.8 KiB
Markdown
# Auth-App
|
|
|
|
The auth-app service provides authentication for 3rd party apps unable to use
|
|
OpenID Connect. The service is enabled by default and started automatically. It
|
|
is possible to disable the service by setting:
|
|
|
|
```bash
|
|
OC_EXCLUDE_RUN_SERVICES=auth-app # deployment specific. Removes service from the list of automatically started services, use with single-binary deployments
|
|
PROXY_ENABLE_APP_AUTH=false # mandatory, disables app authentication. In case of a distributed environment, this envvar needs to be set in the proxy service.
|
|
```
|
|
|
|
## App Tokens
|
|
|
|
App Tokens are password specifically generated to be used by 3rd party applications
|
|
for authentication when accessing the OpenCloud API endpoints. To
|
|
be able to use an app token, one must first create a token. There are different
|
|
options of creating a token.
|
|
|
|
## Important Security Note
|
|
|
|
When using an external IDP for authentication, App Token are NOT invalidated
|
|
when the user is disabled or locked in that external IDP. That means the user
|
|
will still be able to use its existing App Tokens for authentication for as
|
|
long as the App Tokes are valid.
|
|
|
|
## Managing App Tokens
|
|
|
|
### Via API
|
|
|
|
Please note: This API is preliminary. In the future we will provide endpoints
|
|
in the `graph` service for allowing the management of App Tokens.
|
|
|
|
The `auth-app` service provides an API to create (POST), list (GET) and delete (DELETE) tokens at the `/auth-app/tokens` endpoint.
|
|
|
|
* **Create a token**\
|
|
The POST request requires:
|
|
* A `expiry` key/value pair in the form of `expiry=<number><h|m|s>`\
|
|
Example: `expiry=72h`
|
|
```bash
|
|
curl --request POST 'https://<your host:9200>/auth-app/tokens?expiry={value}' \
|
|
--header 'accept: application/json'
|
|
```
|
|
Example output:
|
|
```
|
|
{
|
|
"token": "3s2K7816M4vuSpd5",
|
|
"expiration_date": "2024-08-08T13:42:42.796888022+02:00",
|
|
"created_date": "2024-08-07T13:42:42+02:00",
|
|
"label": "Generated via API"
|
|
}
|
|
```
|
|
|
|
Note, that this is the only time the app token will be returned in cleartext. To use the token
|
|
please copy it from the response.
|
|
|
|
* **List tokens**\
|
|
```bash
|
|
curl --request GET 'https://<your host:9200>/auth-app/tokens' \
|
|
--header 'accept: application/json'
|
|
```
|
|
|
|
Note that the `token` value in the response to the "List Tokens` request is not the actual
|
|
app token, but the UUID of the token. So this value cannot be used for authenticating
|
|
with the token.
|
|
|
|
Example output:
|
|
```
|
|
[
|
|
{
|
|
"token": "155f402e-1c5c-411c-92d4-92f3b612cd99"
|
|
"expiration_date": "2024-08-08T13:44:31.025199075+02:00",
|
|
"created_date": "2024-08-07T13:44:31+02:00",
|
|
"label": "Generated via Impersonation API"
|
|
},
|
|
{
|
|
"token": "8c606bdb-e22e-4094-9304-732fd4702bc9"
|
|
"expiration_date": "2024-08-08T13:46:41.936052281+02:00",
|
|
"created_date": "2024-08-07T13:46:42+02:00",
|
|
"label": "Generated via Impersonation API"
|
|
}
|
|
]
|
|
```
|
|
|
|
* **Delete a token**\
|
|
The DELETE request requires:
|
|
* A `token` key/value pair in the form of `token=<token_issued>`. The value needs to be the hashed value as returned by the `List Tokens` respone.\
|
|
Example: `token=8c606bdb-e22e-4094-9304-732fd4702bc9`
|
|
```bash
|
|
curl --request DELETE 'https://<your host:9200>/auth-app/tokens?token={value}' \
|
|
--header 'accept: application/json'
|
|
```
|
|
|
|
### Via Impersonation API
|
|
|
|
When setting the environment variable `AUTH_APP_ENABLE_IMPERSONATION` to
|
|
`true`, admins will be able to use the `/auth-app/tokens` endpoint to create
|
|
tokens for other users. This can be important for migration scenarios, but
|
|
should not be considered for regular tasks on a production system for security
|
|
reasons.
|
|
|
|
To impersonate, the respective requests from the CLI commands above extend with
|
|
the following parameters, where you can use one or the other:
|
|
|
|
* The `userID` in the form of: `userID={value}`\
|
|
Example:\
|
|
`userID=4c510ada- ... -42cdf82c3d51`
|
|
|
|
* The `userName` in the form of: `userName={value}`\
|
|
Example:\
|
|
`userName=alan`
|
|
|
|
Example:\
|
|
A final create request would then look like:
|
|
```bash
|
|
curl --request POST 'https://<your host:9200>/auth-app/tokens?expiry={value}&userName={value}' \
|
|
--header 'accept: application/json'
|
|
```
|
|
|
|
### Via CLI (developer only)
|
|
|
|
As the CLI is using the internal CS3Apis this needs access to the reva gateway
|
|
service. This is mainly of developer (and admin) usage.
|
|
Replace the `user-name` with an existing user. For the `token-expiration`, you
|
|
can use any time abbreviation from the following list: `h, m, s`. Examples:
|
|
`72h` or `1h` or `1m` or `1s.` Default is `72h`.
|
|
|
|
```bash
|
|
opencloud auth-app create --user-name={user-name} --expiration={token-expiration}
|
|
```
|
|
|
|
## Authenticating using App Tokens
|
|
|
|
To autenticate using an App Token simply use the username for which token was generated
|
|
and the token value as returned by the "Create Token" request.
|
|
|
|
```bash
|
|
curl -u <username>:<tokenvalue> 'https://<your host>/graph/v1.0/me' \
|
|
--header 'accept: application/json'
|
|
```
|