Referencia de configuración de SAML

Acerca de la configuración de SAML

A fin de usar el inicio de sesión único (SSO) de SAML para la autenticación en GitHub, debes configurar tanto el proveedor de identidades (IdP) de SAML externo como tu instancia de GitHub Enterprise Server. En una configuración de SAML, GitHub funciona como un proveedor de servicios (SP) de SAML. Para obtener más información sobre la autenticación para su empresa, consulta Aspectos básicos de la administración de identidades y acceso.

GitHub proporciona integración según la especificación SAML 2.0. Para más información, vea la wiki de SAML en el sitio web de OASIS.

Debe especificar valores únicos para el IdP de SAML al configurar el inicio de sesión único de SAML para GitHub, y también valores únicos de GitHub en el IdP.

Metadatos SAML

Los metadatos del proveedor de servicios para tu instancia de GitHub Enterprise Server están disponibles en http(s)://HOSTNAME/saml/metadata, donde HOSTNAME es el nombre de host de la instancia. GitHub Enterprise Server utiliza la vinculación urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Valor	Otros nombres	Descripción	Ejemplo
ID de Entidad SP	URL de SP, restricción de público	URL de nivel superior para tu instancia de GitHub Enterprise Server	http(s)://HOSTNAME
URL del Servicio de Consumidor de Aserciones (ACS) del SP	Respuesta, destinatario o URL de destino	URL a la que el IdP enviará las respuestas de SAML	http(s)://HOSTNAME/saml/consume
URL de inicio de sesión único (SSO) del SP
URL en donde el IdP comienza con SSO	http(s)://HOSTNAME/sso

Atributos de SAML

Los atributos de SAML siguientes están disponibles para GitHub. También puedes cambiar los nombres de los atributos en la Consola de administración, con la excepción del atributo administrator. Para más información, consulta Administrar la instancia desde la interfaz del usuario web.

Nombre	Obligatorio	Descripción
NameID		Un identificador de usuario persistente. Se puede usar cualquier formato de identificador de nombre persistente. GitHub normalizará el elemento NameID para utilizarlo como nombre de usuario a menos que se proporcione una de las aserciones alternativas. Para más información, consulta Consideraciones sobre el nombre de usuario para la autenticación externa.

          > 
          [!NOTE] Es importante usar un identificador persistente y legible. El uso de un formato de identificador transitorio, como `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`, volverá a vincular las cuentas en cada inicio de sesión, lo que puede ser perjudicial para la administración de la autorización.  |

| SessionNotOnOrAfter | | La fecha en que GitHub invalida la sesión asociada. Después de la invalidación, la persona debe autenticarse nuevamente para acceder a tu instancia de GitHub Enterprise Server. Para más información, consulta Duración y tiempo de espera de la sesión. | | | | administrator | | Cuando el valor sea true, GitHub promoverá automáticamente al usuario para que sea administrador del sitio. Establecer este atributo en cualquier valor, excepto true, generará una disminución de nivel, siempre que el valor no esté en blanco. Omitir este atributo o dejar el valor en blanco no cambiará el rol del usuario. | | username | | El nombre de usuario para tu instancia de GitHub Enterprise Server. | | | | full_name | | El nombre completo del usuario que se va a mostrar en la página de perfil del usuario. | | emails | | Las direcciones de correo electrónico del usuario. Puedes especificar más de una dirección. Si sincronizas el uso de licencias entre GitHub Enterprise Server y GitHub Enterprise Cloud, GitHub Connect utiliza emails para identificar usuarios únicos entre productos. Para más información, consulta Sincronización del uso de licencias de GitHub Enterprise Server a la nube. | | public_keys | | Las claves SSH públicas para el usuario. Puedes especificar más de una clave. | | gpg_keys | | Las claves GPG para el usuario. Puedes especificar más de una clave. |

A fin de especificar más de un valor para un atributo, use varios elementos <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>

Requisitos de respuesta de SAML

GitHub requiere que el mensaje de respuesta del IdP cumpla con los requisitos siguientes.

• El IdP debe proporcionar el elemento <Destination> en el documento de respuesta raíz y hacer coincidir la URL de ACS únicamente cuando dicho documento esté firmado. Si el IdP firma la aserción, GitHub la omitirá.

• El IdP siempre debe proporcionar el elemento <Audience> como parte del elemento <AudienceRestriction>. El valor debe coincidir con EntityId para GitHub. Este valor es la dirección URL en la que accedes a GitHub, como http(s)://HOSTNAME.

• El IdP debe proporcionar una aserción única en la respuesta con una firma digital. Esto puedes lograrlo si se firma el elemento <Assertion> o si se firma el elemento <Response>.

• El IdP debe proporcionar un elemento <NameID> como parte del elemento <Subject>. Puedes utilizar cualquier formato de identificador de nombre persistente.

• El IdP debe incluir el atributo Recipient, que se debe establecer en la URL de ACS. En el ejemplo siguiente, se muestra el atributo.

  <samlp:Response ...>
    <saml:Assertion ...>
      <saml:Subject>
        <saml:NameID ...>...</saml:NameID>
        <saml:SubjectConfirmation ...>
          <saml:SubjectConfirmationData Recipient="https://HOSTNAME/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>
  

Certificado de firma de SAML para AuthnRequests

Al configurar por primera vez GitHub Enterprise Server e iniciar la instancia, se genera un certificado de firma SAML autofirmado, independiente del certificado SAML del IdP. Este certificado se usa para firmar SAML AuthnRequests enviado al IdP y es válido durante diez años. Se almacena en /data/user/common/saml-sp.p12 y puedes ver los detalles en formato codificado en base64 en http(s)://HOSTNAME/saml/metadata.

Si el IdP valida el certificado de firma de SAML o si las aserciones cifradas de SAML están habilitadas, los usuarios pueden tener problemas de autenticación cuando expire el certificado. Para comprobar la fecha de expiración, un administrador de GitHub Enterprise Server puede conectarse al servidor a través de SSH y ejecutar el comando siguiente. Consulta Conexión al shell administrativo a través de SSH.

sudo openssl pkcs12 -in /data/user/common/saml-sp.p12 -clcerts -nokeys -password pass: | sudo openssl x509 -noout -enddate

Para volver a generar este certificado de firma de SAML SP si ha expirado y es necesario para el IdP o las aserciones cifradas, un administrador de GitHub Enterprise Server puede ejecutar los comandos siguientes en una sesión SSH de GitHub Enterprise Server.

# Backup the old certificate
sudo cp /data/user/common/saml-sp.p12 /data/user/common/saml-sp.p12-$(date +%d%m%Y_%H%M%S)

saml_tempdir=$(sudo mktemp -d)
sudo openssl req -new -newkey rsa:4096 -days 3650 -nodes -x509 -sha256 -subj "/CN=github_enterprise" -keyout $saml_tempdir/saml.key -out $saml_tempdir/saml.crt
sudo openssl pkcs12 -export -inkey $saml_tempdir/saml.key -in $saml_tempdir/saml.crt -nodes -password pass: -out /data/user/common/saml-sp.p12
sudo rm -rf $saml_tempdir

sudo nomad stop github-unicorn
sudo nomad run -hcl1 /etc/nomad-jobs/github/unicorn.hcl

Duración y tiempo de espera de la sesión

Para evitar que una persona se autentique con el IdP y permanezca autorizada indefinidamente, GitHub invalida periódicamente la sesión de cada cuenta de usuario con acceso a tu instancia de GitHub Enterprise Server. Después de la invalidación, la persona se debe volver a autenticar con el IdP.

De manera predeterminada, si el IdP no declara un valor para el atributo SessionNotOnOrAfter, GitHub invalida una sesión una semana después de una autenticación correcta con el IdP.

GitHub admitirá una duración de sesión personalizada si su IdP ofrece la opción de configurar un atributo SessionNotOnOrAfter y un valor, y si este atributo se incluye en las respuestas de SAML. Si su IdP no permite un atributo SessionNotOnOrAfter, un administrador del sitio puede configurar un tiempo de espera de sesión SAML personalizado para todos los usuarios de su instancia utilizando el comando ghe-config saml.default-session-expiration [seconds] en el shell administrativo.

Si defines un valor de duración de sesión personalizado inferior a 24 horas, GitHub puede solicitar a los usuarios que se autentiquen cada vez que GitHub inicie un redireccionamiento.

Independientemente del método de autenticación usado en la instancia, GitHub Enterprise Server finalizará una sesión de usuario después de dos semanas de inactividad continua.