Skip to main content
An OIDC application lets people sign in to a service that supports OpenID Connect, with Iru acting as the identity provider. Iru issues the service a client ID and client secret, sends an ID token after sign-on, and maps your users’ profile attributes into that token’s claims. This page covers configuring a custom OIDC app or one you have ejected from a template. You edit configuration in a draft and then set it as the current version - see Applications overview for the version model.

​
Step 1 - Save the client credentials

When you create an OIDC app, Iru generates a client ID and client secret. The secret is shown only once, so copy both into a secure place before closing the dialog.
The client secret is not displayed again after creation. If you lose it, rotate the secret to generate a new one.
The app’s Protocol details also list the endpoints the service needs to talk to Iru:
DetailWhat it is
Client IDThe app’s public identifier.
Well-Known URLThe OpenID discovery document; many services configure everything from this one URL.
Token EndpointWhere the service exchanges an authorization code for tokens.
User Info EndpointWhere the service reads profile claims for the signed-in person.

​
Step 2 - Set redirect URIs

In the app’s draft, under the OIDC settings, add the URIs Iru is allowed to redirect to:
1

Allowed sign-in redirect URIs

Where Iru returns the person after a successful sign-on. Add every URL the service uses.
2

Allowed sign-out redirect URIs

Where Iru returns the person after sign-out.
Redirect URIs must match exactly. There is an option to allow wildcards in redirect URIs - leave it off unless the service specifically requires it, since exact matching is safer.

​
Step 3 - Choose scopes

Scopes control which categories of claims the service may request. Iru offers the standard OpenID Connect scopes:
ScopeGrants access to
OpenID (openid)Required for OpenID Connect; always included.
Profile (profile)Basic profile claims.
Email (email)The person’s email.
Address (address)The person’s address.
Phone (phone)The person’s phone number.
Offline access (offline_access)A refresh token, so the service can stay signed in without re-prompting.
openid is always present and cannot be removed. Enable only the additional scopes the service genuinely needs.

​
Step 4 - Map the subject and claims

Open the application’s mapping. The mapping has a Subject plus any additional claims.

​
Subject

The subject is the primary identifier for the signed-in person, sent as the sub claim. For an OIDC app, the default subject is mapped from the user’s user.id. You can change the value it draws from and associate it with a scope.

​
Claims

Add any extra claims the service expects in the ID token. For each one you set:
  • A Name - the claim name.
  • A value - the profile attribute or expression it draws from.
  • A scope - the scope the claim belongs to.
  • Whether it is enabled.
A live preview shows the token that will be produced, so you can confirm the claims before publishing.
Some claim names are reserved by the OpenID Connect standard and cannot be used as custom claims: iss, aud, exp, nbf, iat, and jti.

​
Step 5 - Rotate the client secret

The client secret can be rotated without re-creating the app, from the app’s Protocol details → Client secrets.
Rotate issues a new client secret while the previous one keeps working for 24 hours, so you can update the service before the old secret stops. During that window the previous secret is listed with an Expires Soon badge; a newly issued secret is long-lived.
Invalidate ends the current secret immediately, with no grace period. Use it if a secret may have been exposed, then update the service right away.
Iru manages the signing keys it uses to sign ID tokens and publishes them at the discovery and keys endpoints, so services validate tokens automatically - there is nothing to rotate by hand.

​
Step 6 - Publish, assign, and activate

1

Set the draft as current

Publish your draft so it becomes the live configuration.
2

Assign access

Assign the users or groups who should have the app. See Assigning access.
3

Activate

Make the app active so assigned people can sign in.
4

Test the sign-on

Sign in as a test user from the app dashboard to confirm the experience.

​
Authentication flow

An OIDC app signs people in with the authorization code flow:
1

Redirect to Iru

The app sends the person to Iru to sign in.
2

Authenticate and evaluate policy

Iru authenticates the person and evaluates the app’s authentication policy.
3

Return an authorization code

Iru redirects back to the app’s redirect URI with a short-lived authorization code.
4

Exchange the code for tokens

The app exchanges the code at Iru’s token endpoint for an ID token (who the person is) and an access token.
5

Read claims (and stay signed in)

The app can call the user info endpoint with the access token to read profile claims, and - if you enabled offline_access - use a refresh token to stay signed in.
Most libraries configure this entire flow from the Well-Known URL in Protocol details.

​
Where to go next

Assigning access

Grant the app to users and groups.

Provisioning

Create and remove accounts in the app automatically as access changes.

Authentication policies

Decide who can sign in and what they must prove.

Applications overview

Review protocols and the draft-to-current version model.