Skip to content

Federation flow for banks ​

In federation, a trusted partner — in practice a bank or payment provider — vouches for its user. It sends Salaxy a signed message describing the user and, where relevant, the company; Salaxy creates the company account, or uses an existing account that has authorised you, and returns the user with an access token.

A federation provider must be committed to strong authentication (bank-ID level) and have signed a contract with Salaxy — in practice banks and payment providers that follow Finnish KYC rules. Interested? Contact Salaxy's customer service or sales.

Examples use test-* hosts — see Environments for demo and production.

Federation flow for banksOnce, sign a contract, get the Federation provider role and a certificate. Then: build the federation message, sign it as a JWT, send it to the federation endpoint; Salaxy creates the account, or uses an existing account that has authorised you, and redirects the browser to your success URL with an access token, or to your cancel URL.Your serverBrowserSalaxy1 · Once: contract, Federation provider role and certificate2 · Build the federation message (OpenID Connect claims)3 · Sign it as a JWT with the certificate4 · Federation token to /security/federation5 · Create the account5b · Existing account: needs your authorisation6 · Redirect to your success URL with the token6b · …or to your cancel URL7 · API calls: Authorization: Bearer …
Dashed: alternative paths. Numbers match the steps below.

Prerequisites ​

  • Federation provider role. In production, only accounts marked as federation providers can use federation. Salaxy's back office sets the role after the contract is signed. In test, any account can currently use federation — this may change without notice, so tell Salaxy if you plan to use it.
  • A certificate for the federation provider account, and its password — the same kind of Salaxy-issued certificate as in the impersonation flow, one per environment.

2. The federation message ​

The message is based on the OpenID Connect UserInfo response. It describes the end-user with the standard claims, plus three Salaxy claims: company, person and app.

Token claims ​

Borrowed from the OpenID Connect ID token, so that Salaxy can check the message:

MemberTypeDescription
audstringRequired. The federation endpoint: https://test-secure.salaxy.com/security/federation in test
expnumberRequired. Expiry time, in seconds since the epoch
issstringThe issuer. Not checked

Standard claims ​

MemberTypeDescription
substringIdentifier for the end-user at the issuer
namestringFull name. Not used: Salaxy uses given_name and family_name
given_namestringGiven name(s)
family_namestringSurname(s)
picturestringURL of the profile picture
emailstringPreferred email address. Used only when email_verified is true
email_verifiedbooleanWhether the email address has been verified
birthdatestringBirthday, if the personal identity code is not known. Workers only
localestringLocale, as a BCP 47 language tag
phone_numberstringPreferred telephone number
phone_number_verifiedbooleanWhether the phone number has been verified
addressobjectPreferred postal address (formatted and region are accepted but not used)
updated_atnumberWhen the information was last updated, in seconds since the epoch

middle_name, nickname, preferred_username, profile, website, gender and zoneinfo are accepted but not used.

Salaxy claims ​

MemberTypeDescription
https://salaxy.com/federation/personobjectPersonal account data
https://salaxy.com/federation/appobjectApplication and session data: return links and state
https://salaxy.com/federation/companyobjectCompany account data

person

MemberTypeDescription
can_sign_companybooleanThe user may sign on behalf of the company or association. Accepted but not currently used
personal_idstringFinnish personal identity code, for digital signature

app

MemberTypeDescription
return_linkstringSuccess URL: link back to your application; the token is added to it
cancel_linkstringCancel URL: link back in case of an error or cancel
stateobjectYour own data, as string values. It comes back to your success or cancel URL as state (Base64-encoded JSON). custom is an older name for the same member
rolestringowner or noAccess. Accepted but not currently used

company

MemberTypeDescription
as_companybooleanIf true, the authorisation is for a company account and the root claims describe the user acting for it. If false, company is ignored
business_idstringBusiness ID, e.g. FI12345678 or 12345678
typestringfiOy (limited company), fiTm (sole trader), fiRy (registered association), fiYy (other Finnish company or association)
namestringCompany name, as in the trade register — shown on calculations, reports and invoices
picturestringURL of an image file (PNG preferred, square) for the company logo
emailstringEmail for salary-payment matters. Used only when email_verified is true
email_verifiedbooleanWhether the email has been verified
phone_numberstringTelephone for salary-payment matters
phone_number_verifiedbooleanWhether the phone number has been verified
addressobjectPostal address for salary-payment matters
proxy_partnerstringThe primary partner account for a new company. You must be authorised to that partner, or be it
partner_account_idstringThe account id at your site. If set, the authorisation is restricted to that one account

3. Sign it as a JWT ​

Sign the message as a JWT with the certificate, RS256, with the certificate in the header: x5c as an array with exactly one item, and x5t as its thumbprint. In Node.js, jsonwebtoken; the current site has a C# example.

4–6. Send it ​

Send the user's browser to the federation endpoint on the API host — https://test-secure.salaxy.com/security/federation?token=<token> in test, by GET or POST. Salaxy looks for an existing account by business ID (company.business_id, when company.as_company is true) or personal identity code (person.personal_id):

  • A new company account — the normal case — is created, and your account is automatically authorised to it.
  • An existing account that has authorised you — the user gets a token for it.
  • An existing company account that has not authorised you — the browser goes to your cancel URL with error=access_denied. The error_description (in Finnish) tells the user to sign in to Salaxy, authorise your service and try again.
  • A personal account that does not exist yet, or has not authorised you, goes to a Salaxy onboarding page first.

The browser then returns to your success URL with the token in the URL fragment — #access_token=…&token_type=bearer&state=… — or to your cancel URL with #error=…&error_description=…. Validation errors also go to the cancel URL, with error=invalid_request and the failed fields listed (in Finnish).

7. Use the token ​

Browser JavaScript sets the token as the Bearer token on each Salaxy API call. See Tokens.

Other federation flows ​

Two alternatives are partly implemented but not in use, and not documented: the full OpenID Connect flow, if you already run an OpenID Provider, and SAML — either a full SAML SSO profile with you as identity provider, or just the signed response message. Ask Salaxy if you would rather use one of these.

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.