> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OIDC applications

> Configure an OIDC application in Iru Identity: client credentials and rotation, redirect URIs, scopes, claim mapping, signing keys, and session length.

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](/en/identity/applications/application-templates). You
edit configuration in a **draft** and then set it as the current version - see
[Applications overview](/en/identity/applications/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.

<Warning>
  The client secret is not displayed again after creation. If you lose it, rotate
  the secret to generate a new one.
</Warning>

The app's **Protocol details** also list the endpoints the service needs to talk
to Iru:

| Detail                 | What it is                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------ |
| **Client ID**          | The app's public identifier.                                                         |
| **Well-Known URL**     | The OpenID discovery document; many services configure everything from this one URL. |
| **Token Endpoint**     | Where the service exchanges an authorization code for tokens.                        |
| **User Info Endpoint** | Where 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:

<Steps>
  <Step title="Allowed sign-in redirect URIs">
    Where Iru returns the person after a successful sign-on. Add every URL the
    service uses.
  </Step>

  <Step title="Allowed sign-out redirect URIs">
    Where Iru returns the person after sign-out.
  </Step>
</Steps>

<Note>
  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.
</Note>

## Step 3 - Choose scopes

**Scopes** control which categories of claims the service may request. Iru
offers the standard OpenID Connect scopes:

| Scope                                 | Grants 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. |

<Tip>
  `openid` is always present and cannot be removed. Enable only the additional
  scopes the service genuinely needs.
</Tip>

## 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.

<Warning>
  Some claim names are reserved by the OpenID Connect standard and cannot be
  used as custom claims: `iss`, `aud`, `exp`, `nbf`, `iat`, and `jti`.
</Warning>

## 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**.

<AccordionGroup>
  <Accordion title="Rotate" icon="rotate">
    **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.
  </Accordion>

  <Accordion title="Invalidate" icon="ban">
    **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.
  </Accordion>
</AccordionGroup>

<Note>
  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.
</Note>

## Step 6 - Publish, assign, and activate

<Steps>
  <Step title="Set the draft as current">
    Publish your draft so it becomes the live configuration.
  </Step>

  <Step title="Assign access">
    Assign the users or groups who should have the app. See
    [Assigning access](/en/identity/applications/assigning-access).
  </Step>

  <Step title="Activate">
    Make the app active so assigned people can sign in.
  </Step>

  <Step title="Test the sign-on">
    Sign in as a test user from the app dashboard to confirm the experience.
  </Step>
</Steps>

## Authentication flow

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

<Steps>
  <Step title="Redirect to Iru">
    The app sends the person to Iru to sign in.
  </Step>

  <Step title="Authenticate and evaluate policy">
    Iru authenticates the person and evaluates the app's
    [authentication policy](/en/identity/authentication/authentication-policies).
  </Step>

  <Step title="Return an authorization code">
    Iru redirects back to the app's **redirect URI** with a short-lived
    authorization **code**.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

Most libraries configure this entire flow from the **Well-Known URL** in
**Protocol details**.

## Where to go next

<CardGroup cols={2}>
  <Card title="Assigning access" icon="user-check" href="/en/identity/applications/assigning-access">
    Grant the app to users and groups.
  </Card>

  <Card title="Provisioning" icon="arrows-rotate" href="/en/identity/applications/provisioning">
    Create and remove accounts in the app automatically as access changes.
  </Card>

  <Card title="Authentication policies" icon="shield-halved" href="/en/identity/authentication/authentication-policies">
    Decide who can sign in and what they must prove.
  </Card>

  <Card title="Applications overview" icon="grip" href="/en/identity/applications/applications-overview">
    Review protocols and the draft-to-current version model.
  </Card>
</CardGroup>