Aura –

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Authentication API environment variables

Notation

List of environment variables defined for Aura Authentication API

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description	Modifiable by OB?
AURA_AUTHENTICATION_BLOCK_MODE	string	DEPRECATED. No longer used during installations. Flag to indicate if the server allows users’ registration, users’ reading or everything. Possible values: `write`, `writeread` and `unblocked`. By default, `unblocked`.	NO
AURA_AUTHORIZATION_HEADER	string	Complete authorization header to be sent to aura-authentication-api, with the following format: `APIKEY xxxxxx`.	YES, but only if the previous APIKey was deprecated.
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT	string	Endpoint for aura-configuration-api.	NO
AURA_DEFAULT_LOCALE	string	Culture code to be used by default in the current deployment: `de-de`, `en-gb`, `es-es`, `pt-br`.	NO
AURA_DEFAULT_TIME_ZONE	string	Timezone where the service is running.	NO
AURA_DIRECTLINE_API_ENDPOINT	string	Direct Line API URL to create tokens and conversations in the current environment. By default, `https://directline.botframework.com/v3/directline/conversations`.	NO
AURA_DIRECTLINE_SECRETS	string	Comma-separated list of strings with all the existing Direct Line secrets of the current instance to be used to generate tokens and conversations.	NO
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm that will be used to validate the APIKey. By default: `aes-256-cbc`.	NO. It would break APIKey and state validation.
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm that validates the APIKey and the state.	NO. It would break APIKey and state validation.
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. By default: `35`.	NO. It would break APIKey and state validation.
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to decrypt the APIKeys or user state during login and to encrypt sensible data, such as async-callback parameters during login.	NO. It would break database encrypted data and APIKey validation.
AURA_ENVIRONMENT_NAME	string	Name of the environment where the aura-authentication-api is deployed. For example: `ap-next`, `es-dev` or `de-pre`.	NO
AURA_ERROR_CODES_CREDENTIALS	string	Credentials error codes returned by the IDP in `error_codes` field. Used to send the correct error response to the user.	YES, if any code must return this type of response.
AURA_ERROR_CODES_TIMEOUT	string	Timeout error codes returned by the IDP in `error_codes` field. Used to send the correct error response.	YES, if any code must return this type of response.
AURA_ERROR_DESCRIPTIONS_CREDENTIALS	string	Credentials error descriptions returned by IDP in `error_description` field. Used to send the correct error response. For example: `IDPSEGU_ERROR 205, IDPSEGU_ERROR 424`	YES, if any error description must return this type of response.
AURA_ERROR_DESCRIPTIONS_TIMEOUT	string	Timeout error descriptions returned by IDP in `error_description` field. Used to send the correct error response. For example: `IDPSEGU_ERROR 300`	YES, if any error description must return this type of response.
AURA_FP_AUTHSERVER_ENDPOINT	string	URL of the Kernel authentication server. It MUST end with `/`	NO
AURA_FP_CLIENT_ID	string	Client ID to be logged in as Kernel .application.	NO
AURA_FP_CLIENT_ISSUER	string	URL of endpoint where Aura public key is published.	NO
AURA_FP_CLIENT_SECRET	string	Client password to be logged in as Kernel application.	NO
AURA_FP_ISSUER	string	URL of the endpoint serving Aura’s public key of the environment.	NO
AURA_FP_PRIVATE_KEY	string	Base64 string with the Aura private key used to cipher OpenId requests.	NO
AURA_FP_PRIVATE_KEY_ID	string	ID to find the private key in the key storage of the docker container. It is also used to generate the proper output for the public key. By default, `8dfe2155bbfe54079ba640560ae930411e93a008`.	NO, it depends on the `AURA_FP_PRIVATE_KEY`
AURA_HTTP_KEEP_ALIVE	boolean	Flag to indicate whether not the outgoing HTTP connections should be established with keep alive or not. By default, `true`.	NO
AURA_HTTP_KEEP_ALIVE_MSECS	number	Number of milliseconds to keep HTTP connections open. By default, `100000`.	NO
AURA_HTTP_MONKEY_PATCHER_ENABLED	boolean	Flag to indicate whether Monkey Patcher is used in service.	NO
AURA_HTTP_PATHS_LOG_DISABLED	string	Comma-separated string with the outgoing path that should not be logged. By default, `aura-kpis`, `static-resources`, `healthz`, `ping`, `aura-configuration`. The paths in this variable will be added to the default ones.	YES, add the values to be filtered as a comma-separated list of paths.
AURA_HTTP_REQUEST_MAX_SOCKETS	number	Maximum number of HTTP sockets open in the server. By default, `100`	NO. Only if indicated by Aura Global Team.
AURA_HTTP_REQUEST_TIMEOUT	number	Number of milliseconds to wait for an HTTP request to be established. By default, `20000`.	NO. Only if indicated by Aura Global Team.
AURA_IGNORE_LOGGING_PATH	string	Comma-separated string with all the incoming paths which requests should not be logged. By default, `/ping,/local-ping`	YES
AURA_IMAGE_SUCCESS	string	Path to the image file to be added in the HTML templates to indicate, in integrated authentication, that the process was successful. By default, no file is configured. It will be read from `AURA_STATIC_RESOURCE_PROVIDER_ENDPOINT` using `AURA_STATIC_RESOURCE_PROVIDER_SAS_TOKEN` as credentials.	YES
AURA_INTERNAL_RETRIES	number	Number of retries for internal calls. By default, `1`	NO, except if requested
AURA_LOCALE_FOLDER	string	Local path in the aura-authentication-api docker container where locale files are found. By default, `./locale`.	NO
AURA_LOCALE_FORCE_IMPORT	boolean	Flag to indicate whether or not remote locale files are to be used instead the local ones. By default, `false`.	NO
AURA_LOCALE_REMOTE_BACKUP	boolean	Flag to indicate whether or not remote locale files are to be backup before overwriting them. By default, `false`.	NO
AURA_LOCALE_REMOTE_CONTAINER	string	Azure Storage blob container where remote locale files are stored. By default, `static-resources`.	NO
AURA_LOCALE_REMOTE_CONTAINER_PREFIX	string	Azure Storage blob container prefix where remote locale files are stored. By default, `authentication/locale`.	NO
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev`(more visual format). By default: `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in monitoring logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default: `INFO`.	YES, for development set it to `DEBUG`. In pre/production should be `INFO` or `ERROR`. For the analysis of an issue in pre/production it may be changed to `DEBUG`.
AURA_MAKEUP_MODE	string	Allow dev mode of the makeup with the value `local`. By default: `full`.	NO, only for development, set it to `local`.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY	string	Microsoft Storage password of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT	string	Microsoft Storage account of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Aura configuration container name. Default: ‘aura-configuration’	NO
AURA_MONGODB_CACHE_COLLECTION	string	Name of the MongoDB collection where cache is stored. By default: `dev-cache`.	NO
AURA_MONGODB_CACHE_INDEX	string	Index used in TwoLevelsCache of aura-behavior-manager. By default, `id`.	YES, only for development environments.
AURA_MONGODB_CACHE_TTL	number	Lifetime of cache used by aura-behavior-manager. It MUST be disabled in PRE and PRO environments. By default, `3600` seconds (1h).	YES, only for development environments.
AURA_MONGODB_PASSWORD	string	MongoDB password to access `MONGODB_USER_DB` in `AURA_MONGODB_URI`.	NO. Only if the credentials must be updated.
AURA_MONGODB_POOL_SIZE	number	Number of connections open with the database in the pool. By default, `60`.	NO. Only if indicated by Aura Global Team.
AURA_MONGODB_SSL	boolean	Flag to indicate whether or not mongodb connection must use SSL. By default, `false`.	NO
AURA_MONGODB_URI	string	MongoDB URI of the MongoDB server of the current environment.	NO
AURA_MONGODB_USER_COLLECTION	string	Name of the MongoDB collection where aura users are stored.	NO
AURA_MONGODB_USER_DB	string	Name of the MongoDB database where aura users are stored.	NO
AURA_MONGODB_USER_LAST_ACCESS_UPDATE_INTERVAL	number	Number of milliseconds to wait to update the last access of user. By default: 86400000 milliseconds	NO
AURA_MONGODB_USERNAME	string	MongoDB username to access `MONGODB_USER_DB` in `AURA_MONGODB_URI`.	NO. Only if the credentials must be updated.
AURA_MONGODB_MAX_POOL_SIZE	number	Maximum number of connections in the MongoDB pool. By default, `60`.	NO
AURA_MONGODB_MIN_POOL_SIZE	number	Minimum number of connections in the MongoDB pool. By default, `2`.	NO
AURA_MONGODB_MAX_IDLE_TIME_MS	number	Maximum idle time in milliseconds for connections in the MongoDB pool. By default, `30000` (30 seconds).	NO
AURA_MONGODB_RETRY_WRITES	boolean	`true` if retry writes are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_RETRY_READS	boolean	`true` if retry reads are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_HEARTBEAT_FREQUENCY_MS	number	Frequency in milliseconds of the heartbeat in the MongoDB connection. By default, `2000` (2 seconds).	NO
AURA_MONGODB_SERVER_SELECTION_TIMEOUT_MS	number	Timeout in milliseconds for server selection in the MongoDB connection. By default, `5000` (5 seconds).	NO
AURA_MONGODB_SOCKET_TIMEOUT_MS	number	Timeout in milliseconds for socket operations in the MongoDB connection. By default, `45000` (45 seconds).	NO
AURA_CONNECTION_TIMEOUT_MS	number	Timeout in milliseconds for establishing a connection to the MongoDB server. By default, `10000` (10 seconds).	NO
AURA_MONGODB_READ_PREFERENCE	string	Read preference for the MongoDB connection. By default, `primaryPreferred`. Possible values: `primary`, `primaryPreferred`, `secondary`, `secondaryPreferred`, `nearest`.	NO
AURA_REDIRECT_URI	string	URL to redirect integrated authentication requests.	NO
AURA_REDIS_MODE	string	Mode of Redis distribution. Values: `CLUSTER`, `SENTINEL`, `SINGLE`. By default: `SENTINEL`.	NO
AURA_REDIS_SENTINEL_INSTANCE_NAME	string	Name of the Redis instance. Use in `SENTINEL` mode.	NO
AURA_REDIS_HOSTS	string	A string with list of nodes separated by ‘,’, including host and port separated by ‘:’. For example: “localhost:port,localhost2:port2”.	NO
AURA_REDIS_DATABASE	number	Database number for `SINGLE` or `SENTINEL` mode. By default: `0`.	YES
AURA_REDIS_PASSWORD	string	String with Redis password.	YES
AURA_ENVIRONMENT_PREFIX	string	Prefix that will be used by all Redis keys when using redis-connector. This allows mixing in a single Redis service messages coming from different environments in the same Azure subscription. By default: ``. (empty)	YES
AURA_REDIS_USE_CONNECTION_POOL	string	Use pool connections for Redis. By default: `true`.	YES
AURA_REDIS_CACHE_TTL	number	Seconds to expire cache documents in Redis cache. By default: `3600` (1h).	YES
AURA_REDIS_CONNECTION_POOL_MIN	number	Minimum number of connections in the pool. By default: `2`.	YES
AURA_REDIS_CONNECTION_POOL_MAX	number	Maximum number of connections in the pool. By default: `100`.	YES
AURA_REDIS_MAX_RECONNECT_RETRIES	number	Number of retries to connect to Redis. By default: `25`	YES
AURA_REDIS_MAX_RECONNECT_INTERVAL	number	Time in milliseconds to wait before reconnecting to Redis. By default: `5000`.	YES
AURA_RESOURCES_FOLDER	string	Local path in the aura-authentication-api docker container where static resources are found. By default, `./settings/resources`.	NO
AURA_SEED_ID	string	Seed used to generate userIds for anonymous users.	NO
AURA_SERVICE_ENVIRONMENT	string	Type of environment: `'DEV', 'PRE', 'PRO'`. By default, `DEV`. It is used during locale translation, to get the correct text reference.	NO
AURA_SERVICE_PORT	number	Port where the aura-authentication-api is listening. By default, `2367`	NO
AURA_STATIC_RESOURCE_PROVIDER_ENDPOINT	string (url)	Azure Storage endpoint where static resources are stored. By default, it is not configured. Only needed if the environment handles integrated authentication and the files have to be uploaded to Azure Storage.	NO
AURA_STATIC_RESOURCE_PROVIDER_SAS_TOKEN	string	Azure Storage SAS token to access the container where the static resources are stored. By default, it is not configured. Only needed if the environment handles integrated authentication and the files have to be uploaded to Azure Storage.	NO. Only if the credentials have to be renewed.
AURA_STATIC_RESOURCES_CONTAINER	string	Azure Storage blob container where static resources are stored. By default, `static-resources`.	NO
AURA_STATIC_RESOURCES_CONTAINER_PREFIX	string	Azure Storage blob container prefix where static resources are stored. By default, `authentication/resources`.	NO
AURA_TRUSTED_HOSTNAMES	string	Comma-separated list of the trusted domains URL of the current environment, to validate non integrated signup and login requests.	YES, all the trusted domains must be added.
AURA_VALID_REGISTER_STATE_MINUTES	number	Number of minutes to expire a received user state during integrated authentication. By default, `10`.	NO
AURA_SHUTDOWN_GRACEFUL_TTL	string	Number of milliseconds to wait until all aura-authentication-api tasks are done before shutting each pod down. By default `25000` (25 seconds)	NO
AURA_VERSION	string	Number of the Aura’s release being executed.	NO
DEV_AURA_AUTH_BEHAVIOR_MICROSOFT_AZURE_STORAGE_SETTINGS_FILE	string	Name of the configuration file route used by aura-behavior-manager. By default, `aura-bot/aura-auth-behavior-manager.json`. It is only valid for development environments.	YES, in development environments
DEV_AURA_AUTH_BEHAVIOR_CRON_PATTERN	string	Cron pattern to set the refresh time of aura-behavior-manager configuration. By default, `/5 * * *` (every 5 minutes). It is only valid for development environments.	YES, in development environments.
DEV_AURA_BEHAVIOR_MANAGER_ACTIVE	boolean	Flag to indicate whether or not aura-behavior-manager module should be activated in the current deployment. It is only valid for development environments.	YES, in development environments.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Authentication API endpoints

