TaleArt docs

Type a word to find a page, a heading or a sentence in the docs.

GitHub

Sign-in methods

This guide turns on the ways people sign in to TaleArt: a passkey (on by default), a username and password, and an identity provider such as Google, Apple or your own OpenID Connect provider. An admin does the setup in the dashboard, step by step. The rules behind each method are in the Sign-in methods reference. The people and invitations side is in Projects, team and sign-in.

Before you start: the secret key

A provider's client secret, and an Apple private key, are stored encrypted. The key that encrypts them is an environment variable of the API, TALEART_SECRET_KEY: 32 random bytes, base64-encoded. Without it the API still runs, but it refuses to save a secret, so a provider that needs one cannot be used. 

# Generate a key once, and keep it with your other secrets:
openssl rand -base64 32

# Set the output as TALEART_SECRET_KEY on the API, then restart the API:
TALEART_SECRET_KEY=<the output of openssl rand -base64 32>

Keep the key with your other secrets. If it is lost, the stored secrets cannot be read, and each provider's secret must be entered again. When the key is missing, the Sign-in methods page shows the notice Provider secrets cannot be saved yet, and saving a provider's secret is refused with the same reason.

Set up the methods

  1. Open Settings > Sign-in methods.

    An admin finds the page in Settings, in the Sign-in methods tab. The Methods section lists Passkey, on from a fresh install, and Username and password, off. The Providers section below it is empty until you add one. Only admins see the tab. API tokens are unchanged by any of this.
    The Sign-in methods page of Settings on a fresh install. A red notice, Provider secrets cannot be saved yet, sits above the Methods section. Passkey is on, Username and password is off, and the Providers section is empty.
    The Sign-in methods page before the secret key is set, a real screenshot of the dashboard. The red notice says provider secrets cannot be saved until TALEART_SECRET_KEY is set.

  2. Turn on username and password.

    Switch Username and password sign-in on. Each person who joins by invitation then chooses a username and a password. People who already have an account set a password under My sign-in methods. Keep the passkey on until another admin can sign in with the new method.

    On an empty install, the first admin can also set up with a username and password, but only when the server runs with TALEART_SETUP_PASSWORD=true. Without it, the setup screen offers the passkey alone. 

    # On an empty install only: the first admin may set up with a username and password.
