---
title: Configurazione whitelabel e aziendale
description: Domini personalizzati, portali con marchio, SAML SSO e accesso API per
  club aziendali
order: 86
source_hash: 2cf29b121add
slug: configurazione-whitelabel-e-aziendale
---

# Configurazione whitelabel e aziendale

Alcuni club utilizzano DistantRace in modalità **whitelabel**: un portale per i partecipanti con marchio su un dominio personalizzato, collegato alla stessa console organizzativa e ai dati degli eventi su DistantRace.

Whitelabel è un'offerta **gestita dalla piattaforma**. DistantRace abilita il flag del club, le credenziali OAuth, le pagine di accesso a tema, l'hosting su dominio personalizzato e i provider di identità SAML. Gli organizzatori continuano a creare eventi e gestire i partecipanti nella **manager console** come di consueto.

Contatta il supporto DistantRace per discutere del whitelabel per la tua organizzazione.

## Cosa abilita il whitelabel

| Funzionalità | Esperienza del partecipante | Organizzatore / piattaforma |
|--------------|-----------------------------|-----------------------------|
| **Dominio personalizzato** | Naviga e registrati all'URL del tuo club (es. `events.yourcompany.com`) | DNS + TLS forniti da DistantRace; dominio verificato tramite [Domini incorporati](embed-domains-for-iframes.md) |
| **Portale con marchio** | Nome del club, logo, colori e interfaccia utente localizzata | Branding SPA configurato al momento del deploy; il contenuto degli eventi proviene comunque da DistantRace |
| **Accesso a tema** | Le pagine di accesso e account corrispondono al tuo marchio durante OAuth | Modelli `domain_theme` sull'host di autenticazione DistantRace |
| **Accesso partecipante OAuth** | Accedi al tuo portale; la sessione persiste nel browser | Applicazione OAuth2 con codice di autorizzazione limitata alla tua organizzazione |
| **Token API organizzativo** | Elenchi pubblici (eventi, sfide, classifiche) senza accesso | Token di lettura a lunga durata per il backend del sito con marchio |
| **API immagini eroe** | Banner a carosello sulla home page del portale | [Branding del club e immagini eroe](club-branding-and-hero-images.md) — disponibile quando `is_whitelabel` è abilitato |
| **SAML / SSO aziendale** | Accedi con email di lavoro tramite Microsoft Entra ID o altro IdP | Mappatura IdP per dominio; scoperta su `/saml2/discovery/` — vedi [SAML aziendale e accesso whitelabel](../joining-events/enterprise-saml-and-whitelabel-login.md) |
| **Email con marchio** | Codici di accesso e email transazionali dal tuo mittente | Integrazione [SendGrid](../integrations/sendgrid.md) nel club |
| **Codici di accesso e inviti** | Riscatta codici e link di invito email sul sito con marchio | Gli stessi codici di accesso di distantrace.com; iscrizione automatica tramite link magico via API |
| **Connessioni app sportive** | Connetti Garmin, Strava, fonti di passi, ecc. | I flussi di connessione OAuth funzionano sull'host di autenticazione DistantRace canonico, quindi ritornano al tuo portale |
| **REST API** | Azioni complete del partecipante dopo l'accesso (unisciti, sincronizza allenamenti, profilo) | La stessa superficie `/api/v1/` dell'app mobile — [Panoramica API pubblica](../more-tools/public-api-overview.md) |
| **Manager console** | N/A — gli organizzatori usano distantrace.com | Invariato; [Autenticazione a due fattori](../joining-events/two-factor-authentication.md) ancora richiesta |

::: note Ambito della piattaforma vs. portale
Un portale partecipante whitelabel è un front end focalizzato sopra l'API DistantRace. Quali schermate sono esposte (solo sfide, competizioni con checkout, classifiche di squadra, ecc.) dipende dal deployment. Tutti i tipi di eventi e impostazioni sottostanti sono configurati nella manager console.
:::

## Come si integra

```mermaid
flowchart LR
  subgraph portal [Portale partecipante con marchio]
    SPA[SPA dominio personalizzato]
  end
  subgraph drace [Piattaforma DistantRace]
    API["/api/v1/"]
    Auth[OAuth + accesso a tema]
    Console[Manager console]
    SAML[Scoperta SAML]
  end
  SPA -->|token org — dati pubblici| API
  SPA -->|token utente — dopo accesso| API
  SPA -->|reindirizzamento| Auth
  Auth --> SAML
  Console --> API
```

1. **Portale partecipante** — un'app web sul tuo dominio. Carica dati pubblici degli eventi con un token API limitato all'organizzazione e invia i partecipanti a DistantRace OAuth per l'accesso.
2. **Autenticazione DistantRace** — gestisce codici di accesso, OAuth, SAML e connessioni app sportive. I modelli a tema si applicano quando la richiesta OAuth include il contesto della tua organizzazione.
3. **Manager console** — gli organizzatori creano sfide, competizioni, biglietti e marketing su distantrace.com. Le modifiche appaiono sul portale con marchio tramite l'API.

## Configurazione (gestita dalla piattaforma)

DistantRace gestisce tipicamente:

| Elemento | Dettagli |
|----------|----------|
| Flag club `is_whitelabel` | Sblocca la gestione delle immagini eroe e l'API delle immagini eroe |
| Applicazioni OAuth | **User client** (codice di autorizzazione) per l'accesso dei partecipanti; **org token** per elenchi pubblici |
| `domain_theme` | Seleziona modelli di accesso/registrazione con marchio sull'host di autenticazione |
| Hosting dominio personalizzato | Certificato TLS, ingress e hostname di staging opzionale `*.wl.distantrace.com` (corrisponde al tuo slug `domain_theme`) |
| Provider di identità SAML | Record `SAMLIdentityProvider` mappati ai domini email |
| Deployment del portale | Build SPA con marchio, proxy cache e CI/CD sull'infrastruttura whitelabel |

