# 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](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Once, 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. (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](https://code.salaxy.com/security/impersonation.md), 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](http://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims), plus three Salaxy claims: `company`, `person` and `app`.

### Token claims

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

| Member | Type | Description |
|---|---|---|
| `aud` | string | **Required.** The federation endpoint: `https://test-secure.salaxy.com/security/federation` in test |
| `exp` | number | **Required.** Expiry time, in seconds since the epoch |
| `iss` | string | The issuer. Not checked |

### Standard claims

| Member | Type | Description |
|---|---|---|
| `sub` | string | Identifier for the end-user at the issuer |
| `name` | string | Full name. Not used: Salaxy uses `given_name` and `family_name` |
| `given_name` | string | Given name(s) |
| `family_name` | string | Surname(s) |
| `picture` | string | URL of the profile picture |
| `email` | string | Preferred email address. Used only when `email_verified` is true |
| `email_verified` | boolean | Whether the email address has been verified |
| `birthdate` | string | Birthday, if the personal identity code is not known. Workers only |
| `locale` | string | Locale, as a BCP 47 language tag |
| `phone_number` | string | Preferred telephone number |
| `phone_number_verified` | boolean | Whether the phone number has been verified |
| `address` | object | Preferred postal address (`formatted` and `region` are accepted but not used) |
| `updated_at` | number | When 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

| Member | Type | Description |
|---|---|---|
| `https://salaxy.com/federation/person` | object | Personal account data |
| `https://salaxy.com/federation/app` | object | Application and session data: return links and state |
| `https://salaxy.com/federation/company` | object | Company account data |

**`person`**

| Member | Type | Description |
|---|---|---|
| `can_sign_company` | boolean | The user may sign on behalf of the company or association. Accepted but not currently used |
| `personal_id` | string | Finnish personal identity code, for digital signature |

**`app`**

| Member | Type | Description |
|---|---|---|
| `return_link` | string | Success URL: link back to your application; the token is added to it |
| `cancel_link` | string | Cancel URL: link back in case of an error or cancel |
| `state` | object | Your 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 |
| `role` | string | `owner` or `noAccess`. Accepted but not currently used |

**`company`**

| Member | Type | Description |
|---|---|---|
| `as_company` | boolean | If true, the authorisation is for a company account and the root claims describe the user acting for it. If false, `company` is ignored |
| `business_id` | string | Business ID, e.g. `FI12345678` or `12345678` |
| `type` | string | `fiOy` (limited company), `fiTm` (sole trader), `fiRy` (registered association), `fiYy` (other Finnish company or association) |
| `name` | string | Company name, as in the trade register — shown on calculations, reports and invoices |
| `picture` | string | URL of an image file (PNG preferred, square) for the company logo |
| `email` | string | Email for salary-payment matters. Used only when `email_verified` is true |
| `email_verified` | boolean | Whether the email has been verified |
| `phone_number` | string | Telephone for salary-payment matters |
| `phone_number_verified` | boolean | Whether the phone number has been verified |
| `address` | object | Postal address for salary-payment matters |
| `proxy_partner` | string | The primary partner account for a new company. You must be authorised to that partner, or be it |
| `partner_account_id` | string | The 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`](https://github.com/auth0/node-jsonwebtoken); the current site has a [C# example](https://code.salaxy.com/security/federation).

## 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](https://code.salaxy.com/security/rest-authentication.md#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.
