Points de terminaison d’API REST pour SCIM

Remarque

Cette opération vous permet de provisionner l’accès à une organisation sur GitHub Enterprise Cloud à l’aide de SCIM. L’opération n’est pas disponible pour une utilisation avec Enterprise Managed Users. Pour plus d’informations sur l’approvisionnement de comptes d’utilisateur managés à l’aide de SCIM, consultez Points de terminaison d’API REST pour SCIM.

À propos de SCIM

Approvisionnement de SCIM pour les organisations

Ces points de terminaison sont utilisés par les fournisseurs d’identité (IdP) prenant en charge SCIM afin d’automatiser le provisionnement des membres de l’organisation GitHub, et sont basés sur la version 2.0 du standard SCIM. Les fournisseurs d’identité doivent utiliser l’URL de base pour les points de terminaison SCIM GitHub.

Remarque

Ces points de terminaison sont uniquement disponibles pour les organisations qui utilisent GitHub Enterprise Cloud avec l’authentification unique SAML activée. Pour plus d’informations sur SCIM, consultez AUTOTITLE. Pour plus d’informations sur l’autorisation d’un jeton dans une organisation avec authentification unique SAML, consultez AUTOTITLE.
Les points de terminaison ne peuvent pas être utilisés avec un compte d’entreprise ou avec une organisation avec utilisateurs managés.

Authentification

Vous devez vous authentifier en tant que propriétaire d’une organisation GitHub pour utiliser ces points de terminaison. L’API REST s’attend à ce qu’un jeton du porteur OAuth 2.0 (par exemple, un jeton d’accès utilisateur GitHub App) soit inclus dans l’en-tête . Si vous utilisez un personal access token (classic) pour l’authentification, celui-ci doit avoir l'étendue nécessaire, et vous devez également l'autoriser pour une utilisation avec votre organisation SSO SAML.

Correspondance des attributs SAML et SCIM

Pour lier avec succès un compte d’utilisateur GitHub à une identité SCIM dans une organisation, les attributs spécifiques de la réponse SAML de votre fournisseur d’identité et de l’appel d’approvisionnement de l’API SCIM doivent correspondre pour un utilisateur.

Microsoft Entra ID pour SAML

Lors de l’utilisation de l’ID Entra (précédemment appelé Azure AD) pour SAML, l’attribut SAML et l’attribut SCIM suivants doivent correspondre.

Attribut SAML	Attribut SCIM correspondant
`http://schemas.microsoft.com/identity/claims/objectidentifier`	`externalId`

Autres fournisseurs d’identité pour SAML

Lors de l’utilisation d’autres fournisseurs d’identité pour SAML, les déclarations SAML et l’attribut SCIM suivant doivent correspondre.

Attribut SAML	Attribut SCIM correspondant
`NameID`	`userName`

Il existe deux manières différentes pour qu’un compte d’utilisateur GitHub puisse être lié à une identité SCIM dans une organisation lorsque ces attributs SAML/SCIM correspondent :

Pour les utilisateurs qui ne sont pas encore membres de l’organisation :
- Le fournisseur d’identité envoie une requête de provisionnement SCIM à GitHub pour un utilisateur qui n’est pas membre d’une organisation. Cela génère une invitation à rejoindre l’organisation et une identité SCIM non liée dans l’organisation.
- L’utilisateur s’authentifie via SAML dans l’organisation.
- GitHub lie automatiquement l’identité SAML et SCIM au nouveau compte d’utilisateur dans l’organisation.
Pour les membres de l’organisation existants :
- Le fournisseur d’identité envoie une requête de provisionnement SCIM à GitHub pour un utilisateur qui n’est pas déjà membre de l'organisation.
- Si le membre de l’organisation ne dispose pas d’une identité SAML liée dans l’organisation, cela génère une invitation de l’organisation et une identité SCIM non liée dans l’organisation. L’utilisateur s’authentifie via SAML dans l’organisation pour lier son identité SAML et SCIM.
- Si le membre de l’organisation possède une identité SAML liée dans l’organisation, GitHub lie automatiquement l’identité SCIM au compte d’utilisateur existant dans l’organisation. Aucune invitation d'organisation n'a été créée.

S’assurer qu’un utilisateur est correctement lié à son identité SCIM dans l’organisation peut aider à prévenir les problèmes inattendus de déprovisionnement SCIM lorsque l'accès de l'utilisateur à l'application est supprimé côté IdP. Pour plus d'informations sur l’audit des identités SCIM liées dans une organisation, consultez AUTOTITLE

Attributs utilisateur SCIM pris en charge