Description of Aura Authentication API endpoints, categorized by how they can be accessed or by their usage

Endpoints by access

aura-authentication-api counts on:

Internal endpoints: they are only allowed to APIKeys generated for aura-groot/aura-bot.
Public endpoints: they are publicly open and all valid APIKeys for the current environment can access them.
Endpoints published in Kernel, i.e. they are publicly open but they are only allowed to APIKeys generated for Kernel. Read Aura Services API published in Kernel for further information.

The following section explains every endpoint, showing whether it is internal, public, Kernel or a mix.

Endpoints by usage

Register new users

GET /users/aura-id: Endpoint published in Kernel, used by Aura Channels that handle their own authentication mechanisms. They must call this endpoint to get a valid authenticated Aura user to start a conversation. This method retrieves the already existing user if the data sent exists or create a new user with the data, otherwise. Authorized by APIKey.
GET /users/aura-id/{auraId}: Internal method used only by aura-groot/aura-bot in order to create a new user when the auraId is based on the external service authentication, such as for WhatsApp users. Authorized by APIKey.
GET /users/auraid/integrated: Endpoint used as callback during non-integrated authentication request. This endpoint is used by Aura clients account linking process without integrated authentication. It is called by Kernel after creating the authentication session, to add the Aura user record. No authorization header. Validation done by a ciphered query param.

