> For the complete documentation index, see [llms.txt](https://docs.opencityitalia.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/single-sign-on/sso-mediante-oauth2.md).

# SSO mediante oAuth2

{% hint style="warning" %}
La funzionalità è disponibile esclusivamente su richiesta.
{% endhint %}

Una autenticazione con SSO tra Opencity Italia e un applicativo in uso allo stesso Ente può essere agevolmente realizzata se può essere garantito il supporto per il protocollo [oAuth2](https://oauth.net/2/).

Vediamo uno schema generale degli attori in gioco:

```mermaid
C4Context
  title OAuth2 Integration
  Boundary(b0, "Opencity Italia SaaS"){
    System(openlogin, "Open Login")
    System(core, "Area personale")
  }

  Person_Ext(cittadino, "Cittadino", "Si autentica con SPID o CIE")
  System_Ext(app3p, "App di terze parti")

  Rel(cittadino, openlogin, "SPID/CIE")
  Rel(app3p, openlogin, "client oAuth2")
  Rel(core, openlogin, "client oAuth2")
  
  UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")

```

Vediamo un flusso di autenticazione di un cittadino che fa login prima sull'area personale e successivamente sull'applicativo di terze parti:

```mermaid
sequenceDiagram
  autonumber
  actor c as Cittadino
  participant core as Area Personale
  participant ol as Openlogin
  participant idp as Identity Provider
  participant app3p as Altra App
  c -->> core: accesso a /login 
  core --> c: il tenant richiede /login-auth
  c -->> core: /login-auth
  Note over core: Il client di Area Personale<br> verifica presenza sessione/avvia<br>flusso oauth2 (definita redirect_url)
  core -->> c: redirect to url_authorize di openlogin
  c -->> ol: login page
  Note over core, ol: Scelta tra Spid/CIE
  rect rgb(192, 223, 255)
  ol -->> c: redirect to SPID Provider o CIE
  c -->> idp: flusso di autenticazione SPID o CIE
  idp -->> c: POST Saml a openlogin / Flusso OpenID CIE
  c -->> ol: il cittadino torna su openlogin
  Note over c, ol: Viene creato l'utente<br> e agganciata la sessione SPID alla sessione OpenLogin.<br>Riparte flusso oAuth
  end
  ol -->> c: openlogin ti rimanda a A.P. a /login-auth con codice autorizzazione
  core -->> ol: con il codice di autorizzazione chiama url_access_token di OpenLogin
  ol -->> core: restituisce il token oAuth2
  core -->> ol: richiede il profilo utente all'indirizzo url_resource_owner_details e<br> li salva nella propria sessione
  
```

L'applicativo di terze parti dovrà essere dotato di un opportuno client oAuth2. Ipotiziamo che le url coinvolte siano le seguenti e mostriamo una tipica configurazione del client.

{% hint style="info" %}
URL dell'area personale: <https://servizi.comune.bugliano.pi.it>

URL della pagina di login (OpenLogin): <http://login.comune.bugliano.pi.it>

URL dell'applicativo di terze parti: <http://myapp.company.com>
{% endhint %}

Per attivare un nuovo client è necessario fornire:

* La URL da autorizzare come redirct uri del client
* La URL di logout

L'attivazione comprende i seguenti dati

```
redirect_url: http://servizi.comune.bugliano.pi.it/lang/auth/login-oauth
url_authorize: http://login.comune.bugliano.pi.it/authorize
url_access_token: http://login.comune.bugliano.pi.it/token
url_resource_owner_details: http://login.comune.bugliano.pi.it/api/profile
url_logout: http://login.comune.bugliano.pi.it/logout?redirect=http://servizi.comune.bugliano.pi.it/lang
client_id: {client_id} fornito da Opencity Labs
client_secret: {client_secret} fornito da Opencity Labs
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/single-sign-on/sso-mediante-oauth2.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.