About SAML for GitHub Enterprise Server
SAML SSO allows people to authenticate and access tu instancia de GitHub Enterprise Server through an external system for identity management.
SAML es un estándar basado en XML para autenticación y autorización. When you configure SAML for tu instancia de GitHub Enterprise Server, the external system for authentication is called an identity provider (IdP). Your instance acts as a SAML service provider (SP). For more information, see Security Assertion Markup Language on Wikipedia.
Si quieres autenticar algunos usuarios sin agregarlos a tu proveedor de identidad, puedes configurar la autenticación integrada adicionalmente al SSO de SAML. Para obtener más información, consulta "Permitir autenticación integrada para usuarios fuera de tu proveedor de identidad".
Servicios SAML admitidos
GitHub Enterprise Server es compatible con el SSO de SAML para los IdP que implementen SAML 2.0 estándar. Para obtener más información, consulta la sección Wiki de SAML en el sitio web de OASIS.
GitHub es oficialmente compatible con y prueba internamente los siguientes IdP.
- 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. To restore the user's access, you'll need to update the user account's NameID
mapping. 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 usuario | Nombre de usuario normalizado | Resultado |
---|---|---|
Ms.Bubbles | ms-bubbles | El nombre de usuario se crea correctamente. |
!Ms.Bubbles | -ms-bubbles | No 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!!Bubbles | ms--bubbles | No se crea este nombre de usuario debido a que contiene dos rayas seguidas. |
Ms!Bubbles | ms-bubbles | No se crea este nombre de usuario. A pesar de que el nombre de usuario normalizado es válido, ya existía. |
Ms.Bubbles@example.com | ms-bubbles | No 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
The service provider metadata for tu instancia de GitHub Enterprise Server is available at 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. You can change the attribute names in the management console, with the exception of the administrator
attribute.
Nombre de atributo predeterminado | Tipo | Descripción |
---|---|---|
ID del nombre | Requerido | Un 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. |
administrador | Opcional | Cuando 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 usuario | Opcional | El nombre de usuario GitHub Enterprise Server. |
nombre_completo | Opcional | El nombre del usuario que se muestra en su página de perfil. Los usuarios pueden cambiar sus nombres después del aprovisionamiento. |
emails | Opcional | Las direcciones de correo electrónico para el usuario. Se puede especificar más de una. |
claves_públicas | Opcional | Las claves SSH públicas para el usuario. Se puede especificar más de una. |
gpg_keys | Opcional | Las claves GPG para el usuario. Se puede especificar más de una. |
Para especificar más de un valor para un atributo, utiliza elementos múltiples de <saml2:AttributeValue>
.
<saml2:Attribute FriendlyName="public_keys" Name="urn:oid:1.2.840.113549.1.1.1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml2:AttributeValue>ssh-rsa LONG KEY</saml2:AttributeValue>
<saml2:AttributeValue>ssh-rsa LONG KEY 2</saml2:AttributeValue>
</saml2:Attribute>
Configurar parámetros SAML
-
Desde una cuenta administrativa de GitHub Enterprise Server, en la esquina superior derecha de cualquier página, haz clic en .
-
Si aún no estás en la página de "Administrador de sitio", en la esquina inferior izquierda, haz clic en Administrador de sitio.
-
En la barra lateral izquierda, haz clic en Consola de administración.
-
En la barra lateral izquierda, da clic en Autenticación.
-
Selecciona SAML.
-
Opcionalmente, para permitir que las personas utilicen una autenticación integrada si no tienen una cuenta en tu IdP, selecciona Permitir la autenticación integrada. Para obtener más información, consulta "Permitir autenticación integrada para usuarios fuera de tu proveedor de identidad".
-
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.Note: We recommend keeping this value unselected. You should enable this feature only in the rare instance that your SAML implementation does not support service provider initiated SSO, and when advised by Soporte para GitHub Enterprise.
-
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.
-
Optionally, to allow tu instancia de GitHub Enterprise Server to send and receive encrypted assertions to and from your SAML IdP, select Require encrypted assertions. For more information, see "Enabling encrypted assertions."
Warning: Incorrectly configuring encrypted assertions can cause all authentication to tu instancia de GitHub Enterprise Server to fail.
-
You must ensure that your IdP supports encrypted assertions and that the encryption and key transport methods in the management console match the values configured on your IdP. You must also provide tu instancia de GitHub Enterprise Server's public certificate to your IdP. For more information, see "Enabling encrypted assertions."
-
Before enabling encrypted assertions, GitHub recommends testing encrypted assertions in a staging environment, and confirming that SAML authentication functions as you expect. Para obtener más información, consulta "Configurar una instancia de preparación."
-
-
In the Single sign-on URL field, type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. Este valor lo provee la configuración de tu IdP. If the host is only available from your internal network, you may need to configure tu instancia de GitHub Enterprise Server to use internal nameservers.
-
Optionally, in the Issuer field, type your SAML issuer's name. This verifies the authenticity of messages sent to tu instancia de GitHub Enterprise Server.
-
In the Signature Method and Digest Method drop-down menus, choose the hashing algorithm used by your SAML issuer to verify the integrity of the requests from tu instancia de GitHub Enterprise Server. Specify the format with the Name Identifier Format drop-down menu.
-
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.
-
Modify the SAML attribute names to match your IdP if needed, or accept the default names.
Updating a user's SAML NameID
-
Desde una cuenta administrativa de GitHub Enterprise Server, en la esquina superior derecha de cualquier página, haz clic en .
-
Si aún no estás en la página de "Administrador de sitio", en la esquina inferior izquierda, haz clic en Administrador de sitio.
-
Selecciona SAML.
-
En la lista de usuarios, da clic en el nombre de usuario del cual te gustaría actualizar el mapeo de la
NameID
. -
En la esquina superior derecha de la página, haz clic en Security (Seguridad).
-
To the right of "Update SAML NameID", click Edit .
-
En el campo de "NameID", teclea la
NameID
nueva para el usuario. -
Da clic en Actualizar NameID.
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>
. It must match theEntityId
for GitHub Enterprise Server. Ésta es la URL para la instancia de GitHub Enterprise Server, tal comohttps://ghe.corp.example.com
. - Each assertion in the response must be protected by a digital signature. 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
GitHub Enterprise Server logs error messages for failed SAML authentication in the authentication log at /var/log/github/auth.log. 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 para tu instancia de GitHub Enterprise Server, se presentará uno de los siguientes mensajes de error en el registro de autenticación cuando un usuario intente autenticarse.
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
.