TALEART_SETUP_PASSWORD=true
    The Methods section with Username and password switched on. Both Passkey and Username and password read On; the notice about the secret key is still shown above.
    The same page after turning username and password on, a real screenshot of the dashboard.

  3. Add Google.

    In the Google Cloud console, create an OAuth client of type Web application, and copy its client ID and client secret. In TaleArt choose Add a provider, then Google. Enter the Button name, the client ID and the client secret, then choose Save provider. The secret is stored encrypted and is never shown again. After saving, copy the Redirect URI from the drawer. It has the form https://api.example.com/api/v1/auth/callback/google. Add it as an authorized redirect URI of the client in Google, then choose Test: the check passes when the provider's settings work.
    The Add a sign-in provider drawer with Google chosen. Button name is Google, Client ID holds an example value, and the client secret is masked. The redirect URI note says it appears once the provider is saved.
    The Google drawer filled with example values, a real screenshot. Nothing is saved: the client secret stays masked as it is typed.

  4. Add a generic OpenID Connect provider.

    Choose Add a provider, then Generic OpenID Connect. Enter a slug, such as company-sso. The method is then oidc:company-sso. Enter the issuer URL, such as https://id.example.com: its discovery document, at /.well-known/openid-configuration, must name exactly this issuer. Enter the client ID and the client secret, save, copy the redirect URI into the provider, then choose Test. A failed check says why, for example The provider did not pass the check: discovery_failed.
    The Edit Company SSO drawer of a saved generic OpenID Connect provider. Its client secret shows only as Secret is set, the redirect URI is visible, and Test reports that the provider settings work, with the issuer and the endpoints found.
    A saved provider after Test, a real screenshot. The secret is never shown, only that it is set. The issuer is a local test issuer.

  5. Add Apple.

    In your Apple developer account, create a Services ID for Sign in with Apple, and a key with Sign in with Apple enabled. Note your 10-character team ID and the key's 10-character key ID. In TaleArt choose Add a provider, then Apple. Enter the Services ID as the client ID, the team ID, the key ID, and paste the private key file (.p8) as PEM text into Private key (.p8). Save, copy the redirect URI, and register it as the Services ID's return URL. Apple sends the user back with a form post, which TaleArt accepts at the same address. The private key is stored encrypted, like a client secret.
    The Add a sign-in provider drawer with Apple chosen. Client ID, Team ID and Key ID hold example values, and the Private key (.p8) field holds the placeholder text. Nothing is saved.
    The Apple drawer filled with example values, a real screenshot. The private key field holds placeholder text; nothing is saved.

  6. See the methods on the sign-in page.

    Open the dashboard in a private window, where you are signed out. The sign-in page shows Sign in with a passkey, a form under With a username and password, and one Continue with button per provider that is on and usable. A provider is usable when it is on, its secret is stored, and the server has its key. A method that is off is not shown at all.
    The sign-in page for a signed-out browser: the Sign in heading, Sign in with a passkey, a username and password form, and a Continue with Company SSO button for the provider.
    The sign-in page with the enabled methods, a real screenshot of the dashboard for a signed-out visitor.

  7. Invite someone to join with a provider or a password.

    In the project, choose Invite. The link, /invite/<token>, is one-time and valid for 7 days, and it is shown only once. The admin does not enter an email: the person opens the link, enters their name and email, and then chooses a passkey, a username and password, or a provider. With a provider, the email the provider verified must equal the email typed on the invitation page. Otherwise the join is refused with email_mismatch, or with email_not_verified when the provider did not verify the address. A provider never creates an account by itself: it can only join an invitation or be linked by a user who is signed in.
    The invitation page Join Shop on TaleArt, opened by a signed-out visitor. It has Name and Email fields, Create passkey, a username and password form with Join with a password, and a Continue with Company SSO button for the provider.
    The invitation page for a fresh visitor, a real full-page screenshot of the dashboard. The link itself is not shown.

  8. Let each user manage their own methods.

    A signed-in user opens Settings > My sign-in methods. There they see their passkeys, their password (its username, never the password itself), and their linked providers. They set or change the password (the current one is needed when one is set), remove a passkey, unlink a provider, or choose Link a provider to attach one to the account. A method can be removed only while another one remains.
    The My sign-in methods page of an admin: Passkeys says No passkeys, Username and password shows the username and Change password and Remove password buttons, and Linked providers offers Continue with Company SSO under Link a provider.
    My sign-in methods, a real screenshot of the dashboard. The username is an example.
  9. An admin opens Settings > Users and chooses Issue reset link on the user's row. The button is available while username and password sign-in is on. Choose Create link, then Copy link. The link is shown only once, and it works once, for 24 hours. Share it with the user. The user opens it, sees Set a new password for their name, enters a password of 12 to 128 characters, and chooses Set password and sign in. Signing in there ends the user's other sessions. A new link replaces the earlier unused ones.
    The Reset link for Sam Example dialog. The Password reset link field is blurred, and a note says the link works once until a date and is shown only now. Copy link and Done are below it.
    The one-time reset link dialog, a real screenshot. The link is blurred: it is shown once and works once.

  10. Turn a method off safely.

    On Settings > Sign-in methods, switch the method off. TaleArt refuses a change that would leave an admin with no way to sign in, and says so: That would leave an admin with no way to sign in. Every admin needs a passkey, a password, or a linked provider that is on. Give each admin one of those first, then try again. It also refuses to turn off the last method on, with Keep at least one sign-in method on. Turn another method on first. Deleting a provider that sign-in depends on is refused the same way. Turn the new method on, check that each admin signs in with it, and only then turn the old one off.
    The Sign-in methods page with the passkey switched off. A red message reads: That would leave an admin with no way to sign in. Every admin needs a passkey, a password, or a linked provider that is on.
    The lock-out guard, a real screenshot of the dashboard. TaleArt refuses to turn the passkey off when no admin keeps another usable method.

Notes

  • Registration stays by invitation, plus the first admin on an empty install. There is no open sign-up.
  • A provider's redirect URI is always PUBLIC_API_URL plus /api/v1/auth/callback/ and the slug.
  • API tokens are unchanged: a script still calls the Management API with its token, and sign-in methods are never reached with a token.

Edit this page on GitHub