Finlay.worksBareBones Ticketing manual

Configure

Customer Portal

How the signed handoff from the Customer Area admits a customer, how to stage the catalog they see, and what the Customer Portal does not give them.

RC2 approved for evaluation Status: release-candidate Audience: System Administrator Source: c4b4d41

Customer Portal

The Customer Portal lets a customer who is already signed in to your organization's Customer Area raise and follow tickets, without a separate BareBones Ticketing account. This page covers configuring that trust, staging the catalog the customer sees, and the limits of what they get.

The division of responsibility is fixed. The Customer Area decides one thing: whether this customer may enter. BareBones Ticketing decides everything else — who the requester is, which services they see, what they can do, and what is never shown to them.

How a customer gets in

The Customer Area sends the customer's browser to BareBones Ticketing with one signed form POST. That request is the handoff. It carries a stable customer identifier, a verified email address, and one boolean claim, portal_access.

  • portal_access=true — the customer may receive or refresh a session.
  • portal_access=false — no session is issued, and any current grant for that customer is revoked.

BareBones Ticketing checks the signature, the issuer, the audience, the freshness of the assertion, and that its one-time nonce has not been used before. If any check fails, the request is refused without saying why.

Identity is bound by issuer plus the stable subject the Customer Area sends. The email address is contact data only. It never selects the identity, and changing it does not move ticket ownership.

Implementers building the sender need the exact field list, ordering, encoding, signature, and time bounds. That is in the Customer Portal SSO handoff contract.

The session is 8 hours, fixed and non-sliding

An accepted handoff creates a grant that lasts at most 8 hours from the moment it was issued. Activity does not extend it. When the 8 hours are up, the customer must come back through the Customer Area for a new handoff.

Before you start

  • You need SystemAdmin access and step-up verification for every change here.
  • The installation needs one validated Hypertext Transfer Protocol Secure (HTTPS) BareBonesTicketing:PublicBaseUrl. The audience is derived from it. The request host is never used instead.
  • The application Data Protection key ring must survive restarts, restores, and deployments. It protects the stored shared secret.
  • You need the full HTTPS Customer Area return address, and its owner.
  • The sender needs somewhere protected to keep a runtime secret. A ticket, chat message, email, source file, or shell history is not that place.
  • Prepare one test Customer Area identity that is eligible and one that is not. Do not use a real customer for first enablement.

Choose which services customers see

The customer catalog is built from a tenant default plus a stored choice on each service.

Set the tenant default

  1. Open Tenant Administration → Customer Portal SSO.
  2. Under Default department, choose either one active department, whose services set to Inherit are then included, or None - select services individually.
  3. Select Save scope.
  4. Check Customer requester scope and Effectively visible services.

None is a complete choice, not an unfinished one. The configuration becomes ready as soon as one eligible service is explicitly shown. Choosing a default department gives customers no authority in that department.

Set the choice on each service

  1. Open one service and review Customer requester selection source and Customer requester availability.

  2. In the edit drawer, set Show for Customer requesters to:

    • Inherit — follow the tenant default;
    • Show — always include this service; or
    • Hide — always exclude this service.

  3. Save and reopen the service. Confirm both the stored choice and the current result.

Show can include a service outside the default department. Hide can exclude one inside it. Changing the default department recalculates the inherited services and leaves explicit choices alone.

A service can be selected and still not appear. These block it:

  • the service is inactive;
  • the service creates action items only;
  • its department is disabled;
  • its category is inactive;
  • its intake form has a Project reference field;
  • its intake form has a User picker or Multi-user picker field; or
  • its configured internal project is unavailable.

The departments and categories a customer sees are derived from the services they can see. The ordinary internal catalog is never shown instead.

The service count is checked when you enable the configuration, and only then. It is not checked again when a customer arrives. If you remove or hide every service after enabling, customers still sign in successfully and land on an empty Service Catalog with nothing they can raise. Nothing warns you and nothing refuses the handoff. After changing which services customers see, check Effectively visible services yourself.

Attach an internal project to a service

A service can put every customer ticket into one internal project without the customer knowing the project exists.

  1. In the service edit drawer, find Internal project for Customer requester tickets (optional).
  2. Choose None or one active project in the same tenant.
  3. Review the project's staffing and the project-role mappings that will apply.
  4. Save and confirm Customer requester internal project.
  5. Create one test customer ticket and check the result from an internal workspace.

At ticket creation BareBones Ticketing reads the project from saved service configuration. It refuses a project identifier posted by the browser. It then creates the ticket-project relationship and runs create-time routing. Which mapping set that routing uses is decided by the department fallback rule in Assignment rules.

