Edge Route SAML Module

Replace HTTPS Edge Route SAML Module

Request

PUT /edges/https/{edge_id}/routes/{id}/saml

Example Request

curl \
-X PUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"idp_metadata":"\n<EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" validUntil=\"2020-09-14T12:53:23.691Z\" cacheDuration=\"PT1M\" entityID=\"http://127.0.0.1:12345/metadata\"><IDPSSODescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"><NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat><SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://127.0.0.1:12345/sso\"></SingleSignOnService><SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://127.0.0.1:12345/sso\"></SingleSignOnService></IDPSSODescriptor></EntityDescriptor>\n"}' \
https://api.ngrok.com/edges/https/edghts_2hrGzFU2NfuBXFG1hUsf6Gj2A2Z/routes/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd/saml

Parameters

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
force_authn	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
nameid_format	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Response

Returns a 200 response on success

Example Response

{
	"allow_idp_initiated": true,
	"assertion_consumer_service_url": "https://idp.local-ngrok.com/saml/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd/acs",
	"authorized_groups": [],
	"cookie_prefix": "",
	"enabled": true,
	"entity_id": "https://idp.local-ngrok.com/saml/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd",
	"force_authn": false,
	"idp_metadata": "\n<EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" validUntil=\"2020-09-14T12:53:23.691Z\" cacheDuration=\"PT1M\" entityID=\"http://127.0.0.1:12345/metadata\"><IDPSSODescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"><NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat><SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://127.0.0.1:12345/sso\"></SingleSignOnService><SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://127.0.0.1:12345/sso\"></SingleSignOnService></IDPSSODescriptor></EntityDescriptor>\n",
	"idp_metadata_url": "",
	"inactivity_timeout": 0,
	"maximum_duration": 0,
	"metadata_url": "https://idp.local-ngrok.com/saml/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd",
	"nameid_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
	"options_passthrough": false,
	"request_signing_certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIEAzCCAuugAwIBAgIQD5rGSbCD95jrowARvfvQKjANBgkqhkiG9w0BAQsFADCB\noDFOMEwGA1UECgxFaHR0cHM6Ly9pZHAubG9jYWwtbmdyb2suY29tL3NhbWwvZWRn\naHRzcnRfMmhyR3pDTnlBNDBiTXZHUzZHNkRHM1FlUlVkMU4wTAYDVQQDDEVodHRw\nczovL2lkcC5sb2NhbC1uZ3Jvay5jb20vc2FtbC9lZGdodHNydF8yaHJHekNOeUE0\nMGJNdkdTNkc2REczUWVSVWQwIBcNMjQwNjE0MDYwNDAzWhgPMjA1OTA2MDYwNjA0\nMDNaMIGgMU4wTAYDVQQKDEVodHRwczovL2lkcC5sb2NhbC1uZ3Jvay5jb20vc2Ft\nbC9lZGdodHNydF8yaHJHekNOeUE0MGJNdkdTNkc2REczUWVSVWQxTjBMBgNVBAMM\nRWh0dHBzOi8vaWRwLmxvY2FsLW5ncm9rLmNvbS9zYW1sL2VkZ2h0c3J0XzJockd6\nQ055QTQwYk12R1M2RzZERzNRZVJVZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAMXPyu7M2XLis3JYb29L7g/u1e0/5Cp4IssDDvLkK65muK0l9CY19VtS\nPfgcdY1Im6c3rciEf/GyImEESM/vcLvzflxLyWMMdaYkBlh8D7CrheNuFialTEt4\nRzQQ4nHH59caQm78u+F3XI+MmDI3KKdw98KE1JTI3/+ysz9lBEUefamgXQLdgx5A\nF3pnfL2WI35KfhoH7go8ThtXSsWaRQimEEOxzg19tWrN7qriD9OrxvAhfj0waDFq\n1WpSWmfCaaMnzaNQbCAj+4UGo03sKhZboJzfrnWLrHKIaXi8YmaQY7DjME27OBMy\nZQZnXZ0ea6UHLOr+fGQZGyODdEofwysCAwEAAaM1MDMwDgYDVR0PAQH/BAQDAgeA\nMBMGA1UdJQQMMAoGCCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwDQYJKoZIhvcNAQEL\nBQADggEBAMKgt3ibXFLlWEkJZKeLDx4X3DJXWPBhsTax5nQv5TgHKTdvHprUjaf0\nIiJMkvm961QvDdsEi58hEqya4wfpfOAfCu6/7OnGjyX7Yq/mIqFb6VoSIfMdfNuZ\nNbF6n2LCOZfBOwfPCkZQ3DFrI3qZnpbk/lqSeUtZBj6hTkBfH66WXQYXKItIGgbV\nlQ4cxjE4M/1EFBAPaqOSNKiwNHHoY6kHOaXP1gk03jeOEz5uO9Cw55K8BcbLIdZo\nuFdD7dEYNKSNMaKzFVUUur/kOxzBeE80cBWH9G4SZWMrsLNQvRPlfNIjFN80o+zx\nmh+TgwgUnhaxJNVFSIs21PqvnxWWNug=\n-----END CERTIFICATE-----\n",
	"single_logout_url": "https://idp.local-ngrok.com/saml/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd/slo"
}

Fields

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
force_authn	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_id	string	The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
assertion_consumer_service_url	string	The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
single_logout_url	string	The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
request_signing_certificate_pem	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported.
metadata_url	string	A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
nameid_format	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Get HTTPS Edge Route SAML Module

