Auth App Service Configuration

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.

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

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-name} --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 preperation, 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. In any example, replace <your host[:port]> with the URL:port of your Infinite Scale instance, and {token} {value} accordingly.

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={value}' \
         --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={value}' \
         --header 'accept: application/json' \
         --header 'authorization: Bearer {token}'

Configuration

Environment Variables

The auth-app service is configured via the following environment variables. Read the Environment Variable Types documentation for important details. Column IV shows with which release the environment variable has been introduced.

  • master + Rolling 6.6.1

Environment variables for the auth-app service
Name IV Type Default Value Description

OCIS_TRACING_ENABLED
AUTH_APP_TRACING_ENABLED

7.0.0

bool

false

Activates tracing.

OCIS_TRACING_TYPE
AUTH_APP_TRACING_TYPE

7.0.0

string

The type of tracing. Defaults to '', which is the same as 'jaeger'. Allowed tracing types are 'jaeger' and '' as of now.

OCIS_TRACING_ENDPOINT
AUTH_APP_TRACING_ENDPOINT

7.0.0

string

The endpoint of the tracing agent.

OCIS_TRACING_COLLECTOR
AUTH_APP_TRACING_COLLECTOR

7.0.0

string

The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset.

OCIS_LOG_LEVEL
AUTH_APP_LOG_LEVEL

7.0.0

string

The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.

OCIS_LOG_PRETTY
AUTH_APP_LOG_PRETTY

7.0.0

bool

false

Activates pretty log output.

OCIS_LOG_COLOR
AUTH_APP_LOG_COLOR

7.0.0

bool

false

Activates colorized log output.

OCIS_LOG_FILE
AUTH_APP_LOG_FILE

7.0.0

string

The path to the log file. Activates logging to this file if set.

AUTH_APP_DEBUG_ADDR

7.0.0

string

127.0.0.1:9245

Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.

AUTH_APP_DEBUG_TOKEN

7.0.0

string

Token to secure the metrics endpoint.

AUTH_APP_DEBUG_PPROF

7.0.0

bool

false

Enables pprof, which can be used for profiling.

AUTH_APP_DEBUG_ZPAGES

7.0.0

bool

false

Enables zpages, which can be used for collecting and viewing traces in-memory.

AUTH_APP_GRPC_ADDR

7.0.0

string

127.0.0.1:9246

The bind address of the GRPC service.

OCIS_GRPC_PROTOCOL
AUTH_APP_GRPC_PROTOCOL

7.0.0

string

tcp

The transport protocol of the GRPC service.

AUTH_APP_HTTP_ADDR

pre5.0

string

127.0.0.1:9247

The bind address of the HTTP service.

AUTH_APP_HTTP_ROOT

pre5.0

string

/

Subdirectory that serves as the root for this HTTP service.

OCIS_CORS_ALLOW_ORIGINS
AUTH_APP_CORS_ALLOW_ORIGINS

pre5.0

[]string

[*]

A list of allowed CORS origins. See following chapter for more details: Access-Control-Allow-Origin at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin. See the Environment Variable Types description for more details.

OCIS_CORS_ALLOW_METHODS
AUTH_APP_CORS_ALLOW_METHODS

pre5.0

[]string

[GET POST DELETE]

A list of allowed CORS methods. See following chapter for more details: Access-Control-Request-Method at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method. See the Environment Variable Types description for more details.

OCIS_CORS_ALLOW_HEADERS
AUTH_APP_CORS_ALLOW_HEADERS

pre5.0

[]string

[Authorization Origin Content-Type Accept X-Requested-With X-Request-Id Ocs-Apirequest]

A list of allowed CORS headers. See following chapter for more details: Access-Control-Request-Headers at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Headers. See the Environment Variable Types description for more details.

OCIS_CORS_ALLOW_CREDENTIALS
AUTH_APP_CORS_ALLOW_CREDENTIALS

pre5.0

bool

true

Allow credentials for CORS.See following chapter for more details: Access-Control-Allow-Credentials at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials.

OCIS_HTTP_TLS_ENABLED

pre5.0

bool

false

Activates TLS for the http based services using the server certifcate and key configured via OCIS_HTTP_TLS_CERTIFICATE and OCIS_HTTP_TLS_KEY. If OCIS_HTTP_TLS_CERTIFICATE is not set a temporary server certificate is generated - to be used with PROXY_INSECURE_BACKEND=true.

OCIS_HTTP_TLS_CERTIFICATE

pre5.0

string

Path/File name of the TLS server certificate (in PEM format) for the http services.

OCIS_HTTP_TLS_KEY

pre5.0

string

Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services.

OCIS_JWT_SECRET
AUTH_APP_JWT_SECRET

7.0.0

string

The secret to mint and validate jwt tokens.

OCIS_REVA_GATEWAY

pre5.0

string

com.owncloud.api.gateway

The CS3 gateway endpoint.

OCIS_GRPC_CLIENT_TLS_MODE

pre5.0

string

TLS mode for grpc connection to the go-micro based grpc services. Possible values are 'off', 'insecure' and 'on'. 'off': disables transport security for the clients. 'insecure' allows using transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates). 'on' enables transport security, including server certificate verification.

OCIS_GRPC_CLIENT_TLS_CACERT

pre5.0

string

Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the go-micro based grpc services.

AUTH_APP_SKIP_USER_GROUPS_IN_TOKEN

7.0.0

bool

false

Disables the encoding of the user’s group memberships in the access token. This reduces the token size, especially when users are members of a large number of groups.

OCIS_MACHINE_AUTH_API_KEY
AUTH_APP_MACHINE_AUTH_API_KEY

7.0.0

string

The machine auth API key used to validate internal requests necessary to access resources from other services.

AUTH_APP_ENABLE_IMPERSONATION

7.0.0

bool

false

Allows admins to create app tokens for other users. Used for migration. Do NOT use in productive deployments.

YAML Example

  • master + Rolling 6.6.1

# Autogenerated
# Filename: auth-app-config-example.yaml

tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9245
  token: ""
  pprof: false
  zpages: false
grpc:
  addr: 127.0.0.1:9246
  tls: null
  protocol: tcp
http:
  addr: 127.0.0.1:9247
  root: /
  cors:
    allow_origins:
    - '*'
    allow_methods:
    - GET
    - POST
    - DELETE
    allow_headers:
    - Authorization
    - Origin
    - Content-Type
    - Accept
    - X-Requested-With
    - X-Request-Id
    - Ocs-Apirequest
    allow_credentials: true
  tls:
    enabled: false
    cert: ""
    key: ""
grpc_client_tls: null
token_manager:
  jwt_secret: ""
reva:
  address: com.owncloud.api.gateway
  tls:
    mode: ""
    cacert: ""
skip_user_groups_in_token: false
machine_auth_api_key: ""
allow_impersonation: false