Usar SAML

SAML es un estándar basado en XML para autenticación y autorización. GitHub Enterprise Server puede actuar como un proveedor de servicios (SP) con tu proveedor de identidad (IdP) SAML interno.

Si quieres autenticar usuarios sin agregarlos a tu proveedor de identidad, puedes configurar la autenticación integrada. Para obtener más información, consulta "Permitir autenticación integrada para usuarios fuera de tu proveedor de identidad".

Servicios SAML admitidos

Ofrecemos soporte limitado para todos los proveedores de identidad que implementan SAML 2.0 estándar. Ofrecemos soporte oficial de estos proveedores de identidad que se han probado internamente:

  • Active Directory Federation Services (AD FS)
  • Azure Active Directory (Azure AD)
  • Okta
  • OneLogin
  • PingOne
  • Shibboleth

GitHub Enterprise Server no es compatible con el cierre de sesión único de SAML. Para terminar una sesión de SAML activa, los usuarios deben salir directamente en tu IdP de SAML.

Consideraciones sobre el nombre de usuario con SAML

Cada nombre de usuario GitHub Enterprise Server lo determina una de las siguientes aserciones en la respuesta SAML, ordenadas por prioridad:

  • El atributo de nombre de usuario personalizado, si está definido y si hay uno.
  • Una aserción http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name, si hay una.
  • Una aserción http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress assertion, si hay una.
  • El elemento NameID.

Se requiere el elemento NameID, incluso si hay otros atributos.

Se crea un mapeo entre la NameID y el nombre de usuario de GitHub Enterprise Server, para que la NameID deba ser persistente, única, y no estar sujeta a cambios para el ciclo de vida del usuario.

Nota: Si la NameID de un usuario sí cambia en el IdP, el usuario verá un mensaje de error cuando intente ingresar en tu instancia de GitHub Enterprise Server. Para restablecer el acceso del usuario, necesitarás actualizar el mapeo de la NameID de la cuenta del usuario. Para obtener más información, consulta la sección "Actualizar la NameID de SAML de un usuario.

Los nombres de usuario del GitHub Enterprise Server únicamente pueden contener caracteres alfanuméricos y rayas (-). El GitHub Enterprise Server convertirá en raya cualquier caracter no alfanumérico en el nombre de tu cuenta de usuario. Por ejemplo, un nombre de usuario gregory.st.john se convertirá en gregory-st-john. Nota que los nombres de usuarios normalizados tampoco pueden comenzar o terminar con una raya. Tampoco pueden contener dos rayas seguidas.

Los nombres de usuarios creados a partir de direcciones de correo electrónico se crean con los caracteres normalizados que preceden al caracter @.

Si múltiples cuentas se normalizan en el mismo nombre de usuario de GitHub Enterprise Server, solo se crea la primera cuenta de usuario. Los siguientes usuarios con el mismo nombre de usuario no podrán registrarse.

Esta tabla brinda ejemplos de cómo se normalizan los nombres de usuarios en el GitHub Enterprise Server:

Nombre de usuarioNombre de usuario normalizadoResultado
Ms.Bubblesms-bubblesEl nombre de usuario se crea correctamente.
!Ms.Bubbles-ms-bubblesNo se crea este nombre de usuario debido a que comienza con una raya.
Ms.Bubbles!ms-bubbles-No se crea este nombre de usuario debido a que termina con una raya.
Ms!!Bubblesms--bubblesNo se crea este nombre de usuario debido a que contiene dos rayas seguidas.
Ms!Bubblesms-bubblesNo se crea este nombre de usuario. A pesar de que el nombre de usuario normalizado es válido, ya existía.
Ms.Bubbles@example.comms-bubblesNo se crea este nombre de usuario. A pesar de que el nombre de usuario normalizado es válido, ya existía.

Autenticación de dos factores

Cuando se utiliza SAML o CAS, la autenticación de dos factores no se admite o se administra en el aparato del GitHub Enterprise Server, pero es posible que lo admita un proveedor de autenticación externo. No está disponible la implementación de la autenticación de dos factores en organizaciones. Para obtener más información sobre cómo implementar la autenticación de dos factores, consulta "Requerir autenticación de dos factores en tu organización."

Metadatos SAML

Los metadatos del provedor de servicios de tu instancia de GitHub Enterprise Server se encuentran disponibles en http(s)://[hostname]/saml/metadata.

Para configurar tu proveedor de identidad de forma manual, la URL del Servicio de consumidor de aserciones (ACS) es http(s)://[hostname]/saml/consume. Esta usa el enlace urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Atributos de SAML

Estos atributos están disponibles. Puedes modificar el nombre del atributo en Consola de administración, a excepción del atributo administrator.

Nombre de atributo predeterminadoTypeDescripción
ID del nombreRequeridoUn identificador de usuario persistente. Se puede usar cualquier formato de identificador de nombre persistente. El elemento NameID se usará para un nombre de usuario GitHub Enterprise Server, a menos que se proporcione una de las aserciones alternativas.
administradorOpcionalCuando el valor es "true", el usuario será promovido automáticamente como un administrador. Cualquier otro valor o un valor no existente degradará al usuario a una cuenta de usuario normal.
nombre de usuarioOpcionalEl nombre de usuario GitHub Enterprise Server.
nombre_completoOpcionalEl nombre del usuario que se muestra en su página de perfil. Los usuarios pueden cambiar sus nombres después del aprovisionamiento.
emailsOpcionalLas direcciones de correo electrónico para el usuario. Se puede especificar más de una.
claves_públicasOpcionalLas claves SSH públicas para el usuario. Se puede especificar más de una.
gpg_keysOpcionalLas claves GPG para el usuario. Se puede especificar más de una.

Configurar parámetros SAML

  1. Desde una cuenta administrativa en GitHub Enterprise Server, da clic en la esquina superior derecha de cualquier página. Ícono de cohete para acceder a las configuraciones de administrador del sitio

  2. En la barra lateral izquierda, haz clic en Consola de administración. pestaña Consola de administración en la barra lateral izquierda

  3. En la barra lateral izquierda, da clic en Autenticación. Pestaña de autenticación en la barra lateral de configuración

  4. Selecciona SAML. Autenticación SAML

  5. Opcionalmente, selecciona Permitir autenticación integrada para invitar a los usuarios a utilizar la autenticación integrada si no pertenecen a el proveedor de identidad de tu instancia de GitHub Enterprise Server. Seleccionar la casilla de verificación Autenticación integrada SAML

  6. Opcionalmente, para activar el SSO de respuesta no solicitada, selecciona IdP initiated SSO. Por defecto, GitHub Enterprise Server responderá a una solicitud iniciada por un proveedor de identidad (IdP) no solicitada con una AuthnRequest de vuelta al IdP. SSO del IdP SAML

    Nota: Te recomendamos mantener este valor sin seleccionar. Debes activar esta función solo en el caso inusual que tu implementación SAML no admita el SSO iniciado del proveedor de servicios y que Soporte para GitHub Enterprise lo aconseje.

  7. Selecciona Disable administrator demotion/promotion (Desactivar la degradación/promoción del administrador) si no quieres que tu proveedor de SAML determine los derechos del administrador para los usuarios en tu instancia de GitHub Enterprise Server. Configuración de inhabilitar administrador de SAML

  8. En el campo URL de inicio de sesión único, escribe la HTTP o el extremo HTTPS en tu IdP para las solicitudes de inicio de sesión único. Este valor lo provee la configuración de tu IdP. Si el host solo está disponible desde tu red interna, es posible que sea necesario configurar tu instancia de GitHub Enterprise Server para usar los servidores de nombres internos. Autenticación SAML

  9. También puedes escribir tu nombre de emisor de SAML en el campo Emisor. Esto verifica la autenticidad de los mensajes enviados a tu instancia de GitHub Enterprise Server. Emisor SAML

  10. En los menúes desplegables Método de firma y Método de resumen, elige el algoritmo de hash que usa tu emisor SAML para verificar la integridad de las respuestas desde tu instancia de GitHub Enterprise Server. Especifica el formato con el menú desplegable Formato de identificador de nombre. Método SAML

  11. Dentro de Verification certificate (Certificado de comprobación), haz clic en Choose File (Elegir archivo) y elige un certificado para validar las respuestas SAML desde el IdP. Autenticación SAML

  12. Modifica los nombres de atributo de SAML para hacerlos coincidir con tu IdP, si es necesario, o acepta los nombres predeterminados. Nombres de atributo de SAML

Revocar acceso a tu instancia de servidor de GitHub Enterprise

  1. Desde una cuenta administrativa en GitHub Enterprise Server, da clic en la esquina superior derecha de cualquier página. Ícono de cohete para acceder a las configuraciones de administrador del sitio
  2. Selecciona SAML. Elemento de "Todos los usuarios" en la barra lateral en la configuración de administrador de sitio
  3. En la lista de usuarios, da clic en el nombre de usuario del cual te gustaría actualizar el mapeo de la NameID. Nombre de usuario en la lista de cuentas de usuario de la instancia
  4. En la esquina superior derecha de la página, haz clic en Security (Seguridad). Pestaña de seguridad
  5. Dentro de Verification certificate (Certificado de comprobación), haz clic en Choose File (Elegir archivo) y elige un certificado para validar las respuestas SAML desde el IdP. Botón de "Editar" debajo de "Autenticación de SAML" y a la derecha de "Actualizar la NameID de SAML"
  6. En el campo de "NameID", teclea la NameID nueva para el usuario. Campo de "NameID" en diálogo modal con el valor de NameID ingresado
  7. Da clic en Actualizar NameID. Botón de "Actualizar NameID" debajo del valor actualizado de la NameID dentro del modal

