# Sign in with Aurora Account: the Node.js example

A small web server that signs a person in with Aurora Account and shows what Aurora Account says about them. It
does what the developers page describes, <https://aurora-ws.com/developers>, step by step:

- `/` links to `/login`;
- `/login` makes a fresh `state`, `nonce` and PKCE verifier, and sends the browser to the authorization endpoint;
- `/callback` checks `state` against this browser's cookie and `iss` against the issuer. It then exchanges the
  code at the token endpoint with a `private_key_jwt` client assertion, checks the ID token against Aurora
  Account's key set (RS256, `iss`, `aud`, `exp`, `nonce`), calls userinfo, and shows the claims.

The endpoints come from the discovery document. Every request to Aurora Account carries a descriptive
`User-Agent`: put your own service's name in `USER_AGENT`, at the top of `app.mjs`.

The assertion is made with [jose](https://github.com/panva/jose)'s `SignJWT`, not by an OpenID Connect client
library: some of those send `aud` as an array of two values, which Aurora Account refuses (section 5 of the
developers page).

It keeps the sign-ins under way in memory, in one process: an example to read and run, not a production server.
Where it says "Here your service starts its own session", yours does.

## Install

Node.js 20 or later.

```sh
npm install
```

## Your key pair

```sh
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out aurora-private.pem
openssl pkey -in aurora-private.pem -pubout -out aurora-public.pem
```

Send `aurora-public.pem` to us with the rest of what section 2 of the developers page asks for, your redirect URI
among it: for this example on your own machine, `https://localhost:8443/callback`. We send you back your
`client_id`.

The private key stays on your machine. Never send it to anyone, us included, and never commit it. It must be the
PKCS #8 file `openssl genpkey` writes (`-----BEGIN PRIVATE KEY-----`).

## A certificate for localhost

Redirect URIs are https only, local development included, so the example serves HTTPS itself when it is given a
certificate. [mkcert](https://github.com/FiloSottile/mkcert) makes one that your browser trusts:

```sh
mkcert -install
mkcert -cert-file localhost.pem -key-file localhost-key.pem localhost
```

## The variables

| Variable | Value |
|---|---|
| `CLIENT_ID` | The `client_id` we sent you. Required. |
| `PRIVATE_KEY_PATH` | Your private key, `aurora-private.pem`. Required. |
| `REDIRECT_URI` | Exactly as registered, such as `https://localhost:8443/callback`. Required. |
| `AURORA_ISSUER` | `https://account.aurora-ws.com/o` unless set. |
| `PORT` | `8443` unless set. It listens on `127.0.0.1` only. |
| `TLS_CERT`, `TLS_KEY` | The certificate and its key, `localhost.pem` and `localhost-key.pem`. Without them it serves plain HTTP, for a reverse proxy in front of it that serves HTTPS. |

## Run

```sh
export CLIENT_ID=your-client-id PRIVATE_KEY_PATH=aurora-private.pem
export REDIRECT_URI=https://localhost:8443/callback TLS_CERT=localhost.pem TLS_KEY=localhost-key.pem
npm start
```

In Windows PowerShell, set each variable as `$env:CLIENT_ID = "your-client-id"`, and so on.

Open <https://localhost:8443/> and sign in. The first time, Aurora Account shows its consent screen with your
service's name; after Allow, the example shows the ID token's claims and userinfo's answer.

If something fails, the page says what Aurora Account answered. Section 9 of the developers page lists the errors.

## Licence

MIT: see `LICENSE`.