OIDC Quickstart

This guide walks you through adding BlokSec as an OpenID Connect identity provider to your web application.

Prerequisites

• Admin access to the BlokSec admin console
• A web application that supports OIDC (most frameworks have an OIDC client library)

Step 1: Create an OIDC application in BlokSec

1. In the admin console, go to Applications > Add Application
2. Enter a name for your application
3. Select OIDC as the application type
4. Add your application’s redirect URI (e.g., https://yourapp.com/callback)
5. Optionally add a post-logout redirect URI
6. Click Create

After creation, note the Client ID shown on the application detail page. You’ll need this in the next step.

If your application is a confidential client (server-side), click Generate Secret to create a client secret. Copy it immediately — it’s only shown once.

Screenshot pending

/screenshots/developer/oidc-quickstart/create-app.png

OIDC application creation form in the admin console

Creating an OIDC application

Step 2: Configure your application

Use BlokSec’s OIDC discovery document to automatically configure your client:

https://api.bloksec.io/oidc/.well-known/openid-configuration

The discovery document provides all the endpoint URLs your application needs. The key endpoints are:

Endpoint	URL
Authorization	https://api.bloksec.io/oidc/auth
Token	https://api.bloksec.io/oidc/token
UserInfo	https://api.bloksec.io/oidc/userinfo
JWKS	https://api.bloksec.io/oidc/jwks
End Session	https://api.bloksec.io/oidc/end_session

Note

Most OIDC client libraries accept a discovery URL and configure themselves automatically. You usually don’t need to set each endpoint manually.

Step 3: Initiate the auth flow

Redirect the user to the authorization endpoint with these parameters:

https://api.bloksec.io/oidc/auth?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=openid email profile
  &state=RANDOM_STATE_VALUE
  &nonce=RANDOM_NONCE_VALUE

Required parameters:

Parameter	Description
client_id	Your application’s Client ID from the admin console
redirect_uri	Must match one of the redirect URIs you configured
response_type	Use code for the authorization code flow
scope	Space-separated list of scopes (see available scopes below)

Recommended parameters:

Parameter	Description
state	A random value your app generates to prevent CSRF attacks. Verify it matches when the user returns.
nonce	A random value included in the ID token. Verify it matches after token exchange.

For public clients (SPAs), you must also include PKCE parameters:

Parameter	Description
code_challenge	SHA-256 hash of a random code_verifier, Base64URL-encoded
code_challenge_method	Must be S256

The user will see the BlokSec login screen and authenticate using their phone.

Step 4: Exchange the code for tokens

After the user authenticates, BlokSec redirects back to your redirect_uri with an authorization code:

https://yourapp.com/callback?code=AUTH_CODE&state=YOUR_STATE_VALUE

Exchange the code for tokens by making a POST request to the token endpoint:

curl -X POST https://api.bloksec.io/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

For public clients using PKCE, omit the client_secret and include the code_verifier instead.

The response contains:

{
  "access_token": "eyJhbGci...",
  "id_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "..."
}

Step 5: Validate the ID token

The id_token is a JWT containing the user’s identity claims. Before trusting it:

1. Verify the signature using BlokSec’s JWKS endpoint (https://api.bloksec.io/oidc/jwks)
2. Check the iss claim matches https://api.bloksec.io
3. Check the aud claim matches your Client ID
4. Check the exp claim to ensure the token hasn’t expired
5. Check the nonce claim matches the nonce you sent in step 3

Most OIDC client libraries handle these checks automatically.

The ID token includes claims based on the scopes you requested:

Scope	Claims included
openid	sub (subject identifier), aud, amr
email	email, email_verified
profile	given_name, family_name, name, picture, preferred_username
phone	phone_number, phone_number_verified

What’s next

• OIDC Reference — complete endpoint documentation, all scopes and claims, token lifetimes
• Authentication Flow — understand how BlokSec’s passwordless authentication works under the hood