Pocket ID 2.19.2

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick Pocket ID 2.19.2 on Ubuntu 24.04 as the software version, choose your Region, then choose Launch through EC2.

Choose m5.large, your key pair and a security group as described above.

To launch with the AWS CLI instead, replace the values in angle brackets:

aws ec2 run-instances --image-id <ami-id-from-the-listing> --instance-type m5.large \
  --key-name <your-key-pair> --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --associate-public-ip-address \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=pocket-id}]'

First boot takes a few seconds after the instance is running. It generates the keys and the certificate, starts Pocket ID and creates the admin account. Only then does it open the web port.

To make the instance use your own name from the start, put the name in /etc/sac/pocket-id-domain.preset with user data, for example a cloud-init write_files entry. Otherwise first boot uses the instance's public DNS name, or its private DNS name if it has no public one.

Operating system SSH user

Ubuntu 24.04 ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

The login message shows the address of Pocket ID and the commands this guide uses.

systemctl is-active pocket-id nginx

active active

pocket-id-firstboot runs once, on the first boot, and shows inactive on every later boot.

Only SSH, HTTP and HTTPS are public. Pocket ID and its internal actor port listen on the loopback address:

sudo ss -tln | grep -E ':(22|80|443|1411|1414) '

LISTEN 0 511 0.0.0.0:443 0.0.0.0:* LISTEN 0 511 0.0.0.0:80 0.0.0.0:* LISTEN 0 4096 0.0.0.0:22 0.0.0.0:* LISTEN 0 128 127.0.0.1:1411 0.0.0.0:* LISTEN 0 511 [::]:443 [::]:* LISTEN 0 511 [::]:80 [::]:* LISTEN 0 4096 [::]:22 [::]:*

A built-in self-test checks four things. It checks the OIDC discovery document and the signing keys over HTTPS. It checks that the setup route is closed. It checks that the admin API refuses a request without a session. It checks that the token endpoint refuses an unknown client:

sudo pocket-id-selftest

