External auth

Public routes that let an external service sign users in with their rCTF account.

These routes power the “Sign in with rCTF” flow for external services. The user-facing consent page lives at /external-auth/authorize; the API routes here are what that page (and the external service’s backend) call.

The admin-side routes for registering and revoking external-auth clients are documented in Admin. The operator walkthrough lives at External apps.

Warning (Not OAuth2)

The wire-level field names (client_id, redirect_uri, code, state) match what integrators expect, but the flow is not OAuth2. There are no scopes, refresh tokens, PKCE, id_token/OIDC discovery, token introspection, or revocation. The access token returned by /token is a regular rCTF auth token - identical to one minted on login - and grants full account access to the signing-in user.

Flow#

The external service sends the user to /external-auth/authorize?client_id=...&redirect_uri=...&state=....
The consent page calls GET /api/v2/external-auth/clients/:id to render the client name and verify the redirect URI.
The user logs into rCTF if needed, then approves. The page calls POST /api/v2/external-auth/authorize with the user’s session token and receives a redirectTo URL.
The browser navigates to redirect_uri?code=...&state=....
The external service’s backend exchanges the code through POST /api/v2/external-auth/token and receives {accessToken, tokenType: "bearer"}.
The service uses the access token in Authorization: Bearer ... against any rCTF endpoint - typically GET /api/v1/users/me to identify the team.

Failure model#

Every failure mode (unknown client, wrong secret, mismatched redirect URI, missing/expired/reused code, mismatched client on a code) returns the same 400 badExternalAuthRequest body. The endpoint deliberately doesn’t distinguish causes so callers can’t probe it. The only authenticated route in the section is POST /api/v2/external-auth/authorize, which additionally returns 401 badToken when the user session token is missing or invalid.

Code lifetime#

Authorization codes live in Redis for 60 seconds and are single-use - the first POST /api/v2/external-auth/token call atomically deletes the code, so a second exchange always fails. There is no per-app token registry: deleting a client through the admin routes blocks future token exchanges but does not revoke access tokens that were already issued.

`GET` Get client metadata

GET /api/v2/external-auth/clients/:id

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/external-auth/clients/11111111-2222-3333-4444-555555555555"

{
  "kind": "goodExternalAuthClient",
  "message": "External-auth client lookup succeeded.",
  "data": {
    "id": "<id>",
    "name": "<name>",
    "redirectUri": "<redirect-uri>"
  }
}

{
  "kind": "badExternalAuthRequest",
  "message": "External-auth request rejected."
}

Auth: Public
Gate: None
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

Public lookup for the consent page. The page calls this route with the client_id from the query string to render the app name and verify the redirect URI before showing the consent prompt. The endpoint never returns the client secret.

Unknown ids return 400 badExternalAuthRequest - the same response used for every other failure mode in the External auth flow.

Path parameters

id
*
 required

string

Public client id.

Response fields

idstring

Unique identifier.

namestring

Display name.

redirectUristring

Returned redirect uri value.

`POST` Authorize

POST /api/v2/external-auth/authorize

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/external-auth/authorize" \
  -H "Authorization: Bearer <auth-token>" \
  --json '{
    "clientId": "11111111-2222-3333-4444-555555555555",
    "redirectUri": "https://my-service.example.com/auth/rctf/callback",
    "state": "opaque-csrf-token"
  }'

{
  "kind": "goodExternalAuthAuthorize",
  "message": "Authorization issued. Redirect to the returned URL.",
  "data": {
    "redirectTo": "<redirect-to>"
  }
}

{
  "kind": "badExternalAuthRequest",
  "message": "External-auth request rejected."
}

{
  "kind": "badToken",
  "message": "The token provided is invalid."
}

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

Auth: Required
Gate: None
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

Mints a single-use authorization code for the signed-in user and returns the URL the browser should navigate to next. The consent page calls this when the user clicks Authorize.

The redirectUri must match what the client was registered with byte-for-byte (no wildcards, no path normalization). Any mismatch returns 400 badExternalAuthRequest - the response intentionally doesn’t distinguish “unknown client” from “wrong redirect URI” so the endpoint can’t be probed.

Request body

clientId
*
 required

string

Request body field for client id.

redirectUri
*
 required

string

Request body field for redirect uri.

statestring

Request body field for state.

Response fields

redirectTostring

Returned redirect to value.

The returned redirectTo is the registered redirectUri with code=... (and, when provided, state=...) appended using a ? or & separator as needed. The code lives in Redis for 60 seconds and is consumed by the first POST /api/v2/external-auth/token call - a second exchange always fails.

The state value is opaque to rCTF and is passed through verbatim. It is the integrator’s responsibility to use it for CSRF protection.

`POST` Exchange code for token

POST /api/v2/external-auth/token

$curl -sS "https://rctf-new-dev.es3n1n.io/api/v2/external-auth/token" \
  --json '{
    "clientId": "11111111-2222-3333-4444-555555555555",
    "clientSecret": "<32-byte base64url secret>",
    "code": "<single-use code from /authorize>"
  }'

{
  "kind": "goodExternalAuthToken",
  "message": "Access token issued.",
  "data": {
    "accessToken": "<access-token>",
    "tokenType": "bearer"
  }
}

{
  "kind": "badExternalAuthRequest",
  "message": "External-auth request rejected."
}

{
  "kind": "badJson",
  "message": "The request JSON body is malformed."
}

{
  "kind": "badBody",
  "message": "The request body does not meet requirements.",
  "data": {
    "reason": "<reason>"
  }
}

Auth: Public
Gate: None
Permissions: No extra permissions
Captcha: No captcha
Rate limit: No rate limit

Server-to-server exchange. The external service’s backend trades the single-use code from the browser redirect for a regular rCTF auth token. Call this from a trusted environment - the client secret must not be exposed to the browser.

The code is consumed atomically: the first call deletes it from Redis, so a replay or any concurrent second exchange always fails.

Note (Failures all look identical)

Unknown client, wrong secret, wrong code, expired code, reused code, and code/client mismatch all return the same 400 badExternalAuthRequest body. Don’t rely on the failure reason to debug an integration - check timestamps, secret rotation, and the exact bytes you sent instead.

Request body

clientId
*
 required

string

Request body field for client id.

clientSecret
*
 required

string

Request body field for client secret.

code
*
 required

string

Request body field for code.

Response fields

accessTokenstring

Returned access token value.

tokenType"bearer"

Returned token type value.

The returned accessToken is a regular rCTF auth token with no expiry - the same kind of token issued at login. Use it in Authorization: Bearer <accessToken> against any rCTF endpoint. There is no per-app token registry: deleting the client through the admin routes prevents future code exchanges but does not revoke tokens that were already minted.