Run a Gateway with a hosted organization: SSO for on-premise applications

Who can do this: a super administrator of the organization (issuing an enrollment token needs that role) and a person with root access on the Gateway server. What you need first: the Gateways feature switched on for your organization by SSOGEN (see below), the Gateway archive and its .sha256 file, and a Linux server that can reach your organization’s address over HTTPS. Result: a Gateway of your own shows online on Secure access > Gateways of your Admin Console, enrolled against your organization’s address and nobody else’s.

On the hosted service every organization runs its own Gateways at its own address. No Gateway is shared between organizations, and SSOGEN does not run one for you. The installation itself is the same as for an SSOGEN you run yourself: follow Install and enroll an SSOGEN Gateway step by step, and apply the differences on this page where it says so. This page uses the fictional company Acme Corp, whose organization’s address is written as https://acme.example, with a Gateway on gw01.acme.example.

1. Before you start: is the feature on?

Gateways are switched on per organization by SSOGEN.

1. Open Monitoring > System health. With the feature off, the item Gateways reads Gateways are not switched on for your organization. Ask SSOGEN to switch them on before you set one up., and Certificate authority for agents and Gateways reads Gateways are not switched on for your organization.
2. Open the menu: with the feature on, Secure access shows App Proxy routes, Directory Connector and Gateways. With it off, those pages are left out and a page opened by its address shows only This feature is not enabled for your organization.

A Gateway enrolled while the feature is off is refused: the enrollment ends with the reason SSO-PLAN-403-FEATURE, feature edge in the Gateway’s log, and the Gateway does not retry. If SSOGEN switches the feature off later, enrolled Gateways are refused the same way at their next call, keep their keys, and work again when it is switched back on.

Remote Access, Outbound Connector and App Proxy certificates are further features that need Gateways on; their pages appear under Secure access when they are on for your organization.

2. Issue the enrollment token

Follow section 2 of Install and enroll an SSOGEN Gateway on Secure access > Gateways. Two things to read on that page before you continue:

• Under Enrollment tokens, the sentence The organization is set by SSOGEN: is followed by your organization’s id. That id is the realmId of the bootstrap file; the console writes it into the file for you after the token is issued.
• Under Certificate authority of your Gateways, your organization’s own authority is listed with its SHA-256 fingerprint and Signs new certificates. It is created for your organization when Gateways are switched on; until then the section reads None yet. It is created when Gateways are enabled for your organization. Every Gateway and Web Agent certificate of your organization is issued from it, and it signs nothing of any other organization. There is no Replace Gateway keys now button on the hosted service: SSOGEN rotates the keys for you.

Choose the role under What this Gateway will do (App Proxy, Outbound Connector or Directory Connector) and select Issue token. Copy the Enrollment token and the Enrolment string now; they are shown once.

3. Install and write the bootstrap file

Install the Gateway as in sections 3 and 4 of Install and enroll an SSOGEN Gateway. In the bootstrap file the console shows under Gateway bootstrap file:

Field	On the hosted service
platformOrigin	Your organization’s own address, exactly as in your invitation, for example https://acme.example. No path, no other host.
realmId	Your organization’s id, as shown under Enrollment tokens. The console has already written it.
Everything else	As the published guide describes.

The Gateway connects to your address by name and presents its certificate only to your organization; a certificate of another organization, or one presented under another organization’s name, is refused by the service.

4. Enrol

Enrol as in section 5 of the published guide, either by pasting the Enrolment string at the prompt or with a token file and the trust bundle from Download trust bundle. The string pins your organization’s authority, so with it there is nothing to download or compare.

5. Directory Connector: enter the Gateway’s address in the console

This step replaces the server-side setting the published guide names for a Directory Connector Gateway. On the hosted service you tell SSOGEN where your Gateway answers in the Admin Console.

