Auth App Service Configuration

Table of Contents

Introduction
Default Values
The auth Service Family
Service Startup
App Tokens
Configuration
- Environment Variables
- YAML Example

Introduction

The Infinite Scale Auth App service provides authentication for 3rd party apps.

With the auth-app service, you can create tokens that can be used to authenticate 3rd party apps accessing Infinite Scale.

To enable auth-app, you first must set PROXY_ENABLE_APP_AUTH to true.

The auth-app service does not start automatically and must be started manually. For more details see the Start Infinite Scale section.
The reason for excluding the auth-app service from autostart is, that generating access tokens is security relevant.

Default Values

Auth Basic listens on port 9245 by default.

The `auth` Service Family

Infinite Scale uses several authentication services for different use cases. All services that start with auth- are part of the authentication service family. Each member authenticates requests with different scopes.

As of now, these `auth` services exist
auth-app	Handles 3rd party app authentication.
auth-basic	Handles basic authentication.
auth-bearer	Handles OIDC authentication.
auth-machine	Handles interservice authentication when a user is impersonated.
auth-service	Handles interservice authentication when using service accounts.

As of now, these auth services exist

auth-app

Handles 3rd party app authentication.

auth-basic

Handles basic authentication.

auth-bearer

Handles OIDC authentication.

auth-machine

Handles interservice authentication when a user is impersonated.

auth-service

Handles interservice authentication when using service accounts.

Service Startup

Because this service is not started automatically, a manual start needs to be initiated which can be done in several ways, only one example using an environment variable is shown below. For more details see the Start Infinite Scale section.
To configure the service usage, an environment variable for the proxy service needs to be set to allow app authentication.

Environment variables related to starting the auth-app service

OCIS_ADD_RUN_SERVICES=auth-app  # deployment specific. Alternatively you can start the service explicitly via the command line.

PROXY_ENABLE_APP_AUTH=true      # mandatory, allow app authentication. In case of a distributed environment, this envvar needs to be set in the proxy service.

App Tokens

In any example, replace <your host[:port]> with the URL:port of your Infinite Scale instance, and ${xxx} accordingly. Note that variables in curly braces are command variables prepared for use with shell environment variables. The complete notation can be fully replaced by their value.

Via CLI

App Tokens are used to authenticate 3rd party access via https like when using curl (apps) to access an API endpoint. These apps need to authenticate themselves, as no logged in user authenticates the request. To be able to use an app token, one must first create a token via the cli. Replace the user-name with an existing Infinite Scale 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.

ocis auth-app create --user-name=${user} --expiration=${token_expiration}

Once generated, these tokens can be used to authenticate requests to ocis. They are passed as part of the request as Basic Auth header.

Via API

An in-depth method to manage tokens is to use the API, which needs a bit more preparation, but offers more possibilities.

The auth-app service provides an API to create (POST), list (GET) and delete (DELETE) tokens at the /auth-app/tokens endpoint.

When using curl for the respective command, you need to authenticate with a header. To do so, get from the browsers developer console the currently active bearer token. Consider that this token has a short lifetime.

The active bearer token authenticates the user the token was issued for. Which means that any action taken and any output printed is only valid for the user authenticated.

Create a token
It is likely more convenient to generate a user token with the ocis command described above.
The POST request requires:
- An expiry key/value pair in the form of expiry=<number><h|m|s>
  Example: expiry=72h
- An active bearer token.
  To get an active bearer token, see the Preparation section of the referenced document for more details.
Command
curl --request POST "https://<your host:9200>/auth-app/tokens?expiry=${token_expiration}" \ --header "accept: application/json" \ --header "authorization: Bearer ${token}"
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" }

List tokens
The GET request only requires an active bearer token for authentication.

To get an active bearer token, see the Preparation section of the referenced document for more details.

Note that --request GET is technically not required because it is curl default.

Command

curl --request GET "https://<your host:9200>/auth-app/tokens" \
     --header "accept: application/json" \
     --header "authorization: Bearer ${token}"

Example output:

[
  {
    "token": "$2a$11$EyudDGAJ18bBf5NG6PL9Ru9gygZAu0oPyLawdieNjGozcbXyyuUhG",
    "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": "$2a$11$dfRBQrxRMPg8fvyvkFwaX.IPoIUiokvhzK.YNI/pCafk0us3MyPzy",
    "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>
  Example: token=$2a$11$EyudDGAJ18bBf5NG6PL9Ru9gygZAu0oPyLawdieNjGozcbXyyuUhG
- An active bearer token
  To get an active bearer token, see the Preparation section of the referenced document for more details.
Command
curl --request DELETE "https://<your host:9200>/auth-app/tokens?token=${token_issued}" \ --header "accept: application/json" \ --header "authorization: Bearer ${token}"

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 but using their own bearer token for authentication. 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=${user}
- Example:
  userID=4c510ada- … -42cdf82c3d51
The userName in the form of: userName=${user}
- Example:
  userName=einstein

A final create request would then look like, where the bearer token is the one of the admin and not of the user: