Skip to main content
O controle de versão da API REST já foi feito. Para obter mais informações, confira "Sobre o controle de versão da API".

Pontos de extremidade da API REST para SCIM

Use a API REST para controlar e gerenciar o acesso dos membros da organização do GitHub com o SCIM.

Nota: essa operação permite provisionar o acesso a uma organização em GitHub Enterprise Cloud usando SCIM. A operação não está disponível para uso com Enterprise Managed Users. Para saber mais sobre o provisionamento de contas de usuário gerenciadas usando SCIM, confira "Pontos de extremidade da API REST para SCIM."

Sobre o SCIM

Provisionamento de SCIM para Organizações

Esses pontos de extremidade são usados por IdPs (Provedores de Identidade) habilitados para SCIM a fim de automatizar o provisionamento da associação à organização do GitHub Enterprise Cloud e se baseiam na versão 2.0 do SCIM padrão. Os IdPs devem usar a URL base https://api.github.com/scim/v2/organizations/{org}/ para pontos de extremidade SCIM do GitHub Enterprise Cloud.

Observações:

  • Esses pontos de extremidade só estão disponíveis para organizações individuais que usam GitHub Enterprise Cloud com o SSO do SAML habilitado. Para obter mais informações sobre o SCIM, confira "Sobre o SCIM para organizações". Para obter mais informações sobre como autorizar um token para uma organização de SSO do SAML, consulte "Autenticação na API REST".
  • Esses pontos de extremidade não podem ser usados com uma conta corporativa ou com um organização com usuários gerenciados.

Autenticação

Você deve efetuar a autenticação como proprietário de uma organização do GitHub Enterprise Cloud para usar esses pontos de extremidade. A API REST espera que um token de portador OAuth 2.0 (por exemplo, um token de acesso do usuário do GitHub App seja incluído no cabeçalho Authorization. Se você usar um personal access token (classic) para autenticação, ele deverá ter o escopo admin:org e você também deverá autorizá-lo para uso com sua organização de SSO do SAML.

Mapear dados do SAML e SCIM

O IdP do SAML e o cliente SCIM devem usar valores correspondentes NameID e userNamepara cada usuário. Isso permite que um usuário que faz autenticação através do SAML seja vinculado à sua identidade SCIM provisionada.

Atributos de usuário de SCIM compatíveis

NomeTipoDescrição
userNamestringO nome de usuário para o usuário.
name.givenNamestringPrimeiro nome do usuário.
name.familyNamestringSobrenome do usuário.
emailsarrayLista de e-mails dos usuários.
externalIdstringEste identificador é gerado pelo provedor do SAML e é usado como um ID exclusivo pelo provedor do SAML para corresponder ao usuário do GitHub. Você pode encontrar a externalID de um usuário no provedor SAML ou usando o ponto de extremidade Listar identidades provisionadas do SCIM e a filtragem de outros atributos conhecidos, como o nome de usuário do GitHub ou o endereço de email de um usuário.
idstringIdentificador gerado pelo ponto de extremidade do SCIM do GitHub.
activebooleanUsado para indicar se a identidade está ativa (verdadeira) ou se deve ser desprovisionada (falso).

Nota: Esses pontos de extremidade diferenciam maiúsculas de minúsculas. Por exemplo, a primeira letra no ponto de extremidade Users precisa ser maiúscula:

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.

When a user with a SAML-provisioned external identity leaves (or is removed from) an organization, the account's metadata is immediately removed. However, the returned list of user accounts might not always match the organization or enterprise member list you see on GitHub Enterprise Cloud. This can happen in certain cases where an external identity associated with an organization will not match an organization member:

  • When a user with a SCIM-provisioned external identity is removed from an organization, the account's metadata is preserved to allow the user to re-join the organization in the future.
  • When inviting a user to join an organization, you can expect to see their external identity in the results before they accept the invitation, or if the invitation is cancelled (or never accepted).
  • When a user is invited over SCIM, an external identity is created that matches with the invitee's email address. However, this identity is only linked to a user account when the user accepts the invitation by going through SAML SSO.

The returned list of external identities can include an entry for a null user. These are unlinked SAML identities that are created when a user goes through the following Single Sign-On (SSO) process but does not sign in to their GitHub Enterprise Cloud account after completing SSO:

  1. The user is granted access by the IdP and is not a member of the GitHub Enterprise Cloud organization.

  2. The user attempts to access the GitHub Enterprise Cloud organization and initiates the SAML SSO process, and is not currently signed in to their GitHub Enterprise Cloud account.

  3. After successfully authenticating with the SAML SSO IdP, the null external identity entry is created and the user is prompted to sign in to their GitHub Enterprise Cloud account:

    • If the user signs in, their GitHub Enterprise Cloud account is linked to this entry.
    • If the user does not sign in (or does not create a new account when prompted), they are not added to the GitHub Enterprise Cloud organization, and the external identity null entry remains in place.

Tokens de acesso refinados para "List SCIM provisioned identities"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Members" organization permissions (read)

Parâmetros para "List SCIM provisioned identities"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
org string Obrigatório

The organization name. The name is not case sensitive.

Parâmetros de consulta
Nome, Tipo, Descrição
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\".

Códigos de status de resposta HTTP para "List SCIM provisioned identities"

Código de statusDescrição
200

OK

304

Not modified

400

Bad request

403

Forbidden

404

Resource not found

429

Too many requests

Exemplos de código para "List SCIM provisioned identities"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Exemplos de solicitação

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."

Tokens de acesso refinados para "Provision and invite a SCIM user"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Members" organization permissions (write)

Parâmetros para "Provision and invite a SCIM user"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
org string Obrigatório

The organization name. The name is not case sensitive.

Parâmetros do corpo
Nome, Tipo, Descrição
userName string Obrigatório

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 Obrigatório
Nome, Tipo, Descrição
givenName string Obrigatório
familyName string Obrigatório
formatted string
emails array of objects Obrigatório

user emails

Nome, Tipo, Descrição
value string Obrigatório
primary boolean
type string
schemas array of strings
externalId string
groups array of strings
active boolean

Códigos de status de resposta HTTP para "Provision and invite a SCIM user"

Código de statusDescrição
201

Created

304

Not modified

400

Bad request

403

Forbidden

404

Resource not found

409

Conflict

500

Internal server error

Exemplos de código para "Provision and invite a SCIM user"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Exemplo de solicitação

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":"octocat","name":"Monalisa Octocat","emails":[{"value":"mona.octocat@github.com","primary":true}]}'

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.

Tokens de acesso refinados para "Get SCIM provisioning information for a user"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Members" organization permissions (read)

Parâmetros para "Get SCIM provisioning information for a user"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
org string Obrigatório

The organization name. The name is not case sensitive.

scim_user_id string Obrigatório

The unique identifier of the SCIM user.

Códigos de status de resposta HTTP para "Get SCIM provisioning information for a user"

Código de statusDescrição
200

OK

304

Not modified

403

Forbidden

404

Resource not found

Exemplos de código para "Get SCIM provisioning information for a user"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Exemplo de solicitação

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}.

