Identity Provider Integration Guide

IdP Integration – Technical implementation guide

Identity Provider Integration Guides

All necessary configuration steps for each supported identity provider (Google, GitHub, OIDC, etc.) are provided in detail within each integration modal available under Settings → Security & Authentication. The setup process is simple and straightforward to follow.

Integrating Google Workspace

Prerequisites

Ensure you have a Google account with the following permissions:

• Create or manage projects

• Manage OAuth Credentials and Consent screen

If you do not have these permissions, please contact your Google Workspace administrator.

1

Create a Google Cloud Project and Configure OAuth

Go to the Google Cloud Console.

• If you haven't already, create or select a project.

• Navigate to APIs & Services → OAuth consent screen.

  • Choose Internal (for Workspace users only).

  • Fill in application name, support email, and developer contact info.

• Save and continue.

2

Create OAuth2 Credentials

• Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.

• Choose Web application.

• Add https://api.{NM_BASE_DOMAIN}/api/oauth/callback as an Authorized redirect URI.

• Save and copy Client ID and Client Secret.

3

Configure API Permissions

• Navigate to Google Cloud Console → APIs and services → Enabled APIs and services → Enable APIs and services.

• Search "Admin SDK API" and click Enable.

• Navigate to APIs and services → Credentials → Create credentials → Service account.

• Configure the service account details:

  • Name: Give the service account a meaningful name.

  • ID: Choose a unique ID for the service account.

  • Description: Provide a brief description outlining its purpose.

Set Permissions:

• Role: Assign the Service Account Token Creator role to this account.

This permission enables the service account to generate short-lived access tokens on behalf of other service accounts.

• Copy the service account email address.

• Create a service account key.

Make sure the constraints/iam.disableServiceAccountKeyCreation policy is not enforced, as it's required for Netmaker to create Service Account keys.

If you do not have the required permissions to modify this policy, contact your GCP Organization Administrator. The role required to adjust this policy is roles/orgpolicy.policyAdmin (assignable only at the organization level).

Steps to update the policy (if needed):

1. Switch to your Organization using the top-left dropdown in the Google Cloud Console.

2. Go to IAM & Admin → IAM and assign yourself the role mentioned above.

3. Disable the constraints/iam.disableServiceAccountKeyCreation constraint in the Organization Policies

4

Delegate Domain-wide Access

• Navigate to Admin Console → Security → Access and data control → API controls → Domain-wide delegate → Manage Domain-Wide Delegation.

• Add new and configure the Service Account client ID and the following scopes:

https://www.googleapis.com/auth/admin.directory.group.readonly

https://www.googleapis.com/auth/admin.directory.group.member.readonly

https://www.googleapis.com/auth/admin.directory.user.readonly

5

Grant Scopes in Admin Console

• Navigate to Admin Console → Account → Admin roles.

• Click Create new role.

• Configure role name and enable the following API privileges:

  • Groups → Read

  • Users → Read

• Once the role is created, click Assign Admin → Assign service accounts, and enter the email address of the service account we created.

6

Configure Netmaker

1. Navigate to the Netmaker Dashboard → Settings → Security & Authentication.

2. Click Integrate under Google Workspace.

3. Configure the OAuth Client ID and Client secret.

4. Enter the email of a Workspace admin for user/group access.

5. Upload the Service Account JSON file.

6. Optionally, configure synchronization. (By default, synchronization is enabled.)

7. Optionally, configure prefixes for users and groups to be synced from IdP. (By default, all users and groups are synced.)

8. Click Finish.

Integrating Microsoft Entra ID (Azure AD)

Prerequisites

Ensure you have an Azure account with the following permissions:

• Create Microsoft Entra ID apps

• Manage Microsoft Entra ID apps

If you do not have these permissions, please contact your Azure administrator.

1

Create and Configure Microsoft Entra ID Application

• Log in to the Azure Portal.

• Select Microsoft Entra ID from the list of services.

• Click on + Add.

• Select App registration and fill in the form:

  • Name: Netmaker

  • Supported Account Types: Accounts in this organizational directory only (Default Directory only - Single tenant)

  • Platform: Web Application

  • Authorized redirect URI: https://api.{NM_BASE_DOMAIN}/api/oauth/callback

  Example: https://api.nm.167-172-115-84.nip.io/api/oauth/callback

• Click Register to create the application.

2

Grant API Permissions

• In your registered app, navigate to API permissions in the left-hand menu.

• Click + Add a permission:

  • Choose Microsoft Graph.

  • Select the Application permissions tab.

• Under Select permissions, add:

  • User.Read.All

  • Group.Read.All

• Click Add permissions.