The customer never sees the project — not its name, number, identifier, a hint that one exists, an eligibility message about it, or the routing result.

Before retiring a configured internal project, change every service that uses it to None or an active replacement, then reconcile the project's existing ticket relationships. Deactivating the project does not do either.

Configure the provider and enable

  1. In Tenant Administration → Customer Portal SSO, confirm the read-only values: Provider is Signed customer portal handoff, Callback is the fixed callback path, Audience is derived from the public base URL, Expected issuer is derived from the Customer Area origin, and Required claim is portal_access.
  2. Enter the full Customer Area return URL and select Save URL.
  3. Confirm the derived issuer is exactly the Customer Area HTTPS origin.
  4. Confirm the effective service count is above zero.
  5. Complete step-up verification and select Generate shared secret.
  6. Copy the displayed value once into the sender's protected runtime secret store. It is shown once and cannot be shown again.
  7. Confirm the sender uses the Unicode Transformation Format 8-bit (UTF-8) bytes of that exact string as its signing key. It must not decode the value first.
  8. Clear your clipboard history.
  9. Confirm the page reports Ready but disabled.
  10. Select Enable. Confirm the status is Enabled.
  11. Perform one handoff from the eligible test identity. Confirm the customer lands in Service Catalog and sees only the services you intended.
  12. Create one test ticket and confirm from an internal workspace that the service, department, workflow, SLA, status, project relationship, and owner are what you expected.
  13. Select Return to Customer Area from the customer session and confirm the session ends and the browser returns to the configured address.
  14. Send one newer handoff with portal_access=false and confirm the grant is revoked and no session is issued.

If the return URL, public base, and services are ready but no secret exists, the page reports Disabled and the readiness message reads Generate a shared secret.

There is a fourth readiness message you will only see after a restore or a key loss: The protected shared secret is unavailable. Preserve the data-protection key ring or rotate the secret. The secret is encrypted with the Data Protection key ring, so restoring a database without its matching key ring leaves the secret unreadable. Either restore the correct key ring or rotate the secret and re-share it with the Customer Area. See Backup and restore.

Once any Customer Portal identity or grant exists, the Customer Area origin cannot be changed. A path or query change on the same origin is still allowed. Moving to a different origin is separate work; do not rename or relink identities to force it.

Rotate the shared secret

There is one current secret and no overlap window.

  1. Agree a cutover time with the sender's owner.
  2. Complete step-up verification and select Rotate shared secret.
  3. Copy the replacement once into the sender's protected store.
  4. Activate the replacement on the sender.
  5. Perform one eligible test handoff and one negative test handoff.

Rotation does not revoke existing grants. To cut off access, select Disable, or have the Customer Area send a current portal_access=false handoff.

What a Customer Portal requester does not get

A Customer Portal requester has exactly three things in the interface: Service Catalog, My Tickets, and Return to Customer Area. They do not get:

  • a username or password of their own — sign-in is through the Customer Area only, and there is no BareBones Ticketing password reset for them;
  • Quick Ticket;
  • search;
  • preferences;
  • approvals;
  • Projects;
  • the Agent workspace; or
  • any administration workspace.

They also cannot be added to product groups, be staffed into a project role, or be selected by an assignment rule.

An operator can see these users in User Administration using the Customer Portal SSO only source filter and search by their Customer Area email. Their contact details are managed by the provider and are read-only in BareBones Ticketing. The internal login name generated for them is a binding, not an identifier to give the customer.

Disabling one of these users is stronger than revoking a grant: a later eligible handoff for that identity is refused and does not reactivate the account.

If it does not work

  • Configure BareBonesTicketing:PublicBaseUrl as an absolute HTTPS URL. Correct the validated HTTPS runtime setting. Do not substitute the request host.
  • Save an HTTPS Customer Area return URL. Save one absolute HTTPS address with no credentials and no fragment.
  • Select at least one eligible service for customer requesters. Review the default department, the per-service choices, and the blockers listed above.
  • The secret cannot be read. Restore the correct Data Protection key ring, or rotate the secret and update the sender.
  • Handoffs are refused and the reason is not given. That is by design. Check the sender against the handoff contract: issuer, audience, encoding, clock, nonce reuse, and which secret it is signing with.
  • The customer sees a project, a person, a role, or a routing detail. Select Disable and report it. Nothing internal should reach that interface.
  • A handoff matched a customer by email address, or reactivated a disabled user. Select Disable and report it. Neither is the intended behaviour.