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 userName
para 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
Nome | Tipo | Descrição |
---|---|---|
userName | string | O nome de usuário para o usuário. |
name.givenName | string | Primeiro nome do usuário. |
name.familyName | string | Sobrenome do usuário. |
emails | array | Lista de e-mails dos usuários. |
externalId | string | Este 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. |
id | string | Identificador gerado pelo ponto de extremidade do SCIM do GitHub. |
active | boolean | Usado 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:
-
The user is granted access by the IdP and is not a member of the GitHub Enterprise Cloud organization.
-
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.
-
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:
- Tokens de acesso de usuário do aplicativo GitHub
- Tokens de acesso à instalação do aplicativo GitHub
- Tokens de acesso pessoal refinados
O token refinado deve ter os seguintes conjuntos de permissões:
- "Members" organization permissions (read)
Parâmetros para "List SCIM provisioned identities"
Nome, Tipo, Descrição |
---|
accept string Setting to |
Nome, Tipo, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
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 (
To filter results for the identity with the email
|
Códigos de status de resposta HTTP para "List SCIM provisioned identities"
Código de status | Descriçã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
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:
- Tokens de acesso de usuário do aplicativo GitHub
- Tokens de acesso à instalação do aplicativo GitHub
- Tokens de acesso pessoal 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"
Nome, Tipo, Descrição |
---|
accept string Setting to |
Nome, Tipo, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
Nome, Tipo, Descrição | ||||
---|---|---|---|---|
userName string ObrigatórioConfigured 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 | ||||
Properties of |
Nome, Tipo, Descrição |
---|
givenName string Obrigatório |
familyName string Obrigatório |
formatted string |
emails
array of objects Obrigatóriouser emails
Properties of 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 status | Descriçã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
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:
- Tokens de acesso de usuário do aplicativo GitHub
- Tokens de acesso à instalação do aplicativo GitHub
- Tokens de acesso pessoal 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"
Nome, Tipo, Descrição |
---|
accept string Setting to |
Nome, Tipo, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
scim_user_id string ObrigatórioThe unique identifier of the SCIM user. |
Códigos de status de resposta HTTP para "Get SCIM provisioning information for a user"
Código de status | Descriçã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
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:
- Tokens de acesso de usuário do aplicativo GitHub
- Tokens de acesso à instalação do aplicativo GitHub
- Tokens de acesso pessoal refinados
O token refinado deve ter os seguintes conjuntos de permissões:
- "Members" organization permissions (write)
Parâmetros para "Update a provisioned organization membership"
Nome, Tipo, Descrição |
---|
accept string Setting to |
Nome, Tipo, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
scim_user_id string ObrigatórioThe unique identifier of the SCIM user. |
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órioConfigured by the admin. Could be an email, login, or username | ||||
name object Obrigatório | ||||
Properties of |
Nome, Tipo, Descrição |
---|
givenName string Obrigatório |
familyName string Obrigatório |
formatted string |
emails
array of objects Obrigatóriouser emails
Properties of 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 status | Descriçã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
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:
- Tokens de acesso de usuário do aplicativo GitHub
- Tokens de acesso à instalação do aplicativo GitHub
- Tokens de acesso pessoal 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"
Nome, Tipo, Descrição |
---|
accept string Setting to |
Nome, Tipo, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
scim_user_id string ObrigatórioThe unique identifier of the SCIM user. |
Nome, Tipo, Descrição | ||||
---|---|---|---|---|
schemas array of strings | ||||
Operations array of objects ObrigatórioSet of operations to be performed | ||||
Properties of |
Nome, Tipo, Descrição |
---|
op string ObrigatórioPode ser um dos: |
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 status | Descriçã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
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:
- Tokens de acesso de usuário do aplicativo GitHub
- Tokens de acesso à instalação do aplicativo GitHub
- Tokens de acesso pessoal 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"
Nome, Tipo, Descrição |
---|
accept string Setting to |
Nome, Tipo, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
scim_user_id string ObrigatórioThe unique identifier of the SCIM user. |
Códigos de status de resposta HTTP para "Delete a SCIM user from an organization"
Código de status | Descriçã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
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