Nom	Type	Description
`userName`	`string`	Nom d’utilisateur de l’utilisateur.
`name.givenName`	`string`	Prénom de l’utilisateur.
`name.familyName`	`string`	Nom de l’utilisateur.
`emails`	`array`	Liste des e-mails de l’utilisateur.
`externalId`	`string`	Cet identificateur est généré par le fournisseur SAML et est utilisé comme ID unique par le fournisseur SAML pour correspondre à un utilisateur GitHub. Vous pouvez trouver le `externalID` d'un utilisateur soit chez le fournisseur SAML, soit en utilisant le point de terminaison List SCIM provisioned identities et en filtrant sur d'autres attributs connus, tels que le nom d'utilisateur GitHub ou l'adresse e-mail d'un utilisateur.
`id`	`string`	Identificateur généré par le point de terminaison SCIM GitHub.
`active`	`boolean`	Utilisé pour indiquer si l’identité est active (vrai) ou doit être désactivée (faux).

Remarque

Ces points de terminaison respectent la casse. Par exemple, la première lettre du point de terminaison doit être en majuscule :

GET /scim/v2/organizations/{org}/Users/{scim_user_id}

List SCIM provisioned identities

Retrieves a paginated list of all provisioned organization members, including pending invitations. If you provide the filter parameter, the resources for all matching provisions members are returned.

The returned list of SCIM provisioned identities from the GitHub Enterprise Cloud might not always match the organization or enterprise member list. Here is why that can occur:

When an organization invitation is generated by a SCIM integration, this creates an unlinked SCIM identity in the organization. When a user logs into their GitHub user account, visits the organization, and successfully authenticates via SAML, they get added as an organization member and linked to their SAML/SCIM identity in the organization. If the user does not do this, the SCIM identity will remain in the organization, not linked to any organization member.
A user's organization membership (inviting and removing a user to/from the organization) should only be managed by a SCIM integration when this is configured for a GitHub organization. If a GitHub user who has a linked SCIM identity is removed from the organization using the GitHub UI or non-SCIM API, as opposed to the SCIM integration, this can leave behind a stale SAML/SCIM identity in the organization for the user.

Jetons d’accès affinés pour « List SCIM provisioned identities »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir l’ensemble d’autorisations suivant:

"Members" organization permissions (read)

Paramètres pour « List SCIM provisioned identities »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Requis The organization name. The name is not case sensitive.

Paramètres de requête
Nom, Type, Description
`startIndex` integer Used for pagination: the index of the first result to return.
`count` integer Used for pagination: the number of results to return.
`filter` string Filters results using the equals query parameter operator (`eq`). You can filter results that are equal to `id`, `userName`, `emails`, and `externalId`. For example, to search for an identity with the `userName` Octocat, you would use this query: `?filter=userName%20eq%20\"Octocat\"`. To filter results for the identity with the email `octocat@github.com`, you would use this query: `?filter=emails%20eq%20\"octocat@github.com\"`.

Codes d’état de la réponse HTTP pour « List SCIM provisioned identities »

Code d’état	Description
`200`	OK
`304`	Not modified
`400`	Bad request
`403`	Forbidden
`404`	Resource not found
`429`	Too many requests

Exemples de code pour « List SCIM provisioned identities »

Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.

Exemples de requête

Select the example type

get/scim/v2/organizations/{org}/Users

curl -L \
  -H "Accept: application/scim+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/scim/v2/organizations/ORG/Users

Response with filter

Status: 200

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 1,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "5fc0c238-1112-11e8-8e45-920c87bdbd75",
      "externalId": "00u1dhhb1fkIGP7RL1d8",
      "userName": "octocat@github.com",
      "displayName": "Mona Octocat",
      "name": {
        "givenName": "Mona",
        "familyName": "Octocat",
        "formatted": "Mona Octocat"
      },
      "emails": [
        {
          "value": "octocat@github.com",
          "primary": true
        }
      ],
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2018-02-13T15:05:24.000-08:00",
        "lastModified": "2018-02-13T15:05:55.000-08:00",
        "location": "https://api.github.com/scim/v2/organizations/octo-org/Users/5fc0c238-1112-11e8-8e45-920c87bdbd75"
      }
    }
  ]
}

Provision and invite a SCIM user

Provisions organization membership for a user, and sends an activation email to the email address. If the user was previously a member of the organization, the invitation will reinstate any former privileges that the user had. For more information about reinstating former members, see "Reinstating a former member of your organization."

Jetons d’accès affinés pour « Provision and invite a SCIM user »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir l’ensemble d’autorisations suivant:

"Members" organization permissions (write)

Paramètres pour « Provision and invite a SCIM user »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Requis The organization name. The name is not case sensitive.

Nom, Type, Description

userName string Requis

Configured by the admin. Could be an email, login, or username

