Integrating OAuth

Introduction

Netmaker offers integration with the following OAuth providers:

• Google

• Okta

• Microsoft Entra ID (Azure AD)

• Open ID Connect (OIDC)

• GitHub

By integrating with an OAuth provider, your Netmaker users can log in via the provider rather than the default simple auth.

Configuring your provider

Starting from version v0.90.0, integrating OAuth is handled directly through the Netmaker Settings interface. For more information, please visit: https://docs.netmaker.io/docs/how-to-guides/identity-provider-integration-guide

In order to use OAuth, configure your OAuth provider (GitHub, Okta, Google, Azure AD, or OIDC).

• Configure your provider (except for Azure AD) to use the Netmaker Dashboard URI as the origin URL:

  • dashboard.<netmaker.base.domain>

  • Example: https://dashboard.mydomain.com

• Configure your provider to use the Netmaker API redirect route with this format:

  • api.<netmaker.base.domain>/api/oauth/callback

  • Example: https://api.mydomain.com/api/oauth/callback

General provider instructions:

• GitHub: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/github

• Google: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/google

• Microsoft Azure AD: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/azure

• OIDC: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/openid_connect

Configuring Netmaker

1

1. Configure your OAuth provider

After registering your application with your provider, note the CLIENT_ID and CLIENT_SECRET. If using Azure AD, note the Azure tenant ID you wish to use (optional but often required).

2

2. Set Netmaker environment variables

Configure Netmaker with the following environment variables. If any required value is left blank, OAuth will fail.

AUTH_PROVIDER: "<azure-ad|github|google|oidc>"
CLIENT_ID: "<client id of your oauth provider>"
CLIENT_SECRET: "<client secret of your oauth provider>"
SERVER_HTTP_HOST: "api.<netmaker base domain>"
FRONTEND_URL: "https://dashboard.<netmaker base domain>"
AZURE_TENANT: "<only for azure, you may optionally specify the tenant for the OAuth>"
OIDC_ISSUER: "<only for oidc, your issuer endpoint for OIDC> ie. http://127.0.0.1:5556/dex"

3

3. Restart Netmaker and verify initialization

Restart your server and check the Netmaker logs to confirm the OAuth provider was successfully initialized:

sudo docker logs netmaker

Once initialized, users will see a “Login with SSO” button on the login page to sign in with the configured OAuth provider.

4

4. User access and approval

• Users can join a Netmaker server via the “Login with SSO” button on the dashboard’s login page.

• From v0.23.1, new OAuth-created accounts are added to a pending list and require admin approval before accessing resources.

• You can whitelist email domains for OAuth users by setting the ALLOWED_EMAIL_DOMAINS environment variable with a comma-separated list, for example:

ALLOWED_EMAIL_DOMAINS=example.net,example.com

Notes

If using Azure AD, you may need to specify the tenant via AZURE_TENANT. For OIDC, ensure OIDC_ISSUER points to your issuer endpoint.

Login Oauth