Eigene External Login Provider

Möchte eine Erweiterung einen neuen External Login Provider hinzufügen, muss diese lediglich die configureExternalLoginProvider Methode auf der Authority aufrufen.

Im Standardfall kann an der Authority nur ein External Login Provider registriert werden. Dieser Provider wird automatisch als Standard External Login Provider registriert. Ist bereits ein External Login Provider registriert, wird dieser ersetzt. Sollen mehrere External Login Provider verwendet werden können, muss ein eigener External Login Provider Manager verwendet werden.

src/backend/index.ts


authority.configureExternalLoginProvider("example", (args) => {
  const { router, getInteractionDetails, finishInteraction, renderPage } = args;
 
  const commonClaimResolver: ClaimResolver = async ({ sub }) => {
    return { sub };
  };
 
  const commonGroupResolver: GroupResolver = async ({ sub }) => {
    return ['exampleGroup'];
  };
 
  router.get(
    "/flow/:uid",
    asyncRequestHandler(async (req, res) => {
      // ...
    })
  );
 
  return {
    accessTokenClaimResolver: commonClaimResolver,
    idTokenClaimResolver: commonClaimResolver,
    groupResolver: commonGroupResolver,
    interactionUrl: async (_, { uid }) => `/flow/${uid}`,
  };
});

Die Methode configureExternalLoginProvider erwartet als ersten Parameter den Namen des External Login Providers und als zweiten Parameter eine Konfigurationsfunktion, die die Konfiguration des External Login Providers zurückgibt. Die Konfigurationsfunktion enthält als Parameter ein Objekt mit folgenden Eigenschaften:

Eigenschaft	Beschreibung
`router`	Express Router mit denen Routen erstellt werden können
`getInteractionDetails`	Funktion, die die Details einer Interaktion zurückgibt
`finishInteraction`	Funktion, die eine Interaktion beendet
`renderPage`	Funktion, die eine Frtonend Seite rendert

Die renderPage-Funktion gibt das HTML einer Frontend Seite zurück. Als Parameter werden die React Props der Webseite, der Name der Seite und ein Kontextobjekt übergeben.

Beispiel für die Verwendung der renderPage Funktion


const frontendHtml = await renderPage({ prop1: 'foo' }, 'my_page', {});

Die gesamte configureExternalLoginProvider muss Konfigurationswerte für den External Login Provider zurückgeben. Dieser werden in Form eines Objekts zurückgegeben. Das Objekt muss folgende Eigenschaften enthalten:

Eigenschaft	Beschreibung
`accessTokenClaimResolver`	Funktion, die die Claims für den Access Token zurückgibt
`idTokenClaimResolver`	Funktion, die die Claims für den ID Token zurückgibt
`groupResolver`	Funktion, die die Gruppen des Nutzers zurückgibt (optional)
`interactionUrl`	Funktion, die die URL für die Interaktion zurückgibt

Die accessTokenClaimResolver und idTokenClaimResolver Funktionen müssen Claims für den Access Token bzw. ID Token zurückgeben. Die Claims müssen als Key-Value Paar zurückgegeben werden.

Die groupResolver Funktion muss eine Liste an Strings zurückgeben, welche die Gruppen oder Rollen beinhaltet, denen der Besitzer des Tokens angehört. Diese Funktion ist relevant, wenn ein eigener Claim Resolver für diese Gruppen implementiert werden soll.

Die interactionUrl Funktion muss die URL für die Interaktion zurückgeben. Typischerweise wird hier die URL für die Interaktion zurückgegeben, die im router Objekt registriert wurde.

Interaktionen

Jeder Loginvorgang ist eine Interaktion. Die Authority entscheidet zu Beginn einer Interaktion mit Hilfe der interactionUrl Funktion, zu welcher Route der Benutzer weitergeleitet wird. Anschließend wird durch den Benutzer diese Route aufgerufen. Der Login Provider muss nun die notwendigen Schritte zur Authentifizierung durchführen. Anschließend muss die Interaktion mit der finishInteraction Funktion beendet werden, die Authority übernimmt dann das Austellen der Tokens und das Weiterleiten des Benutzers.

Der finishInteraction Funktion kann neben den erfordlichen Parametern auch ein Kontext übergeben werden. Dieser wird in den accessTokenClaimResolver und idTokenClaimResolver Funktionen als lastInteractionContext übergeben. Dies erlaubt es Informationen, welche während der Interaktion gesammelt wurden, in den Tokens zu speichern:


const { router, finishInteraction } = ...;
 
const commonClaimResolver: ClaimResolver = async ({ sub, lastInteractionContext }) => {
  const { claims } = lastInteractionContext;
 
  return { sub, ...claims };
};
 
router.get('/flow/:uid', asyncRequestHandler(async (req, res) => {
  // ...
  const loginResult = {
    login: {
      account: 'foo',
    },
  };
 
  const claims = {
    foo: 'bar',
  };
 
  return finishInteraction(req, res, loginResult, { mergeWithLastSubmission: false }, { claims });
}));

Überschreiben der renderPage-Funktion

Möchte eine Erweiterung die renderPage-Funktion überschreiben, muss diese lediglich die authority.renderPage.set Methode auf der Authority aufgerufen werden.


authority.renderPage.set(
  async (props, targetPage, ctx) =>
    `<html>
    <body>
      <h1>${targetPage}</h1>
 
      <pre>${JSON.stringify(props, null, 2)}</pre>
    </body>
  </html>`,
);

Page Payload des Frontends bearbeiten

Mit dem pagePayloadInterceptor kann eine Erweiterung die Payload-Daten des Frontends bearbeiten. Immer wenn eine Seite gerendert wird, ruft die Authority die pagePayloadInterceptor Funktion auf. Der Rückgabewert der Funktion wird als Page Payload-Objekt des Frontends verwendet.


authority.pagePayloadInterseptor.set(...);

Dies ist ein fortgeschrittenes Feature. Es ist nur für Erweiterungen relevant, welche selbst External Login Provider verwalten möchten. Soll hingegen nur ein External Login Provider registriert werden, kann dies wie unter Eigene External Login Provider beschrieben umgesetzt werden.

Ein External Login Provider Manager kann registriert werden, um von anderen Extensions registrierte External Login Provider zu verwalten. Die Authority hat standardmäßig einen External Login Provider Manager, welcher lediglich einen External Login Provider zulässt. Werden mehrere External Login Provider registriert, wird der vohandene External Login Provider verworfen.

Typisches Anwendungsszenario für einen eigenen External Login Provider Manager ist, dass mehrere External Login Provider verwendet werden sollen. Beispielsweise könnte ein External Login Provider Manager beim Login alle möglichen External Login Provider anbieten und dem Benutzer wählen lassen.


authority.configureExternalLoginProviderManager((router, build) => {
  router.get('/acr/', asyncRequestHandler(async (req, res) => {
    const frontend = await authority.renderPage({ ... }, 'login_provider_chooser', {});
    res.send(frontend);
  }));
 
  return {
    configureExternalLoginProvider: (name, callback) => {
      const configuired = build(name, callback);
      // (...) im Router registrieren
    },
 
    getLoginProviderInteractionUrl: async (ctx, interaction) => {
      return '/acr';
    },
 
    resolveAccessTokenClaims: async (args) => {
      // (...) Funktion vom External Login Provider aufrufen
    },
 
    resolveIdTokenClaims: async (args) => {
      // (...) Funktion vom External Login Provider aufrufen
    }
  }
});

Eigene External Login Provider

Interaktionen

Überschreiben der renderPage-Funktion

Page Payload des Frontends bearbeiten

Eigenen External Login Provider Manager registrieren