Remove users

DELETE /admin/users/phone-numbers/{phone_number}: Endpoint published in Kernel, used by OB administrators to fulfill GDPR and remove users by phone number that are not longer Telefonica’s customers. Authorized by APIKey.
GET /users/auraid/integrated/logout: Public endpoint used as callback during non-integrated logout request. This endpoint is used by Aura clients account unlinking process without integrated authentication. It is called by Kernel after removing the authentication session, to remove the Aura user record. No authorization header. Validation done by a ciphered queryparam.
DELETE /users/{auraId}: Internal and also published in Kernel endpoint used by aura-bot and the non-integrated channels, to remove the information of an already logged in Aura user. Authorized by APIKey.

Gather users’ information

GET /users/{auraId}: Internal endpoint used by aura-groot/aura-bot to get and validate the information of an already logged in Aura user. Authorized by APIKey.
GET /users/aura-id-global/{aura_id_global}: Endpoint published in Kernel, used to get the last valid auraId for the channel, generated for the given auraIdGlobal. Authorized by APIKey.

Retrieve a valid Direct Line token from the current Aura Bot instance and start a conversation with it

GET /token: Public endpoint used by Aura channels accessing by Direct Line, to get a valid Direct Line-Token to access the bot in the selected environment. This endpoint just returns the token and its expiration time. Authorized by APIKey.
GET /token/wss: Public endpoint used by Aura channels accessing by Direct Line, to get a valid Direct Line-Token to access the bot in the selected environment. This endpoint returns the token, the websocket stream URL, the expiration time and some other fields returned by Direct Line API. Authorized by APIKey.

Public key (no APIKey)

GET /openid/issuer/.well-known/openid-configuration: Public endpoint to get the public key URL of aura-groot/aura-bot.
GET /openid/jwk: Public endpoint to get the public key configuration of aura-groot/aura-bot. Used to validate the requests signed with aura-groot/aura-bot private key.

Monitoring methods

GET /healthz: Internal health check endpoint to validate the server status by the Kubernetes cluster. No authorization header needed.
GET /ping: Endpoint published in Kernel to validate the server status.

Configuration method

GET /config: Public endpoint to return the name of the Azure Storage subdomain.

Metrics method

GET /metrics: Public endpoint where Prometheus requests the metrics.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Authentication API definition

Definition of APIs in aura-authentication-api component

Introduction

This section includes the API definition files that affects to the authentication processes in Aura: