SCIM
Você pode controlar e gerenciar o acesso dos integrantes da sua organização do GitHub usando a API de SCIM.
Sobre a API do SCIM
Provisionamento de SCIM para Organizações
A API do SCIM é usada pelos provedores de identidade (IdPs) habilitados pelo SCIM para automatizar o provisionamento de integrantes da organização de GitHub Enterprise Cloud. A GitHub API tem por base a versão 2.0 do Padrão do SCIM. O ponto de extremidade do SCIM do GitHub Enterprise Cloud que um IdP deve usar é: https://api.github.com/scim/v2/organizations/{org}/
.
Notas:
- A API do SCIM está disponível apenas para organizações individuais que usam GitHub Enterprise Cloud com SAML SSO habilitado. Para obter mais informações sobre o SCIM, consulte "Sobre o SCIM para as organizações".
- A API SCIM não pode ser usada com uma conta corporativa ou com um organization with managed users.
Autenticar chamadas para a API de SCIM
Você deve efetuar a autenticação como dono de uma organização do GitHub Enterprise Cloud para usar sua API do SCIM. A API espera que um token OAuth 2.0 seja incluído no cabeçalho da Autorização
. Você também pode usar um token de acesso pessoal, mas primeiro deve autorizá-lo para uso com sua organização SAML SSO.
Mapear dados do SAML e SCIM
O SAML IdP e o cliente SCIM devem usar valores correspondentes ao 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 | O primeiro nome do usuário. |
name.familyName | string | O 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 o externalID para um usuário no provedor do SAML ou usar a listar identidades fornecidas pelo ponto de extremidade do SCIM e filtrar outros atributos conhecidos, como, por exemplo, o nome de usuário no GitHub ou endereço de e-mail de usuário. |
id | string | Identificador gerado pelo ponto de extremidade do SCIM do GitHub. |
ativo | boolean | Usado para indicar se a identidade está ativa (verdadeira) ou se deve ser desprovisionada (falso). |
Observação: As URLs de Endpoint para a API SCIM são sensíveis a maiúsculas e minúsculas. Por exemplo, a primeira letra no endpoint Usuários
deve 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. 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 account after completing SSO:
-
The user is granted access by the IdP and is not a member of the GitHub organization.
-
The user attempts to access the GitHub organization and initiates the SAML SSO process, and is not currently signed in to their GitHub 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 account:- If the user signs in, their GitHub 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 organization, and the external identity
null
entry remains in place.
Parâmetros
Headers |
---|
Nome, Tipo, Descrição |
accept stringSetting to |
Path parameters |
Nome, Tipo, Descrição |
org stringObrigatórioThe organization name. The name is not case sensitive. |
Parâmetros de consulta |
Nome, Tipo, Descrição |
startIndex integerUsed for pagination: the index of the first result to return. |
count integerUsed for pagination: the number of results to return. |
filter stringFilters results using the equals query parameter operator (
To filter results for the identity with the email
|
HTTP response status codes
Status code | Descrição |
---|---|
200 | OK |
304 | Not modified |
400 | Bad Request |
403 | Forbidden |
404 | Resource not found |
429 | Too Many Requests |
Amostras de código
curl \
-H "Accept: application/scim+json" \
-H "Authorization: token <TOKEN>" \
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
Provision organization membership for a user, and send an activation email to the email address.
Parâmetros
Headers | |||||||
---|---|---|---|---|---|---|---|
Nome, Tipo, Descrição | |||||||
accept stringSetting to | |||||||
Path parameters | |||||||
Nome, Tipo, Descrição | |||||||
org stringObrigatórioThe organization name. The name is not case sensitive. | |||||||
Body parameters | |||||||
Nome, Tipo, Descrição | |||||||
userName stringObrigatórioConfigured by the admin. Could be an email, login, or username | |||||||
displayName stringThe name of the user, suitable for display to end-users | |||||||
name objectObrigatório | |||||||
Properties of the |
Nome, Tipo, Descrição |
---|
givenName stringObrigatório |
familyName stringObrigatório |
formatted string |
emails
array of objectsObrigatóriouser emails
Properties of theemails
items
Nome, Tipo, Descrição |
---|
value stringObrigatório |
primary boolean |
type string |
schemas
array of stringsexternalId
stringgroups
array of stringsactive
booleanHTTP response status codes
Status code | Descrição |
---|---|
201 | Created |
304 | Not modified |
400 | Bad Request |
403 | Forbidden |
404 | Resource not found |
409 | Conflict |
500 | Internal Error |
Amostras de código
curl \
-X POST \
-H "Accept: application/scim+json" \
-H "Authorization: token <TOKEN>" \
https://api.github.com/scim/v2/organizations/ORG/Users
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
Parâmetros
Headers |
---|
Nome, Tipo, Descrição |
accept stringSetting to |
Path parameters |
Nome, Tipo, Descrição |
org stringObrigatórioThe organization name. The name is not case sensitive. |
scim_user_id stringObrigatórioThe unique identifier of the SCIM user. |
HTTP response status codes
Status code | Descrição |
---|---|
200 | OK |
304 | Not modified |
403 | Forbidden |
404 | Resource not found |
Amostras de código
curl \
-H "Accept: application/scim+json" \
-H "Authorization: token <TOKEN>" \
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}
.
Parâmetros
Headers | |||||||
---|---|---|---|---|---|---|---|
Nome, Tipo, Descrição | |||||||
accept stringSetting to | |||||||
Path parameters | |||||||
Nome, Tipo, Descrição | |||||||
org stringObrigatórioThe organization name. The name is not case sensitive. | |||||||
scim_user_id stringObrigatórioThe unique identifier of the SCIM user. | |||||||
Body parameters | |||||||
Nome, Tipo, Descrição | |||||||
schemas array of strings | |||||||
displayName stringThe name of the user, suitable for display to end-users | |||||||
externalId string | |||||||
groups array of strings | |||||||
active boolean | |||||||
userName stringObrigatórioConfigured by the admin. Could be an email, login, or username | |||||||
name objectObrigatório | |||||||
Properties of the |
Nome, Tipo, Descrição |
---|
givenName stringObrigatório |
familyName stringObrigatório |
formatted string |
emails
array of objectsObrigatóriouser emails
Properties of theemails
items
Nome, Tipo, Descrição |
---|
type string |
value stringObrigatório |
primary boolean |
HTTP response status codes
Status code | Descrição |
---|---|
200 | OK |
304 | Not modified |
403 | Forbidden |
404 | Resource not found |
Amostras de código
curl \
-X PUT \
-H "Accept: application/scim+json" \
-H "Authorization: token <TOKEN>" \
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 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
}
}]
}
Parâmetros
Headers | |||||||
---|---|---|---|---|---|---|---|
Nome, Tipo, Descrição | |||||||
accept stringSetting to | |||||||
Path parameters | |||||||
Nome, Tipo, Descrição | |||||||
org stringObrigatórioThe organization name. The name is not case sensitive. | |||||||
scim_user_id stringObrigatórioThe unique identifier of the SCIM user. | |||||||
Body parameters | |||||||
Nome, Tipo, Descrição | |||||||
schemas array of strings | |||||||
Operations array of objectsObrigatórioSet of operations to be performed | |||||||
Properties of the |
Nome, Tipo, Descrição |
---|
op stringObrigatórioPode ser uma das ações a seguir: |
path string |
value object or array or string or |
HTTP response status codes
Status code | Descrição |
---|---|
200 | OK |
304 | Not modified |
400 | Bad Request |
403 | Forbidden |
404 | Resource not found |
429 | Too Many Requests |
Amostras de código
curl \
-X PATCH \
-H "Accept: application/scim+json" \
-H "Authorization: token <TOKEN>" \
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"
}
}
Delete a SCIM user from an organization
Parâmetros
Headers |
---|
Nome, Tipo, Descrição |
accept stringSetting to |
Path parameters |
Nome, Tipo, Descrição |
org stringObrigatórioThe organization name. The name is not case sensitive. |
scim_user_id stringObrigatórioThe unique identifier of the SCIM user. |
HTTP response status codes
Status code | Descrição |
---|---|
204 | No Content |
304 | Not modified |
403 | Forbidden |
404 | Resource not found |
Amostras de código
curl \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID
Response
Status: 204