1. Authentication
  2. User authentication

Gandalf


Require user authentication

If you’re using Mage version 0.8.4 or greater, than you can optionally turn on user authentication.

Set the following environment variable name and value:

NameREQUIRE_USER_AUTHENTICATION
Value1

Running Mage in Docker

If you’re running Mage using Docker, you can run Mage and set the environment variable in the docker run command. Follow these instructions to learn how.

Set the environment variable using -e REQUIRE_USER_AUTHENTICATION=1.

For example:

docker run -it -p 6789:6789 \
  -v $(pwd):/home/src \
  -e REQUIRE_USER_AUTHENTICATION=1 \
  mageai/mageai /app/run_app.sh mage start demo_project

Running Mage without Docker

If you installed Mage using pip, conda, poetry, etc. and are running it using the mage start command, then you need to set the environment variable on your workstation.

macOS

Run the following command to set environment variables:

export REQUIRE_USER_AUTHENTICATION=1

Windows

Read Microsoft’s instructions on how to do this.

Default owner user

When Mage starts, if there is no existing owner user, then a new user will be created with owner permissions (e.g. all permissions).

The owner user can create, edit, and delete other users.

Here are the default credentials for the owner user to sign in with:

FieldValue
Emailadmin@admin.com
Passwordadmin

Sign in page

Before using Mage, users will have to sign in at /sign-in. If you go to a page that requires authentication and you’re not signed in, you’ll be redirected to the sign in page.

Sign in page

User management page

If you’re signed in as the owner user, you’ll have access to the user management page at /settings/workspace/users.

On this page, you can:

  1. Add new users
  2. Edit existing users
  3. Reset user passwords
  4. Delete users

Sign in page

Roles and permissions

RolePermissions
ViewerCan read.
EditorCan do everything a viewer can, create, update, and delete.
AdminCan do everything a viewer can, an editor can, and manage user.
OwnerCan do everything.

LDAP

If you want to enable LDAP authentication mode, Set the following environment variable name and value:

Variable nameValue
AUTHENTICATION_MODEldap

In this case, you will also need to configure the following variables:

Variable nameDescriptionExample value
LDAP_ADMIN_USERNAMEThe username of the owner user created on first runadmin
LDAP_SERVERThe host of the LDAP serverldap.example.com
LDAP_BIND_DNThe bind_dn for the LDAP account that will be used to perform search operationscn=admin,dc=example,dc=com
LDAP_BIND_PASSWORDThe password for the LDAP account that will be used to perform search operationspassword
LDAP_BASE_DNThe base DN of the serverdc=example,dc=com
LDAP_AUTHENTICATION_FILTERThe authentication filter to use in template format using the variable username(&(|(objectClass=inetOrgPerson)(objectClass=groupOfNames))(cn={username}))
LDAP_AUTHORIZATION_FILTERThe authorization filter to use in template format using the variable user_dn(&(objectClass=groupOfNames)(cn=group)(member={user_dn}))

Make sure to adjust the values of the variables to match your LDAP configuration.

When LDAP authentication is enabled, users will need to provide their LDAP credentials to log in to the system. Once authenticated, Mage will use the authorization filter to determine the user’s permissions based on their LDAP group membership.

Authenticated requests

If you require user authentication by turning it on via the environment variable mentioned above, then each API request the front-end client makes to the backend server will include an API key and an OAuth2 token.

The API key and OAuth2 token is used to authenticate the incoming request. If the requester doesn’t have the proper permissions, the backend server will respond with a 4XX error code.

API errors

If a page loads and no data is visible, it could either mean there is no data or the user doesn’t have the proper permissions.

If there is no visible error message on the page, you can view the browser’s network tab and inspect the API request response to view the full error details (we’re working on showing better errors and making it easier to display them).

Learn how to view the network requests in Chrome by following these instructions.

Error codeDescription
401Expired OAuth token.
401Invalid OAuth token.
402Record is invalid.
403Invalid API key.
403Unauthorized access.
404Record not found.
500API resource error.