This guide explains how to integrate external OpenID providers with DRIVR to enable seamless authentication using JWT tokens. By leveraging OpenID Bearer Token providers, you can synchronize authentication across multiple applications.

Overview

In many setups, DRIVR is part of a larger ecosystem where multiple applications require authentication. OpenID providers simplify this by issuing JWT tokens that can be shared across systems. DRIVR supports this through the OpenIdDelegatedAuthenticationMethod, which validates JWT tokens using public keys provided by the OpenID provider.

How It Works

1. OpenID Configuration: The OpenID provider must expose a .well-known/openid-configuration endpoint. For example, if the provider's URL is https://my-provider.example.com, the configuration must be available at: https://my-provider.example.com/.well-known/openid-configuration.

2. JWKs URI: The configuration must include a jwks_uri that provides the public keys used to validate JWT tokens. Example response:
   json { "jwks_uri": "https://my-provider.example.com/jwks" }
3. JWT Validation: DRIVR fetches the public keys from the jwks_uri and uses them to validate JWT tokens. If the token is valid, DRIVR authenticates the user. If the user does not already exist, DRIVR automatically creates it based on the token's information.

Setting Up OpenID Integration

To integrate an OpenID provider with DRIVR, you need the following:

• Client ID: The unique identifier for your application, configured in the OpenID provider.
• Issuer: The root URL of the OpenID provider.

Steps to Configure OpenID Integration

You can configure OpenID integration via the DRIVR UI or the GraphQL API.

Option 1: Using the DRIVR UI

1. Login to the DRIVR UI (https://{slug}.ui.drivr.com/graphql, replace {slug} with your domain identifier).
2. Navigate to Settings then on left-hand side, click on Authentication Methods.
3. Add a new authentication method with the type OPENID DELEGATION.
4. Provide the required configuration details, including the Client ID and Issuer.
5. Click Create to create the authentication method.

Option 2: Using the GraphQL API

Run the following mutation to create an OpenID Delegated Authentication Method:

mutation createOpenIDBearerToken {
  createOpenIdDelegatedAuthenticationMethod(
    configuration: {
      clientId: "open-id-client-id",
      issuer: "https://my-provider.example.com"
    }
  ) {
    uuid
    status
    configuration {
      clientId
      issuer
    }
  }
}

{
  "data": {
    "createOpenIdDelegatedAuthenticationMethod": {
      "uuid": "b1b3b1b3-1b3b-1b3b-1b3b-1b3b1b3b1b3b",
      "status": "ACTIVATED",
      "configuration": {
        "clientId": "open-id-client-id",
        "issuer": "https://my-provider.example.com"
      }
    }
  }
}

Once configured, DRIVR will accept JWT tokens issued by the specified provider for authentication.

Using JWT Tokens for Authentication

JWT tokens issued by the OpenID provider must include the following fields:

1. Issuer (iss): The URL of the OpenID provider.
   Example:

   "iss": "https://my-provider.example.com"
   

2. Audience (aud): The Client ID for which the token is valid.
   Example:

   "aud": "ea248356-b014-44d4-8f9d-746fa0770f8c"
   

3. User Identification:

   • sub: The unique identifier for the user.
   • email: The user's email address (optional).
   • name: The user's name (optional).
     Example:

   {
     "sub": "user-123",
     "email": "user@example.com",
     "name": "John Doe"
   }
   

Here is an example of a valid JWT token that DRIVR can authenticate:

{
  "iss": "https://my-provider.example.com",
  "aud": "ea248356-b014-44d4-8f9d-746fa0770f8c",
  "sub": "user-123",
  "email": "user@example.com",
  "name": "John Doe"
}

DRIVR uses these fields to validate the token and identify the user. If the user does not exist, it is automatically created.

Best Practices

1. Pre-create Users:
   To ensure a smooth experience, pre-create users in DRIVR with matching email or sub fields from the JWT token. This avoids any delays during the first authentication.
2. Secure Configuration:
   Ensure the issuer and clientId are correctly configured to prevent unauthorized access.
3. Monitor OpenID Configuration:
   Regularly check the .well-known/openid-configuration endpoint to ensure the JWKs keys are up-to-date.

Integrating OpenID Bearer Token providers with DRIVR allows you to streamline authentication across multiple applications.

By validating JWT tokens, DRIVR ensures secure and seamless user authentication. Use the steps and best practices outlined in this guide to configure OpenID integration for your domain.