Tokens de acesso refinados para "Update a provisioned organization membership"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Members" organization permissions (write)

Parâmetros para "Update a provisioned organization membership"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
org string Obrigatório

The organization name. The name is not case sensitive.

scim_user_id string Obrigatório

The unique identifier of the SCIM user.

Parâmetros do corpo
Nome, Tipo, Descrição
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 Obrigatório

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

name object Obrigatório
Nome, Tipo, Descrição
givenName string Obrigatório
familyName string Obrigatório
formatted string
emails array of objects Obrigatório

user emails

Nome, Tipo, Descrição
type string
value string Obrigatório
primary boolean

Códigos de status de resposta HTTP para "Update a provisioned organization membership"

Código de statusDescrição
200

OK

304

Not modified

403

Forbidden

404

Resource not found

Exemplos de código para "Update a provisioned organization membership"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Exemplo de solicitação

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":"octocat","name":"Monalisa Octocat","emails":[{"value":"mona.octocat@github.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
    }
  }]
}

Tokens de acesso refinados para "Update an attribute for a SCIM user"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Members" organization permissions (write)

Parâmetros para "Update an attribute for a SCIM user"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
org string Obrigatório

The organization name. The name is not case sensitive.

scim_user_id string Obrigatório

The unique identifier of the SCIM user.

Parâmetros do corpo
Nome, Tipo, Descrição
schemas array of strings
Operations array of objects Obrigatório

Set of operations to be performed

Nome, Tipo, Descrição
op string Obrigatório

Pode ser um dos: add, remove, replace

path string
value object or array or string

Códigos de status de resposta HTTP para "Update an attribute for a SCIM user"

Código de statusDescrição
200

OK

304

Not modified

400

Bad request

403

Forbidden

404

Resource not found

429

Too Many Requests

Exemplos de código para "Update an attribute for a SCIM user"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Exemplo de solicitação

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.

Tokens de acesso refinados para "Delete a SCIM user from an organization"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Members" organization permissions (write)

Parâmetros para "Delete a SCIM user from an organization"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
org string Obrigatório

The organization name. The name is not case sensitive.

scim_user_id string Obrigatório

The unique identifier of the SCIM user.

Códigos de status de resposta HTTP para "Delete a SCIM user from an organization"

Código de statusDescrição
204

No Content

304

Not modified

403

Forbidden

404

Resource not found

Exemplos de código para "Delete a SCIM user from an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Exemplo de solicitação

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