Bring Your Own IAM

Federation vs. Replacement

Bring Your Own IAM (BYOIAM) is a federation model, not a full replacement. Your external IdP handles authentication and issues tokens. BizFirstGO accepts and validates those tokens. BizFirstGO's own permission system, resource policies, and node capability policies remain fully active — they operate on the mapped identity.

IExternalTokenProvider

namespace BizFirst.Essentials.Passport.Federation;

public interface IExternalTokenProvider
{
    /// <summary>
    /// The issuer URI this provider handles. Matched against the "iss" claim in incoming tokens.
    /// </summary>
    string Issuer { get; }

    /// <summary>
    /// Validate the token and return identity claims.
    /// Returns null if the token is invalid.
    /// </summary>
    Task<ExternalIdentityClaims?> ValidateTokenAsync(
        string token,
        CancellationToken ct = default);
}

public class ExternalIdentityClaims
{
    public required string UserId      { get; init; }
    public required string TenantId    { get; init; }
    public required string Email       { get; init; }
    public string? DisplayName         { get; init; }
    public IReadOnlyList<string> Groups{ get; init; } = [];  // external groups/roles
    public IReadOnlyDictionary<string, string> RawClaims { get; init; } = new Dictionary<string, string>();
}

How Token Validation Works with External IdPs

Supported Providers