SPID/CIE OIDC Service Provider

Integrate with SPID and CIE authentication using the OIDC federation protocol.

---

Documentation · Releases

Note

This library is still in development, all feedback is welcome!

Warning

At this moment, SPID does not officially support the OIDC federation protocol.

Let your users to authenticate with SPID and CIE using the OIDC federation protocol in your applications, with a simple and easy-to-use library. And also TypeScript compatible.

Installation

npm install @xevolab/spid-cie-oidc-ts

Usage

Creating a key set

The object passed to the OIDCClient constructor must contain two key sets. These keys are used to:

• Sign, verify and encrypt the JWTs exchanged with the OIDC provider
• Sign and verify the OIDC federation manifest

const keys = {
	oidc: {
		sig: {
			public:  "-----BEGIN PUBLIC KEY-----...",
			private: "-----BEGIN RSA PRIVATE KEY-----..."
		},
		enc: {
			public:  "-----BEGIN PUBLIC KEY-----...",
			private: "-----BEGIN RSA PRIVATE KEY-----..."
		},
	},
	federation: {
		sig: {
			public:  "-----BEGIN PUBLIC KEY-----...",
			private: "-----BEGIN RSA PRIVATE KEY-----..."
		}
	}
};

If a specific set of federation sig key is not provided, the library will use the OIDC sig key.

Initializing the Client

import OIDCClient, { devTrustAnchors, prodTrustAnchors } from 'oidc-client-library';

const client = new OIDCClient({
  clientID:  process.env.APP_FULL_URL,
	providers: [{
		id: "cie",
		wellKnown: "https://preproduzione.oidc.idserver.servizicie.interno.gov.it/.well-known/openid-federation"
	}],
	keys,
	callbackURL:  process.env.APP_FULL_URL + "/callback",
	spidLevel: 2,
	attributes: ["given_name", "family_name", "email", "birthdate", "https://attributes.eid.gov.it/fiscal_number"],
	trustAnchors: devTrustAnchors,
	trustMarks: [{
		"id": "",
		"iss": "",
		"trust_mark": "eyJ..."
	}],
	logger: (state, action, payload) => { /* ... */ },
	cacheAdapter: SomeCacheAdapter<Session>,
});

Creating a cache adapter

The cache adapter is used to store the state of the authentication flow.

It must implement the CacheAdapter interface, meaning it must expose the following methods:

interface CacheAdapter<T> {
  upsert: (key: string, value: T, ttl?: number) => Promise<void>;
  get: (key: string, value: string) => Promise<T>;
  take: (key: string) => Promise<T>;
}

The key passed in the function calls is the state parameter of the OIDC flow. This can be modified however you want before it is passed to your persistence layer, but, of course, it must be retrievable.

By default, the library uses an in-memory cache adapter, which is not recommended for production use.

Starting the Authentication Flow

const authResponse = client.authorization(providerID);
if (authResponse.ok) {
  // Redirect the user to the URL provided in authResponse.url
}

Handling the Callback

// Grab the state, code, and iss parameters from the callback URL query string
const callbackResponse = await client.callback({ state, code, iss });

if (callbackResponse.ok) {
  // Handle successful authentication
} else {
  // Handle errors
}