Pontos de extremidade da API REST para SCIM

Observação

Essa operação permite provisionar o acesso a uma organização na GitHub Enterprise Cloud usando o 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 com o objetivo de automatizar o provisionamento da associação à organização do GitHub e são baseados na versão 2.0 do padrão SCIM. Os IdPs devem usar a URL base https://api.github.com/scim/v2/organizations/{org}/ para os pontos de extremidade SCIM do GitHub.

Observação

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, confira 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 realizar a autenticação como proprietário de uma organização do GitHub 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.

Correspondência de atributos de SAML e SCIM

Para vincular com êxito uma conta de usuário do GitHub a uma identidade do SCIM em uma organização, atributos específicos da resposta SAML do provedor de identidade e da chamada de provisionamento da API do SCIM devem corresponder a um usuário.

Microsoft Entra ID para SAML

Ao usar o Entra ID (o antigo Azure AD) para SAML, os seguintes atributos do SAML e o atributo do SCIM devem corresponder.

Atributo do SAML	Atributo correspondente do SCIM
`http://schemas.microsoft.com/identity/claims/objectidentifier`	`externalId`

Outros IdPs para SAML

Ao usar outros IdPs para SAML, as seguintes declarações do SAML e o atributo do SCIM devem corresponder.

Atributo do SAML	Atributo correspondente do SCIM
`NameID`	`userName`

Há duas maneiras diferentes de uma conta de usuário do GitHub ser vinculada a uma identidade do SCIM em uma organização quando esses atributos de SAML/SCIM correspondem:

Para usuários que ainda não são membros da organização:
- O IdP envia uma chamada de provisionamento do SCIM para o GitHub para um usuário que não é membro de uma organização. Isso gera um convite da organização e uma identidade de SCIM desvinculada na organização.
- O usuário é autenticado via SAML na organização.
- O GitHub vincula automaticamente a identidade do SAML e SCIM à nova conta de usuário na organização.
Para membros da organização existentes:
- O IdP envia uma chamada de provisionamento do SCIM para o GitHub para um usuário que já é membro da organização.
- Se o membro da organização não tiver uma identidade do SAML vinculada na organização, será gerado um convite da organização e uma identidade do SCIM desvinculada na organização. O usuário se autentica via SAML na organização para vincular sua identidade do SAML e do SCIM.
- Se o membro da organização tiver uma identidade do SAML vinculada na organização, o GitHub vinculará automaticamente a identidade do SCIM à conta de usuário existente na organização. Nenhum convite da organização é criado.

Garantir que um usuário seja vinculado corretamente à sua identidade do SCIM na organização pode ajudar a evitar problemas inesperados com o desprovisionamento do SCIM quando o acesso do usuário ao aplicativo é removido no IdP. Para obter mais informações sobre como auditar as identidades do SCIM vinculadas em uma organização, consulte Solução de problemas de gerenciamento de identidade e acesso da organização

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

Observação

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.

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.

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

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em api.SUBDOMAIN.ghe.com.

Exemplos de solicitação

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

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.

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

Properties of name

Nome, Tipo, Descrição
`givenName` string Obrigatório
`familyName` string Obrigatório
`formatted` string

emails array of objects Obrigatório

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

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em 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":"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.

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

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em 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.

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

Properties of name

Nome, Tipo, Descrição
`givenName` string Obrigatório
`familyName` string Obrigatório
`formatted` string

emails array of objects Obrigatório

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

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em 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":"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
    }
  }]
}

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.

Nome, Tipo, Descrição

schemas array of strings

Operations array of objects Obrigatório

Set of operations to be performed

Properties of Operations

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

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em 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 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"

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em 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