You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: articles/protocols/saml/saml-configuration/special-configuration-scenarios/signing-and-encrypting-saml-requests.md
+152-48
Original file line number
Diff line number
Diff line change
@@ -11,59 +11,152 @@ useCase:
11
11
12
12
# Special Configuration Scenarios: Signing and Encrypting SAML Requests
13
13
14
-
To increase the security of your transactions, you can sign or encrypt both your requests and your responses.
14
+
To increase the security of your transactions, you can sign or encrypt both your requests and your responses in the SAML protocol. In this article you'll find configurations for specific scenarios, separated under two use cases:
15
15
16
-
## Sign the SAML Authentication Request
16
+
- Auth0 as the SAML **service provider** (i.e. a SAML **Connection**)
17
+
- Auth0 as the SAML **identity provider** (i.e. an **Application** configured with the **SAML Web App Addon**)
18
+
19
+
## Auth0 as the SAML Service Provider
20
+
21
+
These scenarios apply when Auth0 is the SAML Service Provider, i.e. Auth0 connects to a SAML identity provider by creating a SAML connection.
22
+
23
+
### Sign the SAML Authentication Request
17
24
18
25
If Auth0 is the SAML **service provider**, you can sign the authentication request Auth0 sends to the IdP as follows:
19
26
20
27
1. For the Connection in which you're interested, navigate to **Enterprise** -> **SAMLP Identity Provider** -> **Settings**.
21
28
2. Enable the **Sign Request** toggle.
22
29
3. Download the certificate beneath the **Sign Request** toggle and provide it to the IdP so that it can validate the signature.
23
30
24
-
### Enable/Disable Deflate Encoding
31
+
####Enable/Disable Deflate Encoding
25
32
26
33
By default, SAML authentication requests are sent via HTTP-Redirect and use deflate encoding, which puts the signature in a query parameter.
27
34
28
35
To turn off deflate encoding, you can make a [PATCH call to the Management API's Update a Connection endpoint](/api/management/v2#!/Connections/patch_connections_by_id) and set the `deflate` option to `false`.
29
36
30
-
```har
37
+
::: note
38
+
Updating the `options` object for a connection overrides the whole `options` object. To keep previous connection options, get the existing `options` object and add new key/values to it.
## Sign the SAML Authentication Responses/Assertions
55
+
### Use a custom certificate to sign requests
56
+
57
+
By default, Auth0 uses the tenant private key to sign SAML requests (when the **Sign Request** toggle is enabled). You can also provide your own private/public key pair to sign requests coming from a specific connection.
58
+
59
+
You can generate your own certificate and private key using this command:
Changing the key used to sign requests in the connection can't be done on the Dashboard UI, so you will have to use the [Update a Connection endpoint](/api/management/v2#!/Connections/patch_connections_by_id) from the Management API v2, and add a `signing_key` property to the `options` object, as shown in the payload example below.
66
+
67
+
::: note
68
+
Updating the `options` object for a connection overrides the whole `options` object. To keep previous connection options, get the existing `options` object and add new key/values to it.
"cert":"-----BEGIN CERTIFICATE-----\n...{your public key cert here}...\n-----END CERTIFICATE-----"
83
+
}
84
+
}
85
+
}
86
+
```
87
+
88
+
See [Working with private and public keys as strings](#working-with-certificates-as-strings) for details on how to get the private key and certificate formatted as a JSON string to use in the payload.
89
+
90
+
### Receive Signed SAML Authentication Responses
91
+
92
+
If Auth0 is the SAML **service provider**, all SAML responses from your identity provider should be signed to indicate it hasn't been tampered with by an unauthorized third-party.
93
+
94
+
You will need to configure Auth0 to validate the responses' signatures by:
95
+
96
+
* Obtaining a signing certificate from the IdP
97
+
* Loading the certificate from the IdP into your Auth0 Connection (in the Management Dashboard, go to the **Upload Certificate** section for your Connection by navigating to **Connections** -> **Enterprise** -> **SAMLP Identity Provider** -> **Settings**)
98
+
99
+
Auth0 can accept a signed response for the assertion, the response, or both.
If Auth0 is the SAML **service provider**, it may need to receive encrypted assertions from an identity provider. To do this, you must provide Auth0's public key and certificate to the IdP. The IdP encrypts the SAML assertion using the public key and sends it to Auth0, which decrypts it using the private key.
104
+
105
+
To retrieve the certificate you need to send to your IdP from the [Management Dashboard](${manage_url}), go to **Connections** -> **Enterprise** -> **SAMLP Identity Provider** and click on the **Setup Instructions** button next to the connection.
106
+
107
+
Navigate to the section titled **Encrypted Assertions** and download the certificate in the format requested by the IdP.
108
+
109
+
## Auth0 as the SAML Identity Provider
110
+
111
+
This scenarios apply when Auth0 is the SAML Identity Provider for an application. This is represented in the dashboard by an **Application** that has the SAML Web App Addon enabled.
52
112
53
-
If Auth0 is the SAML **identity provider**, it can sign responses/assertions with its private key and provide the service provider with the public key/certificate necessary to validate the signature.
113
+
### Sign the SAML Responses/Assertions
114
+
115
+
If Auth0 is the SAML **identity provider**, it will sign SAML assertions with the tenant's private key and provide the service provider with the public key/certificate necessary to validate the signature.
54
116
55
117
To retrieve the certificate you need to send to your IdP from the [Management Dashboard](${manage_url}):
56
118
57
119
1. Go to **Applications** -> **Settings** -> **Show Advanced Settings**.
58
120
2. Scroll to the *Certificates* section, and click **Download Certificate* to obtain the signing certificate you need to provide to your IdP.
59
121
3. Send your certificate to the service provider.
60
122
61
-
Next, you'll need make sure that the SAML assertion is *not* signed (you can sign either the assertion or the response, but not both). Here's how to unsign the SAML Assertion:
123
+
By default, Auth0 signs the SAML **assertion** within the response. If you want to sign the SAML **response** instead, follow this instructions:
62
124
63
125
1. In the [Management Dashboard](${manage_url}), navigate to **Applications**. Find the Application you're interested in go to **Addons** > SAML2 WEB APP > Settings.
64
-
2. By default, `signResponse` is true. As such, uncomment this line and set the value to `false`. Your SAML assertion will no longer be signed.
126
+
2. Look for the `"signResponse"` key. Add it or uncommented if required, and set its value to `true` (the default value is `false`). The configuration should look like this:
127
+
128
+
```json
129
+
{
130
+
[...], // other settings
131
+
"signResponse": true
132
+
}
133
+
```
134
+
135
+
#### Change the signing key for SAML responses
65
136
66
-
## Receive Signed SAML Authentication Requests
137
+
Auth0 will by default use the private/public key pair assigned to your tenant to sign SAML responses or assertions. For very specific scenarios you might wish to provide your own key pair. You can do so with a rule like this:
138
+
139
+
```javascript
140
+
function (user, context, callback) {
141
+
// replace with the ID of the application that has the SAML Web App Addon enabled
142
+
// for which you want to change the signing key pair.
143
+
var samlIdpClientId ='YOUR_SAML_APP_CLIENT_ID';
144
+
// only for a specific client
145
+
if (context.clientID!== samlIdpClientId) {
146
+
returncallback(null, user, context);
147
+
}
148
+
149
+
// provide your own private key and certificate here
Take a look at [Working with certificates as strings](#working-with-certificates-as-strings) for information on how to turn the private key and certificate files into strings that you can use in a rule.
158
+
159
+
### Receive Signed SAML Authentication Requests
67
160
68
161
If Auth0 is the SAML **identity provider**, it can received requests signed with the service provider's private key. Auth0 will then use the service providers' public key/certificate to validate the signature.
69
162
@@ -78,40 +171,51 @@ The configuration should look like this:
78
171
}
79
172
```
80
173
81
-
## Receive Signed SAML Authentication Responses
82
-
83
-
If Auth0 is the SAML **service provider**, all SAML responses from your identity provider should be signed to indicate it hasn't been tampered with by an unauthorized third-party.
84
-
85
-
You will then need to configure Auth0 to validate the responses' signatures by:
86
-
87
-
* Obtaining a signing certificate from the IdP
88
-
* Loading the certificate from the IdP into your Auth0 Connection (in the Management Dashboard, go to the **Upload Certificate** section for your Connection by navigating to **Connections** -> **Enterprise** -> **SAMLP Identity Provider** -> **Settings**)
89
-
90
-
Auth0 can accept a signed response for the assertion, the response, or both.
91
-
92
-
## Send Encrypted SAML Authentication Assertions
174
+
### Send Encrypted SAML Authentication Assertions
93
175
94
176
If Auth0 is the SAML **identity provider**, you can use [Rules](/rules) to encrypt the SAML assertions it sends.
95
177
96
-
You'll need to obtain the public key/certificate from the service provider.
178
+
You'll need to obtain the certificate and the public key from the service provider. If you only got the certificate, you can derive the public key using `openssl`. Assuming that the certificate file is named `certificate.pem` you can do:
Once you get the certificate and public key files, you'll need to [turn them into strings](#working-with-certificates-as-strings) to use them in a rule. The rule will look like this:
If Auth0 is the SAML **service provider**, it may need to receive encrypted assertions from an identity provider. To do this, you must provide Auth0's public key and certificate to the IdP. The IdP encrypts the SAML assertion using the public key and sends it to Auth0, which decrypts it using the private key.
200
+
When working with certificates or keys in rules or Management API v2 requests, you will most likely require a string representation of the file.
114
201
115
-
To retrieve the certificate you need to send to your IdP from the [Management Dashboard](${manage_url}), go to **Connections** -> **Enterprise** -> **SAMLP Identity Provider** and click on the **Setup Instructions** button next to the connection.
202
+
If you open a certificate file (`cer`, `pem`) with a text editor, you'll see something like this:
116
203
117
-
Navigate to the section titled **Encrypted Assertions** and download the certificate in the format requested by the IdP.
The lines between the `-----BEGIN CERTIFICATE-----` header and `-----END CERTIFICATE-----` footer contain base64-encoded binary information. Public keys and private keys (`.key` files) will look similar, with just a different header/footer.
216
+
217
+
For a string representation of a certificate/key file, you will need to concatenate everything in one line, with a `\n` (escaped new-line) sequence replacing the actual new lines in the file. So from the above sample you'd obtain something like this:
218
+
219
+
```
220
+
"-----BEGIN CERTIFICATE-----\nMIICzDCCAbQCCQDH8GvxPIeH+DANBgkqhkiG9w0BAQsFADAoMQswCQYDVQQGEwJh\n[..all the other lines..]-----END CERTIFICATE-----\n"
0 commit comments