Skip to main content

OAuth setup

The contributor portal's proposals panel needs an authenticated GitLab session to read issue comments and project members. Once an admin registers this static site as a GitLab OAuth application (Authorization Code + PKCE, no client secret), the Sign in with GitLab button on /contribute/view works in one click for any user who is already logged in to GitLab.

Register the application​

  1. Sign in to https://opensource.unicc.org as an admin (or a user with permission to create user-level applications).
  2. Go to User Settings → Applications at /-/user_settings/applications, or site-wide admin Applications at /admin/applications.
  3. Create a new application with:
    • Name: UN/LOCODE contributor portal (or similar)
    • Redirect URI — register every origin the site is served from, one per line:
      • http://localhost:3000/contribute/auth (local dev)
      • https://vocab-locode-40898c.opensource.unicc.org/contribute/auth (current preview origin)
      • your production origin + /contribute/auth once the custom domain is live
    • Confidential: unchecked (it is a public client; PKCE replaces the client secret)
    • Scopes: api
  4. Save. GitLab gives you an Application ID (the OAuth client_id).

The api scope (rather than read_api) is required because the portal now lets the chair Approve/Reject DMRs and lets anyone signed in vote 👍/👎 and post amendment comments directly. If you only need read-only browsing (no writes from the portal), read_api is still sufficient and the write buttons will fail with a clear error message until the scope is broadened.

Paste the client_id​

Open website/static/data/oauth-config.json and set the value:

{
  "clientId": "PASTE_THE_APPLICATION_ID_HERE",
  "gitlabHost": "https://opensource.unicc.org",
  "scope": "api"
}

Commit + deploy. The Sign in with GitLab button on /contribute/view is now active.

What happens at runtime​

  1. User clicks Sign in with GitLab on /contribute/view.
  2. Browser redirects to …/oauth/authorize?client_id=…&code_challenge=…&scope=api.
  3. Because the user is already signed in to GitLab, GitLab shows a one-time "Authorize?" page (or skips it on subsequent sign-ins).
  4. GitLab redirects back to /contribute/auth?code=…&state=….
  5. The callback page POSTs to /oauth/token with the PKCE code verifier, receives a short-lived access token, and stores it in localStorage.
  6. Subsequent GitLab API calls send Authorization: Bearer <access_token>. The token's api scope covers reads (issues, notes, members, reactions) and writes (Approve / Reject, vote 👍/👎, post amendment comment).

Upgrading an existing read_api app to api​

If the OAuth app was originally registered with read_api scope:

  1. Open the app in GitLab (User Settings → Applications), change the scope to api, save.
  2. Update scope in website/static/data/oauth-config.json to "api".
  3. In the portal: sign out from the GitLabAuth banner and sign back in. The next token will carry the broader scope, and the write buttons (chair Approve / Reject, vote 👍/👎, Post amendment) will start working.

Trouble-shooting​

  • "OAuth is not configured" in the banner — clientId is empty; finish step 2.
  • "State mismatch — possible CSRF" — the sign-in tab is not the same browser that started the flow (e.g. you copied the redirect URL). Click Sign in with GitLab again.
  • Token exchange 401 — the redirect URI used at runtime is not registered on the OAuth app. The application's redirect URIs must include the exact origin + /contribute/auth.

Why not just use my existing GitLab session?​

Because this static site lives at a different origin from opensource.unicc.org, the browser will not send GitLab's session cookie on cross-origin fetch() calls — that is a hard browser rule. OAuth is the standard way to bridge that, and it is effectively one-click because you are already authenticated at GitLab.