Log in with Pocket ID

Before you start

• Pocket ID, reachable with HTTPS. The server accepts http only for localhost.
• The public URL of ShellGraph, for example https://shellgraph.example.net.

Make the groups

1. In Pocket ID, open Administration, then User Groups.
2. Make the group shellgraph-admins, and add the users that change data.
3. Make the group shellgraph-viewers, and add the users that only read.

Add the client

1. Open OIDC Clients and add a client.
2. Type the name ShellGraph.
3. Type the callback URL: https://shellgraph.example.net/api/auth/oidc/callback.
4. Set PKCE to on.
5. Optional: allow only the two groups.
6. Save, and copy the client ID and the client secret.

Configure the server

1. Set the variables of the server.

   SHELLGRAPH_ADMIN_GROUP=shellgraph-admins
   SHELLGRAPH_VIEWER_GROUP=shellgraph-viewers
   SHELLGRAPH_PUBLIC_URL=https://shellgraph.example.net
   SHELLGRAPH_OIDC_ISSUER=https://id.example.net
   SHELLGRAPH_OIDC_CLIENT_ID=<client ID>
   SHELLGRAPH_OIDC_CLIENT_SECRET=<client secret>
   SHELLGRAPH_OIDC_BUTTON="Log in with Pocket ID"
   

2. Restart the server.

Pocket ID puts the group names in the groups claim when the client asks for the scope groups. The default scopes ask for it.

Use a different identity provider

The same steps work with other OIDC providers. Make sure that:

• The provider sends the group names in a claim of the ID token or of the userinfo response. If the claim does not have the name groups, set SHELLGRAPH_OIDC_GROUPS_CLAIM.
• The provider signs the ID token with RS256, RS384, RS512, ES256, ES384 or EdDSA.

Test the login

1. Open the server UI.
2. Select Log in with Pocket ID.
3. Log in to Pocket ID. Pocket ID sends you back to ShellGraph.

If the login fails, see Login messages.