Quick Start - DRIVR Docs

OAuth - Provider Integrations and Setup

A Domain Authentication Method defines how users and devices can authenticate to access the DRIVR GraphQL/REST APIs. Each domain must have at least one authentication method, and the DEFAULT method is automatically added when a domain is created.

Before proceeding with the OAuth authentication method, ensure you’ve created a Domain via the DRIVR Customer Portal.

Once your Domain is set up, you can log in and access the GraphQL API using GraphiQL (https://{slug}.api.drivr.cloud/graphiql) or DRIVR UI (https://{slug}.ui.drivr.cloud/graphiql), replacing {slug} with your custom domain slug.

The DomainAuthenticationMethods define the authentication settings for DRIVR, allowing integration with both DRIVR's internal system and third-party providers. This flexibility ensures secure and customizable authentication options for your domain.

To enable access for additional applications, you must configure at least one DomainAuthenticationMethod with a status of ACTIVATED.

Creating a user prior to first authentication: Sometimes, you may want to create users before they first authenticate against DRIVR. To do this, ensure you create a user with a matching email within the JWT token. The user will then be automatically assigned to it.

Here are the available DomainAuthenticationMethods:

DEFAULT: DRIVR's built-in authentication system. Users can log in directly using their DRIVR credentials.
GOOGLE: Enables users to sign in with their Google accounts via Google's OAuth service, ensuring secure and delegated access.
AZURE_AD: Allows users to authenticate using their Azure Active Directory (AD) credentials, integrating seamlessly with Microsoft's identity platform.
OPEN_ID_BEARER_DELEGATION: Supports authentication using OpenID Bearer tokens from third-party OAuth providers. This method validates tokens issued by trusted providers. This provides an easier way to integrate DRIVR with existing identity platforms and allows for seamless SSO (single-sign-on) flow.

By default, the DEFAULT authentication method is used (e.g., for GraphiQL and DRIVR UI). However, this can be deactivated or removed if another method is properly configured. Only one ACTIVATED instance of each method is allowed at a time.

Certain domain features can impact login authentication flows. When a user logs in for the first time using Google, Azure, or the OpenID Delegated method, they are automatically created within DRIVR. However, specific domain settings may require adjustments to ensure smooth operation:

USER_MUST_HAVE_EMAIL: Some Identity Providers may not always provide an email address for the user. To prevent authentication issues, this setting may need to be turned off.
USER_MUST_HAVE_PASSWORD: Users authenticating via Google, Azure, or the OpenID Delegated method are created in DRIVR without a password. Disabling this setting ensures these users can be created without interruptions.

Review and configure these settings as needed to maintain seamless authentication flows.

You can retrieve the DEFAULT authentication method, which is automatically created by DRIVR for a Domain, using the following query:

query domainAuthenticationMethod{
  authenticationMethods(where:{authenticationType:{_eq: DEFAULT }}){
    items{
      ... on DefaultAuthenticationMethod{
        authenticationType
        status
        domainUuid
        uuid
      }
    }
  }
}

Response

{
  "data": {
    "authenticationMethods": {
      "items": [
        {
          "authenticationType": "DEFAULT",
          "status": "ACTIVATED",
          "domainUuid": "7b6f629d-872b-48a0-9386-7c0ee61ceb06",
          "uuid": "cd3a2eb3-52ca-4f77-942d-6e62e7f2e697"
        }
      ]
    }
  }
}

Add DRIVR as a new OAuth2.0 Client within your Google Cloud environment.
Provide the following details in your Google Cloud Console to configure the OAuth client:

Application Type: Web Application
Authorized JavaScript Origins: https://{your-domain-slug}.api.drivr.cloud
Authorized Redirect URIs: https://{your-domain-slug}.api.drivr.cloud/authenticate/authorize/google

To add a GOOGLE authentication method on DRIVR, use the following mutation. Replace clientId and clientSecret with values from your Google Cloud Console:

mutation createGoogleAuthenticationMethod {
  createGoogleAuthenticationMethod(
    configuration: {
      clientId: "google-client-id",
      clientSecret: "google-client-secret",
      scopes: [
        "https://www.googleapis.com/auth/userinfo.email",
        "https://www.googleapis.com/auth/userinfo.profile"
      ]
    }
  ) {
    uuid
    authenticationType
    status
  }
}

Response

{
  "data": {
    "createGoogleAuthenticationMethod": {
      "uuid": "19f1b631-061f-4685-8619-374a56d43da2",
      "authenticationType": "GOOGLE",
      "status": "ACTIVATED"
    }
  }
}

Add configuration using : Azure Oauth2.
Provide the following details in your Azure Cloud Console to configure the OAuth client:

Application Type: Web
Authorized Redirect URI: https://{your-domain-slug}.api.drivr.cloud/authenticate/authorize/azure-ad

To add a AZURE_AD authentication method, use the following mutation. Replace client_id, client_secret and tenant with values from your Azure Cloud Console:

mutation createAzureAuthenticationMethod {
  createAzureAuthenticationMethod(
    configuration: {
      clientId: "azure-client-id",
      clientSecret: "azure-client-secret",
      tenant: "organizations"
    }
  ) {
    uuid
    authenticationType
    status
  }
}

Response

{
  "data": {
    "createAzureAuthenticationMethod": {
      "uuid": "c6a1625d-a7d3-4ab2-b5d1-004d00d07818",
      "authenticationType": "AZURE_AD",
      "status": "ACTIVATED"
    }
  }
}

To integrate OpenID Bearer Token providers and build an SSO flow, refer to the OpenID Provider Integration Guide.

This query shows how to retrieve all active DomainAuthenticationMethods within a Domain.

query getDomainAuthenticationMethods {
  authenticationMethods(
    where: {
      status: {
        _eq: ACTIVATED
      }
    },
    offset: 0,
    limit: 1000
  ) {
    items {
      ... on DefaultAuthenticationMethod {
        uuid
        authenticationType
        status
      }
      ... on GoogleAuthenticationMethod {
        uuid
        authenticationType
        status
      }
      ... on AzureAuthenticationMethod {
        uuid
        authenticationType
        status
      }
      ... on OpenIdDelegatedAuthenticationMethod {
        uuid
        authenticationType
        status
      }
    }
    limit
    totalItems
  }
}

Response

{
  "data": {
    "authenticationMethods": {
      "items": [
        {
          "uuid": "3d286020-10d5-446e-b294-1c4d4964ac35",
          "authenticationType": "AZURE_AD",
          "status": "ACTIVATED"
        },
        {
          "uuid": "6be7bc0e-3c04-4da3-a940-ba02be9a2d1f",
          "authenticationType": "OPEN_ID_BEARER_DELEGATION",
          "status": "ACTIVATED"
        },
        {
          "uuid": "cd3a2eb3-52ca-4f77-942d-6e62e2f2e690",
          "authenticationType": "DEFAULT",
          "status": "ACTIVATED"
        },
        {
          "uuid": "dca1c873-54fc-43f1-bc43-783e305215b9",
          "authenticationType": "GOOGLE",
          "status": "ACTIVATED"
        }
      ],
      "limit": 1000,
      "totalItems": 4
    }
  }
}

You can now use a Google Account via the GOOGLE authenticationType to login to DRIVR UI and GraphiQL without any further steps.

Similar, Azure Account steps are necessary to enable access to the DRIVR API via the AZURE_AD authenticationType.

OpenID Bearer Delegation method can be used to authenticate with DRIVR using the OpenID provider's JWT token as mentioned in OpenID Provider Integration Guide.

Domain Authentication Methods provide a flexible way to manage how users can authenticate against DRIVR.

By supporting multiple authentication types and configurations, DRIVR ensures secure and customizable access to its APIs.

OAuth - Provider Integrations and Setup

For further information