Vai al contenuto

Sicurezza

L'API relativa alla sicurezza permette di gestire gli utenti di un registrar, i gruppi da associare agli utenti e gli indirizzi IP abilitati per l'accesso a un particolare servizio. Per tutti i metodi è richiesta la presenza dello scope security nel token.

Gestione utenti

E’ possibile ottenere i dati di tutti gli utenti o di uno specifico utente del Registrar, ottenere i dati del proprio utente autenticato, creare o cancellare un utente.

Per quanto riguarda l’associazione fra utenti e gruppi, è possibile ottenere i dati dei gruppi associati ad uno specifico utente o all’utente autenticato ed ottenere i requisiti che una password di un utente deve soddisfare.

Creare un utente

1.0 | security | admin |

POST https://api.nic.it/v1/users

Il Registrar può creare un utente come nell'esempio seguente:

POST /v1/users HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: api.nic.it
Authorization: Bearer token.....

{
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "password" : "Abcdef-123"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id" : 7,
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "created" : "2024-05-06T16:45:46+02:00",
  "lastupdate" : "2024-05-06T16:45:46+02:00"
}

curl -X POST "https://api.nic.it/v1/users" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '
 {
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "password" : "Abcdef-123"
}`

{
  "id" : 7,
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "created" : "2024-05-06T16:45:46+02:00",
  "lastupdate" : "2024-05-06T16:45:46+02:00"
}

http https://api.nic.it/v1/users \
"Authorization: Bearer token..." \
--raw '
{
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "password" : "Abcdef-123"
}'

{
  "id" : 7,
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "created" : "2024-05-06T16:45:46+02:00",
  "lastupdate" : "2024-05-06T16:45:46+02:00"
}

Info

Al primo accesso il nuovo utente dovrà confermare i propri dati, verificare l'email e modificare la password.

Ottenere un utente tramite id

1.0 | security | admin |

GET https://api.nic.it/v1/users/{userId}

E' possibile ottenere i dati di un utente tramite id come nell'esempio seguente:

GET /v1/users/7 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token.....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 7,
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "created" : "2024-05-06T16:45:46+02:00",
  "lastupdate" : "2024-05-06T16:45:46+02:00"
}

curl "https://api.nic.it/v1/users/7" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 7,
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "created" : "2024-05-06T16:45:46+02:00",
  "lastupdate" : "2024-05-06T16:45:46+02:00"
}

http https://api.nic.it/v1/users/7 "Authorization: Bearer token..."

{
  "id" : 7,
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "created" : "2024-05-06T16:45:46+02:00",
  "lastupdate" : "2024-05-06T16:45:46+02:00"
}

Ottenere i dati dell'utente autenticato

1.0 | security |

GET https://api.nic.it/v1/user

Ogni utente autenticato può ottenere i dati del proprio utente come nell'esempio che segue:

GET /v1/user HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token.....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 7,
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "created" : "2024-05-06T16:45:46+02:00",
  "lastupdate" : "2024-05-06T16:45:46+02:00"
}

curl "https://api.nic.it/v1/user" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 7,
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "created" : "2024-05-06T16:45:46+02:00",
  "lastupdate" : "2024-05-06T16:45:46+02:00"
}

http https://api.nic.it/v1/user "Authorization: Bearer token..."

{
  "id" : 7,
  "username" : "giulio.cesare",
  "name" : "Giulio",
  "lastName" : "Cesare",
  "email" : "giulio.ceare@test-giulio-cesare.it",
  "created" : "2024-05-06T16:45:46+02:00",
  "lastupdate" : "2024-05-06T16:45:46+02:00"
}

Cancellare un utente tramite id

1.0 | security | admin |

DELETE https://api.nic.it/v1/users/{userId}

E' possibile cancellare un utente tramite id come nell'esempio seguente:

DELETE /v1/users/1 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: api.nic.it
Authorization: Bearer token.....

HTTP/1.1 204 No Content

curl -X DELETE "https://api.nic.it/v1/users/1" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

http DELETE https://api.nic.it/v1/users/1 "Authorization: Bearer token..."

Info

E' possibile cancellare tutti gli utenti a esclusione dell'utente principale TAG-REG

Ricercare gli utenti

1.0 | security | admin |

GET https://api.nic.it/v1/users

La ricerca degli utenti associati a un Registrar può essere fatta utilizzando vari parametri di ricerca e operatori (ricerca avanzata).

Di seguito sono riportati i parametri e gli operatori supportati:

Parametro Tipo Cardinalità Operatori supportati Operatore default
username String Singolo eq, ne, in, notIn eq
name String Singolo eq, ne, in, notIn, contains, startsWith, endsWith eq
lastName String Singolo eq, ne, in, notIn, contains, startsWith, endsWith eq
email String Singolo eq, ne, in, notIn eq
group String Singolo - -
created DateTime Multiplo eq, ne, in, notIn, ge, gt, le, lt, between eq
lastupdate DateTime Multiplo eq, ne, in, notIn, ge, gt, le, lt, between eq
lastPasswordChange DateTime Multiplo eq, ne, in, notIn, ge, gt, le, lt, between eq

Esempio di ricerca degli utenti del Registrar creati a partire dal 2024 e appartenenti al gruppo domain:

GET /v1/users?created=ge%3A2024-01-01&group=domain HTTP/1.1
Accept: application/json
Host: api.nic.it
Authentication: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "elements" : [ {
    "id" : 5,
    "username" : "alessandro.magno",
    "name" : "Alessandro",
    "lastName" : "Magno",
    "email" : "alessandro.magno@nic.it",
    "created" : "2024-02-05T10:25:03+02:00",
    "lastupdate" : "2024-03-05T08:25:02+02:00",
    "lastPasswordChange" : "2024-03-05T08:25:02+02:00"
  }, {
    "id" : 6,
    "username" : "giulio.cesare",
    "name" : "Giulio",
    "lastName" : "Cesare",
    "email" : "giulio.cesare@nic.it",
    "created" : "2024-03-05T10:25:03+02:00",
    "lastupdate" : "2024-04-05T08:25:02+02:00",
    "lastPasswordChange" : "2024-04-05T08:25:02+02:00"
  } ],
  "page" : {
    "number" : 0,
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1
  }
}

curl "https://api.nic.it/v1/users?created=ge:2024-01-01&group=domain" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "elements" : [ {
    "id" : 5,
    "username" : "alessandro.magno",
    "name" : "Alessandro",
    "lastName" : "Magno",
    "email" : "alessandro.magno@nic.it",
    "created" : "2024-02-05T10:25:03+02:00",
    "lastupdate" : "2024-03-05T08:25:02+02:00",
    "lastPasswordChange" : "2024-03-05T08:25:02+02:00"
  }, {
    "id" : 6,
    "username" : "giulio.cesare",
    "name" : "Giulio",
    "lastName" : "Cesare",
    "email" : "giulio.cesare@nic.it",
    "created" : "2024-03-05T10:25:03+02:00",
    "lastupdate" : "2024-04-05T08:25:02+02:00",
    "lastPasswordChange" : "2024-04-05T08:25:02+02:00"
  } ],
  "page" : {
    "number" : 0,
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1
  }
}

http https://api.nic.it/v1/users \
"Authorization: Bearer token..." \
created==ge:2024-01-01 group==domain

{
  "elements" : [ {
    "id" : 5,
    "username" : "alessandro.magno",
    "name" : "Alessandro",
    "lastName" : "Magno",
    "email" : "alessandro.magno@nic.it",
    "created" : "2024-02-05T10:25:03+02:00",
    "lastupdate" : "2024-03-05T08:25:02+02:00",
    "lastPasswordChange" : "2024-03-05T08:25:02+02:00"
  }, {
    "id" : 6,
    "username" : "giulio.cesare",
    "name" : "Giulio",
    "lastName" : "Cesare",
    "email" : "giulio.cesare@nic.it",
    "created" : "2024-03-05T10:25:03+02:00",
    "lastupdate" : "2024-04-05T08:25:02+02:00",
    "lastPasswordChange" : "2024-04-05T08:25:02+02:00"
  } ],
  "page" : {
    "number" : 0,
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1
  }
}

I risultati della ricerca sono paginati.

Info

Se non viene specificato alcun parametro di ricerca saranno riportati tutti gli utenti del Registrar.

Ottenere i gruppi di un utente

1.0 | security | admin |

GET https://api.nic.it/v1/users/{userId}/groups

E' possibile ottenere i gruppi a cui appartiene un utente come nell'esempio che segue:

GET /v1/users/1/groups HTTP/1.1
Accept: application/json
Host: api.nic.it
Authentication: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

[ "domain", "billing" ]

curl "https://api.nic.it/v1/users/1/groups" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

[ "domain", "billing" ]

http https://api.nic.it/v1/users/1/groups "Authorization: Bearer token..."

[ "domain", "billing" ]

Modificare i gruppi di un utente

1.0 | security | admin |

GET https://api.nic.it/v1/users/{userId}/groups

E' possibile modificare i gruppi a cui appartiene un utente come nell'esempio che segue:

PUT /v1/users/1/groups HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api.nic.it
Authentication: Bearer token....

[ "domain", "billing" ]

HTTP/1.1 200 OK
Content-Type: application/json

[ "domain", "billing" ]

curl -X PUT "https://api.nic.it/v1/users/1/groups" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."
-d '[ "domain", "billing" ]'

[ "domain", "billing" ]

echo '[ "domain", "billing" ]' | http PUT https://api.nic.it/v1/users/1/groups "Authorization: Bearer token..."

[ "domain", "billing" ]

Info

Non è possibile modificare i gruppi dell'utente principale TAG-REG.

Ottenere i gruppi dell'utente autenticato

1.0 | security |

GET https://api.nic.it/v1/user/groups

Un utente autenticato può ottenere i gruppi a cui appartiene come nell'esempio seguente:

GET /v1/user/groups HTTP/1.1
Accept: application/json
Host: api.nic.it
Authentication: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

[ "domain" ]

curl "https://api.nic.it/v1/user/groups" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

[ "domain" ]

http https://api.nic.it/v1/user/groups "Authorization: Bearer token..."

[ "domain" ]

Ottenere i requisiti delle password

1.0 | security |

GET https://api.nic.it/v1/passwordRequirements

Le password devono soddisfare alcuni requisiti che si possono ottenere come nell'esempio seguente:

GET /v1/passwordRequirements HTTP/1.1
Accept: application/json
Host: api.nic.it
Authentication: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "minLength" : 8,
  "maxLength" : 16,
  "upperCaseCharacters" : 1,
  "lowerCaseCharacters" : 1,
  "digits" : 1,
  "specialCharacters" : 1,
  "whiteSpaces" : false,
  "notEqualsLastPassword" : true
}

curl "https://api.nic.it/v1/passwordRequirements" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "minLength" : 8,
  "maxLength" : 16,
  "upperCaseCharacters" : 1,
  "lowerCaseCharacters" : 1,
  "digits" : 1,
  "specialCharacters" : 1,
  "whiteSpaces" : false,
  "notEqualsLastPassword" : true
}

http https://api.nic.it/v1/passwordRequirements "Authorization: Bearer token..."

{
  "minLength" : 8,
  "maxLength" : 16,
  "upperCaseCharacters" : 1,
  "lowerCaseCharacters" : 1,
  "digits" : 1,
  "specialCharacters" : 1,
  "whiteSpaces" : false,
  "notEqualsLastPassword" : true
}

Gestione indirizzi IP

La gestione degli indirizzi IP permette al Registrar di aggiungere/abilitare i propri indirizzi IP per l'accesso ai seguenti servizi:

  • epp-server
  • das

E’ possibile ottenere l’elenco degli indirizzi IP associati a uno specifico servizio, aggiungere o cancellare un indirizzo IP.

Gli indirizzi IP per il servizio epp-server possono essere associati a tutti gli utenti appartenenti al gruppo epp, mentre per il servizio das si possono aggiungere indirizzi IP solo per l'utente principale TAG-REG del Registrar.

Info

Al momento è possibile specificare per entrambi i servizi sopra indicati solo indirizzi IPv4.

Warning

L'aggiunta o cancellazione di un indirizzo IP non è immediatamente applicata nei sistemi del Registro .it e può richiedere diversi minuti prima che sia effettiva.

Aggiungere un indirizzo IP

1.0 | security | admin |

POST https://api.nic.it/v1/ipAddresses

E' possibile aggiungere un indirizzo IP per un servizio come nell'esempio seguente:

POST /v1/ipAddresses HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: api.nic.it
Authentication: Bearer token....

{
"ipAddress" : "192.12.192.1",
"service" : "epp-server",
"userId" : 5
}

HTTP/1.1 201 Created
Content-Type: application/json

[ {
"id" : 15,
"userId" : 5,
"service" : "epp-server",
"ipAddress" : "192.12.192.1",
"ipVersion" : "IPv4",
"created" : "2024-04-18T14:55:22+02:00"
} ]

curl -X POST "https://api.nic.it/v1/ipAddresses" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '
{
    "ipAddress" : "192.12.192.1",
    "service" : "epp-server",
    "userId" : 5
}'

[ {
"id" : 15,
"userId" : 5,
"service" : "epp-server",
"ipAddress" : "192.12.192.1",
"ipVersion" : "IPv4",
"created" : "2024-04-18T14:55:22+02:00"
} ]

http https://api.nic.it/v1/ipAddresses "Authorization: Bearer token..." \
--raw '
{
    "ipAddress" : "192.12.192.1",
    "service" : "epp-server",
    "userId" : 5
}'

[ {
"id" : 15,
"userId" : 5,
"service" : "epp-server",
"ipAddress" : "192.12.192.1",
"ipVersion" : "IPv4",
"created" : "2024-04-18T14:55:22+02:00"
} ]

La risposta contiene tutti gli indirizzi IP per il servizio a cui è stato aggiunto l'indirizzo, nell'esempio sopra riporta quindi gli indirizzi IP del servizio epp-server.

Cancellare un indirizzo IP

1.0 | security | admin |

DELETE https://api.nic.it/v1/ipAddresses/{ipAddressId}

E' possibile cancellare un indirizzo IP tramite l'identificativo numerico dell'IP come nell'esempio seguente:

DELETE /v1/ipAddresses/15 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authentication: Bearer token....

HTTP/1.1 204 No Content

curl -X DELETE "https://api.nic.it/v1/ipAddresses/15" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

http DELETE https://api.nic.it/v1/ipAddresses/15 "Authorization: Bearer token..."

Elenco degli indirizzi IP

1.0 | security | admin |

GET https://api.nic.it/v1/ipAddresses

E' possibile ottenere l'elenco degli indirizzi IP di un servizio come nell'esempio seguente:

GET /v1/ipAddresses?service=epp-server HTTP/1.1
Accept: application/json
Host: api.nic.it
Authentication: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

[ {
  "id" : 4,
  "userId" : 2,
  "service" : "epp-server",
  "ipAddress" : "192.12.192.3",
  "ipVersion" : "IPv4",
  "created" : "2023-09-23T17:21:15+02:00"
}, {
  "id" : 5,
  "userId" : 2,
  "service" : "epp-server",
  "ipAddress" : "192.12.192.5",
  "ipVersion" : "IPv4",
  "created" : "2020-08-01T16:10:11+02:00"
} ]

curl "https://api.nic.it/v1/ipAddresses?service=epp-server" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

[ {
  "id" : 4,
  "userId" : 2,
  "service" : "epp-server",
  "ipAddress" : "192.12.192.3",
  "ipVersion" : "IPv4",
  "created" : "2023-09-23T17:21:15+02:00"
}, {
  "id" : 5,
  "userId" : 2,
  "service" : "epp-server",
  "ipAddress" : "192.12.192.5",
  "ipVersion" : "IPv4",
  "created" : "2020-08-01T16:10:11+02:00"
} ]

http https://api.nic.it/v1/ipAddresses "Authorization: Bearer token..." \
service==epp-server

[ {
  "id" : 4,
  "userId" : 2,
  "service" : "epp-server",
  "ipAddress" : "192.12.192.3",
  "ipVersion" : "IPv4",
  "created" : "2023-09-23T17:21:15+02:00"
}, {
  "id" : 5,
  "userId" : 2,
  "service" : "epp-server",
  "ipAddress" : "192.12.192.5",
  "ipVersion" : "IPv4",
  "created" : "2020-08-01T16:10:11+02:00"
} ]

Oltre al parametro service, obbligatorio, è possibile specificare anche i seguenti due parametri di ricerca opzionali:

  • userId: id utente a cui è associato l'indirizzo IP
  • ipAddress: indirizzo IP