Hoppa till huvudinnehållet

Cosafe Support Center


Exempel på hur man skickar SCIM-förfrågningar

Important

Den här artikeln innehåller exempel på SCIM-slutpunktsförfrågningar som API:et stöder. Din identitetsleverantör (IdP) hanterar vanligtvis dessa förfrågningar automatiskt, så manuell interaktion är vanligtvis onödig.

Använd endast dessa exempel om du bygger en anpassad koppling och behöver testa mot SCIM API:et. Anpassade kopplingar kan ge instabila eller oförutsägbara resultat om de beter sig oväntat, så vi avråder generellt från att skriva dem från grunden. Om din situation kräver manuell integration och du inte kan använda en förbyggd tredjepartskoppling, se dessa exempel som vägledning.

Base URL​

Använd bas-URL:en som angavs under aktiveringen av SCIM-tillägget. Exempel i det här dokumentet refererar till detta som <base-url>.

Headers​

Alla förfrågningar måste innehålla följande headers:

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

För enkelhetens skull visar efterföljande exempel endast URL:en och begärandetexten.

Begränsningar​

  • Maximalt antal sidnumreringar: 1000
  • Maximal längd på attributet members för förfrågningar: 1000
  • GET filter stöder endast ett attribut med eq (lika med) operationen

Read endpoints​

Lista alla användare​

GET <base-url>/Users

Svar:

{
  "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
}

Lista alla grupper​

GET <base-url>/Groups

Svar:

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

Hitta befintlig användare​

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

För att kontrollera om en användare redan finns i systemet och för att hämta deras id för efterföljande förfrågningar, använd parametern filter med det matchande attributet userName för att hitta användare med deras unika namn.

Om användaren finns returnerar endpoint användarschemat som innehåller attributet id, vilket du använder för alla efterföljande förfrågningar för den här användaren:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1,
  "Resurser": [
    {
      "active": true,
      "id": "8693b7d1-afe8-11f0-8cc2-3a7cb373875a",
      "användarnamn": "john@example.com",
      "e-postmeddelanden": [
        {
          "värde": "john@example.com",
          "primär": sant
        }
      ],
      "displayName": "John Doe",
      "telefonnummer": [
        {
          "primär": sant,
          "värde": "+46701740635",
          "typ": "arbete"
        },
        {
          "primär": falskt,
          "värde": "+46313900642",
          "typ": "mobil"
        }
      ]
    }
  ]
}

Om användaren inte finns returnerar endpoint 200 OK med en tom lista.

Hämta en användare​

Hämta en befintlig användare genom att göra en GET-request till /Users med användarens id.

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

Svar:

{
  "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"
    }
  ]
}

Använd den här endpointen för att verifiera att användaren fortfarande finns i systemet eller för att kontrollera om attributen inte matchar.

Hitta befintlig grupp​

Använd attributet externalId för att hitta en grupp. För instruktioner om hur du konfigurerar fältet Grupp-ID i administratörspanelen, se Konfigurera grupper.

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

Svar:

{
  "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
}

Viktiga överväganden:

  • Om denna endpoint returnerar "totalResults": 2 (eller ett värde större än 1), betrakta associationen som misslyckad och försök inte använda det första elementet i listan som matchad användare.
  • Om gruppen inte hittas, skapa en grupp från Cosafe-administratörspanelen och ange grupp-ID:t som ditt interna system-ID. Det här fältet blir attributet externalId.
  • Attributet members är exkluderat från den här listan. För att hämta medlemmar, använd get a group endpoint.
  • Om svaret inte innehåller attributet externalId är grupp-ID:t inte korrekt konfigurerat i administratörspanelen. Se Konfigurera grupper.

Hämta en grupp​

Hämta en befintlig grupp genom att göra en GET-request till /Groups-slutpunkten med grupp-id`.

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

Svar:

{
  "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" }
  ]
}

Attributet members innehåller en lista över användar-ID:n (id) som tillhör den gruppen som value.

I gruppnamnet är prefixet "West County" inte en del av gruppnamnet. Det är namnet på det underkonto som gruppen tillhör. Detta prefix läggs till för IdP:er som behöver skilja returnerade grupper med deras displayName, eftersom olika underkonton ofta innehåller grupper med identiska namn.

Skapa objekt​

Skapa en användare​

POST <base-url>/Users

Begäran:

{
  "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" }
  ]
}

Svar:

{
  "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
    }
  ]
}

Svaret innehåller attributet id, som du använder för alla efterföljande förfrågningar för den här användaren.

Skapa en grupp​

För att skapa en grupp, skapa den i Cosafe-administratörspanelen och ange grupp-ID:t som ditt interna system-ID, vilket blir externalId.

Uppdatera objekt​

Den föredragna metoden för att modifiera en resurs är att använda en PATCH-begäran med en åtgärd på attributet.

Uppdatera en grupp​

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

Begäran:

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

PATCH-operation kan innehålla flera operationer.

Denna begäran ersätter "all personal" med "ledande personal".

Svar:

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

Uppdatera gruppmedlemmar​

Du kan uppdatera gruppmedlemmar med två metoder:

1. Delvis uppdatering (lägg till eller ta bort specifika användare)​

Lägger till medlemmar:

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

Begäran:

{
  "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" }
      ]
    }
  ]
}

Elementet value är användarens id.

Svar:

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

Tar bort medlemmar:

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

Begäran:

{
  "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" }
      ]
    }
  ]
}

Svar:

{
  "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. Ersätt hela medlemsmatrisen​

Om du föredrar att ersätta samtliga medlemmar, använd en PUT-begäran.

Obs! Den här metoden rekommenderas inte för grupper med ett stort antal medlemmar. Av prestandaskäl, använd partiella uppdateringar via Lägg till/ta bort-åtgärder med endast de ändrade medlemskapen, inklusive under den initiala grupppåfyllningen.

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

Begäran:

{
  "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" }
  ]
}

Svar:

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

Uppdatera användarattribut​

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

Begäran:

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

Svar:

{
  "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
    }
  ]
}

Uppdatera användarens flervärdesattribut​

1. Ersätt telefonnummer​

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

Begäran:

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

Svar:

{
  "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. Ersätt telefonnummer med borttagning​

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

Begäran:

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

Svar:

{
  "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-kompatibelt format​

API:et stöder även formatet som skickas av Entra:

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

Begäran:

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

Svar:

{
  "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
    }
  ]
}

Ta bort​

Ta bort en användare​

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

Svar:

204 No Content

Efterföljande GET-förfrågningar för denna resurs via ID kommer att returnera 404 Not Found.

Ta bort en grupp​

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

Svar:

204 No Content

Efterföljande GET-förfrågningar för denna resurs via ID kommer att returnera 404 Not Found.