# Identity Provider Integration Guide

IdP Integration – Technical implementation guide

## Identity Provider Integration Guides

Each supported identity provider (Google, Microsoft Entra ID, Okta, GitHub, and OIDC) includes **detailed configuration instructions within its integration modal under Settings → Security & Authentication,** ensuring a simple and well-guided setup process.

![](/files/lm8QMPokly1nqAjVZKJA)

## Integrating Google Workspace

![](/files/bXd1k66i1uIGJfE1IcA5)

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

{% stepper %}
{% step %}

### Create a Google Cloud Project and Configure OAuth

Go to the [Google Cloud Console](https://console.cloud.google.com/).

* 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.
  {% endstep %}

{% step %}

### 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.
  {% endstep %}

{% step %}

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

{% hint style="warning" %}
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).
{% endhint %}

**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
   {% endstep %}

{% step %}

### Delegate Domain-wide Access

* Navigate to [Admin Console](https://admin.google.com/) → **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:

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

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

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

{% endstep %}

{% step %}

### 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.
  {% endstep %}

{% step %}

### Configure Netmaker

1. Navigate to the Netmaker Dashboard → Settings → Security & Authentication. ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)
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**.
   {% endstep %}
   {% endstepper %}

## Integrating Microsoft Entra ID (Azure AD)

![](/files/is970RfAkVkK5aiCKmhX)

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

{% stepper %}
{% step %}

### Create and Configure Microsoft Entra ID Application

* Log in to the [Azure Portal](https://portal.azure.com/).
* 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.
  {% endstep %}

{% step %}

### 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**.
  {% endstep %}

{% step %}

### 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.
  {% endstep %}

{% step %}

### 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
    {% endstep %}

{% step %}

### 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)
    {% endstep %}
    {% endstepper %}

## Integrating Okta

![](/files/wMxds8YSR4KjMVa6lC75)

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

{% stepper %}
{% step %}

### 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**
  {% endstep %}

{% step %}

### 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.
  {% endstep %}

{% step %}

### 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.
  {% endstep %}
  {% endstepper %}

## Integrating GitHub

![](/files/FDHzq8bDGtlLfWzydFXe)

### Prerequisites

Ensure you have a GitHub account with the following permission:

* Ability to register an OAuth application

{% stepper %}
{% step %}

### Register an OAuth Application in GitHub

* Go to [GitHub Developer Settings](https://github.com/settings/developers).
* Under **OAuth Apps**, click **New OAuth App**.
* Fill in the form with the following values:

| Field                      | Value                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| Application Name           | Netmaker                                                                                              |
| Homepage URL               | <p>\[Enter your Netmaker callback URL]<br>e.g: <https://dashboard.netmaker.io></p>                    |
| Application Description    | Authorization for Netmaker                                                                            |
| Authorization Callback URL | <p>\[Enter your Netmaker callback URL]<br>e.g: <https://dashboard.netmaker.io/api/oauth/callback></p> |

* Click **Register Application**.
  {% endstep %}

{% step %}

### 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.** ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)
* Choose **GitHub** as the provider, and enter the Client ID and Client Secret obtained from GitHub. ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)
  {% endstep %}
  {% endstepper %}

## Integrating Generic OpenID (OIDC) Provider

![](/files/B0nwy6hTJ3Bbo9Fow7ow)

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

{% stepper %}
{% step %}

### 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 | <p>\[Enter your Netmaker callback URL]<br>e.g: <https://dashboard.netmaker.io></p>                    |
| Authorization Callback URL       | <p>\[Enter your Netmaker callback URL]<br>e.g: <https://dashboard.netmaker.io/api/oauth/callback></p> |

* Complete the registration to generate the required credentials.
  {% endstep %}

{% step %}

### 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.** ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)
* Select **OIDC** as the provider. ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)
* Enter the Client ID, Client Secret, and OIDC Issuer URL from your OIDC application. ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)

Reference for OIDC: <https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/openid\\_connect>
{% endstep %}
{% endstepper %}

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

![](/files/QWyd7akDq6MHygG9gMj1)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.netmaker.io/how-to-guides/identity-provider-integration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.