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

# OpenID Connect (OIDC)

> What OIDC is, why it matters for you, recommended client libraries, and how Hopae Connect acts as an OpenID Provider (OP).

## Overview

OpenID Connect (OIDC) is a widely adopted identity layer on top of OAuth 2.0. It standardizes how your application (the Relying Party, RP) verifies a user's identity with an OpenID Provider (OP) and receives verified identity data in a secure and interoperable way.

With Hopae Connect, your app integrates using standard OIDC discovery, authorization, token, and userinfo endpoints. That means you can use battle‑tested OIDC client libraries instead of building custom flows.

## Issuer & Endpoints

Use the issuer for the environment you are targeting.

<Tabs>
  <Tab title="Production">
    * **Issuer:** `https://connect.hopae.com`
    * **Discovery:** `GET /.well-known/openid-configuration`
    * **Auth:** `GET /auth`
    * **Token:** `POST /token`
    * **UserInfo:** `GET /userinfo`
    * **JWKS:** `GET /.well-known/jwks.json`
  </Tab>

  <Tab title="Sandbox">
    * **Issuer:** `https://sandbox.connect.hopae.com`
    * **Discovery:** `GET /.well-known/openid-configuration`
    * **Auth:** `GET /auth`
    * **Token:** `POST /token`
    * **UserInfo:** `GET /userinfo`
    * **JWKS:** `GET /.well-known/jwks.json`
  </Tab>
</Tabs>

## Why Use OIDC with Hopae Connect

* **Standards-based:** Works with any OIDC-compliant client; no custom protocol.
* **Drop-in libraries:** Use established OSS clients with built-in token validation, discovery, and refresh logic.
* **Security best practices:** Exact `redirect_uri` matching, signed JWTs, and JWKS-based key rotation.
* **Simple configuration:** One `issuer` URL enables automatic discovery of all endpoints and capabilities.
* **Clear separation:** Verification and OIDC endpoints live on `connect.hopae.com` (or sandbox), isolated from API resource servers for security and clarity.

## How the Flow Works

```mermaid theme={null}
sequenceDiagram
  participant User as User
  participant App as Your App
  participant Hopae as Hopae Connect
  participant eID as eID Provider

  Note over User, Hopae: Simple user verification flow

  User->>App: Clicks “Verify identity”
  App->>User: Send to Hopae Connect
  User->>Hopae: Open verification page
  Hopae->>User: Show eID options
  User->>eID: Verify identity (e.g., BankID / SmartID)
  eID-->>Hopae: Verification result
  Hopae->>User: Return to your app with a one‑time code

  App->>Hopae: Swap code for tokens (/token)
  Hopae-->>App: Access Token + ID Token
  App->>Hopae: Request user info (/userinfo)
  Hopae-->>App: Verified user profile

  App->>User: Verification complete
```

* Send the user to Hopae Connect to start
* User verifies identity with an eID and comes back with a code
* Your app swaps the code for tokens, then requests user info
* Create a session with the verified profile

<Info>
  Wondering what data you’ll get back? See the Return Data Model for normalized claims, assurance, issuers, presentation, and evidence.

  <br />

  <a href="/guides/concepts/return-data-model">Explore the Return Data Model →</a>
</Info>

## Quick Start Examples

