dfinity/icskills

organization-sign-in

Set up an organization's own single sign-on for Internet Identity, so staff sign in to II-powered apps against Okta, Entra ID, Google Workspace or Auth0.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/dfinity/icskills --skill organization-sign-in

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Organization Sign-In

What this is, and who does it

Internet Identity (II) authenticates an organization's staff against its own OpenID Connect provider (Okta, Entra ID, Google Workspace, Auth0). Nothing is registered with Internet Identity: it discovers the configuration from one file on the organization's domain.

This is work an organization's IT administrator does once, on the organization's own domain and identity provider. It is not app code, and no app can do it. The app side is one constructor option, new AuthClient({ ssoDomain: "acme.com" }), documented in the user-sign-in skill along with the getSsoStatus() check that tells an app whether a domain has SSO at all.

1. Register an OIDC client

In the identity provider, create an OIDC web application:

SettingValue
Redirect URIhttps://id.ai/callback
Grant typesAuthorization Code and Implicit (hybrid): II requests response_type=code id_token with response_mode=form_post
ID tokenAllowed with the implicit grant
Access tokenNot needed
Scopesopenid, profile, email

2. Publish the discovery file

Serve it over HTTPS at exactly https://<domain>/.well-known/ii-openid-configuration:

json
{
  "client_id": "0oaDEFAULT",
  "openid_configuration": "https://acme.okta.com/.well-known/openid-configuration",
  "name": "Acme Corp",
  "session_max_age_seconds": 28800,
  "app_clients": {
    "https://payroll.acme.com": "0oaPAYROLL"
  },
  "gate_all_apps": false,
  "stable_identifier_claim": "sub"
}
FieldRequiredDefaultMeaning
client_idyesThe client from step 1
openid_configurationyesThe provider's OIDC discovery URL
namenothe domainLabel on the sign-in screen, and available.name from getSsoStatus()
session_max_age_secondsno28800 (8 hours)How long a sign-in through this domain stays valid; also caps an app's own session length
app_clientsnononeMaps an app's exact origin, or a salted hash of it, to that app's own client
gate_all_appsnofalsetrue refuses apps not listed in app_clients
stable_identifier_claimnosubA claim that is the same for one person across all the organization's clients (Entra ID: oid, since its sub differs per client)

No CORS header is required: Internet Identity fetches the file server-side, and @icp-sdk/auth 11.x checks a domain through II (getSsoStatus()), not from the browser. isValidSsoDomain() in 10.x and earlier fetched the file cross-origin, so keep Access-Control-Allow-Origin: * on it while any app on an older major still signs in through this domain.

The domain users enter is a bare domain such as acme.com, not https://acme.com, acme.com/, or a path.

Per-app access

Give an app its own OIDC client, assign the allowed groups or users to that client in the provider (on Entra ID also set "Assignment required" to Yes), and add one app_clients line keyed by the app's exact origin. A trailing slash, a path, or a different scheme does not match, and the app then silently falls back to the organization's client.

To list an app without naming it in the public file, key it by a salted hash: sha256(origin || salt) as hex, then :, then the salt as hex:

bash
origin=https://payroll.acme.com
salt=$(openssl rand -hex 8)
hash=$(printf %s "$origin$salt" | openssl dgst -sha256 -r | cut -d' ' -f1)
echo "$hash:$salt"

Cleartext and hashed keys can be mixed in one file. Changing stable_identifier_claim on a live domain changes how identities key onto anchors: treat it as a migration, not a config tweak.

Limits: one bad value rejects the whole file

Internet Identity rejects the entire file, not just the offending field, when any of these is exceeded. SSO is then unavailable for the whole domain (getSsoStatus() reads unavailable):

  • the file larger than 64 KiB (the same limit applies to the provider's OIDC discovery document);
  • more than 100 app_clients entries;
  • an app_clients key or client id longer than 255 bytes;
  • app_clients keys and client ids together longer than 16 KiB;
  • client_id, name, or stable_identifier_claim longer than 255 bytes;
  • session_max_age_seconds of 0 or above 2592000 (30 days); it is rejected, not clamped;
  • in the OIDC discovery document: issuer, jwks_uri, or authorization_endpoint longer than 255 bytes.

When changes take effect

Internet Identity caches each domain's discovery result:

  • fresh for 1 hour; after that, the next sign-in through the domain starts a refresh and is served the cached result while it runs;
  • kept for 7 days past freshness, so a domain signed in through within the week starts from the cache;
  • a refresh that fails stops serving the old result 1 hour past freshness, then backs off (60 s, doubling) before retrying.

So removing an app_clients entry or enabling gate_all_apps applies after the next refresh, normally within an hour of active use; the first sign-in after a quiet period is checked against the cached result while the refresh runs. The provider's signing keys (JWKS) are cached separately for at most 1 hour past freshness, so key rotation is picked up within that window.

What an organization cannot assert

No `verified_email` under `sso:`. An organization's SSO cannot produce a verified email. Its sso:<domain>:email is asserted by the organization's own provider, so an app trusts it only for domains it lists.

from this repository

More skills

All skills
dfinity
Community

autoupgrade-icp-cli

One-time installer that keeps a project's Internet Computer CLI toolchain current. Sets up a SessionStart hook plus a script that compares the installed icp and ic-wasm against the latest release and either reports the upgrade or applies it, using whichever channel each tool was installed from (npm, Homebrew, or the shell installer). Use when a user wants to install, bootstrap, or enable automatic icp-cli / ic-wasm updates, asks to stop running an outdated icp, asks how to upgrade or check the v

1h installs
1
GitHub stars
39
Updated
Nov 11
dfinity
Community

buy-cycles

Buy cycles with a credit card for the CLI's own identity with icp cycles buy, through CyclePay's on-chain gateway, then continue deploying. Use when a mainnet deploy or canister creation fails for lack of cycles, the user has no ICP, no wallet or no exchange account, or asks to pay for cycles by card, Stripe, fiat or USD. Do NOT use for converting ICP you already hold (cycles-management: icp cycles mint), for topping up a canister from an existing balance, or for Internet Identity sign-in (agent

1h installs
1
GitHub stars
39
Updated
Nov 11
dfinity
Community

canhelp

Display a human-readable summary of a canister's interface given its mainnet canister ID or a human-readable name. Like --help but for canisters. Only for mainnet canisters — for local canisters, read the generated .did file in your project directly.

1h installs
1
GitHub stars
39
Updated
Nov 11
dfinity
Community

canister-security

IC-specific security patterns for canister development in Motoko and Rust. Covers access control, anonymous principal rejection, reentrancy prevention (CallerGuard pattern), async safety (saga pattern), callback trap handling, cycle drain protection, and safe upgrade patterns. Use when writing or modifying any canister that modifies state, handles tokens, makes inter-canister calls, or implements access control.

1h installs
1
GitHub stars
39
Updated
Nov 11