MinIO Gateway with DigitalOcean Spaces, NGINX and auth0
Intro
This post illustrates how to install MinIO Gateway for DigitalOcean Spaces. There’s lots of great guides for how to set up all the necessary components already so where possible the links to these resources will be provided. For the authentication and authorization we’ll use a free Auth0 account. The fully self-hosted solution is also possible via KeyCloak or similar open source tools.
Tech stack
- MinIO
- DigitalOcean Ubuntu 20.04 instance
- Custom domain
- Certbot for SSL cert installation and renewal
- Auth0 for authentication and authorization
- NGINX web server for connecting everything together
Cost
Cost of the implementation per month: USD $10 + transfer charge above the droplet and storage limits (so far haven’t managed to go over the limits).
Installation includes provisioning a number of resources
with different providers, including: DigitalOcean,
auth0 and GoDaddy. The cost of
the domain for the 1st year is negligible and the cost of the DigitalOcean Droplet (s-1vcpu-1gb
)
with Spaces is around USD $10 per month:

Droplet cost breakdown
DigitalOcean instance
DigitalOcean is a good alternative for AWS or Azure when it comes to testing things out. Very simple pricing structure, easy to work with management console make it a very attractive environment for the development projects like this.
Few easy steps to get things going:
- Sing up, if you haven’t already.
- Create a new Project for the MinIO resources
DigitalOcean new Project
- Provision a new droplet or use an existing one. The rest of the walk-through is based on Ubuntu 20.04.
The provisioning process is very straight forward. Choose the right data center region, add monitoring, public IP address,
SSH keys and assign it to the right Project.
DigitalOcean new Droplet
- Provision Spaces object store, S3 in DO-land.
With all this we should be set for the next steps, basic NGINX configuration and MinIO install.
Custom Domain
To enable oAuth authentication with 3rd party provider a custom domain is required. Below is example DNS configuration for a domain registered with GoDaddy.

