Anwender

Administratoren

Dienstleister

Partner

Einleitung

optiGov verwendet OAuth2.0 als Framework zur Authentifizierung und Autorisierung. Dabei werden zwei verschiedene Flows unterstützt, je nach Anwendungsfall:

1. Authorization Code Flow mit PKCE – Wird verwendet, wenn ein Nutzer authentifiziert werden soll. Dies ist relevant, wenn eine Anwendung im Namen eines Nutzers auf geschützte Ressourcen zugreifen möchte.
2. Client-Credentials-Flow – Wird für die Maschine-zu-Maschine-Kommunikation genutzt, bei der kein Nutzer involviert ist. Ein Dienst kann sich so selbst authentifizieren, um auf API-Ressourcen zuzugreifen.

Nach einer erfolgreichen Authentifizierung wird ein Token-Paar ausgestellt, welches aus einem kurzlebigen Access-Token und ggf. einem langlebigen Refresh-Token besteht. Das Access-Token ist an die in dem Token enthaltenen Scopes gebunden, welche bei der Autorisierung angefragt werden und durch den Nutzer oder den Client erlaubt werden können.

OAuth2.0-Client einrichten

Um eine Authentifizierung gegen optiGov durchzuführen, ist es notwendig, dies im Kontext eines "OAuth2.0 Client" zu tun. Dieser Client muss in der jeweiligen optiGov-Installation angelegt und konfiguriert werden. Dies muss durch einen Administrator dieser Installation geschehen.

• Authorization Code Flow: Hier wird die Return-URL benötigt, auf welche nach der Autorisierung oder bei Abbruch weitergeleitet werden darf.
• Client-Credentials-Flow: Hier muss eine Rolle definiert werden, deren Scopes dem Token bei der Ausstellung zugewiesen werden.

Referenzimplementation

Inhalt dieser Seite ist eine Referenzimplementation, welche einen beispielhaften PKCE-Flow gegen die optiGov OAuth2.0 Schnittstelle implementiert.

Authorization Code Flow mit PKCE

Der Authorization Code Flow mit PKCE (Proof Key for Code Exchange) wird verwendet, wenn eine Anwendung eine Benutzeranmeldung durchführen möchte.

Aufruf der Authentifizierung / Autorisierung

Als erster Schritt ist eine Authentifizierung und darauf aufbauende Autorisierung des Nutzers notwendig. Diese geschieht auf der Seite von optiGov, welche durch eine speziell zusammengesetzte URL aufgerufen wird.

// generate state 
const state = Str.random(40)
Store.store({key: "oauth-state", value: state})

// generate code verifier
const codeVerifier = Str.random(128)
Store.store({key: "oauth-code-verifier", value: codeVerifier})

// create code challenge
const codeChallenge = Base64.encode(await SHA256.hash(codeVerifier))

// create redirect url
const redirectUrl = "https://meine-redirect-url.dd"

// set url in body
this.url = window.config.oauth.endpoints.authorize 
	+  "?client_id=" + MEINE_CLIENT_ID 
	+  "&redirect_uri=" + encodeURIComponent(redirectUrl) 
	+  "&response_type=code" 
	+  "&scope=" + encodeURIComponent("LISTE_ALLER_SCOPES") 
	+  "&state=" + state 
	+  "&code_challenge=" + codeChallenge 
	+  "&code_challenge_method=S256"

// redirect to url
await window.location.href = this.url

Hinweis: optiGov verwendet OAuth2.0 für verschiedene weitere Authentifizierungskomponenten. Über das Parameter component können diese angesprochen werden. Standardmäßig wird die optiGov-Komponente verwendet. Um die Komponente für das Bürgerkonto zu verwenden kann das folgende Parameter in der URL ergänzt werden:

+ "&component=buergerkonto"

Um die Komponente für das Unternehmenskonto zu verwenden kann das folgende Parameter in der URL ergänzt werden:

+ "&component=unternehmenskonto"

Erhalt eines Token-Paars

Nach erfolgreicher Authentifizierung und Autorisierung durch den Nutzer wird ein Authorization Code zurückgegeben, der dann gegen ein Access-Token eingetauscht werden kann:

const response = await fetch('https://meine-optiGov-instanz.de/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    client_id: 'MEIN_CLIENT_ID',
    grant_type: 'authorization_code',
    code: 'ERHALTENER_AUTH_CODE',
    redirect_uri: 'https://meine-redirect-url.dd',
    code_verifier: 'MEIN_CODE_VERIFIER'
  })
});

const data = await response.json();
console.log('Access Token:', data.access_token);

Antwort:

{
  "access_token": "ey...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "xxx"
}

Client-Credentials-Flow

Der Client-Credentials-Flow wird für die Maschine-zu-Maschine-Kommunikation eingesetzt. Hierbei authentifiziert sich eine Anwendung direkt mit ihren Zugangsdaten, um ein Access-Token zu erhalten. Nutzerinteraktion ist nicht erforderlich.

Abruf eines Access-Tokens

Der Client sendet eine Anfrage an den Token-Endpunkt, um ein Access-Token zu erhalten:

const response = await fetch('https://meine-optiGov-instanz.de/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    client_id: 'MEIN_CLIENT_ID',
    client_secret: 'MEIN_CLIENT_SECRET',
    grant_type: 'client_credentials',
  })
});

const data = await response.json();
console.log('Access Token:', data.access_token);

Antwort

{
  "access_token": "ey...",
  "token_type": "bearer",
  "expires_in": 3600
}

• Einleitung
• OAuth2.0-Client einrichten
• Referenzimplementation
• Authorization Code Flow mit PKCE
• Aufruf der Authentifizierung / Autorisierung
• Erhalt eines Token-Paars
• Client-Credentials-Flow
• Abruf eines Access-Tokens