Trait Authentication

Source

pub trait Authentication:
    Send
    + Sync
    + 'static {
    // Required method
    fn authenticate<'life0, 'life1, 'async_trait>(
        &'life0 self,
        headers: &'life1 HeaderMap,
    ) -> Pin<Box<dyn Future<Output = Option<Identity>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided methods
    fn security_scheme(&self) -> Option<(String, Value)> { ... }
    fn security_schemes_all(&self) -> Vec<(String, Value)> { ... }
    fn is_anonymous(&self) -> bool { ... }
}

Expand description

The authentication contract. Inspect headers, return an Identity if recognised. Async because most real backends hit the DB.

Object-safe via async-trait’s Pin<Box<...>> desugaring; that’s what makes Arc<dyn Authentication> work in RestPlugin.

Required Methods§

Source

fn authenticate<'life0, 'life1, 'async_trait>( &'life0 self, headers: &'life1 HeaderMap, ) -> Pin<Box<dyn Future<Output = Option<Identity>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Try to identify the caller. None means “anonymous”; the permission check decides whether to allow that.

Returning an error isn’t part of the contract — auth backends should silently return None on invalid credentials and let the permission check produce a 403. The alternative (returning a typed error) leaks “which credential you tried” information to the client.

Provided Methods§

Source

fn security_scheme(&self) -> Option<(String, Value)>

OpenAPI securitySchemes entry this backend contributes — Some((name, scheme_value)) for documented schemes, None to skip.

name is the key under components.securitySchemes.<name>; consumers also reference it from operation-level security: [{<name>: []}] entries. scheme_value is the OpenAPI 3.0 Security Scheme Object serialised as a serde_json::Value.

Default None — anonymous / no-auth backends contribute nothing. Concrete classes can override when they want to document their shape.

Source

fn security_schemes_all(&self) -> Vec<(String, Value)>

All securitySchemes entries the backend (and any children it might wrap) contributes. The default impl returns self.security_scheme().into_iter().collect() — fine for every leaf backend. ChainAuthentication overrides to walk every child so the OpenAPI plugin can publish the full list.

Source

fn is_anonymous(&self) -> bool

True when this backend never identifies anyone — every request is anonymous (NoAuthentication). Used only by the boot-time security warning (WEB-1); defaults to false so a real backend is never mistaken for the no-op.