GoDaddy DNS config.
Note: Above config already contains minio
and minio-server
CNAME that will be later used
to configure NGINX for MinIO console and MinIO server respectively.
NGINX configuration
- Follow instructions to install NGINX.
If you run everything correctly you should see at droplets IP address:
NGINX home page
- Use Certbot to provision and add SSL cert for
the domain registered in Custom Domain step to NGINX configuration.
- DigitalOcean provides a great guide on how to do this
- After installation is complete the NGINX config should look very similar to the following:
|
|
MinIO Gateway installation
- There’s an existing installation guide MinIO Server installation for DigitalOcean here.
- Follow the installation Step 1 and Step 2.
- We’ll use NGINX to
proxy_pass
our custom minio subdomains to MinIO server and MinIO console. - SSL certs can be provisioned with
certbot
just like for the full domain in the previous step.
- Adjust config from the DigitalOcean MinIO guide:
- fix the server and console ports to
9000
and9001
respectively - Add DigitalOcean Spaces Endpoint - you can find the correct value in the Spaces settings
MINIO_ROOT_USER
andMINIO_ROOT_PASSWORD
are the SECRET and KEY for the DigitalOcean Spaces.
- fix the server and console ports to
|
|
systemd
service file adjusted for MinIO Gateway:
|
|
- The MinIO Gateway and Console should start at this point but won’t be reachable since we do not have NGINX config yet.
- If you haven’t added subdomains for the server and console, yet you’ll need to add it to the DNS record, e.g.:
minio.domain-name.com
minio-server.domain-name.com
- Run
certbot
to get certs for new subdomains, only pass the domains and subdomains you’re going to use:
|
|
Check this guide out for more details
certbot
should update the NGINX configuration automatically. You can also do it yourself, it should look similar to:
|
|
- NGINX config for MinIO Server API and MinIO Console. We’ll use the info from the MinIO Cookbook to set the appropriate config for the server and console:
|
|
At this point you should have MinIO console accessible at minio.domain-name.com
.
Since you only have a single user for now you’ll need to use the MinIO Root user login and password to login.
In the next step we’ll configure MinIO to use Auth0 as authentication provider.
If things are not running check the debugging section to find out how to get some insight to what’s happening with your MinIO.
Auth0.com
Auth0 provides a great flexibility and tooling around Single SingOn authorization and authentication services which comes very handy when building new services.
- Create a free account.
- Create a new application from the Applications menu. In this example the application will be called
minio-domain-name
.- Choose a single page application template.
- In the settings page add the following information:
- Application Login URI: https://minio.domain-name.com/login
- Allowed Callback URLs: https://minio.domain-name.com/oauth_callback
- The above settings will allow the Auth0 to authenticate and authorize the user to MinIO Console via Single Sign On.
- Create a new User from the User Management menu. Add user to the
minio-domain-name
in the Authorized Applications tab. - MinIO expects policy claims to be available in the id token. Since policy claims are not part of
the standard we’ll need to use Auth Pipeline Rule to add MinIO policy claims to the id tokens.
- Create a new Rule from the Auth Pipeline -> Rules menu.
- There’s lots of potential ways of sorting out the authorization and access policies
to the buckets, external DBs, Auth0 API permissions, etc. In this simple example all registered users
will receive the
readwrite
permissions. In the Script input of the new Rule paste the following:
1 2 3 4 5 6 7 8 9 10 11 12 13
function (user, context, callback) { const namespace = 'https://minio'; let idTokenClaims = context.idToken || {}; let accessTokenClaims = context.accessToken || {}; idTokenClaims[`${namespace}/policy`] = "readwrite"; accessTokenClaims[`${namespace}/policy`] = "readwrite"; context.idToken = idTokenClaims; context.accessToken = accessTokenClaims; callback(null, user, context); }
- You can check the existing policies with MinIO client by running:
1 2 3 4 5 6
mc admin policy list local readwrite writeonly consoleAdmin diagnostics readonly
- Advance authorization with roles. Following the built-in MinIO policies we can
build a simple authorization system with Auth0 by using Roles.
- Adding MinIO roles to Auth0:
MinIO -> Auth0
- Adjust the Auth Pipeline Rule to use the new policy mechanism:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
function (user, context, callback) { const namespace = 'https://minio'; const assignedRoles = (context.authorization || {}).roles; let idTokenClaims = context.idToken || {}; let accessTokenClaims = context.accessToken || {}; idTokenClaims[`${namespace}/policy`] = assignedRoles; accessTokenClaims[`${namespace}/policy`] = assignedRoles; context.idToken = idTokenClaims; context.accessToken = accessTokenClaims; callback(null, user, context); }
- Adding MinIO roles to Auth0:
- Add appropriate roles to User settings in Auth0. Changing the roles should be reflected in MinIO after next login.
- Adjust MinIO config to use Single Sing On.
- Client ID and Client Secret are available from the Application, Settings menu.
- Open ID configuration endpoint is available in the Applications, Advanced Settings, Endpoints tab.
|
|
- Restart MinIO, head to
minio.domain-name.com
:MinIO SSO Login
MinIO Auth0 Login
DigitalOcean Spaces in MinIO Console
Debugging
MinIO Client debugging for when things go wrong
Install MinIO client on your local laptop or the MinIO Server depending on which step you have issues.
If you’re debugging MinIO sever startup with no NGINX configuration, etc. use the client on the server:
|
|
If you have NGINX config set, SSL certs provisioned you can setup a client on you local machine:
|
|
Example use:
|
|
Client usage
- List current policies
|
|
- Trace server. This command will allow you to see the requests and the error codes and messages in case of any issues.
|
|
You can find more here.
Testing Auth0 with API debugger
Auth0 API debugger extension is an incredibly useful tool especially if you’re trying to add some custom content to the tokens, like MinIO policy claims. Follow the [instructions]((https://auth0.com/docs/extensions/authentication-api-debugger-extension) to learn how to enable and use.
Some example use below:
- Launch the extension
Extension list
- Check the config:
Config
- Get the token, in
OAuth2 / OIDC
:- Set
Response Type
to “code” - Use “OAUTH2/OIDC LOGIN” User Flow (Blue button top of the page)
Code
- Set
- After getting successful response go back to
Login
thenOAuth2 / OIDC
Authorization Code
should be filled in from the previous request- Set
Response Type
to “id_token” - Use “OAUTH2 CODE EXCHANGE” User Flow (Blue button top of the page) to get the token payload:
ID TOKEN