Skip to content
Big Picture

Directory Services Integration

Big Picture integrates with directory services to provide authentication and user management. Directory services enable single sign-on (SSO) and centralized user management through OIDC/OAuth2 providers, Active Directory, and LDAP.

How Directory Services Integration Works

Section titled “How Directory Services Integration Works”

Directory services provide authentication for Big Picture users. Big Picture supports multiple authentication providers:

  1. OIDC/OAuth2 — Standard OAuth2 and OpenID Connect providers
  2. Active Directory — Microsoft Active Directory via OIDC
  3. LDAP — LDAP directories via OIDC bridge or direct integration

Users authenticate through directory services, and Big Picture derives user identity and group membership from directory attributes.

OIDC/OAuth2 Integration

Section titled “OIDC/OAuth2 Integration”

OIDC/OAuth2 is the primary integration method for directory services. Most modern directory services support OIDC/OAuth2.

Supported Providers

Section titled “Supported Providers”
  • Google Workspace — Google OAuth2 provider
  • Microsoft Azure AD — Azure AD OIDC provider
  • Okta — Okta OIDC provider
  • Auth0 — Auth0 OIDC provider
  • Generic OIDC — Any OIDC-compliant provider

Configuration

Section titled “Configuration”

Configure OIDC/OAuth2 provider:

auth:
  provider: oidc
  oidc:
    issuer: https://accounts.google.com
    client_id: your-client-id
    client_secret: your-client-secret
    scopes:
      - openid
      - email
      - profile

User Attributes

Section titled “User Attributes”

Big Picture extracts user information from OIDC claims:

  • Subject (sub) — Unique user identifier
  • Email — User email address
  • Name — User display name
  • Groups — Group membership (if available in claims)

Active Directory Integration

Section titled “Active Directory Integration”

Active Directory integrates via Azure AD or OIDC bridge. Azure AD provides native OIDC support for Active Directory.

Azure AD Integration

Section titled “Azure AD Integration”

Configure Azure AD as OIDC provider:

auth:
  provider: oidc
  oidc:
    issuer: https://login.microsoftonline.com/{tenant-id}/v2.0
    client_id: your-azure-ad-client-id
    client_secret: your-azure-ad-client-secret
    scopes:
      - openid
      - email
      - profile
      - User.Read

Group Membership

Section titled “Group Membership”

Azure AD provides group membership in OIDC claims or via Microsoft Graph API.

LDAP Integration

Section titled “LDAP Integration”

LDAP directories integrate via OIDC bridge or direct LDAP authentication.

OIDC Bridge

Section titled “OIDC Bridge”

Use an OIDC bridge (e.g., Keycloak, Dex) to convert LDAP to OIDC:

  1. Configure OIDC bridge to authenticate against LDAP
  2. Configure Big Picture to use OIDC bridge as provider
  3. Users authenticate through OIDC bridge

Direct LDAP

Section titled “Direct LDAP”

Direct LDAP integration may be available in future releases.

User Management

Section titled “User Management”

User Provisioning

Section titled “User Provisioning”

Users are provisioned automatically on first login:

  1. User authenticates through directory service
  2. Big Picture extracts user attributes from claims
  3. User account created if not exists
  4. User assigned to tenants based on group membership or claims

Group Mapping

Section titled “Group Mapping”

Map directory groups to Big Picture roles:

  • Extract group membership from OIDC claims
  • Map groups to Big Picture roles (admin, user, viewer)
  • Assign users to tenants based on group membership

Single Sign-On (SSO)

Section titled “Single Sign-On (SSO)”

SSO enables users to authenticate once and access Big Picture without re-authenticating.

SSO Flow

Section titled “SSO Flow”
  1. User accesses Big Picture
  2. User redirected to directory service login
  3. User authenticates with directory service
  4. Directory service redirects back with authorization code
  5. Big Picture exchanges code for user information
  6. User session established

Session Management

Section titled “Session Management”
  • Sessions managed by Big Picture
  • Session duration configurable
  • Refresh tokens supported for long-lived sessions

Configuration

Section titled “Configuration”

Environment Variables

Section titled “Environment Variables”
Terminal window
BP_AUTH_PROVIDER=oidc
BP_OIDC_ISSUER=https://accounts.google.com
BP_OIDC_CLIENT_ID=your-client-id
BP_OIDC_CLIENT_SECRET=your-client-secret

Configuration File

Section titled “Configuration File”
auth:
  provider: oidc
  oidc:
    issuer: https://accounts.google.com
    client_id: your-client-id
    client_secret: your-client-secret
    scopes:
      - openid
      - email
      - profile

Best Practices

Section titled “Best Practices”
  1. Secure secrets — Store client secrets securely (secrets management, not in code)
  2. HTTPS only — Use HTTPS for all OIDC endpoints
  3. Scope minimization — Request only necessary OIDC scopes
  4. Group mapping — Map directory groups to Big Picture roles consistently
  5. User provisioning — Configure automatic user provisioning
  6. Session management — Configure appropriate session timeouts

Troubleshooting

Section titled “Troubleshooting”

Authentication failures — Verify OIDC provider configuration and credentials

User not found — Check user provisioning and group mapping configuration

Group membership not working — Verify group claims are included in OIDC tokens

SSO not working — Check redirect URIs and OIDC provider configuration

Section titled “Related Documentation”