## Cosa configurano gli organizzatori

| Compito | Dove |
|---------|------|
| Eventi, biglietti, codici di accesso | Manager console — come per qualsiasi club |
| Immagini eroe per il carosello del portale | Marketing → **Immagini eroe** (solo club whitelabel) |
| Domini incorporati / personalizzati | Club → **Domini incorporati** — [Domini incorporati per iframe](embed-domains-for-iframes.md) |
| Mittente email con marchio | Club → Integrazioni → [SendGrid](../integrations/sendgrid.md) |
| Logo del club | Club → Impostazioni |
| Disabilita email panoramica giornaliera | Impostazione a livello di club o per sfida (club whitelabel) |

## Flussi di accesso del partecipante

I portali whitelabel utilizzano comunemente il **codice di autorizzazione OAuth**:

1. Il partecipante clicca su **Accedi** sul sito con marchio.
2. Il browser reindirizza a DistantRace `/oauth/authorize/` con l'UUID della tua organizzazione.
3. DistantRace mostra una pagina di accesso **a tema** (codice email, passkey o SAML — a seconda della configurazione del club).
4. Dopo l'autenticazione, il browser ritorna al tuo portale con un codice scambiato per token di accesso e aggiornamento.
5. Il portale chiama `/api/v1/` con il token utente per azioni personali (unisciti alla sfida, sincronizza allenamenti, aggiorna profilo).

I **link di invito email** possono effettuare l'accesso automatico dei partecipanti tramite l'endpoint API `redeem-email-token` quando il portale è configurato con un token organizzativo.

Il **SAML SSO** è disponibile per i club aziendali. I partecipanti inseriscono un'email di lavoro; DistantRace instrada al corretto IdP per dominio. Vedi [SAML aziendale e accesso whitelabel](../joining-events/enterprise-saml-and-whitelabel-login.md).

## Credenziali API (panoramica)

Le integrazioni whitelabel utilizzano due tipi di credenziali:

| Credenziale | Concessione / tipo | Uso tipico |
|-------------|---------------------|------------|
| **Org token** | Token bearer a lunga durata (utente admin org) | Elenchi pubblici di sfide/eventi, immagini eroe, validazione codici di accesso, riscatto token email |
| **User OAuth client** | Codice di autorizzazione (+ token di aggiornamento) | Accesso partecipante, unisciti agli eventi, allenamenti, profilo, checkout |

Entrambi sono creati e ruotati da DistantRace durante l'onboarding. Gli URI di reindirizzamento devono corrispondere al percorso `/auth/callback` del tuo portale in ogni ambiente (staging `*.wl.distantrace.com` e dominio personalizzato di produzione).

### URL di autorizzazione OAuth

L'accesso del partecipante inizia su `/oauth/authorize/` con:

- `client_id` — la tua applicazione OAuth utente
- `redirect_uri` — callback registrato sul tuo portale
- `response_type=code`
- `org=<club-uuid>` — lega la pagina di accesso alla tua organizzazione e seleziona il modello a tema

Dopo che il partecipante si autentica (codice email, passkey o SAML), DistantRace reindirizza al tuo callback con un codice di autorizzazione. Scambialo lato server o nella SPA per token di accesso e aggiornamento.

### Codici di accesso e email di invito

| Passo | API |
|-------|-----|
| Valida un codice prima di mostrare il checkout | `GET /api/v1/event/joincode/{code}/validate/` (org token) |
| Riscatta link magico email | `POST /api/v1/event/joincode/redeem-email-token/` con `{ "token": "…" }` |
| Crea codici dal tuo back office | `POST /api/v1/event/joincode/` (token utente admin — non il token org pubblico) |

Il riscatto del link magico può creare automaticamente un account dai dati precompilati del codice di accesso, restituire token OAuth e iscrivere automaticamente il partecipante in una sfida collegata quando configurato.

Mappa completa degli endpoint: [Panoramica API pubblica](../more-tools/public-api-overview.md).

## Email e notifiche

Quando [SendGrid](../integrations/sendgrid.md) è connesso:

- Le email di **codice di accesso** utilizzano il modello transazionale e l'indirizzo del mittente della tua organizzazione.
- I modelli di registrazione e marketing seguono la stessa integrazione.

I club whitelabel possono sopprimere l'email automatica **Panoramica giornaliera** per le sfide di passi a livello di organizzazione (`daily_email_disabled`) o per singola sfida.

## App mobile

L'app mobile standard **DistantRace** rimane disponibile. I partecipanti possono connettere app sportive e sincronizzare i passi tramite l'app anche quando si registrano su un portale web con marchio. L'app non è whitelabel; i dati dell'account sono condivisi tra distantrace.com, l'app mobile e il portale con marchio.

## Accesso organizzatore

Gli organizzatori e il personale continuano a utilizzare la **manager console** su distantrace.com:

- Modello URL: `/console/<org-code>/`
- [Autenticazione a due fattori](../joining-events/two-factor-authentication.md) è richiesta
- SAML può essere utilizzato per l'accesso del personale nei club aziendali, ma l'accesso alla console è separato dal flusso OAuth del portale partecipante

Vedi [Come accedere alla console organizzativa](access-the-organizer-console.md).

## Correlati

- [SAML aziendale e accesso whitelabel](../joining-events/enterprise-saml-and-whitelabel-login.md) — accesso partecipante
- [Branding del club e immagini eroe](club-branding-and-hero-images.md)
- [Domini incorporati per iframe](embed-domains-for-iframes.md)
- [Panoramica API pubblica](../more-tools/public-api-overview.md)
- [SendGrid](../integrations/sendgrid.md)