Puntos de conexión de API de REST para SCIM

Note

Esta operación permite aprovisionar el acceso a una organización en GitHub Enterprise Cloud mediante SCIM. La operación no está disponible para su uso con Enterprise Managed Users. Para más información sobre el aprovisionamiento de cuentas de usuario administradas, mediante SCIM, consulta Puntos de conexión de API de REST para SCIM.

Acerca de SCIM

Aprovisionamiento de SCIM para las Organizaciones

Estos puntos de conexión los usan los proveedores de identidades (IDP) habilitados para SCIM a fin de automatizar el aprovisionamiento de la pertenencia de la organización de GitHub y se basan en la versión 2.0 del estándar SCIM. Los IDP deben usar la dirección URL https://api.github.com/scim/v2/organizations/{org}/ base para los puntos de conexión SCIM de GitHub.

Note

Estos puntos de conexión solo están disponibles para organizaciones individuales que usen GitHub Enterprise Cloud con el inicio de sesión único de SAML habilitado. Para más información sobre SCIM, consulta Acerca de SCIM para las organizaciones. Para obtener más información sobre cómo autorizar un token para una organización de SSO de SAML, consulta Autenticación en la API REST.
Estos puntos de conexión no se puede usar con una cuenta de empresa con una organización con usuarios administrados.

Autenticación

Debes autenticarte como un propietario de una organización de GitHub para poder usar estos puntos de conexión. La API de REST espera que se incluya un token de portador de OAuth 2.0 (por ejemplo, un token de acceso de usuario de GitHub App) en el encabezado Authorization. Si usa un personal access token (classic) para la autenticación, debe tener el ámbito admin:org y también debes autorizarlo para su uso con la organización de SSO de SAML.

Coincidencia de atributos de SAML y SCIM

Para vincular correctamente una cuenta de usuario de GitHub a una identidad SCIM de una organización, los atributos específicos de la respuesta SAML del proveedor de identidades y la llamada de aprovisionamiento de la API de SCIM deben coincidir para un usuario.

Microsoft Entra ID para SAML

Al usar Entra ID (anteriormente conocido como Azure AD) para SAML, deben coincidir los siguientes atributos de SAML y de SCIM.

Atributo de SAML	Atributo SCIM coincidente
`http://schemas.microsoft.com/identity/claims/objectidentifier`	`externalId`

Otros idP para SAML

Al usar otros idP para SAML, deben coincidir las siguientes notificaciones de SAML y el atributo SCIM.

Atributo de SAML	Atributo SCIM coincidente
`NameID`	`userName`

Hay dos formas diferentes de vincular una cuenta de usuario de GitHub a una identidad SCIM de una organización cuando coinciden estos atributos de SAML o SCIM:

Para los usuarios que aún no son miembros de la organización:
- El IdP envía una llamada de aprovisionamiento SCIM a GitHub para un usuario que no es miembro de una organización. Esto genera una invitación de la organización y una identidad de SCIM desvinculada en la organización.
- El usuario se autentica mediante SAML en la organización.
- GitHub vincula automáticamente la identidad de SAML y SCIM a la nueva cuenta de usuario en la organización.
Para los miembros de la organización existentes:
- El IdP envía una llamada de aprovisionamiento de SCIM a GitHub para un usuario que ya es miembro de la organización.
- Si el miembro de la organización no tiene una identidad de SAML vinculada en la organización, se genera una invitación a la organización y una identidad de SCIM desvinculada en la organización. El usuario se autentica mediante SAML en la organización para vincular su identidad de SAML y SCIM.
- Si el miembro de la organización tiene una identidad de SAML vinculada en la organización, GitHub vincula automáticamente la identidad de SCIM a la cuenta de usuario existente en la organización. No se crea ninguna invitación de la organización.

Asegurarse de que un usuario se vincula correctamente a su identidad de SCIM en la organización puede ayudar a evitar problemas inesperados con el desaprovisionamiento de SCIM cuando se quita el acceso del usuario a la aplicación en el lado del IdP. Para más información sobre la auditoría de las identidades SCIM vinculadas de una organización, consulta Solución de problemas de administración de acceso e identidad para la organización

Atributos de Usuario de SCIM compatibles

Nombre	Escribir	Descripción
`userName`	`string`	El nombre de usuario para el usuario.
`name.givenName`	`string`	El nombre del usuario.
`name.familyName`	`string`	Los apellidos del usuario.
`emails`	`array`	Lista de correos electrónicos del usuario.
`externalId`	`string`	El proveedor de SAML genera este identificador, el cual utiliza como una ID única para empatarla contra un usuario de GitHub. Puede encontrar el valor `externalID` de un usuario mediante el proveedor de SAML o bien con el punto de conexión Enumerar las identidades aprovisionadas de SCIM y filtrar por otros atributos conocidos, como el nombre de usuario o la dirección de correo electrónico de GitHub de un usuario.
`id`	`string`	Identificador que genera la terminal de SCIM de GitHub.
`active`	`boolean`	Se utiliza para indicar si la identidad está activa (true) o si debe desaprovisionarse (false).

