Error codes: bad gateway errors and other SSOGEN messages
An SSOGEN error code looks like SSO-FORM-503-PAUSED: the product, the area, a number and a short name. This page lists the codes a person can meet, grouped by the place where they appear: a Gateway page shown to an employee, the Gateway’s own log, the certificate automation interface, and the Admin Console. Other failures are shown as a sentence without a code, and the pages for each feature explain those.
1. How to read an error
Section titled “1. How to read an error”| Part | What it tells you |
|---|---|
| Code | What kind of failure this is. The meaning of a code does not change. |
| Number in the middle | Usually the HTTP status of the answer: 403 refused, 502 or 503 something behind SSOGEN did not answer, 400 the request itself was wrong. |
| Message | A short, safe sentence. It never contains a password, token, code or key. |
| Correlation id (shown as a reference) | One identifier for this single request. It ties the page a person saw to the audit record of what happened. |
When an employee reports an error, ask for the code and the reference shown on the page. Then open the audit log, enter the reference in the Correlation id filter, and read what was recorded. See Audit log.
Interfaces that return a code as data use this form:
{ "error": { "code": "SSO-CERT-400-EXPIRED", "message": "The certificate has expired or expires within a day.", "correlation_id": "0f8b2c1e-7a4d-4e55-9c1b-3d2a6f7e8b90" }}2. Pages an employee sees from a Gateway
Section titled “2. Pages an employee sees from a Gateway”When a Gateway cannot open an application for a person, it shows a short page with the code, a fixed sentence and the reference. The administrator sees the same outcome in the console, in Last sign-in on the application’s tab Sign-in to the application.
2.1 The application is not reachable
Section titled “2.1 The application is not reachable”| Code | The page says | Meaning | What to do |
|---|---|---|---|
SSO-EDGE-503-UNAVAILABLE |
This application is temporarily unavailable. | The Gateway cannot confirm the current access state with SSOGEN, so it refuses instead of guessing. | Check that the Gateway can reach SSOGEN and that SSOGEN is healthy. See Gateway troubleshooting. |
SSO-EDGE-503-CONNECTOR-UNAVAILABLE |
This application is temporarily unavailable. | The application is reached through an Outbound Connector, and no connector of its group is connected. | Start or repair the connector. See Outbound Connector for private apps. |
SSO-EDGE-503-NOT-IN-EFFECT |
This application is temporarily unavailable. If this continues, contact your administrator and quote the code below. | The route is saved, but this Gateway left it out of the configuration it runs. Other routes keep working. | On the Gateways page, read the Not in effect line of the instance: it names the route and the reason. The reasons are in Gateway troubleshooting, section 4. |
SSO-EDGE-403-BACKEND-SIGNIN |
Sign-in to this application was refused. | SSOGEN refused to release the application’s sign-in for this request. | Search the audit log for the reference on the page, then see Gateway troubleshooting. |
2.2 The address was refused
Section titled “2.2 The address was refused”These two are plain-text answers with status 400. They end with “If you followed a link, contact your administrator and quote this code”.
| Code | The page says | What to do |
|---|---|---|
SSO-EDGE-400-PATH-PARAMETER |
This address has a path parameter (a semicolon in the path), which this gateway does not accept. | Correct the link. The Gateway does not pass on an address with a semicolon in its path. |
SSO-EDGE-400-PATH-CHARACTER |
This address has a space, a control character or a non-ASCII character in its path, which this gateway does not accept. | Correct the link so that its path holds none of these characters. |
2.3 Windows (Kerberos) sign-in to the application
Section titled “2.3 Windows (Kerberos) sign-in to the application”| Code | The page says | The console says |
|---|---|---|
SSO-KRB-403-PRINCIPAL |
Sign-in to this application is not available for your account. | No Windows account matched the person |
SSO-KRB-403-DELEGATION |
Sign-in to this application is not available for your account. | Windows refused the delegation |
SSO-KRB-502-KDC |
The sign-in service for this application did not respond. | The domain controller did not respond |
SSO-KRB-500-KEYTAB |
Sign-in to this application is not configured correctly. | The keytab is missing or wrong |
SSO-KRB-503-UNAVAILABLE |
This application is temporarily unavailable. | The gateway could not reach the sign-in service |
What to check for each code is in Form fill and Kerberos sign-in, in the table of outcomes, and in Gateway troubleshooting.
2.4 Form fill
Section titled “2.4 Form fill”| Code | The page says | The console says |
|---|---|---|
SSO-FORM-403-NOACCOUNT |
Sign-in to this application is not configured. | No shared account is set |
SSO-FORM-403-NOPERSONCREDENTIAL |
SSOGEN does not have your sign-in for this application yet. Add it under App passwords in your account. | |
SSO-FORM-403-PERSON-UPDATE |
Your saved password for this application needs updating. Update it under App passwords in your account. | |
SSO-FORM-502-REJECTED |
SSOGEN could not sign you in to this application. Your administrator has been told. | The application rejected the shared account |
SSO-FORM-502-UNSUPPORTED |
SSOGEN could not sign you in to this application. Your administrator has been told. | The login page does not match the settings |
SSO-FORM-503-PAUSED |
Sign-in to this application is paused. Try again in a few minutes. | Paused after repeated failures |
SSO-FORM-503-BUSY |
Many people are signing in to this application right now. Try again in a moment. | |
SSO-FORM-503-UNAVAILABLE |
This application is temporarily unavailable. |
For the two codes that name App passwords, the page links the employee to that section of their account. What to check for a shared account is in Form fill and Kerberos sign-in; what to check for a person’s own sign-in is in Per-person form fill.
3. Messages in the Gateway’s log
Section titled “3. Messages in the Gateway’s log”The Gateway writes these to its log, and ssogen-edge --check and the Gateway’s readiness answer repeat them, each followed by a reason.
| Code | Message | What to do |
|---|---|---|
SSO-EDGE-502-PLATFORM-KEYS |
The Platform’s keys could not be verified with the trust bundle. Download the trust bundle from the console again. | Download the trust bundle from the console again, replace the file on the Gateway and restart it. See Install and enrol a Gateway. |
SSO-EDGE-502-PLATFORM-ANSWER |
An answer that claimed to come from the Platform was refused. | The same: download the trust bundle from the console again, replace the file on the Gateway and restart it. When this happens during enrolment, also check that the SSOGEN address the Gateway was given is exactly the one the console shows. |
4. Certificate automation for the App Proxy
Section titled “4. Certificate automation for the App Proxy”A script that replaces an App Proxy certificate receives one of these codes when the upload is refused. The interface and its client are described in Publish an internal app with the App Proxy.
| Status | Code | Message | What to do |
|---|---|---|---|
| 400 | SSO-CERT-400-PEM |
The certificate or key could not be read. | Send PEM text: the certificate, its chain and the private key. |
| 400 | SSO-CERT-400-KEY-MISMATCH |
The private key does not belong to the certificate. | Send the key that was used for this certificate. |
| 400 | SSO-CERT-400-KEY-UNSUPPORTED |
This key type or size is not accepted. | Use RSA with 2048 bits or more, or ECDSA P-256 or P-384. |
| 400 | SSO-CERT-400-EXPIRED |
The certificate has expired or expires within a day. | Send a current certificate. |
| 400 | SSO-CERT-400-NOT-SERVER |
This is not a TLS server certificate. | Send a certificate issued for server authentication. |
| 400 | SSO-CERT-400-CHAIN |
The certificate chain is incomplete or out of order. | Send the server certificate first, then the certificate that issued it, and so on. A server certificate alone is not enough. |
| 400 | SSO-SEC-400-VALIDATION |
Request validation failed. | Check the request against the interface description. |
| 400 | SSO-SEC-400-SECRET-KEY |
This deployment has no secret encryption key, so secrets cannot be stored here. | Configure the secret encryption key on the SSOGEN server. See Secrets. |
| 401 | SSO-AUTH-401-INVALID |
Authentication failed. | Check the client’s credential. |
| 403 | SSO-CERT-403-CLIENT |
This client may not change App Proxy certificates. | The client does not hold the permission. Set it up as the App Proxy page describes. |
| 404 | SSO-CERT-404-UNKNOWN |
There is no such certificate. | Check the certificate identifier in the address. |
| 409 | SSO-CERT-409-SAN |
The certificate does not cover every hostname that uses it. | Issue a certificate that names every hostname using it, or move the hostnames first. |
| 409 | SSO-CERT-409-IN-USE |
This certificate is in use. Move its hostnames and listeners to another certificate first. | Move them, then repeat the request. |
| 429 | SSO-SEC-429-RATE |
Request rate is limited. | Wait 60 seconds (the answer carries Retry-After: 60), then try again. |
5. The Admin Console and its interface
Section titled “5. The Admin Console and its interface”The Admin Console turns a refusal into a sentence, so an administrator normally reads the sentence, not the code. A script that calls the same interface receives the code.
| Code | Message | Meaning | What to do |
|---|---|---|---|
SSO-ADMIN-403-SECOND-FACTOR-REQUIRED |
The Admin Console’s sign-in policy asks for a second factor. | This sign-in did not include a second factor the console’s policy accepts. | Sign in again with a second factor. See Admin console sign-in. |
SSO-ADMIN-403-CAPABILITY-DENIED |
Your administrator role or your sign-in does not allow this. | The role does not include this action, or the console’s sign-in policy does not accept this sign-in. | Ask a Super Admin for the role, or sign in the way the console’s policy asks. See Branding and admin roles. |
SSO-ADMIN-403-TARGET-OUTRANKS-CALLER |
This account holds an administrator role you cannot assign, so you cannot change it. | Only a Super Admin can change an administrator’s account. Recorded in the audit log as admin.target_action_refused. |
Ask a Super Admin to make the change. |
When the console has no sentence of its own for a refusal, it shows “The server refused to …” followed by a reference in brackets. That reference is the correlation id: search the audit log for it.
6. Sign-in through a SAML identity provider
Section titled “6. Sign-in through a SAML identity provider”| Code | Where it appears | Meaning | What to do |
|---|---|---|---|
SSO-SAML-400-ASSERTION |
The browser receives an answer with status 400 and this code after the identity provider sends the person back | SSOGEN rejected the identity provider’s response. The reason is not shown to the browser. | Read the reason in the SSOGEN server log for that time, and compare the connection’s settings (certificate, addresses, clock) with the identity provider. Use Test on the connection before activating it, as Add a SAML identity provider describes. |
7. When there is no code
Section titled “7. When there is no code”Most refusals an administrator meets are sentences in the console, and most refusals an employee meets are sentences on the sign-in page. For those:
- The page for the feature lists its messages. For lockout refusals, see Admin lockout protection. For provisioning, see the SCIM reference.
- A reference shown with a message is a correlation id. Search the audit log for it.
- The Audit event reference explains the events you find there.