1. On the Gateway host, finish the Directory Connector steps the console shows under the bootstrap file (the directory’s CA certificate and the bind password files), and let your organization’s SSOGEN address reach the Gateway on port 9945.
2. Open Secure access > Directory Connector and enter the Gateway group.
3. Under Gateway address for the Directory Connector, the line Not set for this group. shows nothing is set yet. In Address, enter https://<the Gateway's public host name>:9945/edge/directory/execute, for example https://gw01.acme.example:9945/edge/directory/execute, and select Save address. The page answers Saved. and the line reads Now: followed by the address.
4. To take it away later, select Remove address; the page answers Removed.

Only a public address is accepted: That address cannot be used: it is inside this service’s own network or a private or reserved address. Use the Gateway’s public address. A malformed address answers Enter an https address ending in /edge/directory/execute, with no user name, query or fragment. The service presents a certificate of your organization’s authority to the Gateway and trusts only your Gateways of that group.

The console’s Test of a directory connection goes through the Directory Connector; sign-in does not use it (the token form says so). People in a directory that only a Gateway can reach cannot sign in with that directory’s password from the hosted service.

6. When SSOGEN rotates your organization’s authority

SSOGEN rotates the certificate authority of your organization from time to time. On Secure access > Gateways, under Certificate authority of your Gateways, a second entry appears, marked Next: add it to every Gateway before it signs. A running Gateway learns the next authority from SSOGEN by itself and renews its own certificate once it is promoted; you download nothing. In the instances table, an instance that has not yet picked up the next authority is marked so beside its State.

A Gateway that was stopped across the whole rotation may be refused afterwards (its log names SSO-EDGE-502-PLATFORM-KEYS). Then select Download trust bundle, replace the file named by pki.trustBundle in the bootstrap file with the downloaded one, as it is, and restart the Gateway.

7. Reaching your Gateway through a relay

A Gateway inside your network can be reached through a relay, as Reach a Gateway through a relay with ACME certificates describes. On the hosted service the Relay registrations section is not on the route’s Uplink relay section: your registrations are handled for you, ask SSOGEN.

Check it worked

1. On the Gateway host, ssogen-edge-diagnostics --config /etc/ssogen-edge/edge.yaml --readiness exits 0 (a Gateway with no published route yet is not ready; that is normal until you publish one).
2. On Secure access > Gateways, the group appears with your instance, State healthy, and the token’s row reads State used with your instance under Used by.
3. Monitoring > System health: Certificate authority for agents and Gateways and Gateways show no problem.
4. For a Directory Connector: Secure access > Directory Connector shows Now: with the saved address, and Test on a directory connection of that group succeeds.

Troubleshooting

What you see	Why	What to do
Gateways are not switched on for your organization. Ask SSOGEN to switch them on before you set one up. on System health; no Gateways page in the menu	The feature is off for your organization.	Ask SSOGEN to switch it on.
SSO-PLAN-403-FEATURE, feature edge in the Gateway’s log at enrollment or later	The feature is off, or was switched off after enrollment.	Ask SSOGEN. The Gateway keeps its keys and works again when the feature is on.
None yet. It is created when Gateways are enabled for your organization. under the authority section while Gateways is in the menu, or Your organization’s certificate authority has not been created yet. Contact SSOGEN support. on System health	The authority of your organization is not there yet.	Contact SSOGEN support; a Gateway cannot enrol until it exists.
The enrolment string is refused as being for another organization or out of date	The string names an authority that is not the one your address presents now.	Issue a new token on Gateways and use its string.
SSO-EDGE-502-PLATFORM-KEYS after the Gateway was off for a long time	It missed a rotation of the authority.	Section 6: download the trust bundle again, replace the file, restart.
Gateways are not enabled for your organization. when saving the Directory Connector address	The feature is off.	Ask SSOGEN.
That address cannot be used: it is inside this service’s own network or a private or reserved address. Use the Gateway’s public address.	The Directory Connector address is private.	Give the Gateway a public host name and open port 9945 to your organization’s SSOGEN address.
This service is suspended.	Your organization is not in service.	Contact SSOGEN.
Anything else	The common Gateway problems.	Gateway troubleshooting: routes, certificates, 503.