<Tabs>
  <Tab title="Node.js (openid-client)">
    ```ts theme={null}
    import { Issuer } from 'openid-client'

    const issuer = await Issuer.discover('https://sandbox.connect.hopae.com')
    const client = new issuer.Client({
      client_id: process.env.CLIENT_ID!,
      client_secret: process.env.CLIENT_SECRET, // confidential clients only
      redirect_uris: ['https://your.app/callback'],
      response_types: ['code']
    })

    // 1) Redirect user to authorization URL
    const authUrl = client.authorizationUrl({
      scope: 'openid profile email',
    })

    // 2) After callback, exchange code for tokens
    const params = client.callbackParams(request)
    const tokenSet = await client.callback('https://your.app/callback', params)
    const userinfo = await client.userinfo(tokenSet.access_token!)
    ```
  </Tab>

  <Tab title="Python (Authlib)">
    ```py theme={null}
    from authlib.integrations.requests_client import OAuth2Session

    issuer = 'https://sandbox.connect.hopae.com'
    discovery = requests.get(f'{issuer}/.well-known/openid-configuration').json()

    client = OAuth2Session(
        client_id=CLIENT_ID,
        client_secret=CLIENT_SECRET,  # confidential clients only
        scope='openid profile email'
    )

    # 1) Redirect user
    uri, state = client.create_authorization_url(discovery['authorization_endpoint'])

    # 2) Exchange code
    token = client.fetch_token(
        discovery['token_endpoint'],
        grant_type='authorization_code',
        code=auth_code,
        redirect_uri=REDIRECT_URI,
    )

    # 3) UserInfo
    resp = client.get(discovery['userinfo_endpoint'])
    user = resp.json()
    ```
  </Tab>

  <Tab title="Go (go-oidc)">
    ```go theme={null}
    import (
      oidc "github.com/coreos/go-oidc"
      "golang.org/x/oauth2"
    )

    ctx := context.Background()
    provider, _ := oidc.NewProvider(ctx, "https://sandbox.connect.hopae.com")

    oauth := oauth2.Config{
      ClientID:     os.Getenv("CLIENT_ID"),
      ClientSecret: os.Getenv("CLIENT_SECRET"), // confidential only
      Endpoint:     provider.Endpoint(),
      RedirectURL:  "https://your.app/callback",
      Scopes:       []string{"openid", "profile", "email"},
    }

    // 1) Redirect to oauth.AuthCodeURL(state, ...)
    // 2) Exchange code: oauth.Exchange(ctx, code)
    // 3) Verify ID Token and call /userinfo with access token
    ```
  </Tab>

  <Tab title="Java (Spring Security)">
    ```yaml theme={null}
    spring:
      security:
        oauth2:
          client:
            registration:
              hopae:
                client-id: ${CLIENT_ID}
                client-secret: ${CLIENT_SECRET}
                scope: openid, profile, email
                redirect-uri: https://your.app/login/oauth2/code/hopae
                authorization-grant-type: authorization_code
            provider:
              hopae:
                issuer-uri: https://sandbox.connect.hopae.com
    ```
  </Tab>

  <Tab title=".NET (OpenIdConnect)">
    ```csharp theme={null}
    builder.Services.AddAuthentication(options => {
        options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddOpenIdConnect("oidc", options => {
        options.Authority = "https://sandbox.connect.hopae.com";
        options.ClientId = Configuration["CLIENT_ID"];
        options.ClientSecret = Configuration["CLIENT_SECRET"]; // confidential only
        options.ResponseType = "code";
        options.Scope.Add("openid");
        options.Scope.Add("profile");
        options.Scope.Add("email");
    });
    ```
  </Tab>
</Tabs>

## Recommended Libraries

Choose what fits your stack. All are OIDC‑compliant and widely used:

* Node.js: [openid-client](https://github.com/panva/node-openid-client)
* Python: [Authlib](https://docs.authlib.org/)
* Java (Spring): [Spring Security OIDC](https://docs.spring.io/spring-security/reference/servlet/oauth2/login/openid.html)
* .NET: [ASP.NET Core OpenIdConnect](https://learn.microsoft.com/aspnet/core/security/authentication/openid-connect)
* Go: [go-oidc](https://github.com/coreos/go-oidc)
* PHP: [jumbojett/openid-connect-php](https://github.com/jumbojett/OpenID-Connect-PHP)

## Next Steps

<Card title="See Returned Data" icon="list" href="/guides/concepts/return-data-model">
  Learn exactly which claims and fields you receive
</Card>