Commit 3c26b4e7 authored by Evan Read's avatar Evan Read Committed by James Edwards-Jones

Add information on signing and encrypting for SAML

parent 3289398c
......@@ -429,6 +429,120 @@ args: {
}
```
## Response signature validation (required)
We require Identity Providers to sign SAML responses to ensure that the assertions are
not tampered with.
This prevents user impersonation and prevents privilege escalation when specific group
membership is required. Typically this:
- Is configured using `idp_cert_fingerprint`.
- Includes the full certificate in the response, although if your Identity Provider
doesn't support this, you can directly configure GitLab using the `idp_cert` option.
Example configuration with `idp_cert_fingerprint`:
```yaml
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
}
```
Example configuration with `idp_cert`:
```yaml
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert: '-----BEGIN CERTIFICATE-----
<redacted>
-----END CERTIFICATE-----',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
}
```
If the response signature validation is configured incorrectly, you can see error messages
such as:
- A key validation error.
- Digest mismatch.
- Fingerprint mismatch.
Refer to the [troubleshooting section](#troubleshooting) for more information on
debugging these errors.
## Assertion Encryption (optional)
GitLab requires the use of TLS encryption with SAML, but in some cases there can be a
need for additional encryption of the assertions.
This may be the case, for example, if you terminate TLS encryption early at a load
balancer and include sensitive details in assertions that you do not want appearing
in logs. Most organizations should not need additional encryption at this layer.
The SAML integration supports EncryptedAssertion. You need to define the private key and the public certificate of your GitLab instance in the SAML settings:
```yaml
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
certificate: '-----BEGIN CERTIFICATE-----
<redacted>
-----END CERTIFICATE-----',
private_key: '-----BEGIN PRIVATE KEY-----
<redacted>
-----END PRIVATE KEY-----'
}
```
Your Identity Provider will encrypt the assertion with the public certificate of GitLab. GitLab will decrypt the EncryptedAssertion with its private key.
NOTE: **Note:**
This integration uses the `certificate` and `private_key` settings for both assertion encryption and request signing.
## Request signing (optional)
Another optional configuration is to sign SAML authentication requests. GitLab SAML Requests uses the SAML redirect binding so this is not necessary, unlike the SAML POST binding where signing is required to prevent intermediaries tampering with the requests.
In order to sign, you need to create a private key and public certificate pair for your GitLab instance to use for SAML. The settings related to signing can be set in the `security` section of the configuration.
For example:
```yaml
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
certificate: '-----BEGIN CERTIFICATE-----
<redacted>
-----END CERTIFICATE-----',
private_key: '-----BEGIN PRIVATE KEY-----
<redacted>
-----END PRIVATE KEY-----',
security: {
authn_requests_signed: true, # enable signature on AuthNRequest
want_assertions_signed: true, # enable the requirement of signed assertion
embed_sign: true, # embedded signature or HTTP GET parameter signature
metadata_signed: false, # enable signature on Metadata
signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
}
}
```
GitLab will sign the request with the provided private key. GitLab will include the configured public x500 certificate in the metadata for your Identity Provider to validate the signature of the received request with. For more information on this option, see the [ruby-saml gem documentation](https://github.com/onelogin/ruby-saml/tree/v1.7.0). The `ruby-saml` gem is used by the [omniauth-saml gem](https://github.com/omniauth/omniauth-saml) to implement the client side of the SAML authentication.
## Troubleshooting
### 500 error after login
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment