SCIM-Benutzer-API-Referenz¶

Sie können die SCIM-Benutzer-API verwenden, um auf Benutzerdaten zuzugreifen und Benutzerdaten zu erstellen und zu ändern.

HTTP-Header¶

Die Snowflake SCIM API verwendet Bearer-Token für die HTTP-Authentifizierung.

Jede HTTP-Anfrage an Snowflake SCIM API erlaubt die folgenden HTTP-Header:

Header	Wert
`Authorization` (erforderlich)	`Bearer <Zugriffstoken>`
`Content-Type`	`application/scim+json`
`Accept-Encoding`	`utf-8`
`Accept-Charset`	`utf-8`

Benutzerattribute¶

Sie können Benutzerattribute im Textkörper (Body) von API-Anforderungen als Schlüssel-Wert-Paare im JSON-Format angeben. Diese Paare enthalten Informationen zu dem Benutzer, wie Anzeigename oder E-Mail-Adresse des Benutzers. Identitätsanbieter können ihre eigenen Schlüsselnamen für jedes Attribut angeben. So können Identitätsanbieter beispielsweise den Schlüssel lastName anstelle von familyName verwenden, um den Nachnamen des Benutzers zu repräsentieren. Snowflake unterstützt keine mehrwertigen Benutzerattribute.

Wichtig

In der nachstehenden Tabelle beziehen sich die Attribute userName und loginName beide auf das Attribut userName. Snowflake unterstützt die Angabe unterschiedlicher Werte für die Attribute userName und loginName.

Snowflake unterstützt die folgenden Attribute für die Verwaltung des Benutzerlebenszyklus.

SCIM-Benutzerattribut	Snowflake-Benutzerattribut	Typ	Beschreibung
`id`	`ID`	string	Der unveränderliche, eindeutige Bezeichner (GUID) des Benutzers in Snowflake. Snowflake zeigt diesen Wert weder in der Ausgabe von DESCRIBE USER noch in der Ausgabe von SHOW USERS an. Für Anforderungen an Endpunkte, die dieses Attribut erfordern, wie `PATCH scim/v2/Users/{{id}}`, kann das Attribut `id` mit der Funktion REST_EVENT_HISTORY gefunden werden. Überprüfen Sie die IdP-Protokolle, um sicherzustellen, dass die Werte übereinstimmen.
`userName`	`NAME`, `LOGIN_NAME`	string	Der Bezeichner für die Anmeldung bei Snowflake. Weitere Informationen zu diesen Attributen finden Sie unter CREATE USER.
`name.givenName`	`FIRST_NAME`	string	Der Vorname des Benutzers.
`name.familyName`	`LAST_NAME`	string	Der Nachname des Benutzers.
`emails`	`EMAIL`	string	Die E-Mail-Adresse des Benutzers.
`displayName`	`DISPLAY_NAME`	string	Der Text, der auf der Benutzeroberfläche angezeigt wird, wenn er sich auf den Benutzer bezieht.
`externalID`	N/A	string	Der vom Bereitstellungsclient (z. B. Azure, Okta) festgelegte eindeutige Bezeichner.
`password`	`PASSWORD`	string	Das Kennwort für den Benutzer. Dieser Wert wird in der JSON-Antwort nicht zurückgegeben. Wenn die Eigenschaft `SYNC_PASSWORD` in der SCIM-Sicherheitsintegration auf `FALSE` gesetzt ist und die SCIM-API-Anforderung das Attribut `password` angibt, ignoriert Snowflake den Wert des Attributs `password`. Alle anderen Attribute in der API-Anforderung werden entsprechend verarbeitet.
`active`	`DISABLED`	boolean	Deaktiviert den Benutzer, wenn `false` eingestellt ist.
`groups`	N/A	string	Eine Liste von Gruppen, zu denen der Benutzer gehört. Der `displayName`-Wert der Gruppe ist erforderlich. Die Gruppen des Benutzers sind unveränderlich. Ihre Mitgliedschaft muss mithilfe de SCIM-Gruppen-API aktualisiert werden.
`meta.created`	`CREATED_ON`	string	Der Zeitpunkt, zu der der Benutzer zu Snowflake hinzugefügt wurde.
`meta.lastModified`	`UPDATED_ON`	string	Der Zeitpunkt, zu dem der Benutzer zuletzt in Snowflake geändert wurde.
`meta.resourceType`	N/A	string	Der Typ der Ressource für den Benutzer. Sie sollten `user` als Wert für dieses Attribut verwenden.
`schemas`	N/A	string	Ein kommatgetrenntes Array von Zeichenfolgen, das die Namespace URIs angibt. Snowflake unterstützt die folgenden Werte: `urn:ietf:params:scim:schemas:core:2.0:User` `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` `urn:ietf:params:scim:schemas:extension:2.0:User`

Kundenspezifische Attribute¶

Sie können benutzerdefinierte Attribute festlegen, die nicht durch RFC 7643 definiert sind, wie z. B. defaultRole.

Sie können die folgenden Namespaces verwenden, um benutzerdefinierte Attribute für POST-, PUT- und PATCH-Anforderungen festzulegen:

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Dieser Namespace war Teil der ursprünglichen SCIM-Implementierung in Snowflake. Sie können diesen Namespace nur für das Festlegen benutzerdefinierter Attribute in Okta-SCIM-Sicherheitsintegrationen verwenden.

Sie können diesen Namespace nicht verwenden, um benutzerdefinierte Attribute in Microsoft Azure-SCIM-Sicherheitsintegrationen oder benutzerdefinierten SCIM-Integrationen festzulegen.

urn:ietf:params:scim:schemas:extension:2.0:User

Sie können diesen Namespace verwenden, um benutzerdefinierte Attribute für alle SCIM-Integrationen festzulegen. Sie müssen diesen Namespace verwenden, um benutzerdefinierte Attribute in Microsoft Azure-SCIM-Sicherheitsintegrationen oder benutzerdefinierten SCIM-Sicherheitsintegrationen festzulegen.

Snowflake unterstützt die folgenden benutzerdefinierten Attribute:

SCIM Benutzerdefiniertes Attribut	Snowflake-Benutzerattribut	Typ	Beschreibung
`defaultWarehouse`	`DEFAULT_WAREHOUSE`	string	Virtuelles Warehouse, das bei der Anmeldung standardmäßig für die Sitzung des Benutzers aktiv ist.
`defaultRole`	`DEFAULT_ROLE`	string	Die Primärrolle, die bei der Anmeldung standardmäßig für die Sitzung des Benutzers aktiv ist.
`defaultSecondaryRoles`	`DEFAULT_SECONDARY_ROLES`	string	Die Liste der Sekundärrollen, die bei der Anmeldung für die Sitzung des Benutzers aktiv sind. Sie können dieses Attribut auf `ALL` als Alias für `('ALL')` festlegen, oder Sie können dieses Attribut auf `NONE` oder `""` als Alias für `()` festlegen.
`type`	`TYPE`	string	Der Typ des Benutzers. Standard: `null`. Sie können dieses Attribut auf `person`, `service`, `legacy_service` oder `null` festlegen. Weitere Informationen über die Typen von Benutzern finden Sie unter TYPE Objekteigenschaften von Benutzern.

Überprüfen, ob ein Benutzer existiert¶

Methode und Endpunkt:

GET /scim/v2/Users?filter=userName eq "{{user_name}}"

Beschreibung:

Gibt Details zu einem Benutzer zurück, der mit dem Abfrageparameter userName verbunden ist.

Gibt den HTTP-Antwort-Statuscode 200 zurück, wenn die HTTP-Anforderung erfolgreich abgeschlossen wurde.

Details zu einem Benutzer abrufen¶

Methode und Endpunkt:

GET /scim/v2/Users/{{user_id}}

Beschreibung:

Gibt Details zu einem Benutzer zurück, der mit dem Pfadparameter user_id verbunden ist.

Gibt den HTTP-Antwort-Statuscode 200 zurück, wenn die HTTP-Anforderung erfolgreich abgeschlossen wurde.

Benutzer erstellen¶

Methode und Endpunkt:

POST /scim/v2/Users

Beschreibung:

Erstellt einen Benutzer in Snowflake.

Gibt den HTTP-Antwort-Statuscode 201 zurück, wenn die HTTP-Anforderung erfolgreich abgeschlossen wurde.

Wenn der Benutzer bereits existiert oder die HTTP-Anfrage aus einem anderen Grund fehlgeschlagen ist, gibt Snowflake den HTTP-Antwortstatuscode 409 zurück.

Beispiele:

Erstellen eines Benutzers mit userName und loginName, die demselben Wert zugeordnet sind:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:2.0:User"
  ],
  "userName": "test_user_1",
  "password": "test",
  "name": {
    "givenName": "test",
    "familyName": "user"
  },
  "emails": [
    {"value": "test.user@snowflake.com"}
  ],
  "displayName": "test user",
  "active": true
}

Copy

Erstellen eines Benutzers mit userName und loginName, die unterschiedlichen Werten zugeordnet sind:

Bemerkung

Wenn Sie Okta als Identitätsanbieter verwenden, folgen Sie diesem Verfahren.

{
  "active": true,
  "displayName": "test user",
  "emails": [
    {"value": "test.user@snowflake.com"}
  ],
  "name": {
    "familyName": "test_last_name",
    "givenName": "test_first_name"
  },
  "password": "test_password",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "snowflakeUserName": "USER5"
  },
  "userName": "USER5"
}

Copy

Benutzerattribute ersetzen¶

Methode und Endpunkt:

PATCH /scim/v2/Users/{{id}}

Beschreibung:

Ersetzt die Attribute des Benutzers, der mit dem Pfadparameter id verbunden ist.

Sie müssen op auf replace setzen, um diese HTTP-Anforderung ausführen zu können.

active kann folgende Werte haben:

false: Deaktiviert den Benutzer.
true: Aktiviert den Benutzer.

Gibt den HTTP-Antwort-Statuscode 200 zurück, wenn die HTTP-Anforderung erfolgreich abgeschlossen wurde.

Wenn die Ausführung nicht erfolgreich war, wird der HTTP-Antwortcode 204 zurückgegeben.

Beispiele:

Deaktivieren eines Benutzers und aktualisieren seines givenName-Wertes auf deactivated_user:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "value": { "active": false }}
    {"op": "replace", "value": { "givenName": "deactivated_user" }}
  ],
}

Copy

Aktualisieren eines Benutzers mit userName und loginName, die demselben Wert zugeordnet sind:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "value": { "active": false }}
  ]
}

Copy

Aktualisieren eines Benutzers mit userName und loginName, die verschiedenen Werten zugeordnet sind.

Wenn Okta Ihr Identitätsanbieter ist, führen Sie diese Schritte aus.

{
  "Operations": [
    {
      "op": "replace",
      "path": "userName",
      "value": "test_updated_name"
    },
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.snowflakeUserName",
      "value": "USER5"
    }
  ],
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]
}

Copy

Benutzer aktualisieren¶

Methode und Endpunkt:

PUT /scim/v2/Users/{{id}}

Beschreibung:

Aktualisiert die Attribute des Benutzers, der mit dem Pfadparameter id verbunden ist.

Wenn die Ausführung nicht erfolgreich war, wird der HTTP-Antwortcode 400 zurückgegeben. Die HTTP-Anforderung ist erfolglos, wenn die Anforderung versucht, unveränderliche Attribute zu ändern oder wenn die zu ändernden Attribute in Snowflake nicht vorhanden sind.

Beispiele:

Aktualisieren eines Benutzers und seiner Attribute "defaultRole", "defaultSecondaryRoles" und "defaultWarehouse":

Um die Attribute "defaultRole", "defaultSecondaryRoles" und "defaultWarehouse" anzugeben, müssen Sie eines der extension-Schemas verwenden. Das Attribut defaultSecondaryRoles akzeptiert nur "ALL" als Wert.

Bemerkung

Die PUT-Methode ist kostenintensiver als die PATCH-Methode. Verwenden Sie stattdessen die Operation PATCH.

{
  "schemas": [
   "urn:ietf:params:scim:schemas:core:2.0:User",
   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "test_user_1",
  "password": "test",
  "name": {
    "givenName": "test",
    "familyName": "user"
  },
  "emails": [{
    "primary": true,
    "value": "test.user@snowflake.com",
    "type": "work"
  }
  ],
  "displayName": "test user",
  "active": true,
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "defaultRole" : "test_role",
    "defaultSecondaryRoles" : "ALL",
    "defaultWarehouse" : "test_warehouse"
  }
}

Copy

Benutzer löschen¶

Methode und Endpunkt:: DELETE /scim/v2/Users/{{id}}
Beschreibung:: Löscht den Benutzer, der mit dem Pfadparameter id verbunden ist.