Trait AuthenticationExtension 

pub trait AuthenticationExtension: Sized + 'static {
    // Required methods
    fn new(config: Configuration) -> Result<Self, Error>;
    fn authenticate(
        &mut self,
        ctx: &RequestContext,
        headers: &GatewayHeaders,
    ) -> Result<Token, ErrorResponse>;

    // Provided method
    fn public_metadata(&mut self) -> Result<Vec<PublicMetadataEndpoint>, Error> { ... }
}

An authentication extension is called before any request processing, authenticating a user with a token or returning an error response.

Example

You can initialize a new authentication extension with the Grafbase CLI:

grafbase extension init --type authentication my-auth

This will generate the following:

use grafbase_sdk::{
    AuthenticationExtension,
    types::{GatewayHeaders, Configuration, ErrorResponse, Token, Error, RequestContext}
};

#[derive(AuthenticationExtension)]
struct MyAuth {
    config: Config
}

#[derive(serde::Deserialize)]
struct Config {
    my_custom_key: String
}

impl AuthenticationExtension for MyAuth {
    fn new(config: Configuration) -> Result<Self, Error> {
        let config: Config = config.deserialize()?;
        Ok(Self { config })
    }

    fn authenticate(&mut self, ctx: &RequestContext, headers: &GatewayHeaders) -> Result<Token, ErrorResponse> {
        todo!()
    }
}

Configuration

The configuration provided in the new method is the one defined in the grafbase.toml file by the extension user:

[extensions.my-auth.config]
my_custom_key = "value"

Once your business logic is written down you can compile your extension with:

grafbase extension build

It will generate all the necessary files in a build directory which you can specify in the grafbase.toml configuration with:

[extensions.my-auth]
path = "<project path>/build"

Required Methods

fn new(config: Configuration) -> Result<Self, Error>

Creates a new instance of the extension. The Configuration will contain all the configuration defined in the grafbase.toml by the extension user in a serialized format.

Example

The following TOML configuration:

[extensions.my-auth.config]
my_custom_key = "value"

can be easily deserialized with:

#[derive(serde::Deserialize)]
struct Config {
    my_custom_key: String
}

let config: Config = config.deserialize()?;

fn authenticate( &mut self, ctx: &RequestContext, headers: &GatewayHeaders, ) -> Result<Token, ErrorResponse>

Authenticate the user with a Token or return an ErrorResponse. It is called before any GraphQL processing and an error will stop any further actions.

The [HttpHeaders] are the headers received by the gateway before any header rules.

Provided Methods

fn public_metadata(&mut self) -> Result<Vec<PublicMetadataEndpoint>, Error>

Define endpoints on the gateway that expose authentication related metadata. This can be used to implement OAuth 2.0 Protected Resource Metadata, for example. This method is only called once, on gateway initialization. The endpoints are available on the gateway for GET requests at a custom path, and they return a static payload with custom headers.

See the docs on public-metadata-endpoint for details.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors