Siirry pääsisältöön

Cosafe Support Center


Esimerkkejä SCIM-pyyntöjen lähettämisestä

Important

Tässä artikkelissa on esimerkkejä API:n tukemista SCIM-päätepistepyynnöistä. Identiteettipalveluntarjoajasi (IdP) käsittelee nämä pyynnöt yleensä automaattisesti, joten manuaalinen toiminta on yleensä tarpeetonta.

Käytä näitä esimerkkejä vain, jos olet rakentamassa mukautettua yhdistintä ja sinun on testattava sitä SCIM API:a vasten. Mukautetut liittimet voivat tuottaa epävakaita tai arvaamattomia tuloksia, jos ne toimivat odottamatta, joten emme yleensä suosittele niiden kirjoittamista alusta alkaen. Jos tilanteesi kuitenkin vaatii manuaalista integrointia etkä voi käyttää valmiiksi rakennettua kolmannen osapuolen yhdistintä, katso ohjeita näistä esimerkeistä.

Perus-URL​

Käytä SCIM-lisäosan aktivoinnin aikana annettua perus-URL-osoitetta. Tämän dokumentin esimerkeissä tähän viitataan muodossa <base-url>.

Ylätunnisteet​

Kaikkien pyyntöjen on sisällettävä seuraavat otsikot:

'Authorization': 'Bearer <your-api-key>',
'Content-Type': 'application/scim+json; charset=utf-8',

Yksinkertaisuuden vuoksi seuraavat esimerkit näyttävät vain URL-osoitteen ja pyynnön rungon.

Rajoitukset​

  • Sivutusten enimmäismäärä: 1000
  • Pyynnön members-attribuutin enimmäispituus: 1000
  • GET filter tukee yhtä attribuuttia vain eq (equal) -operaatiolla

Lue päätepisteitä​

Listaa kaikki käyttäjät​

GET <base-url>/Users

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "active": true,
      "id": "8693b7d1-afe8-11f0-8cc2-3a7cb373875a",
      "userName": "john@example.com",
      "emails": [
        {
          "value": "john@example.com",
          "primary": true
        }
      ],
      "displayName": "John Doe",
      "phoneNumbers": [
        {
          "primary": true,
          "value": "+467017406351",
          "type": "work"
        },
        {
          "primary": false,
          "value": "+46313900642",
          "type": "mobile"
        }
      ]
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1
}

Listaa kaikki ryhmät​

GET <base-url>/Groups

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "id": "8e9d1a59-bbe5-11f0-90fb-3e40deb6141c",
      "displayName": "West county -- all-staff"
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1
}

Etsi olemassa oleva käyttäjä​

GET <base-url>/Users?filter=userName eq "john@example.com"

Tarkistaaksesi, onko käyttäjä jo järjestelmässä, ja hakeaksesi hänen id-tietonsa myöhempiä pyyntöjä varten, käytä filter-parametria ja vastaavaa userName-attribuuttia käyttäjän löytämiseksi hänen yksilöllisen nimensä perusteella.

Jos käyttäjä on olemassa, päätepiste palauttaa käyttäjäskeeman, joka sisältää id-attribuutin, jota käytetään kaikissa tämän käyttäjän myöhemmissä pyynnöissä:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1,
  "Resources": [
    {
      "active": true,
      "id": "8693b7d1-afe8-11f0-8cc2-3a7cb373875a",
      "userName": "john@example.com",
      "emails": [
        {
          "value": "john@example.com",
          "primary": true
        }
      ],
      "displayName": "John Doe",
      "phoneNumbers": [
        {
          "primary": true,
          "value": "+46701740635",
          "type": "work"
        },
        {
          "primary": false,
          "value": "+46313900642",
          "type": "mobile"
        }
      ]
    }
  ]
}

Jos käyttäjää ei ole olemassa, päätepiste palauttaa arvon 200 OK tyhjällä listalla.

Hanki käyttäjä​

Hae olemassa oleva käyttäjä tekemällä GET-pyyntö /Users-päätepisteeseen käyttäjän id-arvolla.

GET <base-url>/Users/8693b7d1-afe8-11f0-8cc2-3a7cb373875a

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "8693b7d1-afe8-11f0-8cc2-3a7cb373875a",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/8693b7d1-afe8-11f0-8cc2-3a7cb373875a"
  },
  "userName": "john@example.com",
  "displayName": "John Doe",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "primary": true,
      "value": "+46701740635",
      "type": "work"
    },
    {
      "primary": false,
      "value": "+46313900642",
      "type": "mobile"
    }
  ]
}

Käytä tätä päätepistettä varmistaaksesi, että käyttäjä on edelleen järjestelmässä, tai tarkistaaksesi yhteensopimattomat määritteet.

Etsi olemassa oleva ryhmä​

Käytä externalId-attribuuttia ryhmän etsimiseen. Ohjeet Ryhmätunnus-kentän määrittämiseen hallintapaneelissa ovat kohdassa Ryhmien määrittäminen.

GET <base-url>/Groups?filter=externalId eq "b55a6bbf-fcc1-4d06-943e-896d963b649a"

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
      "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
      "displayName": "West county -- all-staff"
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1
}

Tärkeitä huomioitavia asioita:

  • Jos tämä päätepiste palauttaa arvon "totalResults": 2 (tai minkä tahansa arvon, joka on suurempi kuin 1), liittämistä pidetään epäonnistuneena äläkä yritä käyttää luettelon ensimmäistä elementtiä vastaavana käyttäjänä.
  • Jos ryhmää ei löydy, luo ryhmä Cosafe-hallintapaneelista ja aseta ryhmän tunnus sisäiseksi järjestelmätunnukseksesi. Tästä kentästä tulee externalId-attribuutti.
  • Members-attribuuttia ei ole sisällytetty tähän luetteloon. Jäsenten hakemiseen käytä get a group endpoint -metodia.
  • Jos vastaus ei sisällä externalId-attribuuttia, ryhmän tunnusta ei ole määritetty oikein hallintapaneelissa. Katso Ryhmien määrittäminen.

Hanki ryhmä​

Hae olemassa oleva ryhmä tekemällä GET-pyyntö /Groups-päätepisteeseen ryhmän id-määritteellä.

GET <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- all-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" }
  ]
}

members-attribuutti sisältää luettelon kyseiseen ryhmään kuuluvista käyttäjätunnuksista (id) value-arvona.

Ryhmän nimessä etuliite "West County" ei ole osa ryhmän nimeä. Se on sen alatilin nimi, johon ryhmä kuuluu. Tämä etuliite lisätään IdP:ille, joiden on erotettava palautetut ryhmät niiden displayName-attribuutin perusteella, koska eri alatileillä on usein identtisen nimen omaavia ryhmiä.

Luo päätepisteitä​

Luo käyttäjä​

POST <base-url>/Users

Pyynnön runko:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "active": true,
  "userName": "john@example.com",
  "displayName": "John Doe",
  "title": "Teacher",
  "phoneNumbers": [
    { "primary": true, "type": "work", "value": "+46701740635" },
    { "primary": false, "type": "mobile", "value": "+46313900642" }
  ]
}

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "+46313900642",
      "type": "mobile",
      "primary": false
    }
  ]
}

Vastaus sisältää id-attribuutin, jota käytät kaikissa tämän käyttäjän myöhemmissä pyynnöissä.

Luo ryhmä​

Luodaksesi ryhmän, luo se Cosafe-hallintapaneelissa ja aseta ryhmän tunnus sisäiseksi järjestelmätunnukseksi, josta tulee externalId.

Päivitä päätepisteitä​

Suositeltava tapa muokata resurssia on käyttää PATCH-pyyntöä, jossa on operaatio attribuutille.

Ryhmän päivittäminen​

PATCH <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Pyynnön runko:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "senior-staff"
    }
  ]
}

PATCH-operaatiopyyntö voi sisältää useita toimintoja.

Tämä pyyntö korvaa "all-staff"-sanan "senior-staff"-sanalla.

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" }
  ]
}

Päivitä ryhmän jäsenet​

Voit päivittää ryhmän jäseniä kahdella tavalla:

1. Osittainen päivitys (lisää tai poista tiettyjä käyttäjiä)​

Jäsenten lisääminen:

PATCH <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Pyynnön runko:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
        { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
      ]
    }
  ]
}

Elementti value on käyttäjän id.

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
    { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
  ]
}

Jäsenten poistaminen:

PATCH <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Pyynnön runko:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members",
      "value": [
        { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
        { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
      ]
    }
  ]
}

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" }
  ]
}

2. Korvaa koko jäsentaulukko​

Jos haluat mieluummin korvata koko members-taulukon, käytä PUT-pyyntöä.

Huomautus: Tätä lähestymistapaa ei suositella ryhmille, joissa on paljon jäseniä. Suorituskyvyn vuoksi käytä osittaisia päivityksiä lisää/poista-toimintojen kautta vain muuttuneille jäsenyyksille, myös ryhmän alkutäytön aikana.

PUT <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Pyynnön runko:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "displayName": "senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
    { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
  ]
}

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
    { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
  ]
}

Päivitä käyttäjän tavalliset määritteet​

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Pyynnön runko:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "John Doe Jr."
    }
  ]
}

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "+46313900642",
      "type": "mobile",
      "primary": false
    }
  ]
}

Päivitä käyttäjän moniarvoiset määritteet​

1. Vaihda puhelinnumerot​

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Pyynnön runko:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "phoneNumbers",
      "value": [
        { "primary": true, "value": "+46701740635" },
        { "primary": false, "value": "+46406280473" }
      ]
    }
  ]
}

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "+46406280473",
      "type": "mobile",
      "primary": false
    }
  ]
}

2. Korvaa puhelinnumerot poistamalla​

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Pyynnön runko:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "phoneNumbers",
      "value": [{ "primary": true, "value": "+46701740635" }]
    }
  ]
}

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "",
      "type": "mobile",
      "primary": false
    }
  ]
}

3. Entra-yhteensopiva formaatti​

API tukee myös Entran lähettämää muotoa:

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Pyynnön runko:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "phoneNumbers[type eq \"mobile\"].value",
      "value": "+46980319247"
    }
  ]
}

Vastaus:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "+46980319247",
      "type": "mobile",
      "primary": false
    }
  ]
}

Poista päätepisteet​

Käyttäjän poistaminen​

DELETE <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Vastaus:

204 No Content

Tämän resurssin myöhemmät GET-pyynnöt ID:n perusteella palauttavat virheen 404 Not Found.

Ryhmän poistaminen​

DELETE <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Vastaus:

204 No Content

Tämän resurssin myöhemmät GET-pyynnöt ID:n perusteella palauttavat virheen 404 Not Found.