DocsAPI

Identity Provider Integration Guide

IdP Integration – Technical implementation guide

Identity Provider Integration GuidesCopied!

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 WorkspaceCopied!

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.

Step 1: Create and Configure Google Cloud Project

  1. Go to the Google Cloud Console.

  2. Click New Project.

  3. Enter a Project Name (e.g., Netmaker) and click Create.

  4. In the left-hand menu, select OAuth consent screen.

  5. If not already set up, fill in the following fields:

    a. App Name: Netmaker

    b. User Support Email: [Your Admin/Support Email]

    c. Audience: Internal (only Google Workspace users will have access)

    d. Contact Information: [Your Admin/Support Email]

  6. Click Save.

Step 2: Generate OAuth Credentials

  1. In your project, navigate to APIs & Services → Credentials.

  2. Click + Create Credentials → OAuth Client ID.

  3. Configure as follows:

    a. Application Type: Web application

    b. Name: Netmaker

    c. Authorized Redirect URIs: [Enter your Netmaker callback URL]

  4. Click Create and save:

    a. Client ID

    b. Client Secret

Step 3: Enable Admin SDK API

  1. Navigate to APIs & Services → Enabled APIs & services.

  2. Search for and Enable the Admin SDK API.

Step 4: Create Service Account

  1. Go to APIs & Services → Credentials → + Create Credentials → Service Account.

  2. Configure the following:

    a. Service Account Name: Netmaker

    b. Service Account ID: netmaker

    c. Description: Service Account for Netmaker to use for read-only access to Users and Groups in the Workspace.

  3. After creating the service account:

        a. Go to the Service Account Keys tab.
        b. Generate a new JSON key file — save this file securely.

⚠️ Note:

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

If you have already created a Service Account, this constraint is likely already unenforced by default. However, it is recommended to verify the setting to avoid potential issues.

To adjust this policy, you need the following role:

roles/orgpolicy.policyAdmin

Note: This role can only be assigned at the organization level.

Steps to update the policy:

  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. Replace the Disable Service Account Key Creation with constraints/iam.disableServiceAccountKeyCreation


If you do not have the required permissions, please contact your GCP Organization Administrator.

Step 5: Provide Credentials to Netmaker

  1. Log in to the Netmaker dashboard with Admin rights.

  2. Go to: Settings → Security & Authentication.

  3. Select Google Workspace.

  4. Enter the following:

    a. OAuth Client ID: [Your Client ID]

    b. OAuth Client Secret: [Your Client Secret]

    c. Service Account Email: [Your Service Account Email]

    d. Service Account JSON Key File: [Upload the generated JSON file]

  5. Enable Auto-Synchronization to sync users and groups automatically.

Step 6: Configure Synchronization Settings (Optional)

  • Synchronization Interval: 24 hours (default)

  • Groups to Synchronize:
    By default, all groups are synchronized. To filter by prefix, specify prefixes (case-sensitive, comma-separated).

  • Users to Synchronize:
    By default, all users are synchronized. To filter by prefix, specify prefixes (case-sensitive, comma-separated).

Integrating Microsoft Entra ID (Azure AD)Copied!

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.

Step 1: Create and Configure Microsoft Entra ID Application

  1. Log in to the Azure Portal.

  2. Select Microsoft Entra ID from the list of services.

  3. Click on + Add

  4. Select App registration and fill in the form:

    a. Name: Netmaker

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

    c. Redirect URI:

    d. Platform: Single-page application (SPA)

    e. URI: [Enter your Netmaker callback URL]

  5. Click Register to create the application.

Step 2: Grant API Permissions

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

  2. Click + Add a permission:

    a. Choose Microsoft Graph.

    b. Select the Application permissions tab.

  3. Under Select permissions, add:

    a. User.Read.All

    b. Group.Read.All

  4. Click Add permissions.

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

Step 3: Generate a Client Secret

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

  2. Click + New client secret.

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

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

Step 4: Retrieve Application (Client) ID and Directory (Tenant) ID

  1. In the left-hand menu, select Overview.

  2. Copy the following values:

    a. Application (Client) ID

    b. Directory (Tenant) ID

Step 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 GitHubCopied!

Prerequisites

Ensure you have a GitHub account with the following permission:

  • Ability to register an OAuth application

Step 1: Register an OAuth Application in GitHub

  1. Go to GitHub Developer Settings.

  2. Under OAuth Apps, click New OAuth App.

  3. 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

4. Click Register Application.

Step 2: Enter Client Credentials

  1. After the app is registered, you will get:

    a. Client ID

    b. Client Secret

  2. In the Netmaker dashboard:

    a. Go to Settings → Security & Authentication.

    b. Select GitHub as the provider.

    c. Enter the Client ID and Client Secret from GitHub.

Integrating Generic OpenID (OIDC) ProviderCopied!

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.

Step 1: Register an OAuth Application in Your OIDC Provider

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

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

  3. 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

4. Complete the registration to generate the required credentials.

Step 2: Enter Client Credentials

  1. After successful registration, locate the following values in your OIDC application:

    a. Client ID

    b. Client Secret

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

  2. In the Netmaker dashboard:

    a. Go to Settings → Security & Authentication.

    b. Select OIDC as the provider.

    c. 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

Once successful, users can click on the “Login with SSO” button in the login page to sign-in with your configured OAuth provider.

Oauth UsersCopied!

Users are able to join a Netmaker server via OAuth. They can do this by clicking the “Continue with SSO” button on the dashboard’s login page.
From v0.23.1, new accounts would be added to a pending list and would require approval from an admin before they can access any resource. This version also allows whitelisting of email domains for OAuth users.

Copied!