pocket-id-selftest: discovery (issuer https://ec2-198-51-100-24.compute-1.amazonaws.com), JWKS 1 signing key(s), setup closed, admin API 401, unknown client invalid_client POCKET_ID_SELFTEST_OK

sudo cat /root/pocket-id-credentials.txt

Only root can read this file (mode 0600). It holds this instance's address, the SHA-256 fingerprint of its certificate and the one-time sign-in link for the admin account. There is no administrator password, because Pocket ID has none.

# Pocket ID 2.19.2 on this instance (sac). Sign in once with POCKET_ID_ADMIN_LINK, then add a passkey.
# The certificate is self-signed for this instance: compare its SHA-256 fingerprint with POCKET_ID_TLS_SHA256.
# Passkeys need a DNS name with a trusted certificate:
sudo pocket-id-set-domain (see the guide) BEFORE adding one.
# A new one-time link at any time:
sudo pocket-id-admin-link POCKET_ID_URL=https://ec2-198-51-100-24.compute-1.amazonaws.com/ POCKET_ID_HOST=ec2-198-51-100-24.compute-1.amazonaws.com POCKET_ID_ADMIN_USERNAME=admin POCKET_ID_TLS_SHA256=10:D6:AA:F8:...:(64 hex digits in pairs) POCKET_ID_NAME_SOURCE=public-dns-name POCKET_ID_ADDRESS=198.51.100.24 POCKET_ID_ADDRESS_SOURCE=imdsv2-public-ipv4 GUIDE=https://secureanycloud.com/stacks/pocket-id-2-19-2/ POCKET_ID_ADMIN_LINK_USER=admin POCKET_ID_ADMIN_LINK=https://ec2-198-51-100-24.compute-1.amazonaws.com/lc/<12-character one-time code> POCKET_ID_ADMIN_LINK_EXPIRES=2026-11-08T15:10:32Z

Treat the link like a password until you have used it. Whoever opens it first becomes the admin's session. It works once and expires at POCKET_ID_ADMIN_LINK_EXPIRES. You can make a new link at any time, for example after it expired, or for another user by username:

sudo pocket-id-admin-link

pocket-id-admin-link: a one-time sign-in link for 'admin' (valid until 2026-11-08T15:23:04Z, single use) is in /root/pocket-id-credentials.txt (POCKET_ID_ADMIN_LINK)

The certificate is self-signed and unique to your instance, so your browser warns about it. Open the certificate details in the browser and check that its SHA-256 fingerprint matches POCKET_ID_TLS_SHA256. Only then continue.

Do not add the certificate to your operating system's trust store, because Step 6 replaces it with a trusted one. Copy the certificate to your home directory so that the commands in this guide can use it as their trust anchor:

sudo cat /etc/ssl/pocket-id/pocket-id.crt > ~/pocket-id-instance.crt openssl x509 -in ~/pocket-id-instance.crt -noout -subject -ext basicConstraints,keyUsage,extendedKeyUsage,subjectAltName

subject=CN = ec2-198-51-100-24.compute-1.amazonaws.com, O = sac X509v3 Subject Alternative Name: DNS:ec2-198-51-100-24.compute-1.amazonaws.com, IP Address:198.51.100.24, IP Address:172.31.16.20, DNS:ip-172-31-16-20.ec2.internal, IP Address:127.0.0.1 X509v3 Basic Constraints: critical CA:FALSE X509v3 Key Usage: critical Digital Signature, Key Encipherment X509v3 Extended Key Usage: TLS Web Server Authentication

Open the POCKET_ID_ADMIN_LINK URL in your browser and accept the certificate once you have checked its fingerprint. Pocket ID signs you in as admin. Because the account has no passkey yet, it opens Set up your passkey.

Choose Skip for now. A passkey belongs to the name in your address bar, so add it once Pocket ID has the name you will keep and a certificate your browser trusts (Steps 6 and 7):

The link is now used up. Opened again, in any browser, it is refused and signs nobody in. The spent code is masked here:

You can run the same check from the instance. The pocket-id-admin-link command above made a new link, so this check uses that link and then tries it a second time:

L=$(sudo sed -n 's|^POCKET_ID_ADMIN_LINK=.*/lc/||p' /root/pocket-id-credentials.txt)
H=$(sudo sed -n 's/^POCKET_ID_HOST=//p' /root/pocket-id-credentials.txt) for try in first second; do printf '%s use: ' "$try" curl -s -o /dev/null -w '%{http_code}\n' --cacert ~/pocket-id-instance.crt -X POST -H "Origin: https://$H" "https://$H/api/one-time-access-token/$L" done unset L

first use: 200 second use: 401

A 200 response is a sign-in, and a 401 response is the refusal.

Before you add a passkey, give Pocket ID a DNS name with a trusted certificate (next step). Also replace the admin's placeholder email address. Open Settings > My Account, change Email from admin@pocket-id.invalid to your own address and save.

First boot uses that placeholder because Pocket ID requires an email for every account. Nothing is ever sent to it.

Passkeys belong to a domain: a passkey registered at ec2-...amazonaws.com only works there, and browsers create passkeys only for a site whose certificate they trust. Before your users add passkeys, point your own name at Pocket ID:

• Create a DNS record for your name, for example an A record id.example.com that points to the instance's Elastic IP address.
• Point Pocket ID at the name. The first name becomes Pocket ID's URL, and any names after it keep working too:

sudo pocket-id-set-domain id.example.com "$(sudo sed -n 's/^POCKET_ID_HOST=//p' /root/pocket-id-credentials.txt)"

• Get a certificate for the name. With Let's Encrypt, nginx already serves the HTTP challenge directory, so the certbot webroot mode works without stopping anything. Port 80 must be reachable from the internet while it runs:

sudo apt-get install -y certbot
sudo certbot certonly --webroot -w /var/www/sac-acme -d id.example.com --email you@example.com --agree-tos -n \
  --deploy-hook 'pocket-id-set-domain --tls-cert /etc/letsencrypt/live/id.example.com/fullchain.pem --tls-key /etc/letsencrypt/live/id.example.com/privkey.pem id.example.com'

The deploy hook installs the certificate now and again after every automatic renewal. With a certificate from another authority, run sudo pocket-id-set-domain --tls-cert <fullchain.pem> --tls-key <private-key.pem> id.example.com yourself. It checks that the key matches and that the certificate covers the name.

• Make a new one-time link for the new name with sudo pocket-id-admin-link. Links made before the change point at the old name.

Changing the name later invalidates every passkey registered for the old one, so choose the name you will keep.

Without --tls-cert, pocket-id-set-domain issues a new self-signed certificate for the names you give. It refuses an IP address as the first name:

sudo pocket-id-set-domain --no-restart 203.0.113.9 || true

[2026-11-08T14:23:09+0000] pocket-id-set-domain: FATAL: '203.0.113.9' is an IP address: Pocket ID needs a DNS name for its URL (the passkey relying-party ID must be a domain; Pocket ID refuses to start with an IP). Give a DNS name first; an address may follow as an extra name

At https://id.example.com/, open Settings > My Account and choose Add Passkey. Your browser or operating system asks which authenticator to use (this computer, a phone or a security key). The new passkey appears under Passkeys. Rename it from its menu, here Laptop, so that you can tell your passkeys apart:

Sign out and sign back in. The sign-in page has one button, Authenticate, which asks for your passkey:

Add a second passkey, on another device or a security key, so that losing one does not lock you out. If you are ever locked out, run sudo pocket-id-admin-link on the instance to get a new one-time link.

Under Settings > Administration, use Users to add people. Each user gets a one-time link or code to register their own passkey. Use User Groups to group users, so that you can restrict an application to a group.

To connect an application, open OIDC Clients and choose Add OIDC Client. Give the client a name and the callback URL your application documents:

After you choose Create, Pocket ID shows the client ID and, once only, the client secret (masked here). Copy the secret into your application's configuration now:

Your application needs the issuer URL. If it does not read the discovery document itself, it also needs the endpoints in that document:

H=$(sudo sed -n 's/^POCKET_ID_HOST=//p' /root/pocket-id-credentials.txt)
curl -s --cacert ~/pocket-id-instance.crt "https://$H/.well-known/openid-configuration" \
  | jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, end_session_endpoint}'
