Federation support

Python Keystone is not implementing the Federation natively (neither SAML2, nor OIDC). It relies on the proxy server for the authentication protocol specifics and tries to map resulting users into the local database. This leads to a pretty big number of limitations (not limited to):

Identity Provider can be only configured by cloud administrators only
Pretty much any change on the IdP configuration require restart of the service
Certain protocol specifics can not be implemented at all (i.e. backend initiated logout)
Forces deployment of the proxy service in front of Keystone relying on the modules for SAML2 and/or OIDC implementation (such modules may be abandoned or removed).
Client authentication right now is complex and error prone (every public provider has implementation specifics that are often even not cross-compatible)

In order to address those challenges and complete reimplementation is being done here. This leads to a completely different design opening doors for new features.

Federation is controlled on the domain level by the domain managers. This means that the domain manager is responsible for the configuration of how users should be federated from external IdPs.
Keystone serves as a relying party in the OIDC authentication flow. This moves the complex logic from client to the the Keystone side. This allows making client applications much simpler and more reliable.

Authentication using the Authorization Code flow and Keystone serving as RP

sequenceDiagram

    Actor Human
    Human ->> Cli: Initiate auth
    Cli ->> Keystone: Fetch the OP auth url
    Keystone --> Keystone: Initialize authorization request
    Keystone ->> Cli: Returns authURL of the IdP with cli as redirect_uri
    Cli ->> User-Agent: Go to authURL
    User-Agent -->> IdP: opens authURL
    IdP -->> User-Agent: Ask for consent
    Human -->> User-Agent: give consent
    User-Agent -->> IdP: Proceed
    IdP ->> Cli: callback with Authorization code
    Cli ->> Keystone: Exchange Authorization code for Keystone token
    Keystone ->> IdP: Exchange Authorization code for Access token
    IdP ->> Keystone: Return Access token
    Keystone ->> Cli: return Keystone token
    Cli ->> Human: Authorized

Authenticating with the JWT

This is a work in progress and is not implemented yet

API changes

A series of brand new API endpoints have been added to the Keystone API.

/v3/federation/identity_providers (manage the identity providers)
/v3/federation/mappings (manage the mappings tied to the identity provider)
/v3/federation/auth (initiate the authentication and get the IdP url)
/v3/federation/oidc/callback (exchange the authorization code for the Keystone token)

DB changes

Following tables are added:

federated_identity_provider

#![allow(unused)]
fn main() {
//! `SeaORM` Entity, @generated by sea-orm-codegen 1.1.7

use sea_orm::entity::prelude::*;

#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]
#[sea_orm(table_name = "federated_identity_provider")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: String,
    pub name: String,
    pub domain_id: Option<String>,
    pub oidc_discovery_url: Option<String>,
    pub oidc_client_id: Option<String>,
    pub oidc_client_secret: Option<String>,
    pub oidc_response_mode: Option<String>,
    pub oidc_response_types: Option<String>,
    #[sea_orm(column_type = "Text", nullable)]
    pub jwt_validation_pubkeys: Option<String>,
    pub bound_issuer: Option<String>,
    pub default_mapping_name: Option<String>,
    pub provider_config: Option<Json>,
}

#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
pub enum Relation {
    #[sea_orm(
        belongs_to = "super::project::Entity",
        from = "(Column::DomainId, Column::DomainId, Column::DomainId, Column::DomainId)",
        to = "(super::project::Column::Id, super::project::Column::Id, super::project::Column::Id, super::project::Column::Id)",
        on_update = "NoAction",
        on_delete = "Cascade"
    )]
    Project,
}

impl Related<super::project::Entity> for Entity {
    fn to() -> RelationDef {
        Relation::Project.def()
    }
}

impl ActiveModelBehavior for ActiveModel {}
}

federated_mapping

#![allow(unused)]
fn main() {
    pub id: String,
    pub name: String,
    pub idp_id: String,
    pub domain_id: Option<String>,
    pub allowed_redirect_uris: Option<String>,
    pub user_id_claim: String,
    pub user_name_claim: String,
    pub domain_id_claim: Option<String>,
    pub groups_claim: Option<String>,
    pub bound_audiences: Option<String>,
    pub bound_subject: Option<String>,
    pub bound_claims: Option<Json>,
    pub oidc_scopes: Option<String>,
    pub token_user_id: Option<String>,
    pub token_role_ids: Option<String>,
    pub token_project_id: Option<String>,
}

federated_auth_state

#![allow(unused)]
fn main() {
    pub idp_id: String,
    pub mapping_id: String,
    #[sea_orm(primary_key, auto_increment = false)]
    pub state: String,
    pub nonce: String,
    pub redirect_uri: String,
    pub pkce_verifier: String,
    pub expires_at: DateTime,
    pub requested_scope: Option<Json>,
}

Compatibility notes

Since the federation is implemented very differently to how it was done before it certain compatibility steps are implemented:

Identity provider is "mirrored" into the existing identity_provider with the subset of attributes
For every identity provider "oidc" protocol entry in the federation_protocol table is created pointing to the "<>" mapping.

Testing

Federation is very complex and need to be tested with every supported public provider. Only this can guarantee that issues with not fully compliant OIDC implementations can be identified early enough.

Authorization code flow requires presence of the browser. Due to that the tests need to rely on Selenium.

At the moment following integrations are tested automatically:

Keycloak (login using browser)

Keyboard shortcuts