Revocar acceso a tu instancia de GitHub Enterprise Server

Si eliminas un usuario desde tu proveedor de identidad, también debes suspenderlos de forma manual. De lo contrario, seguirán estando disponibles para autenticarse usando los tokens de acceso o las claves SSH. Para obtener más información, consulta "Suspender y anular suspensión de usuarios".

Requisitos para los mensajes de respuesta

El mensaje de respuesta debe cumplir con los siguientes requisitos:

  • Se debe proporcionar el elemento <Destination> en el documento de respuesta raíz y empatar la URL ACS únicamente cuando dicho documento se firme. Si la aserción está firmada, ésta se ignorará.
  • Siempre deberá proporcionarse el elemento <Audience> como parte del elemento <AudienceRestriction>. Siempre deberá proporcionarse el elemento <Audience> como parte del elemento <AudienceRestriction>. Ésta es la URL para la instancia de GitHub Enterprise Server, tal como https://ghe.corp.example.com.
  • Cada aserción en la respuesta debe estar protegida por una firma digital. Esto se puede lograr firmando cada elemento <Assertion> individual o firmando el elemento <Response>.
  • Un elemento <NameID> se debe proporcionar como parte del elemento <Subject>. Se puede usar cualquier formato de identificador de nombre persistente.
  • El atributo Recipient debe estar presente y establecido en la URL ACS. Por ejemplo:
<samlp:Response ...>
  <saml:Assertion ...>
    <saml:Subject>
      <saml:NameID ...>...</saml:NameID>
      <saml:SubjectConfirmation ...>
        <saml:SubjectConfirmationData Recipient="https://ghe.corp.example.com/saml/consume" .../>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:AttributeStatement>
      <saml:Attribute FriendlyName="USERNAME-ATTRIBUTE" ...>
        <saml:AttributeValue>monalisa</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

Autenticación SAML

de entidad del GitHub Enterprise Server, se presentará el siguiente mensaje de error en el registro de autenticación: Para obtener más información sobre los requisitos de respuesta de SAML, consulta la sección "Requisitos de mensaje de respuesta".

Error: "Another user already owns the account"

Cuando un usuario ingresa en GitHub Enterprise Server por primera vez con la autenticación de SAML, GitHub Enterprise Server crea una cuenta de usuario en la instancia y mapea la NameID de SAML hacia la cuenta.

Cuando el usuario vuelve a ingresar, GitHub Enterprise Server compara el mapeo de la NameID de la cuenta con la respuesta del IdP. Si la NameID en la respuesta del IdP ya no empata con la NameID que GitHub Enterprise Server espera para el usuario, el inicio de sesión fallará. El usuario verá el siguiente mensaje.

Another user already owns the account. Please have your administrator check the authentication log.

Este mensaje habitualmente indica que el nombre de usuario o dirección de correo electrónico cambió en el IdP. Asegúrate de que el mapeo de la NameID para la cuenta de usuario en GitHub Enterprise Server empate con la NameID en tu IdP. Para obtener más información, consulta la sección "Actualizar la NameID de SAML de un usuario".

Si la respuesta SAML no está firmada o la firma no coincide con los contenidos, se presentará el siguiente mensaje de error en el registro de autenticación:

Si el Recipient no coincide con la URL ACS, se presentará el siguiente mensaje de error en el registro de autenticación:

El destinatario en la respuesta SAML no debe estar en blanco.
El destinatario en la respuesta SAML no era válido.

Asegúrate de que configuraste el valor para Recipient en tu IdP como la URL de ACS completa para tu instancia de GitHub Enterprise Server. Por ejemplo, https://ghe.corp.example.com/saml/consume.

Error: "SAML Response is not signed or has been modified"

Si tu IdP no firma la respuesta de SAML, o si la firma no empata con el contenido, se mostrará el siguiente mensaje de error en la bitácora de autenticación.

SAML Response is not signed or has been modified.

Asegúrate de haber configurado aserciones firmadas para la aplicación de GitHub Enterprise Server en tu IdP.

Error: "Audience is invalid" or "No assertion found"

Si la respuesta del IdP carece o tiene un valor incorrecto para Audience, se mostrará el siguiente mensaje de error en la bitácora de autenticación.

La audiencia es no válida. Audience attribute does not match https://YOUR-INSTANCE-URL

Asegúrate de haber configurado el valor para Audience en tu IdP como la EntityId para tu instancia de GitHub Enterprise Server, la cual es la URL completa para tu instancia de GitHub Enterprise Server. Por ejemplo, https://ghe.corp.example.com.

¿Te ayudó este documento?

Política de privacidad

¡Ayúdanos a hacer geniales estos documentos!

Todos los documentos de GitHub son de código abierto. ¿Notas algo que esté mal o que no sea claro? Emite una solicitud de cambios.

Haz una contribución

O, aprende cómo contribuir.