Connecting a client¶
Handover works like VATSIM Connect. A service that supports VATSIM Connect can use Handover by changing the URLs, the client ID and the secret. A service that supports OpenID Connect can use Handover's discovery, ID token and UserInfo endpoint instead. See OpenID Connect.
OAuth credentials¶
First create an OAuth client in Handover. Then configure the service with:
| Setting | Value |
|---|---|
| Method | Authorization code |
| Client ID | The ID of the client: a number for older clients, a UUID for new ones |
| Client secret | The secret shown when you created the client. A public client has none. |
| Authorization endpoint | https://YOUR_HANDOVER/oauth/authorize |
| Token endpoint | https://YOUR_HANDOVER/oauth/token |
| User information endpoint | https://YOUR_HANDOVER/api/user |
| JSON Web Key Set (JWKS) | https://YOUR_HANDOVER/.well-known/jwks.json |
The callback URL of the service must exactly match one of the client's redirect URIs in Handover.
Scopes¶
Request the scopes the service needs, separated by spaces.
The service may request only the scopes its client allows.
A request for any other scope fails with the invalid_scope error.
A refresh fails the same way if an administrator removes a scope that the token holds.
For details, see allowed scopes.
| Scope | Gives access to |
|---|---|
full_name |
First and last name |
email |
E-mail address |
vatsim_details |
Ratings, region, division and subdivision |
country |
Country |
groups |
The groups the member belongs to |
openid |
Sign in with OpenID Connect. The user API ignores it. |
profile |
First and last name, as OpenID Connect claims. The user API ignores it. |
If the service requests no scopes, Handover grants full_name, email, vatsim_details and country, limited to the scopes the client allows.
It never grants groups, openid or profile by default.
See the user API for the data each scope returns.
Tokens¶
- An access token expires after one hour. To get a new access token, use the refresh token.
- A refresh token expires after 30 days. Each refresh returns a new refresh token that is valid for another 30 days. Store the new refresh token, because the old one stops working.
- By default, each member can have one session per client. When a member signs in again, Handover revokes their earlier access and refresh tokens for that client. An administrator can turn this off per client. See single session.
- If the client has required groups, a refresh fails with the
invalid_granterror once the member has left them. Send the member through the sign-in again. - Handover deletes revoked and expired tokens daily. For details, see background jobs.
- Handover may replace its signing key without warning if the key leaks. Access tokens signed by that key then fail. Use the refresh token to get a new access token. See signing keys.
Verifying access tokens¶
Most services send the access token to Handover and never read it. If the service checks access tokens itself:
- An access token is a JWT signed with RS256. Its
kidheader names the signing key. - Pick the key by
kidfrom the JWKS. When you see an unknownkid, fetch the JWKS again. - Cache the JWKS for at most one hour.
- If the token holds the
groupsscope, it carries agroupsclaim with the IDs of the member's groups. See groups.
Control Center¶
Control Center supports Handover out of the box. See Control Center's documentation for its settings.