Note

Estos puntos de conexión distinguen mayúsculas de minúsculas. Por ejemplo, la primera letra del punto de conexión Users debe ser mayú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 acceso específicos para "List SCIM provisioned identities"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Members" organization permissions (read)

Parámetros para "List SCIM provisioned identities"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.

Parámetros de consulta
Nombre, Tipo, Descripción
`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 estado de respuesta HTTP para "List SCIM provisioned identities"

status code	Descripción
`200`	OK
`304`	Not modified
`400`	Bad request
`403`	Forbidden
`404`	Resource not found
`429`	Too many requests

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

Si accedes a GitHub en GHE.com, reemplaza api.github.com por el subdominio dedicado de la empresa en api.SUBDOMAIN.ghe.com.

Ejemplos de solicitud

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 acceso específicos para "Provision and invite a SCIM user"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Members" organization permissions (write)

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

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.

Nombre, Tipo, Descripción

userName string Requerido

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 Requerido

Properties of name

Nombre, Tipo, Descripción
`givenName` string Requerido
`familyName` string Requerido
`formatted` string

emails array of objects Requerido

user emails

Properties of emails

Nombre, Tipo, Descripción
`value` string Requerido
`primary` boolean
`type` string

schemas array of strings

externalId string

groups array of strings

active boolean

Códigos de estado de respuesta HTTP para "Provision and invite a SCIM user"

status code	Descripción
`201`	Created
`304`	Not modified
`400`	Bad request
`403`	Forbidden
`404`	Resource not found
`409`	Conflict
`500`	Internal server error

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

Si accedes a GitHub en GHE.com, reemplaza api.github.com por el subdominio dedicado de la empresa en api.SUBDOMAIN.ghe.com.

Ejemplo de solicitud

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 acceso específicos para "Get SCIM provisioning information for a user"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Members" organization permissions (read)

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

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.
`scim_user_id` string Requerido The unique identifier of the SCIM user.

Códigos de estado de respuesta HTTP para "Get SCIM provisioning information for a user"

status code	Descripción
`200`	OK
`304`	Not modified
`403`	Forbidden
`404`	Resource not found

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

Si accedes a GitHub en GHE.com, reemplaza api.github.com por el subdominio dedicado de la empresa en api.SUBDOMAIN.ghe.com.

Ejemplo de solicitud

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 acceso específicos para "Update a provisioned organization membership"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Members" organization permissions (write)

Parámetros para "Update a provisioned organization membership"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.
`scim_user_id` string Requerido The unique identifier of the SCIM user.

Nombre, Tipo, Descripción

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 Requerido

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

name object Requerido

Properties of name

Nombre, Tipo, Descripción
`givenName` string Requerido
`familyName` string Requerido
`formatted` string

emails array of objects Requerido

user emails

Properties of emails

Nombre, Tipo, Descripción
`type` string
`value` string Requerido
`primary` boolean

Códigos de estado de respuesta HTTP para "Update a provisioned organization membership"

status code	Descripción
`200`	OK
`304`	Not modified
`403`	Forbidden
`404`	Resource not found

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

Si accedes a GitHub en GHE.com, reemplaza api.github.com por el subdominio dedicado de la empresa en api.SUBDOMAIN.ghe.com.

Ejemplo de solicitud

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 acceso específicos para "Update an attribute for a SCIM user"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Members" organization permissions (write)

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

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.
`scim_user_id` string Requerido The unique identifier of the SCIM user.

Nombre, Tipo, Descripción

schemas array of strings

Operations array of objects Requerido

Set of operations to be performed

Properties of Operations

Nombre, Tipo, Descripción
`op` string Requerido Puede ser uno de los siguientes: `add`, `remove`, `replace`
`path` string
`value` object or array or string

Códigos de estado de respuesta HTTP para "Update an attribute for a SCIM user"

status code	Descripción
`200`	OK
`304`	Not modified
`400`	Bad request
`403`	Forbidden
`404`	Resource not found
`429`	Too Many Requests

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

Si accedes a GitHub en GHE.com, reemplaza api.github.com por el subdominio dedicado de la empresa en api.SUBDOMAIN.ghe.com.

Ejemplo de solicitud

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 acceso específicos para "Delete a SCIM user from an organization"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Members" organization permissions (write)

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

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`org` string Requerido The organization name. The name is not case sensitive.
`scim_user_id` string Requerido The unique identifier of the SCIM user.

Códigos de estado de respuesta HTTP para "Delete a SCIM user from an organization"

status code	Descripción
`204`	No Content
`304`	Not modified
`403`	Forbidden
`404`	Resource not found

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

Si accedes a GitHub en GHE.com, reemplaza api.github.com por el subdominio dedicado de la empresa en api.SUBDOMAIN.ghe.com.

Ejemplo de solicitud

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