DocsAPI

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.

Step 1: Create a Google Cloud Project and Configure OAuth

  1. Go to the Google Cloud Console.

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

  3. Navigate to APIs & Services → OAuth consent screen.

    a. Choose Internal (for Workspace users only).

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

  4. Save and continue.

Step 2: Create OAuth2 Credentials

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

  2. Choose Web application.

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

  4. Save and copy Client ID and Client Secret.

Step 3: Configure API Permissions

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

  2. Search "Admin SDK API"  and click Enable.

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

  4. Configure the service account name and ID.

  5. Copy the service account email address.

  6. Create a service account key.

⚠️ 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. Disable the constraints/iam.disableServiceAccountKeyCreation constraint in the Organization Policies


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

7. Assign Service Account Token Creator and Service Account User roles to the admin user and to self.

Step 4: Delegate Domain-wide Access

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

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

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

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

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

Step 5: Grant Scopes in Admin Console

  1. Navigate to Admin Console → Account → Admin roles.

  2. Click Create new role.

  3. Configure role name and enable the following API privileges.

    1. Groups → Read.

    2. Users → Read.

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


Step 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. Configure the Google Admin email address.

  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.

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)

    d. 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 GitHub

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 registering the app, you will receive a Client ID and a Client Secret.

  2. In the Netmaker dashboard:

    Go to Settings → Security & Authentication.

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

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


  2. In the Netmaker dashboard:

    Go to Settings → Security & Authentication.

  3. Select OIDC as the provider.

  4. 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 Users

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.