curl -s --cacert ~/pocket-id-instance.crt "https://$H/.well-known/jwks.json" | jq '.keys[] | {kty, alg, use, kid}'

{ "issuer": "https://ec2-198-51-100-24.compute-1.amazonaws.com", "authorization_endpoint": "https://ec2-198-51-100-24.compute-1.amazonaws.com/authorize", "token_endpoint": "https://ec2-198-51-100-24.compute-1.amazonaws.com/api/oidc/token", "userinfo_endpoint": "https://ec2-198-51-100-24.compute-1.amazonaws.com/api/oidc/userinfo", "jwks_uri": "https://ec2-198-51-100-24.compute-1.amazonaws.com/.well-known/jwks.json", "end_session_endpoint": "https://ec2-198-51-100-24.compute-1.amazonaws.com/api/oidc/end-session" } { "kty": "RSA", "alg": "RS256", "use": "sig", "kid": "ZArsZwkzSq0" }

The JSON Web Key Set holds only the public half of this instance's signing key.

To check a client's credentials from the instance, ask for a token with the client credentials grant. Replace the values in angle brackets with your client's ID and secret. A wrong secret is refused:

curl -s --cacert ~/pocket-id-instance.crt -u '<client-id>:<client-secret>' -d grant_type=client_credentials \
  "https://$(sudo sed -n 's/^POCKET_ID_HOST=//p' /root/pocket-id-credentials.txt)/api/oidc/token" | jq '{token_type, expires_in}'

{ "token_type": "bearer", "expires_in": 3599 }

nginx limits Pocket ID's sign-in, one-time-code, signup and token endpoints to 30 requests a minute per client address, with a burst of 20. Past that, a client gets HTTP 429 until its allowance refills, while other clients carry on.

All other requests are limited to 20 a second per client address (bursts of 100). The web interface's own script and style files under /_app/immutable/ are limited to 100 a second (bursts of 600), because a browser fetches about 120 of them on its first visit. The limits are in /etc/nginx/conf.d/sac-pocket-id.conf:

grep -E '^limit_req' /etc/nginx/conf.d/sac-pocket-id.conf

