Skip to content

OIDC Integration

Jump to bottom
Teo Elmfeldt edited this page Oct 24, 2026 · 2 revisions

OIDC Integration

ScoutID supports OpenID Connect (OIDC) and is the recommended protocol for new integrations. This page covers the endpoints, client types, and flows you need to integrate.

Before you start, make sure you have requested a client and received your client ID (and secret, for confidential clients).

Discovery

ScoutID publishes a standard OIDC discovery document at:

Environment Base URL
Development https://dev1.id.scouterna.se/realms/scoutid/.well-known/openid-configuration
Production https://id.scouterna.se/realms/scoutid/.well-known/openid-configuration

Most OIDC libraries can auto-configure from this URL.

Endpoints

Endpoint URL
Authorization https://id.scouterna.se/realms/scoutid/protocol/openid-connect/auth
Token https://id.scouterna.se/realms/scoutid/protocol/openid-connect/token
UserInfo https://id.scouterna.se/realms/scoutid/protocol/openid-connect/userinfo
End session https://id.scouterna.se/realms/scoutid/protocol/openid-connect/logout

Client types

Confidential clients (server-side applications)

Use this for applications where the client secret can be kept private — typically server-rendered apps or APIs with a backend.

  • Flow: Authorization code
  • Authentication: Client ID + client secret
  • When you request a client, specify your redirect URI(s). You will receive a client ID and secret.

Authorization request:

GET https://id.scouterna.se/realms/scoutid/protocol/openid-connect/auth
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.example.com/callback
  &response_type=code
  &scope=openid profile email
  &state=RANDOM_STATE_VALUE

Token exchange:

POST https://id.scouterna.se/realms/scoutid/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://yourapp.example.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Public clients (SPAs and mobile apps)

Use this for applications where there is no backend to keep a secret — single-page apps, mobile apps, or desktop clients.

  • Flow: Authorization code with PKCE
  • Authentication: Client ID only (no secret); PKCE is required
  • When you request a client, specify that it is a public client and provide your redirect URI(s).

Generate a PKCE pair before the authorization request:

  1. Generate a random code_verifier (43–128 characters, URL-safe)
  2. Compute code_challenge = BASE64URL(SHA256(code_verifier))

Authorization request:

GET https://id.scouterna.se/realms/scoutid/protocol/openid-connect/auth
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.example.com/callback
  &response_type=code
  &scope=openid profile email
  &state=RANDOM_STATE_VALUE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

Token exchange:

POST https://id.scouterna.se/realms/scoutid/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://yourapp.example.com/callback
&client_id=YOUR_CLIENT_ID
&code_verifier=CODE_VERIFIER

Scopes

Request scopes in the scope parameter of the authorization request. openid is always required.

Scope What it includes
openid sub, preferred_username
profile Name, birthdate, avatar, member number
email Email addresses
phone Phone number
scoutnet-memberships Group memberships, roles, organisational data

See ScoutID Data Reference for the full list of claims per scope.

Sessions and token lifetimes

ScoutID login sessions last 30 days. Access tokens have a shorter lifetime configured per client — the default is suitable for most use cases, but you can request a different value when registering your client.

Keep in mind that membership data (roles, groups) in a token reflects what Scoutnet returned at the time of login. If your application makes authorisation decisions based on roles, consider how stale that data could be given your token lifetime. See Advanced Topics for more on this tradeoff.

Local development and testing

The development environment at dev1.id.scouterna.se is available for testing against a real ScoutID instance. If you want to run a fully local setup instead, the scoutid-keycloak-provider repository includes a Docker Compose setup with pre-configured provider settings.

Clone this wiki locally