• Grant admin consent by clicking Grant admin consent for Default Directory, then confirm by clicking Yes.

3

Generate a Client Secret

• Go to Certificates & secrets in the left-hand menu.

• Click + New client secret.

• Add a description (e.g., Netmaker) and click Add.

• Copy the Client Secret Value immediately — you’ll need this for Netmaker configuration.

4

Retrieve Application (Client) ID and Directory (Tenant) ID

• In the left-hand menu, select Overview.

• Copy the following values:

  • Application (Client) ID

  • Directory (Tenant) ID

5

Configure Synchronization Settings (Optional)

• Synchronization Interval: 24 hours (default)

• Groups to Synchronize:

  • By default, all groups are synchronized. To filter by prefix, specify the prefix (case-sensitive).

• Users to Synchronize:

  • By default, all users are synchronized. To filter by prefix, specify the prefix (case-sensitive)

Integrating Okta

Prerequisites

Ensure you have access to an Okta Admin account with permissions to:

• Create and manage applications

• Generate API tokens

If you do not have these permissions, please contact your Okta administrator.

1

Create and Configure Okta Application

• Log in to the Okta Admin Console.

• Navigate to Applications → Applications, then click Create App Integration.

• In the Create App Integration dialog:

  • Sign-in method: Select OIDC - OpenID Connect

  • Application type: Choose Web Application

• Fill in the application details:

  • App integration name: Netmaker

  • Sign-in redirect URIs: https://api.{NM_BASE_DOMAIN}/api/oauth/callback

• Click Save

2

Collect Application Credentials

• After saving, go to the app’s General tab and locate Client Credentials.

• Copy the following values:

  • Client ID

  • Client Secret

• Navigate to the Sign On tab:

  • Scroll to OpenID Connect ID Token

  • Click Edit

  • Change Issuer from Dynamic to Okta URL

  • Click Save

• Copy the Okta URL — this will serve as the Issuer URL in the Netmaker configuration.

3

Generate an API Token (Optional – For Sync)

• In the Okta Admin Console, go to Security → API → Tokens.

• Click Create token and fill out the form:

  • Name: Netmaker

  • API call origin: Select a suitable value based on your organization's policy. If unsure, choose Any IP.

• Click Create token

• Copy the token value immediately — this will be used for synchronization.

Integrating GitHub

Prerequisites

Ensure you have a GitHub account with the following permission:

• Ability to register an OAuth application

1

Register an OAuth Application in GitHub

• Go to GitHub Developer Settings.

• Under OAuth Apps, click New OAuth App.

• Fill in the form with the following values:

Field	Value
Application Name	Netmaker
Homepage URL	[Enter your Netmaker callback URL] e.g: https://dashboard.netmaker.io
Application Description	Authorization for Netmaker
Authorization Callback URL	[Enter your Netmaker callback URL] e.g: https://dashboard.netmaker.io/api/oauth/callback

• Click Register Application.

2

Enter Client Credentials

• After registering the app, you will receive a Client ID and a Client Secret.

• In the Netmaker dashboard: Go to Settings → Security & Authentication.

• Choose GitHub as the provider, and enter the Client ID and Client Secret obtained from GitHub.

Integrating Generic OpenID (OIDC) Provider

Prerequisites

Ensure you have the necessary permissions to register an OAuth (OIDC) application with your Identity Provider (IdP).

If you lack these permissions, please contact your IdP administrator.

1

Register an OAuth Application in Your OIDC Provider

• Navigate to your OIDC provider’s application settings page.

• Find and select the option to add/register a new OAuth (OIDC) application.

• Fill in the application form with the following details:

Field	Value
Application Name	Netmaker
Application Description	Authorization for Netmaker
Homepage URL / Authorized Origin	[Enter your Netmaker callback URL] e.g: https://dashboard.netmaker.io
Authorization Callback URL	[Enter your Netmaker callback URL] e.g: https://dashboard.netmaker.io/api/oauth/callback

• Complete the registration to generate the required credentials.

2

Enter Client Credentials

• Once your OIDC application is registered, make sure to note the following values:

  • Client ID

  • Client Secret

  • OIDC Issuer URL (e.g., https://corp.okta.com/oauth2/default)

• In the Netmaker dashboard: Go to Settings → Security & Authentication.

• Select OIDC as the provider.

• Enter the Client ID, Client Secret, and OIDC Issuer URL from your OIDC application.

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

OAuth Users

Users are able to join a Netmaker server via OAuth by clicking the “Continue with SSO” button on the dashboard’s login page.

From v0.23.1, new accounts will be added to a pending list and require approval from an admin before they can access any resource. This version also allows whitelisting of email domains for OAuth users.