limit_req_zone $binary_remote_addr zone=pid_auth:10m rate=30r/m; limit_req_zone $binary_remote_addr zone=pid_all:10m rate=20r/s; limit_req_zone $binary_remote_addr zone=pid_static:10m rate=100r/s; limit_req_status 429;

The limits and Pocket ID's audit log (Settings > Audit Log) use the address of the TCP connection that reached nginx: Pocket ID trusts only the local nginx as a proxy (TRUST_PROXY=127.0.0.1/32,::1/128), and nginx replaces any X-Forwarded-For or X-Real-IP a client sends.

If you put a load balancer in front of the instance, every request then comes from the load balancer's address. Add its addresses to the nginx set_real_ip_from setting, with real_ip_header X-Forwarded-For, so that the limits apply per real client again.

Your security group and the passkeys or one-time links you issue decide who can sign in. Pocket ID has no open registration. Settings > Administration > Application Configuration controls whether people may sign up on their own, and this is off by default.

Pocket ID reads its settings from /etc/pocket-id/pocket-id.env (mode 0640, root:pocket-id), which holds no secret. Most options are also in Application Configuration in the admin UI. This is the file the image ships:

sudo grep -vE '^(#|$)' /etc/pocket-id/pocket-id.env

APP_URL=https://ec2-198-51-100-24.compute-1.amazonaws.com ENCRYPTION_KEY_FILE=/etc/pocket-id/encryption.key DB_CONNECTION_STRING=/var/lib/pocket-id/data/pocket-id.db FILE_BACKEND=filesystem UPLOAD_PATH=/var/lib/pocket-id/data/uploads GEOLITE_DB_PATH=/var/lib/pocket-id/data/GeoLite2-City.mmdb HOST=127.0.0.1 PORT=1411 ACTORS_HOST=127.0.0.1 ACTORS_PORT=1414 TRUST_PROXY=127.0.0.1/32,::1/128 ANALYTICS_DISABLED=true VERSION_CHECK_DISABLED=true ALLOW_INSECURE_CALLBACK_URLS=false OUTBOUND_ALLOWED_HOSTS_SCIM=none OUTBOUND_ALLOWED_HOSTS_BACKCHANNEL_LOGOUT=none OUTBOUND_ALLOWED_HOSTS_FEDERATED_JWKS=none OTEL_TRACES_EXPORTER=none OTEL_METRICS_EXPORTER=none OTEL_LOGS_EXPORTER=none LOG_LEVEL=warn

pocket-id-set-domain sets APP_URL, so do not edit it by hand. After you change anything else, run sudo systemctl restart pocket-id.

Email (sign-in codes by email and notifications) is off until you configure SMTP under Application Configuration > Email. MAXMIND_LICENSE_KEY adds city lookups to the audit log. It makes Pocket ID download the GeoLite database, so allow that outbound connection in your security group and network ACLs.

Pocket ID keeps users, passkeys (their public keys), clients and the audit log in the SQLite database /var/lib/pocket-id/data/pocket-id.db. Secrets inside it (the token signing key, client secrets) are encrypted with this instance's key in /etc/pocket-id/encryption.key. Only the pocket-id user can read either file:

sudo stat -c '%a %U:%G %n' /etc/pocket-id/encryption.key /etc/pocket-id/pocket-id.env /var/lib/pocket-id/data /var/lib/pocket-id/data/pocket-id.db

600 pocket-id:pocket-id /etc/pocket-id/encryption.key 640 root:pocket-id /etc/pocket-id/pocket-id.env 700 pocket-id:pocket-id /var/lib/pocket-id/data 600 pocket-id:pocket-id /var/lib/pocket-id/data/pocket-id.db

Back up the key with the database, and protect both. Without the key, the database's secrets cannot be read, and with the key they can.

To back up, stop Pocket ID briefly and copy both files. Replace <backup-dir> with a directory that only root can read:

sudo systemctl stop pocket-id
sudo install -d -m 0700 <backup-dir>
sudo cp -p /etc/pocket-id/encryption.key /var/lib/pocket-id/data/pocket-id.db <backup-dir>/
sudo systemctl start pocket-id