Request

GET /edges/https/{edge_id}/routes/{id}/saml

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_2hrGzFU2NfuBXFG1hUsf6Gj2A2Z/routes/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd/saml

Response

Returns a 200 response on success

Example Response

{
	"allow_idp_initiated": true,
	"assertion_consumer_service_url": "https://idp.local-ngrok.com/saml/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd/acs",
	"authorized_groups": [],
	"cookie_prefix": "",
	"enabled": true,
	"entity_id": "https://idp.local-ngrok.com/saml/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd",
	"force_authn": false,
	"idp_metadata": "\n<EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" validUntil=\"2020-09-14T12:53:23.691Z\" cacheDuration=\"PT1M\" entityID=\"http://127.0.0.1:12345/metadata\"><IDPSSODescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"><NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat><SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://127.0.0.1:12345/sso\"></SingleSignOnService><SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://127.0.0.1:12345/sso\"></SingleSignOnService></IDPSSODescriptor></EntityDescriptor>\n",
	"idp_metadata_url": "",
	"inactivity_timeout": 0,
	"maximum_duration": 0,
	"metadata_url": "https://idp.local-ngrok.com/saml/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd",
	"nameid_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
	"options_passthrough": false,
	"request_signing_certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIEAzCCAuugAwIBAgIQD5rGSbCD95jrowARvfvQKjANBgkqhkiG9w0BAQsFADCB\noDFOMEwGA1UECgxFaHR0cHM6Ly9pZHAubG9jYWwtbmdyb2suY29tL3NhbWwvZWRn\naHRzcnRfMmhyR3pDTnlBNDBiTXZHUzZHNkRHM1FlUlVkMU4wTAYDVQQDDEVodHRw\nczovL2lkcC5sb2NhbC1uZ3Jvay5jb20vc2FtbC9lZGdodHNydF8yaHJHekNOeUE0\nMGJNdkdTNkc2REczUWVSVWQwIBcNMjQwNjE0MDYwNDAzWhgPMjA1OTA2MDYwNjA0\nMDNaMIGgMU4wTAYDVQQKDEVodHRwczovL2lkcC5sb2NhbC1uZ3Jvay5jb20vc2Ft\nbC9lZGdodHNydF8yaHJHekNOeUE0MGJNdkdTNkc2REczUWVSVWQxTjBMBgNVBAMM\nRWh0dHBzOi8vaWRwLmxvY2FsLW5ncm9rLmNvbS9zYW1sL2VkZ2h0c3J0XzJockd6\nQ055QTQwYk12R1M2RzZERzNRZVJVZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAMXPyu7M2XLis3JYb29L7g/u1e0/5Cp4IssDDvLkK65muK0l9CY19VtS\nPfgcdY1Im6c3rciEf/GyImEESM/vcLvzflxLyWMMdaYkBlh8D7CrheNuFialTEt4\nRzQQ4nHH59caQm78u+F3XI+MmDI3KKdw98KE1JTI3/+ysz9lBEUefamgXQLdgx5A\nF3pnfL2WI35KfhoH7go8ThtXSsWaRQimEEOxzg19tWrN7qriD9OrxvAhfj0waDFq\n1WpSWmfCaaMnzaNQbCAj+4UGo03sKhZboJzfrnWLrHKIaXi8YmaQY7DjME27OBMy\nZQZnXZ0ea6UHLOr+fGQZGyODdEofwysCAwEAAaM1MDMwDgYDVR0PAQH/BAQDAgeA\nMBMGA1UdJQQMMAoGCCsGAQUFBwMBMAwGA1UdEwEB/wQCMAAwDQYJKoZIhvcNAQEL\nBQADggEBAMKgt3ibXFLlWEkJZKeLDx4X3DJXWPBhsTax5nQv5TgHKTdvHprUjaf0\nIiJMkvm961QvDdsEi58hEqya4wfpfOAfCu6/7OnGjyX7Yq/mIqFb6VoSIfMdfNuZ\nNbF6n2LCOZfBOwfPCkZQ3DFrI3qZnpbk/lqSeUtZBj6hTkBfH66WXQYXKItIGgbV\nlQ4cxjE4M/1EFBAPaqOSNKiwNHHoY6kHOaXP1gk03jeOEz5uO9Cw55K8BcbLIdZo\nuFdD7dEYNKSNMaKzFVUUur/kOxzBeE80cBWH9G4SZWMrsLNQvRPlfNIjFN80o+zx\nmh+TgwgUnhaxJNVFSIs21PqvnxWWNug=\n-----END CERTIFICATE-----\n",
	"single_logout_url": "https://idp.local-ngrok.com/saml/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd/slo"
}

Fields

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
force_authn	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_id	string	The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
assertion_consumer_service_url	string	The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
single_logout_url	string	The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
request_signing_certificate_pem	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported.
metadata_url	string	A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
nameid_format	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Delete HTTPS Edge Route SAML Module

Request

DELETE /edges/https/{edge_id}/routes/{id}/saml

Example Request

curl \
-X DELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_2hrGzFU2NfuBXFG1hUsf6Gj2A2Z/routes/edghtsrt_2hrGzCNyA40bMvGS6G6DG3QeRUd/saml

Response

Returns a 204 response with no body on success