displayName string

The name of the user, suitable for display to end-users

name object Requis

Properties of name

Nom, Type, Description
`givenName` string Requis
`familyName` string Requis
`formatted` string

emails array of objects Requis

user emails

Properties of emails

Nom, Type, Description
`value` string Requis
`primary` boolean
`type` string

schemas array of strings

externalId string

groups array of strings

active boolean

Codes d’état de la réponse HTTP pour « Provision and invite a SCIM user »

Code d’état	Description
`201`	Created
`304`	Not modified
`400`	Bad request
`403`	Forbidden
`404`	Resource not found
`409`	Conflict
`500`	Internal server error

Exemples de code pour « Provision and invite a SCIM user »

Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.

Exemple de requête

post/scim/v2/organizations/{org}/Users

curl -L \
  -X POST \
  -H "Accept: application/scim+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/scim/v2/organizations/ORG/Users \
  -d '{"userName":"mona.octocat@okta.example.com","externalId":"a7d0f98382","name":{"givenName":"Monalisa","familyName":"Octocat","formatted":"Monalisa Octocat"},"emails":[{"value":"mona.octocat@okta.example.com","primary":true},{"value":"monalisa@octocat.github.com"}]}'

Response

Status: 201

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "edefdfedf-050c-11e7-8d32",
  "externalId": "a7d0f98382",
  "userName": "mona.octocat@okta.example.com",
  "displayName": "Monalisa Octocat",
  "name": {
    "givenName": "Monalisa",
    "familyName": "Octocat",
    "formatted": "Monalisa Octocat"
  },
  "emails": [
    {
      "value": "mona.octocat@okta.example.com",
      "primary": true
    },
    {
      "value": "monalisa@octocat.github.com"
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00",
    "location": "https://api.github.com/scim/v2/organizations/octo-org/Users/edefdfedf-050c-11e7-8d32"
  }
}

Get SCIM provisioning information for a user

Gets SCIM provisioning information for a user.

Jetons d’accès affinés pour « Get SCIM provisioning information for a user »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir l’ensemble d’autorisations suivant:

"Members" organization permissions (read)

Paramètres pour « Get SCIM provisioning information for a user »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Requis The organization name. The name is not case sensitive.
`scim_user_id` string Requis The unique identifier of the SCIM user.

Codes d’état de la réponse HTTP pour « Get SCIM provisioning information for a user »

Code d’état	Description
`200`	OK
`304`	Not modified
`403`	Forbidden
`404`	Resource not found

Exemples de code pour « Get SCIM provisioning information for a user »

Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.

Exemple de requête

get/scim/v2/organizations/{org}/Users/{scim_user_id}

curl -L \
  -H "Accept: application/scim+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID

Response

Status: 200

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "edefdfedf-050c-11e7-8d32",
  "externalId": "a7d0f98382",
  "userName": "mona.octocat@okta.example.com",
  "displayName": "Monalisa Octocat",
  "name": {
    "givenName": "Monalisa",
    "familyName": "Octocat",
    "formatted": "Monalisa Octocat"
  },
  "emails": [
    {
      "value": "mona.octocat@okta.example.com",
      "primary": true
    },
    {
      "value": "monalisa@octocat.github.com"
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00",
    "location": "https://api.github.com/scim/v2/organizations/octo-org/Users/edefdfedf-050c-11e7-8d32"
  }
}

Update a provisioned organization membership

Replaces an existing provisioned user's information. You must provide all the information required for the user as if you were provisioning them for the first time. Any existing user information that you don't provide will be removed. If you want to only update a specific attribute, use the Update an attribute for a SCIM user endpoint instead.

You must at least provide the required values for the user: userName, name, and emails.

Warning

Setting active: false removes the user from the organization, deletes the external identity, and deletes the associated {scim_user_id}.

Jetons d’accès affinés pour « Update a provisioned organization membership »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir l’ensemble d’autorisations suivant:

"Members" organization permissions (write)

Paramètres pour « Update a provisioned organization membership »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Requis The organization name. The name is not case sensitive.
`scim_user_id` string Requis The unique identifier of the SCIM user.

Nom, Type, Description

schemas array of strings

displayName string

The name of the user, suitable for display to end-users

externalId string

groups array of strings

active boolean

userName string Requis

Configured by the admin. Could be an email, login, or username

name object Requis

Properties of name

Nom, Type, Description
`givenName` string Requis
`familyName` string Requis
`formatted` string

emails array of objects Requis

user emails

Properties of emails

Nom, Type, Description
`type` string
`value` string Requis
`primary` boolean

Codes d’état de la réponse HTTP pour « Update a provisioned organization membership »

Code d’état	Description
`200`	OK
`304`	Not modified
`403`	Forbidden
`404`	Resource not found

Exemples de code pour « Update a provisioned organization membership »

Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.

Exemple de requête

put/scim/v2/organizations/{org}/Users/{scim_user_id}

curl -L \
  -X PUT \
  -H "Accept: application/scim+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID \
  -d '{"userName":"mona.octocat@okta.example.com","externalId":"a7d0f98382","name":{"givenName":"Monalisa","familyName":"Octocat","formatted":"Monalisa Octocat"},"emails":[{"value":"mona.octocat@okta.example.com","primary":true}]}'

Response

Status: 200

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "edefdfedf-050c-11e7-8d32",
  "externalId": "a7d0f98382",
  "userName": "mona.octocat@okta.example.com",
  "displayName": "Monalisa Octocat",
  "name": {
    "givenName": "Monalisa",
    "familyName": "Octocat",
    "formatted": "Monalisa Octocat"
  },
  "emails": [
    {
      "value": "mona.octocat@okta.example.com",
      "primary": true
    },
    {
      "value": "monalisa@octocat.github.com"
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00",
    "location": "https://api.github.com/scim/v2/organizations/octo-org/Users/edefdfedf-050c-11e7-8d32"
  }
}

Update an attribute for a SCIM user

Allows you to change a provisioned user's individual attributes. To change a user's values, you must provide a specific Operations JSON format that contains at least one of the add, remove, or replace operations. For examples and more information on the SCIM operations format, see the SCIM specification.

Note

Complicated SCIM path selectors that include filters are not supported. For example, a path selector defined as "path": "emails[type eq \"work\"]" will not work.

Warning

If you set active:false using the replace operation (as shown in the JSON example below), it removes the user from the organization, deletes the external identity, and deletes the associated :scim_user_id.

{
  "Operations":[{
    "op":"replace",
    "value":{
      "active":false
    }
  }]
}

Jetons d’accès affinés pour « Update an attribute for a SCIM user »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir l’ensemble d’autorisations suivant:

"Members" organization permissions (write)

Paramètres pour « Update an attribute for a SCIM user »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Requis The organization name. The name is not case sensitive.
`scim_user_id` string Requis The unique identifier of the SCIM user.

Nom, Type, Description

schemas array of strings

Operations array of objects Requis

Set of operations to be performed

Properties of Operations

Nom, Type, Description
`op` string Requis Peut être: `add`, `remove`, `replace`
`path` string
`value` object or array or string

Codes d’état de la réponse HTTP pour « Update an attribute for a SCIM user »

Code d’état	Description
`200`	OK
`304`	Not modified
`400`	Bad request
`403`	Forbidden
`404`	Resource not found
`429`	Too Many Requests

Exemples de code pour « Update an attribute for a SCIM user »

Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.

Exemple de requête

patch/scim/v2/organizations/{org}/Users/{scim_user_id}

curl -L \
  -X PATCH \
  -H "Accept: application/scim+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID \
  -d '{"Operations":[{"op":"replace","value":{"displayName":"Octocat"}}]}'

Response

Status: 200

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "edefdfedf-050c-11e7-8d32",
  "externalId": "a7d0f98382",
  "userName": "mona.octocat@okta.example.com",
  "displayName": "Monalisa Octocat",
  "name": {
    "givenName": "Monalisa",
    "familyName": "Octocat",
    "formatted": "Monalisa Octocat"
  },
  "emails": [
    {
      "value": "mona.octocat@okta.example.com",
      "primary": true
    },
    {
      "value": "monalisa@octocat.github.com"
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00",
    "location": "https://api.github.com/scim/v2/organizations/octo-org/Users/edefdfedf-050c-11e7-8d32"
  }
}

Delete a SCIM user from an organization

Deletes a SCIM user from an organization.

Jetons d’accès affinés pour « Delete a SCIM user from an organization »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir l’ensemble d’autorisations suivant:

"Members" organization permissions (write)

Paramètres pour « Delete a SCIM user from an organization »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Requis The organization name. The name is not case sensitive.
`scim_user_id` string Requis The unique identifier of the SCIM user.

Codes d’état de la réponse HTTP pour « Delete a SCIM user from an organization »

Code d’état	Description
`204`	No Content
`304`	Not modified
`403`	Forbidden
`404`	Resource not found

Exemples de code pour « Delete a SCIM user from an organization »

Si vous accédez à GitHub à GHE.com, remplacez api.github.com par le sous-domaine dédié de votre entreprise à api.SUBDOMAIN.ghe.com.

Exemple de requête

delete/scim/v2/organizations/{org}/Users/{scim_user_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID

Response

Status: 204