rloisell BC Gov IAM Agent
Implements authentication and authorisation for BC Government applications using DIAM (Digital Identity and Access Management) or Common SSO Keycloak.
Related skills:
- Security controls →
../security-architect/SKILL.md - Vault for storing OIDC client secrets →
../vault-secrets/SKILL.md
Identity Provider Reference
| Provider | Base URL | Realm | Use When |
|---|---|---|---|
| Common SSO (IDIR + BCeID) | https://loginproxy.gov.bc.ca |
standard |
Internal staff / business users |
| DIAM | https://diam-dev.gov.bc.ca / diam.gov.bc.ca |
Project-specific | Ministry-specific brokered identity |
| IDIR (direct) | https://loginproxy.gov.bc.ca |
idir |
IDIR only, no BCeID needed |
| BCeID (direct) | https://loginproxy.gov.bc.ca |
bceidbasic / bceidbusiness |
BCeID only |
DIAM brokers to Common SSO as a federation layer. Most new projects use Common SSO standard
unless there is a specific requirement for DIAM's additional brokering or custom attribute mapping.
OIDC Discovery URL
https://loginproxy.gov.bc.ca/auth/realms/standard/.well-known/openid-configuration
PKCE Flow Summary
Browser React App Keycloak
| | |
|── click Login ──> | |
| generate code_verifier |
| hash → code_challenge |
| |── GET /auth? |
| | client_id |
| | code_challenge ──> |
| | redirect_uri + auth_code
| |<── auth_code ─────────|
| |── POST /token |
| | code + code_verifier|
| |──────────────────────>|
| |<── access_token |
| | refresh_token ─────|
No client_secret required for public clients (SPA). The code_verifier/code_challenge pair
replaces the implicit flow's reliance on a trusted origin.
React Setup (oidc-client-ts)
Install
npm install oidc-client-ts react-oidc-context
Auth config
// src/auth/authConfig.js — OIDC UserManager config
// Author: Ryan Loiselle | Date: <date>
export const oidcConfig = {
authority: import.meta.env.VITE_OIDC_AUTHORITY,
// e.g. https://loginproxy.gov.bc.ca/auth/realms/standard
client_id: import.meta.env.VITE_OIDC_CLIENT_ID,
redirect_uri: `${window.location.origin}/callback`,
post_logout_redirect_uri: `${window.location.origin}/`,
response_type: 'code',
scope: 'openid profile email',
automaticSilentRenew: true,
silent_redirect_uri: `${window.location.origin}/silent-callback.html`,
monitorSession: true,
filterProtocolClaims: true,
loadUserInfo: true,
};
Provider wrapping
// src/main.jsx
import { AuthProvider } from 'react-oidc-context';
import { oidcConfig } from './auth/authConfig';
root.render(
<AuthProvider {...oidcConfig}>
<App />
</AuthProvider>
);
Callback page
// src/pages/Callback.jsx — redirect landing page
import { useAuth } from 'react-oidc-context';
import { useNavigate } from 'react-router-dom';
import { useEffect } from 'react';
export default function Callback() {
const auth = useAuth();
const navigate = useNavigate();
useEffect(() => {
if (!auth.isLoading && !auth.error) navigate('/');
}, [auth.isLoading, auth.error]);
if (auth.error) return <div>Login error: {auth.error.message}</div>;
return <div>Logging in…</div>;
}
Silent renew page
Create /public/silent-callback.html:
<!doctype html>
<html><body>
<script src="/oidc-client-ts/dist/browser/oidc-client-ts.min.js"></script>
<script>new oidc.UserManager().signinSilentCallback();</script>
</body></html>
Using the token in API calls
// src/api/apiClient.js — axios interceptor using shared UserManager instance
import { UserManager } from 'oidc-client-ts';
import { oidcConfig } from '../auth/authConfig';
import axios from 'axios';
// Share the same UserManager instance used by AuthProvider
export const userManager = new UserManager(oidcConfig);
const apiClient = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL });
apiClient.interceptors.request.use(async (config) => {
const user = await userManager.getUser();
if (user?.access_token) {
config.headers.Authorization = `Bearer ${user.access_token}`;
}
return config;
});
export default apiClient;
Alternatively, if you are inside a React component or hook, read the token directly from
auth.user?.access_token(viauseAuth()fromreact-oidc-context) rather than creating a secondUserManagerinstance.
.NET API — JWT Validation
Package
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
Program.cs
// OIDC JWT bearer authentication — validates tokens from Keycloak
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer(options =>
{
options.Authority = builder.Configuration["Oidc:Authority"];
// e.g. https://loginproxy.gov.bc.ca/auth/realms/standard
options.Audience = builder.Configuration["Oidc:ClientId"];
options.RequireHttpsMetadata = !builder.Environment.IsDevelopment();
options.TokenValidationParameters = new TokenValidationParameters
{
ValidateIssuer = true,
ValidateAudience = true,
ValidateLifetime = true,
ClockSkew = TimeSpan.FromSeconds(60),
};
});
builder.Services.AddAuthorization();
// ...
app.UseAuthentication();
app.UseAuthorization();
Extracting claims
// returns the sub claim (Keycloak user ID)
private static Guid? GetUserId(ClaimsPrincipal user)
=> Guid.TryParse(user.FindFirstValue(ClaimTypes.NameIdentifier), out var id)
? id : null;
Keycloak Client Registration
Public client (React SPA)
| Setting | Value |
|---|---|
| Access type | public |
| Standard flow | ON |
| Implicit flow | OFF |
| Valid redirect URIs | https://<app>-<license>-dev.apps.emerald.devops.gov.bc.ca/callback |
| Post logout redirect URIs | https://<app>-<license>-dev.apps.emerald.devops.gov.bc.ca/ |
| Web origins | same as redirect (no + wildcard in prod) |
| PKCE method | S256 |
Confidential client (API-to-API)
| Setting | Value |
|---|---|
| Access type | confidential |
| Service accounts | ON |
client_secret |
Store in Vault at secret/<license>/<env>/oidc-client-secret |
Backchannel Logout (.NET API)
// POST /logout/backchannel — handles Keycloak backchannel logout token
[HttpPost("/logout/backchannel")]
[AllowAnonymous]
[Consumes("application/x-www-form-urlencoded")]
public async Task<IActionResult> BackchannelLogout([FromForm] string logout_token)
{
// 1. Validate logout_token JWT: issuer, audience, iat, jti
// 2. Extract 'sub' or 'sid' claim
var sub = User.FindFirstValue(ClaimTypes.NameIdentifier) ?? "(unknown)";
// 3. Invalidate any server-side session or cached token for that sub/sid
// 4. Return 200 OK or 400 Bad Request
_logger.LogInformation("Backchannel logout received for sub={Sub}", sub);
return Ok();
}
IAM_KNOWLEDGE
confirmed_facts:
- "Common SSO 'standard' realm brokers IDIR, BCeID Basic, and BCeID Business"
- "PKCE with S256 is mandatory for public clients — implicit flow is disabled on Common SSO"
- "automaticSilentRenew uses a hidden iframe; may fail in Safari with ITP — use refresh_token_grant as fallback"
- "Keycloak sub claim = user's UUID in the realm — use as the canonical user identifier"
- "DIAM adds a JAG-specific brokering layer on top of Common SSO for JAG ministry projects"
- "Vault path for OIDC client secret: secret/<license>/<env>/oidc-client-secret"
common_pitfalls:
- "do NOT store access_token in localStorage — use oidc-client-ts in-memory store"
- "ClockSkew must be set to at least 30s to tolerate server timing differences with Keycloak"
- "Post logout redirect URI must be registered in Keycloak or the logout will fail silently"
- "Bearer token audience validation: Keycloak issues 'account' audience by default — configure 'Add Audience' mapper"