Skip to main content
An app behind your own sign-in, such as a browser softphone, shouldn’t need a SIP password as well. With Bearer tokens, your sign-in service issues the app a short-lived token for the user. The app sends the token in its REGISTER, pgw checks it, and pgw registers at the PBX with the user’s stored password. This works only on a managed mode upstream, because pgw must hold the password that the app doesn’t have.

Before you begin

  • A managed upstream with its users. See Set up managed mode.
  • A sign-in service that can sign JSON Web Tokens with an ES256 key and publish its public keys at an HTTPS URL.

Turn on Bearer tokens

1

Turn on Bearer tokens for the managed upstream

Set --app-auth to both to accept a token or the user’s password, or to bearer to accept only a token.
2

Issue tokens that pgw accepts

3

Send the token from the app

In each REGISTER, send Authorization: Bearer <token>. pgw checks the token only when the app registers. pgw then renews at the PBX without the token, so a token lifetime of a few minutes is enough.

Check that it works

Register the app with a token, then run pgw binding list. The list shows a binding for the user in the token’s sub.

If it doesn’t work

The first two count toward the REGISTER ban.

Sign a user out

Because pgw checks a token only when the app registers, an expired token doesn’t sign anyone out. pgw keeps the registration at the PBX alive without it. When a user signs out of your service, tell pgw:
Your sign-in service can do the same with POST /api/v1/upstreams/{id}/revocations.

How pgw handles signing keys

pgw fetches the key set over HTTPS and refreshes it every hour. When a token is signed with a key that pgw doesn’t know, pgw fetches the set again, at most once a minute, so a new signing key works as soon as you publish it. pgw never logs a token.

Next steps

Web apps

Connect a browser softphone, the usual client for token sign-in.

Managed mode

Review how pgw keeps registrations alive without the app.