First SSO sign-in and setup of a hosted organization

Who can do this: the person whose email address SSOGEN recorded as the organization’s owner contact. That address receives the invitation; nobody at SSOGEN has an account in your organization. What you need first: the invitation email, an authenticator app on your phone or desktop, and a safe place for recovery codes. Result: your organization has its first administrator with a second factor, a second administrator, your branding, a first way for people to sign in and a first application.

This page uses the fictional company Acme Corp, whose organization’s address is written as https://acme.example. Read Your hosted SSOGEN organization first for what differs from an SSOGEN you run yourself.

1. Open the invitation

The invitation email has the subject Set up your SSOGEN tenant on followed by your organization’s address. It says Your SSOGEN tenant is ready. Open this link to create its first administrator. and has a button Set up tenant. (The word tenant means your organization.) Below the button it says The link works once and until a date and time in UTC: the link is valid for 72 hours from when SSOGEN sent it.

1. Select Set up tenant. Your browser opens your organization’s address on a page titled Set up SSOGEN.
2. The link carries a setup token. The page reads it, removes it from the address bar and fills in the Setup token field for you. If you reload the page later, open the link from the email again.

If the link has expired, or you cannot find the email, ask SSOGEN to send the invitation again. A new invitation replaces the old link and goes to the same owner contact. SSOGEN can only resend it while the organization has no administrator yet.

2. Create the first administrator

On Set up SSOGEN the page says Create the first administrator. If you reload before entering the authenticator code, open the link from your email again.

1. Setup token: already filled in from the link. Leave it.
2. Administrator username: ssogen.admin is suggested. The hint reads 3 to 64 letters, digits, dots, underscores or hyphens. You may keep ssogen.admin or choose another. The name is stored in lower case.
3. Password and Confirm password: the hint under the field states the length rule of your organization’s password policy (for example Use at least 12 characters.).
4. Select Create administrator.

The page checks the form before sending it:

Message	Meaning
The username must be 3 to 64 letters, digits, dots, underscores or hyphens.	Change the username.
Enter a password. / The password must be … to 256 characters.	The password is empty or outside the length rule.
The two passwords do not match.	Retype the confirmation.
Paste the whole setup token from the file the server wrote.	The token in the field is incomplete. On the hosted service there is no file: open the link from your email again, exactly as it was sent.

3. Add an authenticator

The next page, Add an authenticator, says Administrators sign in with a second factor. Scan the code with an authenticator app for <username>, then enter the code it shows.

1. Scan the QR code with your authenticator app, or enter the key shown under Can’t scan it? Enter this key instead: by hand.
2. Type the six-digit code the app shows into SSOGEN MFA code.
3. Select Finish setup.

The administrator exists only after this step. If you close the page now, open the invitation link again and start over; your unfinished attempt is replaced.

Message	Meaning
Enter the 6-digit code from your authenticator app.	The field is empty or not a code.
That code was not accepted. Enter the current code from your authenticator app.	The code expired or was mistyped; enter the one the app shows now.
Setup was restarted with the setup token, so this attempt cannot finish. Start again with the token. If you did not restart it, someone else has the token: stop SSOGEN.	The link was opened again in another window and this attempt was superseded. Start again from the link. If you did not do that yourself, contact SSOGEN at once: on the hosted service you cannot stop the service.
Too many attempts. Wait a minute and try again.	The page was retried too often. Wait a minute.

4. Keep the recovery codes

The page Setup is complete says <username> is the administrator. Keep these recovery codes somewhere safe: each one signs in once if the authenticator is lost, and they are not shown again.

1. Copy the recovery codes to a password manager or print them. They are not shown again.
2. Select Sign in to the console.

Finishing setup from the invitation link also confirms your email address as the organization’s owner contact.

5. Sign in to the Admin Console

Sign in at your organization’s address with the username, the password and a code from your authenticator app. The sign-in page, lockout protection and administrator elevation are described in Admin Console sign-in and lockout protection.

6. Add a second administrator

Do this before anything else: there is no recovery invitation on the hosted service yet, so an organization whose only administrator loses both the authenticator and the recovery codes has no way back in except through SSOGEN.

1. Open Identity > Users and create the person, or let them come from the directory or identity provider you add later.
2. Open Settings > Admin roles and give them an administrator role.

The steps are in Your first hour with SSOGEN: from install to first sign-in (its sections on a second administrator and on admin roles apply as written) and SSO login page branding and admin roles.

7. Email: nothing to set up

On the hosted service your organization’s codes, links and notices are sent by SSOGEN’s mail service, so the step “add a mail server” of the first-hour guide does not apply. Monitoring > System health shows the mail item under Mail server (SMTP). To send through your own mail server instead, see the email rules in Your hosted SSOGEN organization.

8. Branding

Open Settings > Branding and follow SSO login page branding and admin roles: logo, colours, the text on the sign-in page. Everything on that page applies on the hosted service. The display name on the emails your organization sends is your organization’s name as SSOGEN recorded it, not the branding text.

9. The first directory or identity provider

Choose one of these, as in Your first hour with SSOGEN:

• An identity provider (Entra ID, Keycloak, any OpenID Connect or SAML provider): SSO policies > Identity providers; see Identity providers and federated login, Add an OpenID Connect identity provider (Entra, Keycloak) or Add a SAML identity provider (Entra ID, Keycloak). On the hosted service the setting Second factor after sign-in with this provider does not offer Never ask: the provider is the only factor.
• A directory (Active Directory or LDAP): Identity > Directories, if the menu shows it (the Directories feature must be switched on for your organization). See Connect Active Directory or LDAP authentication. The directory must be reachable at a public address on port 636 or 3269 (LDAPS) or 389 or 3268 (StartTLS); a directory on a private network cannot sign people in from the hosted service. Store the bind password as a secret under Settings > Secrets.
• People managed in SSOGEN only: Identity > Users > Create user, or a CSV import; see Manage users and bulk import from CSV.

Test the connection, then activate it, exactly as those pages describe. Check the sign-in policy under SSO policies > Defaults and try a sign-in with SSO policies > What if.

10. The first application

1. Open Applications > App gallery and pick the application, or Applications > SAML or OpenID Connect for an application of your own; see SAML vs OIDC: choose how to connect an app.
2. Assign people or groups on the application’s Assignments tab, test and activate it: Test SAML SSO and activate an application.
3. Open My Apps at your organization’s address as one of the assigned people and launch it.

Web Agents, App Proxy and Remote Access appear in the menu only when SSOGEN has switched them on for your organization; see Run a Gateway with a hosted organization.

Check it worked

1. Sign out and sign in again at your organization’s address with the username, the password and a code from the authenticator: the Admin Console opens.
2. Open the invitation link once more: the page reads Setup is already complete / An administrator exists. Sign in to the console.
3. Settings > Admin roles lists two administrators.
4. Monitoring > System health shows no missing item you did not expect, and Features switched off for your organization lists only features you do not need yet.
5. One person signs in and launches the first application from My Apps.

Troubleshooting

What you see	Why	What to do
Setup is already complete / An administrator exists. Sign in to the console.	The first administrator was created.	Sign in. If it was not you, contact SSOGEN.
Setup is not available / SSOGEN is still starting. Reload this page in a moment.	The service is not ready for your address yet.	Reload in a moment; if it stays, contact SSOGEN.
Checking setup… stays on screen	The page cannot reach the service.	Check your connection and open the link again.
SSOGEN could not be reached. Nothing was changed.	The browser lost the connection while sending the form.	Try again; nothing was created.
The administrator was not created. Check the password rules and the setup token; a token older than 24 hours needs a restart.	The server refused the token or the password.	Open the link from the email again. If the invitation is older than 72 hours, ask SSOGEN for a new one.
The authenticator could not be started. Start again with the setup token; one older than 24 hours needs a restart.	The attempt could not continue.	Open the link again and start over.
The password does not meet the password policy.	The password breaks a rule of the policy.	Follow the rule in the message.
Open this page at SSOGEN’s own address, then try again.	The page was opened at another address.	Open the link from the email, which uses your organization’s address.
The invitation email never arrived	It went to the owner contact SSOGEN recorded.	Check that mailbox and its spam folder; ask SSOGEN to resend it or to correct the owner contact.
This service is suspended.	Your organization is not in service.	Contact SSOGEN.