• Metadata service and private addresses. The AMI requires IMDSv2. systemd denies Pocket ID, nginx and the first-boot service the instance metadata addresses, and denies Pocket ID every private, link-local, shared and reserved range plus this VPC's own range. A small service reads the VPC range from the instance metadata at every boot. This fails closed. The service retries the metadata service six times over about 30 seconds. If it still cannot read this VPC's range, Pocket ID does not start and nginx answers 502. Once the metadata service answers, run sudo systemctl restart sac-pocket-id-metadata pocket-id once. A VPC inside the private ranges, as here with 172.31.0.0/16, is already covered by them. A VPC range outside them is added to the list:

systemctl show -p IPAddressDeny --value pocket-id | tr ' ' '\n' | sort -V | tr '\n' ' '; echo cat /run/sac-pocket-id/vpc-cidrs

0.0.0.0/8 10.0.0.0/8 100.64.0.0/10 168.63.129.16/32 169.254.0.0/16 172.16.0.0/12 192.0.0.0/24 192.168.0.0/16 198.18.0.0/15 224.0.0.0/4 240.0.0.0/4 ::/0
# written by pocket-id-metadata from EC2 metadata at 2026-11-08T14:10:19Z source imds 4 172.31.0.0/16

• No outbound connections. Pocket ID's analytics (ANALYTICS_DISABLED=true) and version check (VERSION_CHECK_DISABLED=true) are off. The outbound features (SCIM provisioning, back-channel logout and federated JWKS) are restricted to no hosts until you allow them. A client logo given as a URL is the only fetch Pocket ID makes by itself, and it is refused for metadata, loopback, private and VPC addresses.
• Where the key lives. Pocket ID reads its encryption key from /etc/pocket-id/encryption.key (mode 0600, pocket-id). The environment only names the file (ENCRYPTION_KEY_FILE), so the key is in no process environment, command line, journal or log. It is generated on your instance at first boot. Core dumps are off for Pocket ID and nginx, and the instance has no swap.
• The setup route. Pocket ID's initial-setup route creates the first admin on an empty database. First boot uses it before the web port opens and checks that it is closed. nginx's start-up gate refuses to start while the route is open, so the route is never reachable from the network.
• Response headers. The image sets Pocket ID's Content-Security-Policy with frame-ancestors 'none', X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: same-origin, a Permissions-Policy and Strict-Transport-Security.
• Upgrades. Ubuntu security updates, including nginx, install automatically. Pocket ID is a pinned release binary, so SecureAnyCloud publishes new versions of this AMI for new Pocket ID releases. Pocket ID 2.19.2 has no open security advisory. Earlier releases, including those some marketplace images still ship, have critical ones.

Pocket ID is licensed under the BSD 2-Clause licence. The image ships its licence and records exactly what it was built from:

cat /usr/share/doc/sac-pocket-id/SOURCE.txt pocket-id version

Pocket ID 2.19.2 (BSD-2-Clause) release asset: https://github.com/pocket-id/pocket-id/releases/download/v2.19.2/pocket-id_linux_amd64 sha256: 85881ea87d78710c34f127b2d849d27dd7e69963723d9e590f66de26e87fc4fb checksums.txt sha256: 555c06bf2d32e58f759fc0710737fa56e59b3a2a74b11e7d4eca96ea49180a85 tag v2.19.2 = commit 2b2750ed61e0016f4c15630322d15ca22143cdb6 source: https://github.com/pocket-id/pocket-id/tree/v2.19.2 pocket-id 2.19.2

SecureAnyCloud installs the official pocket-id_linux_amd64 binary from the upstream v2.19.2 release on GitHub. The binary is checked against a fixed SHA-256 and against the release's own checksum list (also pinned), and a different file stops the build.

The licence text is in /usr/share/doc/sac-pocket-id/LICENSE-pocket-id-BSD-2-Clause.txt. nginx is the Ubuntu package (/usr/share/doc/nginx/copyright).

Pocket ID is a trademark of its respective owner. All product and company names are trademarks or registered trademarks of their respective holders. SecureAnyCloud is not affiliated with or endorsed by them.